@burdenoff/fe-libs 2026.725.4 → 2026.726.1

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@burdenoff/fe-libs",
-  "version": "2026.725.4",
+  "version": "2026.726.1",
   "description": "Burdenoff frontend primitives and domain libraries",
   "type": "module",
+  "bin": {
+    "graphql-schema-drift": "./scripts/graphql-schema-drift/cli.ts"
+  },
   "imports": {
     "#lib/*": "./src/lib/*",
     "#ui/*": "./src/ui/*",
@@ -265,6 +268,8 @@
     "src/shared/styles/**/*",
     "src/shared/shims/**/*",
     "src/vite/**/*",
+    "scripts/graphql-schema-drift/*.ts",
+    "scripts/graphql-schema-drift/README.md",
     "README.md",
     "LICENSE"
   ],
@@ -275,7 +280,8 @@
     "lint:sanity": "if [ \"${CI:-}\" = \"true\" ]; then bun run lint; else bun run lint -- --cache --cache-location .eslintcache; fi",
     "format": "prettier --config shared/config/prettier.config.mjs --write \"src/**/*.{ts,tsx}\" \"!src/config/*.config.ts\"",
     "type:check": "tsc --noEmit",
-    "sanity": "bun run lint:sanity && bun run format && bun run type:check && bun run build",
+    "test": "bun test scripts/graphql-schema-drift/__tests__",
+    "sanity": "bun run lint:sanity && bun run format && bun run type:check && bun run test && bun run build",
     "switch:status": "bun scripts/deps-mode.ts status",
     "switch:remote": "bun scripts/deps-mode.ts remote",
     "switch:local": "bun scripts/deps-mode.ts local",

package/scripts/graphql-schema-drift/README.md

