Generate types and check prepare targets when the CLI runs typegen.js

Add typegen.js, which Shopify CLI runs instead of graphql-code-generator
when this package has it (Shopify/cli#8829). It generates the function's
types with the codegen plugins this package depends on, gives each prepare
result's variables its run query's variables type, and exits non-zero,
failing the build, when a prepare target returns variables its run query
doesn't accept.

The check is moved here from Shopify/cli#8829: it follows what the prepare
export returns, ignoring type annotations and casts, and validates it
against the run query's variable definitions.

Author: saga-dasgupta

.changeset/custom-scalar-overrides.md

@@ -0,0 +1,5 @@
+---
+"@shopify/shopify_function": minor
+---
+
+Check a JavaScript function's prepare targets when its types are generated. With a Shopify CLI that runs this package's `typegen.js`, the types are generated with this package's codegen plugins, a prepare result's `variables` has its run query's variables type, and the build fails when a prepare target returns variables its run query doesn't accept. Also adds `@shopify/shopify_function/codegen`, a plugin to use instead of `typescript` when running codegen yourself.

.changeset/prepare-variables.md

@@ -4,59 +4,43 @@ This repository contains the source code for the [`@shopify/shopify_function`][p
 
 [package]: https://npm.im/@shopify/shopify_function
 
-## Typing a prepare target's variables
+## Prepare targets
 
-A prepare target returns the variables for its run target's input query. The schema types them as `JSON`, so the generated type is `unknown` and nothing checks them against the run query.
+A prepare target returns the variables for its run target's input query. With a Shopify CLI that includes [Shopify/cli#8829](https://github.com/Shopify/cli/pull/8829), this package generates the function's types and checks those variables whenever the CLI generates types: `shopify app function typegen`, and every function build, including `shopify app dev` and `shopify app deploy`. No configuration is needed.
 
-`@shopify/shopify_function/codegen` generates the same types as the `typescript` codegen plugin, and takes `customScalarOverrides` to give a custom scalar field of an input object another type. Use it instead of `typescript` in the function's `package.json`, and give the prepare result's `variables` the run query's variables type:
+- **Types:** the prepare result's `variables` has the run query's variables type, so editors report mismatches as you type.
+- **Checks:** the build fails when a prepare target returns variables its run query doesn't accept:
 
-```json
-"codegen": {
-  "schema": "schema.graphql",
-  "documents": "src/*.graphql",
-  "generates": {
-    "./generated/api.ts": {
-      "plugins": ["@shopify/shopify_function/codegen", "typescript-operations"]
-    }
-  },
-  "config": {
-    "omitOperationSuffix": true,
-    "customScalarOverrides": {
-      "CartValidationsGeneratePrepareResult.variables": "CartValidationsGenerateRunInputVariables"
-    }
-  }
-}
+```
+The function extension "delivery-customization" returns prepare variables its run query doesn't accept
+src/cart_delivery_options_transform_prepare.js:26:23 `variables.ruleQueri` isn't declared by src/cart_delivery_options_transform_run.graphql
 ```
 
-`typescript-operations` generates `CartValidationsGenerateRunInputVariables` for the run query, `query CartValidationsGenerateRunInput($ruleSetHandle: String! = "rules-default") { ... }`.
+The check follows what the prepare export returns through local helpers, conditionals, `??`, `||` and re-exports, and ignores type annotations and casts. It reports:
 
-The prepare target's return type then checks its variables:
+- variables the run query doesn't declare, and required variables that are missing;
+- values of the wrong type, including enum values, list elements and input object fields;
+- `null` or `undefined` where the variable can't take them.
 
-```js
-// @ts-check
-/** @returns {import("../generated/api").CartValidationsGeneratePrepareResult} */
-export function cartValidationsGeneratePrepare(input) {
-  return { variables: { ruleSetHandle: "rules-custom" } };
-}
-```
+Values it can't follow fail too: values typed `any` or `unknown`, such as parsed JSON; objects with arbitrary keys; and variables changed or passed on after they're created. Check and narrow such values before returning them.
 
-A prepare target that no longer matches its run query is a type error:
+The types are generated with the codegen plugins this package depends on, not whichever versions the app's package manager hoists.
 
-| Mismatch | Type error in the prepare target |
-| --- | --- |
-| A variable was renamed or removed | Unknown property |
-| A required variable was added, or a default removed | Missing property |
-| A value has the wrong type, or is `null` for a required variable | Type isn't assignable |
+### Running codegen yourself
 
-- Keys are `"InputObject.field"`, and the field's type must be a custom scalar. Lists and nullability are kept, and oneOf variants work too.
-- An override that isn't a custom scalar field of an input object fails codegen.
-- Without `customScalarOverrides`, the generated types are the same as `typescript`'s.
+To type the variables when running GraphQL Codegen yourself, use `@shopify/shopify_function/codegen` instead of the `typescript` plugin. It generates the same types, and takes `customScalarOverrides` to give a custom scalar field of an input object another type:
 
-### Limits
+```json
+"plugins": ["@shopify/shopify_function/codegen", "typescript-operations"],
+"config": {
+  "omitOperationSuffix": true,
+  "customScalarOverrides": {
+    "CartValidationsGeneratePrepareResult.variables": "CartValidationsGenerateRunInputVariables"
+  }
+}
+```
 
-- Editors and `tsc` report the errors, but `shopify app function build` doesn't type-check, so a mismatch still builds. JavaScript files need `// @ts-check`, as in the function templates, or `checkJs`.
-- `String`, `ID`, and custom scalars mapped to `string` (such as `Handle`) are the same TypeScript type, so switching between them isn't an error.
-- An object literal is checked for unknown keys. A value built elsewhere is checked for missing and mistyped variables, but not for extra keys.
+Keys are `"InputObject.field"`, and the field's type must be a custom scalar. Lists and nullability are kept.
 
 ## Development