test(hydrogen-api): assert checked-in generated types match declared API versions

Adds a unit test that fails if SF_API_VERSION or CA_API_VERSION in
api-versions.ts doesn't match the version the checked-in .d.ts files
were generated against — i.e. someone bumped a version constant
without running `pnpm graphql-types` to regenerate.

Why: the generated .d.ts files are committed to the repo so consumers
and CI get deterministic installs. That's only safe if what ships
matches what's declared. Without this check, a version bump in
isolation silently ships stale types, and `storefront.query()` calls
typecheck against the wrong schema shape.

How: extracted SF_API_VERSION and CA_API_VERSION from codegen.ts into
src/api-versions.ts as a single source of truth imported by both
codegen.ts (the writer) and src/generated-files.test.ts (the verifier).
The test reads the "Based on <API> API <version>" header codegen.ts
embeds on line 3 of each .d.ts and asserts the parsed version equals
the declared one. Uses parametrized `it.each` so each API gets its own
named test; the failure message names the file, both versions, and
the remediation command.

Unit test rather than a tsdown hook: this is an invariant on repo
state (are checked-in files fresh?), not on build output (did
bundling produce correct JS?) — it belongs with the other
`pnpm test` assertions where failures are discoverable and
compose with other invariants.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: fredericoo

packages/hydrogen-api/codegen.ts

@@ -3,9 +3,7 @@ import {
   storefrontApiCustomScalars,
   customerAccountApiCustomScalars,
 } from './src/codegen-helpers';
-
-const SF_API_VERSION = '2026-04';
-const CA_API_VERSION = '2026-04';
+import {SF_API_VERSION, CA_API_VERSION} from './src/api-versions';
 
 const storefrontAPISchema: CodegenConfig['schema'] = {
   [`https://hydrogen-preview.myshopify.com/api/${SF_API_VERSION}/graphql.json`]:

packages/hydrogen-api/src/api-versions.ts

@@ -0,0 +1,11 @@
+/**
+ * Single source of truth for the Shopify API versions this package
+ * generates types against. Imported by `codegen.ts` (the writer) and by
+ * `generated-files.test.ts` (the verifier that ensures the checked-in
+ * generated files were produced against these same versions).
+ *
+ * Bumping a version here without running `pnpm graphql-types` will cause
+ * `pnpm test` to fail.
+ */
+export const SF_API_VERSION = '2026-04';
+export const CA_API_VERSION = '2026-04';

packages/hydrogen-api/src/generated-files.test.ts

@@ -0,0 +1,45 @@
+import {readFileSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {dirname, join} from 'node:path';
+import {describe, it, expect} from 'vitest';
+import {SF_API_VERSION, CA_API_VERSION} from './api-versions';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+// codegen.ts emits a header comment on line 3 of each generated .d.ts
+// like `* Based on Storefront API 2026-04`. If that version doesn't
+// match what api-versions.ts declares, someone bumped the constant
+// without running `pnpm graphql-types`.
+const cases = [
+  {
+    file: 'generated/storefront-api-types.d.ts',
+    apiName: 'Storefront',
+    declaredVersion: SF_API_VERSION,
+  },
+  {
+    file: 'generated/customer-account-api-types.d.ts',
+    apiName: 'Customer Account',
+    declaredVersion: CA_API_VERSION,
+  },
+] as const;
+
+describe('checked-in generated types', () => {
+  it.each(cases)(
+    '$file matches declared $apiName API version ($declaredVersion)',
+    ({file, apiName, declaredVersion}) => {
+      const contents = readFileSync(join(here, file), 'utf8');
+      const match = contents.match(
+        new RegExp(`Based on ${apiName} API (\\S+)`),
+      );
+      expect(
+        match,
+        `"Based on ${apiName} API <version>" header not found in ${file}. Run \`pnpm graphql-types\` to regenerate.`,
+      ).not.toBeNull();
+      const [, generatedVersion] = match!;
+      expect(
+        generatedVersion,
+        `${file} is stale: generated against ${apiName} API ${generatedVersion}, but api-versions.ts declares ${declaredVersion}. Run \`pnpm graphql-types\` to regenerate.`,
+      ).toBe(declaredVersion);
+    },
+  );
+});