@@ -0,0 +1,137 @@
+# graphql-schema-drift
+
+Shared PR-time guard that validates an MFE's **inline** GraphQL query /
+mutation / subscription documents (hand-rolled template literals, `gql`-tagged
+or not) against a configured schema snapshot, and fails the build on any
+mismatch.
+
+## Why this exists (BOFF-3922)
+
+MFEs that write GraphQL as `.graphql` files under `src/operations/**` already
+get this check for free — `graphql-codegen`'s `documents:` glob parses and
+validates those against `schema:` as part of generating types. But several
+MFEs (and more will follow) hand-roll queries as plain template literals
+inside `.ts`/`.tsx` hooks — those never touch `documents:`, so `codegen`
+silently no-ops on them (`ignoreNoDocuments: true`), and nothing else in CI
+looks at them. A backend rename or a flat-list→Connection pagination change
+then breaks the MFE in prod with zero CI signal. This happened three times
+independently before this tool existed:
+
+- **BOFF-3915** (labsofscience) — root incident that opened BOFF-3922.
+- **BOFF-4703** (manufacturedops) — `useDowntimeEvents`/`useInspectionPlans`.
+- **BOFF-3529** (planmagnet) — 44 pages' inline `gql` blocks post field-rename.
+- **movethewheels** `useOrders.ts` (2026-07-25) — hand-rolled queries against
+  the pre-rename `Order`/`orderStats` schema, weeks after the backend renamed
+  the domain to `DeliveryJob`.
+
+manufacturedops and planmagnet each independently wrote a bespoke
+`scripts/validate-schema-drift.ts` to guard against a repeat. This package
+generalizes both into one configurable tool so future repos don't reinvent it
+a fourth, fifth, sixth time.
+
+## What it does NOT (yet) do
+
+- **Doesn't check `.graphql`-file-based MFEs.** Those already get schema
+  validation from `bun run codegen` today. What they're missing is a
+  guarantee that the _committed schema snapshot itself_ is fresh — codegen
+  will happily validate a correct-looking query against a stale local
+  `graphql/wspace.graphql` and pass. That's a different problem (snapshot
+  freshness, not missing validation) and needs a different fix — see
+  "Fleet-wide follow-up" below.
+- **Doesn't fetch schema from Hive CDN.** Every `schemaGroups[].files` entry
+  is a file already committed to the consuming repo. This avoids needing new
+  CI secrets to land the tool in its first 3 repos, but it means the schema
+  source can itself go stale (exactly the manufacturedops/planmagnet root
+  cause) unless someone keeps it refreshed. See "Fleet-wide follow-up".
+- **Doesn't check the version an app-shell actually pins.** BOFF-3922 also
+  flags that a shell can pin an MFE version older than the deployed schema.
+  Out of scope here — this only checks the repo's own HEAD.
+
+## Usage
+
+1. Add `@burdenoff/fe-libs` as a dependency (every MFE already has it).
+2. Create `schema-drift.config.json` at the repo root:
+
+```jsonc
+{
+  "sourceRoots": [{ "dir": "src/myproduct" }],
+  "fragmentDirs": ["src/operations/wspace/myproduct/fragments"],
+  "schemaGroups": [
+    { "name": "subgraph", "files": ["graphql/myproduct.graphql"] },
+    { "name": "gateway-fallback", "files": ["graphql/wspace.graphql"] },
+  ],
+}
+```
+
+3. Add a script and wire it into `sanity`:
+
+```jsonc
+"scripts": {
+  "validate:schema-drift": "graphql-schema-drift",
+  "sanity": "bun run codegen && bun run validate:schema-drift && bun run lint:sanity && bun run format && bun run type:check && bun run build"
+}
+```
+
+4. Keep the referenced schema file(s) fresh — same discipline as
+   `graphql/wspace.graphql` / `graphql/global.graphql` already require. E.g.:
+
+```bash
+cp ../../wspace/myproduct/wspace-myproduct-svc/.hive-schema.graphql graphql/myproduct.graphql
+```
+
+## Config reference
+
+See `types.ts` for the full, documented shape (`SchemaDriftConfig`). Summary:
+
+| Field                                 | Purpose                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sourceRoots[]`                       | Dirs scanned recursively for inline `query`/`mutation`/`subscription`/`fragment` template literals.                                                                                                                                                                                                                          |
+| `fragmentDirs[]`                      | Optional dirs of standalone `.graphql`/`.gql` fragment files, resolved for `...Spread`s (in addition to inline `fragment` blocks, which are always collected automatically).                                                                                                                                                 |
+| `schemaGroups[]`                      | ≥1 named schema targets. A document is clean if it validates against **any one** group — this covers both "try my subgraph, fall back to the gateway snapshot for foreign root fields" (multiple groups) and "concatenate a base SDL + an `extend type Query` roots file into one schema" (`mergeExtends` within one group). |
+| `treatUnresolvedInterpolationAsError` | Default `true`. An operation with a `${...}` this tool can't resolve against a same-file `const` fails loudly rather than silently validating a truncated document.                                                                                                                                                          |
+
+## Extraction rules
+
+- Matches backtick blocks whose content starts with `query`, `mutation`,
+  `subscription`, or `fragment` — with or without a preceding `gql` tag.
+- `${NAME}` interpolations are expanded against same-file top-level
+  `const NAME = \`...\`;` constants (transitively, up to 10 passes).
+- `fragment ... on ... { }` blocks (inline or from `fragmentDirs`) are pooled
+  and spliced in wherever `...FragmentName` is spread, transitively.
+
+## Fleet-wide follow-up (not done in this pass)
+
+BOFF-3922 asks for a fleet-wide rollout across all 63 `microfe-*` repos. That
+is deliberately **not** attempted here — this PR proves the tool on 3 real
+repos (2 migrations off bespoke scripts + 1 fresh installation covering a
+guard gap that a real incident had already exposed) and leaves the rest as
+scoped follow-up:
+
+1. **Wire into the remaining MFEs with inline/hand-rolled documents.** Audit
+   the fleet for `.ts`/`.tsx` files containing bare `` `query `` / `` `mutation ``
+   backtick blocks outside any `documents:` glob (grep
+   ``grep -rlE '`\s*(query|mutation)\s' src --include=*.ts --include=*.tsx``
+   per repo) and add a `schema-drift.config.json` + wire into `sanity` for
+   each hit.
+2. **Solve schema-source freshness**, either by:
+   - a scheduled job per repo that re-runs `schema:pull`-equivalent and opens
+     a PR when the snapshot drifts from the live subgraph, or
+   - a `schemaGroups[].source: 'hive-cdn'` mode that fetches
+     `https://cdn.graphql-hive.com/artifacts/v1/{target}/sdl` with
+     `X-Hive-CDN-Key` at validation time instead of reading a committed file
+     (precedent: `microfe-groups/.graphqlrc.yml`'s `schema-wspace` codegen
+     project already pulls schema this way, just not wired to this tool).
+     This needs a CDN token provisioned per repo/CI — real effort, not a
+     one-line change.
+3. **Extend coverage to `.graphql`-file-based MFEs** (the majority of the
+   fleet) once (2) is solved — at that point the value-add over what codegen
+   already does is real (freshness), not just redundant re-validation of the
+   same local file codegen already checked.
+4. **Pin-aware validation** — validate the _published_ MFE version an
+   app-shell pins, not just the repo's own HEAD, per the original ticket's
+   "worth considering" list.
+
+## Reference incidents this tool is proof against
+
+Run `bun test scripts/graphql-schema-drift/__tests__` in this repo for the
+unit-test coverage of the extraction/fragment/schema-group logic itself.

package/scripts/graphql-schema-drift/cli.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env bun
+/**
+ * graphql-schema-drift — shared CI guard that validates an MFE's inline
+ * GraphQL query/mutation/subscription documents against its own configured
+ * schema snapshot(s), catching the class of bug where a backend rename or
+ * pagination change silently breaks a hand-rolled template-literal query that
+ * `graphql-codegen` never sees (BOFF-3922; incidents BOFF-3915, BOFF-4703,
+ * BOFF-3529, and the movethewheels useOrders.ts rewrite of 2026-07-25).
+ *
+ * Usage (from a consuming MFE repo root):
+ *   bun run node_modules/@burdenoff/fe-libs/scripts/graphql-schema-drift/cli.ts [configPath]
+ * or, since fe-libs declares this as a package `bin`:
+ *   graphql-schema-drift [configPath]
+ *
+ * `configPath` defaults to `./schema-drift.config.json`. See README.md in
+ * this directory for the config shape and worked examples.
+ *
+ * Exit code: 0 if every extracted document validates cleanly, 1 otherwise.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { runValidation } from './validate';
+import type { SchemaDriftConfig } from './types';
+
+function main(): void {
+  const configPathArg = process.argv[2] ?? 'schema-drift.config.json';
+  const repoRoot = process.cwd();
+  const configPath = resolve(repoRoot, configPathArg);
+
+  if (!existsSync(configPath)) {
+    console.error(`[graphql-schema-drift] Config not found: ${configPath}`);
+    console.error(
+      'Create a schema-drift.config.json at your repo root (or pass a path as the first argument). ' +
+        'See @burdenoff/fe-libs/scripts/graphql-schema-drift/README.md for the config shape.'
+    );
+    process.exit(1);
+  }
+
+  let config: SchemaDriftConfig;
+  try {
+    config = JSON.parse(readFileSync(configPath, 'utf8')) as SchemaDriftConfig;
+  } catch (e) {
+    console.error(`[graphql-schema-drift] Failed to parse ${configPath}: ${(e as Error).message}`);
+    process.exit(1);
+    return;
+  }
+
+  let report: ReturnType<typeof runValidation>;
+  try {
+    report = runValidation(config, repoRoot);
+  } catch (e) {
+    console.error(`[graphql-schema-drift] ${(e as Error).message}`);
+    process.exit(1);
+    return;
+  }
+
+  if (report.errors.length > 0) {
+    const fileCount = new Set(report.errors.map((e) => e.file)).size;
+    console.error(
+      `\n[graphql-schema-drift] FAILED — ${report.errors.length} operation(s) with schema drift across ${fileCount} file(s):\n`
+    );
+    for (const err of report.errors) {
+      const label = err.operationName ?? `block #${err.index}`;
+      console.error(`  ${err.file} :: ${label}`);
+      for (const msg of err.messages) {
+        console.error(`    - ${msg}`);
+      }
+    }
+    console.error(
+      '\nEach of these operations must validate against at least one schema group configured in ' +
+        'schema-drift.config.json. Either fix the query/mutation to match the current schema, or refresh ' +
+        'the schema snapshot file(s) referenced there if the schema itself changed.\n'
+    );
+    process.exit(1);
+  }
+
+  console.log(
+    `[graphql-schema-drift] OK — validated ${report.documentCount} operation(s) across ${report.fileCount} source file(s). 0 errors.`
+  );
+}
+
+main();

package/scripts/graphql-schema-drift/extract.ts

@@ -0,0 +1,95 @@
+/**
+ * Extraction of inline GraphQL documents from `.ts`/`.tsx` source.
+ *
+ * Generalizes two patterns proven in production incidents (BOFF-4703
+ * manufacturedops, BOFF-3529 planmagnet):
+ *   - bare backtick template literals: `const LIST = \`query ListX { ... }\`;`
+ *   - `gql`-tagged template literals: `` gql`query ListX { ... }` ``
+ *
+ * Both are matched by the same regex — the extractor only cares that the
+ * backtick content starts with `query` / `mutation` / `subscription` /
+ * `fragment`; whether it's preceded by a `gql` tag is irrelevant to whether
+ * the document is real GraphQL that must validate against the schema.
+ *
+ * Same-file top-level `const NAME = \`...\`;` string constants are collected
+ * and used to expand `${NAME}` interpolations (the manufacturedops
+ * `*_FIELDS` selection-set fragment pattern) before parsing.
+ */
+
+/** Max passes when expanding `${NAME}` interpolations; guards against cyclic consts. */
+const MAX_INTERPOLATION_DEPTH = 10;
+
+const DOC_BLOCK_RE = /`(\s*(?:query|mutation|subscription|fragment)\s[\s\S]*?)`/g;
+const CONST_RE = /const\s+([A-Za-z_$][\w$]*)\s*=\s*`([^`]*)`/g;
+const INTERPOLATION_RE = /\$\{\s*([A-Za-z_$][\w$]*)\s*\}/g;
+
+/**
+ * Collect `const NAME = `...`;` single-backtick string constants from a source
+ * file — the selection-set fragments this codebase interpolates into
+ * operations. Constants containing a nested backtick are intentionally not
+ * matched (same limitation as the original per-repo scripts this generalizes).
+ */
+export function collectStringConstants(source: string): Map<string, string> {
+  const consts = new Map<string, string>();
+  let match: RegExpExecArray | null;
+  CONST_RE.lastIndex = 0;
+  while ((match = CONST_RE.exec(source)) !== null) {
+    consts.set(match[1], match[2]);
+  }
+  return consts;
+}
+
+/** Replace `${NAME}` with the corresponding constant, transitively. */
+export function expandInterpolations(body: string, consts: ReadonlyMap<string, string>): string {
+  let current = body;
+  for (let pass = 0; pass < MAX_INTERPOLATION_DEPTH; pass++) {
+    if (!current.includes('${')) return current;
+    const next = current.replace(INTERPOLATION_RE, (whole, name: string) =>
+      consts.has(name) ? (consts.get(name) as string) : whole
+    );
+    if (next === current) return current;
+    current = next;
+  }
+  return current;
+}
+
+/** Names of any `${...}` interpolations remaining after expansion. */
+export function collectUnresolvedInterpolations(body: string): string[] {
+  const out: string[] = [];
+  let match: RegExpExecArray | null;
+  const re = new RegExp(INTERPOLATION_RE.source, 'g');
+  while ((match = re.exec(body)) !== null) {
+    out.push(match[1]);
+  }
+  return out;
+}
+
+export interface ExtractedBlock {
+  file: string;
+  index: number;
+  /** `false` for a `fragment ... on ...` block — those are collected as fragments, not validated standalone. */
+  isFragment: boolean;
+  /** Fully `${NAME}`-expanded source text. */
+  source: string;
+  unresolved: string[];
+}
+
+/**
+ * Extract every backtick block that looks like a GraphQL document (operation
+ * or fragment) from a single source file's text, expanding same-file
+ * `${NAME}` constant interpolations along the way.
+ */
+export function extractBlocks(source: string, file: string): ExtractedBlock[] {
+  const consts = collectStringConstants(source);
+  const blocks: ExtractedBlock[] = [];
+  let match: RegExpExecArray | null;
+  const re = new RegExp(DOC_BLOCK_RE.source, 'g');
+  let index = 0;
+  while ((match = re.exec(source)) !== null) {
+    const expanded = expandInterpolations(match[1], consts);
+    const unresolved = [...new Set(collectUnresolvedInterpolations(expanded))];
+    const isFragment = /^\s*fragment\s/.test(expanded);
+    blocks.push({ file, index: index++, isFragment, source: expanded, unresolved });
+  }
+  return blocks;
+}

package/scripts/graphql-schema-drift/fragments.ts

@@ -0,0 +1,92 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  Kind,
+  parse,
+  type DefinitionNode,
+  type DocumentNode,
+  type FragmentDefinitionNode,
+} from 'graphql';
+import { safeListFilesRecursive } from './fs-util';
+
+/** Load every `fragment X on Y { ... }` definition from standalone `.graphql`/`.gql` files under `dirs`. */
+export function loadFragmentDefinitionsFromDirs(
+  dirs: readonly string[],
+  repoRoot: string
+): Map<string, FragmentDefinitionNode> {
+  const map = new Map<string, FragmentDefinitionNode>();
+  for (const dir of dirs) {
+    const absDir = join(repoRoot, dir);
+    for (const file of safeListFilesRecursive(absDir, ['.graphql', '.gql'])) {
+      const doc = parse(readFileSync(file, 'utf8'));
+      for (const def of doc.definitions) {
+        if (def.kind === Kind.FRAGMENT_DEFINITION) {
+          map.set(def.name.value, def);
+        }
+      }
+    }
+  }
+  return map;
+}
+
+/** Collect the transitive set of fragment names spread anywhere within a set of definitions. */
+export function collectSpreadNames(
+  definitions: readonly DefinitionNode[],
+  found: Set<string> = new Set()
+): Set<string> {
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) {
+      for (const item of node) visit(item);
+      return;
+    }
+    const obj = node as { kind?: string; name?: { value?: string } };
+    if (obj.kind === Kind.FRAGMENT_SPREAD && obj.name?.value) {
+      found.add(obj.name.value);
+    }
+    for (const key of Object.keys(obj)) {
+      if (key === 'loc') continue;
+      visit((obj as Record<string, unknown>)[key]);
+    }
+  };
+  for (const def of definitions) visit(def);
+  return found;
+}
+
+/**
+ * Given a parsed document and a pool of known fragment definitions (from
+ * inline `fragment` blocks and/or standalone fragment files), return a new
+ * document with every transitively-spread fragment's definition appended.
+ * A spread whose name isn't found in `fragmentPool` is left unresolved —
+ * `validate()` will correctly report it as an "Unknown fragment" error.
+ */
+export function resolveFragments(
+  doc: DocumentNode,
+  fragmentPool: ReadonlyMap<string, FragmentDefinitionNode>
+): DocumentNode {
+  const needed = new Set<string>();
+  let frontier = collectSpreadNames(doc.definitions);
+  while (frontier.size > 0) {
+    const next = new Set<string>();
+    for (const name of frontier) {
+      if (needed.has(name)) continue;
+      needed.add(name);
+      const fragDef = fragmentPool.get(name);
+      if (fragDef) {
+        for (const nested of collectSpreadNames([fragDef])) {
+          if (!needed.has(nested)) next.add(nested);
+        }
+      }
+    }
+    frontier = next;
+  }
+
+  const extraDefs: DefinitionNode[] = [];
+  for (const name of needed) {
+    const fragDef = fragmentPool.get(name);
+    if (fragDef) extraDefs.push(fragDef);
+  }
+  if (extraDefs.length === 0) return doc;
+
+  return { ...doc, definitions: [...doc.definitions, ...extraDefs] };
+}

package/scripts/graphql-schema-drift/fs-util.ts

@@ -0,0 +1,22 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Recursively list files under `dir` whose name ends with one of `suffixes`. */
+export function listFilesRecursive(dir: string, suffixes: readonly string[]): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...listFilesRecursive(full, suffixes));
+    } else if (suffixes.some((s) => entry.name.endsWith(s))) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/** Same as `listFilesRecursive`, but returns `[]` instead of throwing when `dir` doesn't exist. */
+export function safeListFilesRecursive(dir: string, suffixes: readonly string[]): string[] {
+  if (!existsSync(dir)) return [];
+  return listFilesRecursive(dir, suffixes);
+}

package/scripts/graphql-schema-drift/index.ts

@@ -0,0 +1,11 @@
+/** Programmatic entry point — primarily for tests. CLI usage is via cli.ts. */
+export {
+  collectStringConstants,
+  expandInterpolations,
+  extractBlocks,
+  type ExtractedBlock,
+} from './extract';
+export { collectSpreadNames, loadFragmentDefinitionsFromDirs, resolveFragments } from './fragments';
+export { loadSchemaGroup, loadSchemaGroups, type LoadedSchemaGroup } from './schema';
+export { runValidation, type DriftError, type DriftReport } from './validate';
+export type { SchemaDriftConfig, SchemaGroupConfig, SourceRootConfig } from './types';

package/scripts/graphql-schema-drift/schema.ts

@@ -0,0 +1,42 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildSchema, type GraphQLSchema } from 'graphql';
+import type { SchemaGroupConfig } from './types';
+
+const EXTEND_RE = /\bextend\s+(type|interface)\b/g;
+
+export interface LoadedSchemaGroup {
+  name: string;
+  schema: GraphQLSchema;
+}
+
+/**
+ * Build one `GraphQLSchema` from a group's SDL file(s). Files are concatenated
+ * in the order given. When `mergeExtends` is set, `extend type X` / `extend
+ * interface X` in every file is rewritten to `type X` / `interface X` first —
+ * this lets a file that declares `extend type Query` against root fields only
+ * present in the composed supergraph (not in the group's own base SDL) build
+ * as a single self-contained schema instead of requiring the extend target to
+ * pre-exist.
+ */
+export function loadSchemaGroup(group: SchemaGroupConfig, repoRoot: string): LoadedSchemaGroup {
+  const parts = group.files.map((file) => {
+    const text = readFileSync(join(repoRoot, file), 'utf8');
+    return group.mergeExtends ? text.replace(EXTEND_RE, '$1') : text;
+  });
+  const sdl = parts.join('\n\n');
+  return {
+    name: group.name,
+    schema: buildSchema(sdl, { assumeValidSDL: true, assumeValid: true }),
+  };
+}
+
+export function loadSchemaGroups(
+  groups: readonly SchemaGroupConfig[],
+  repoRoot: string
+): LoadedSchemaGroup[] {
+  if (groups.length === 0) {
+    throw new Error('schema-drift.config.json must declare at least one entry in schemaGroups.');
+  }
+  return groups.map((g) => loadSchemaGroup(g, repoRoot));
+}

package/scripts/graphql-schema-drift/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Config shape for the shared MFE GraphQL schema-drift validator (BOFF-3922).
+ *
+ * One `schema-drift.config.json` lives at the root of a consuming MFE repo.
+ * See README.md in this directory for the full guide and worked examples.
+ */
+
+/**
+ * A named set of schema SDL file(s) that form one validation target.
+ *
+ * A document is considered clean if it validates against **at least one**
+ * configured group (fallback semantics — this is how a repo whose components
+ * legitimately call root fields owned by a different subgraph, e.g. a shared
+ * TagPicker calling wspace-tags-svc fields, can validate against its own
+ * subgraph first and the composed gateway snapshot second).
+ *
+ * Multiple `files` within the SAME group are concatenated into one schema
+ * (this is how a subgraph's base types + a separately-published gateway-roots
+ * extension file are validated as a single schema — see `mergeExtends`).
+ */
+export interface SchemaGroupConfig {
+  /** Human-readable label used only in error output. */
+  name: string;
+  /** SDL file paths, relative to the repo root (the config file's directory). */
+  files: string[];
+  /**
+   * When true, `extend type X` / `extend interface X` in every file of this
+   * group is rewritten to a plain `type X` / `interface X` before the files
+   * are concatenated. Use this when one file declares `extend type Query`
+   * against root fields that only exist in the composed supergraph (not in
+   * the base SDL file itself) — without the rewrite, `buildSchema` would
+   * reject the `extend` because it has nothing to extend.
+   */
+  mergeExtends?: boolean;
+}
+
+/** A directory of `.ts`/`.tsx` source files to scan for inline GraphQL documents. */
+export interface SourceRootConfig {
+  /** Directory path, relative to the repo root. Scanned recursively. */
+  dir: string;
+  /** File extensions to scan. Defaults to `['.ts', '.tsx']`. */
+  extensions?: string[];
+}
+
+export interface SchemaDriftConfig {
+  /**
+   * Directories to scan for inline GraphQL operations — template literals
+   * (optionally `gql`-tagged) whose content starts with `query`, `mutation`,
+   * or `subscription`. This is the primary extraction mode: it is what
+   * catches drift in hand-rolled documents that `graphql-codegen` never sees
+   * because they aren't `.graphql` files on its `documents:` glob.
+   */
+  sourceRoots: SourceRootConfig[];
+  /**
+   * Extra directories of standalone `.graphql`/`.gql` fragment files to
+   * resolve `...FragmentName` spreads against, in addition to any `fragment`
+   * blocks found inline within `sourceRoots` (those are always collected
+   * automatically). Optional — omit if the repo has no separate fragment
+   * files.
+   */
+  fragmentDirs?: string[];
+  /** One or more schema groups. A document must validate against at least one. */
+  schemaGroups: SchemaGroupConfig[];
+  /**
+   * When an inline operation contains an unresolved `${...}` interpolation
+   * (i.e. not a same-file top-level `const NAME = \`...\`` this tool can
+   * expand), fail loudly instead of silently stripping it — a stripped
+   * interpolation can hide the exact selection set that would actually
+   * reveal drift. Defaults to `true`. Only set `false` if a repo has a
+   * verified reason every such interpolation is validation-irrelevant.
+   */
+  treatUnresolvedInterpolationAsError?: boolean;
+}

package/scripts/graphql-schema-drift/validate.ts

@@ -0,0 +1,159 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Kind, parse, validate, type DocumentNode, type FragmentDefinitionNode } from 'graphql';
+import { extractBlocks } from './extract';
+import { safeListFilesRecursive } from './fs-util';
+import { loadFragmentDefinitionsFromDirs, resolveFragments } from './fragments';
+import { loadSchemaGroups } from './schema';
+import type { SchemaDriftConfig } from './types';
+
+export interface DriftError {
+  file: string;
+  index: number;
+  operationName: string | null;
+  messages: string[];
+}
+
+export interface DriftReport {
+  errors: DriftError[];
+  /** Count of operation documents actually validated (fragment-only blocks are not counted). */
+  documentCount: number;
+  fileCount: number;
+}
+
+function getOperationName(doc: DocumentNode): string | null {
+  for (const def of doc.definitions) {
+    if (def.kind === Kind.OPERATION_DEFINITION || def.kind === Kind.FRAGMENT_DEFINITION) {
+      return def.name?.value ?? null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Run the configured extraction + validation pipeline against a repo.
+ *
+ * `repoRoot` is the directory `schema-drift.config.json` lives in — all
+ * paths in the config (`sourceRoots[].dir`, `fragmentDirs`,
+ * `schemaGroups[].files`) are resolved relative to it.
+ */
+export function runValidation(config: SchemaDriftConfig, repoRoot: string): DriftReport {
+  const schemaGroups = loadSchemaGroups(config.schemaGroups, repoRoot);
+  const treatUnresolvedAsError = config.treatUnresolvedInterpolationAsError ?? true;
+
+  // Pass 1: scan every configured source file once, extracting both operation
+  // blocks and inline `fragment` blocks. Inline fragments are pooled globally
+  // (a fragment defined in one file is commonly spread from a hook/component
+  // in another within the same MFE).
+  const sourceFiles: string[] = [];
+  for (const root of config.sourceRoots) {
+    const extensions = root.extensions ?? ['.ts', '.tsx'];
+    sourceFiles.push(...safeListFilesRecursive(join(repoRoot, root.dir), extensions));
+  }
+
+  const inlineFragmentPool = new Map<string, FragmentDefinitionNode>();
+  const pendingOperations: Array<{
+    relFile: string;
+    index: number;
+    source: string;
+    unresolved: string[];
+  }> = [];
+
+  for (const file of sourceFiles) {
+    const relFile = file.slice(repoRoot.length + 1);
+    const text = readFileSync(file, 'utf8');
+    for (const block of extractBlocks(text, relFile)) {
+      if (block.isFragment) {
+        if (block.unresolved.length > 0) continue; // can't parse a fragment with unresolved interpolation; surfaces via any spread that needs it
+        try {
+          const fragDoc = parse(block.source);
+          for (const def of fragDoc.definitions) {
+            if (def.kind === Kind.FRAGMENT_DEFINITION) inlineFragmentPool.set(def.name.value, def);
+          }
+        } catch {
+          // Malformed inline fragment: fall through silently here — if it's
+          // actually spread anywhere, the consuming operation will fail to
+          // resolve the fragment name and be reported as an error there.
+        }
+        continue;
+      }
+      pendingOperations.push({
+        relFile,
+        index: block.index,
+        source: block.source,
+        unresolved: block.unresolved,
+      });
+    }
+  }
+
+  const fileFragmentPool = config.fragmentDirs
+    ? loadFragmentDefinitionsFromDirs(config.fragmentDirs, repoRoot)
+    : new Map<string, FragmentDefinitionNode>();
+  const fragmentPool = new Map<string, FragmentDefinitionNode>([
+    ...fileFragmentPool,
+    ...inlineFragmentPool,
+  ]);
+
+  // Pass 2: parse + resolve fragments + validate every operation block against
+  // every schema group, in order. A document is clean if ANY group accepts it.
+  const errors: DriftError[] = [];
+  let documentCount = 0;
+
+  for (const op of pendingOperations) {
+    documentCount++;
+
+    if (op.unresolved.length > 0 && treatUnresolvedAsError) {
+      errors.push({
+        file: op.relFile,
+        index: op.index,
+        operationName: null,
+        messages: [
+          `Unresolved interpolation(s): ${[...new Set(op.unresolved)].join(', ')}. Define them as ` +
+            `top-level backtick string constants in the same file so this operation can be validated, ` +
+            `or set "treatUnresolvedInterpolationAsError": false in schema-drift.config.json if this is ` +
+            `verified to be validation-irrelevant.`,
+        ],
+      });
+      continue;
+    }
+
+    let doc: DocumentNode;
+    try {
+      doc = parse(op.source);
+    } catch (e) {
+      errors.push({
+        file: op.relFile,
+        index: op.index,
+        operationName: null,
+        messages: [`Parse error: ${(e as Error).message}`],
+      });
+      continue;
+    }
+
+    const resolvedDoc = resolveFragments(doc, fragmentPool);
+
+    let bestErrors: string[] | null = null;
+    let passed = false;
+    for (const group of schemaGroups) {
+      const groupErrors = validate(group.schema, resolvedDoc);
+      if (groupErrors.length === 0) {
+        passed = true;
+        break;
+      }
+      // Report the FIRST group's errors as the actionable ones if nothing passes —
+      // it's the group most likely to be this document's "home" schema.
+      if (bestErrors === null) bestErrors = groupErrors.map((e) => e.message);
+    }
+
+    if (!passed) {
+      errors.push({
+        file: op.relFile,
+        index: op.index,
+        operationName: getOperationName(doc),
+        messages: bestErrors ?? ['No schema group accepted this document.'],
+      });
+    }
+  }
+
+  return { errors, documentCount, fileCount: sourceFiles.length };
+}