refactor(consumer-typecheck): consolidate 3 snapshot scripts into one CLI (SD-3213b)

.github/workflows/ci-superdoc.yml

@@ -154,22 +154,17 @@ jobs:
         # ESM, missing CDN files, unpublished `source` paths.
         run: node tests/consumer-typecheck/package-shape-gate.mjs
 
-      - name: Legacy public no-growth gates (SD-3176)
-        # No-growth snapshots for the legacy public compatibility surfaces.
-        # See tests/consumer-typecheck/snapshots/README.md for the policy.
-        # Runs after the matrix step so the packed-and-installed fixture
-        # is available for Snapshot B (resolved named exports).
-        run: |
-          node tests/consumer-typecheck/snapshot-super-editor-package-exports.mjs --check
-          node tests/consumer-typecheck/snapshot-superdoc-legacy-exports.mjs --check
-
-      - name: Root no-growth + 4-source inventory (SD-3212 PR A0)
-        # The superdoc root entry resolves through four package.json#exports
-        # sources (types.import, types.require, import, require). Each is
-        # snapshotted separately and drift-gated. Cross-source mismatches
-        # (typed-only / runtime-only / ESM vs CJS) are reported in the
-        # companion .md but are not blockers on their own.
-        run: node tests/consumer-typecheck/snapshot-superdoc-root-exports.mjs --check
+      - name: Public surface no-growth snapshots (SD-3176, SD-3212)
+        # Unified entry point for the three snapshot families:
+        #   - super-editor-package: @superdoc/super-editor package.json#exports keys
+        #   - legacy: resolved exports for superdoc/* legacy subpaths
+        #   - root: 4-source inventory (types.import, types.require, import,
+        #     require) for the superdoc root entry. Cross-source mismatches
+        #     are reported in the companion .md but are not blockers on their
+        #     own.
+        # Runs after the matrix step so the packed-and-installed fixture is
+        # available. See tests/consumer-typecheck/snapshots/README.md.
+        run: node tests/consumer-typecheck/snapshot.mjs --all --check
 
       - name: Root classification closure gate (SD-3212 PR A1b)
         # Asserts the dependency-closure rule from the A1 classification:

.github/workflows/release-stable.yml

@@ -127,13 +127,10 @@ jobs:
       - name: Package shape gates
         run: node tests/consumer-typecheck/package-shape-gate.mjs
 
-      - name: Legacy public no-growth gates (SD-3176)
-        run: |
-          node tests/consumer-typecheck/snapshot-super-editor-package-exports.mjs --check
-          node tests/consumer-typecheck/snapshot-superdoc-legacy-exports.mjs --check
-
-      - name: Root no-growth + 4-source inventory (SD-3212 PR A0)
-        run: node tests/consumer-typecheck/snapshot-superdoc-root-exports.mjs --check
+      - name: Public surface no-growth snapshots (SD-3176, SD-3212)
+        # Unified entry point for all three snapshot families
+        # (super-editor-package, legacy, root). Same gate as PR CI.
+        run: node tests/consumer-typecheck/snapshot.mjs --all --check
 
       - name: Root classification closure gate (SD-3212 PR A1b)
         run: node tests/consumer-typecheck/check-root-classification-closure.mjs

.github/workflows/release-superdoc.yml

@@ -149,15 +149,11 @@ jobs:
         # the packed tarball. Same step as PR CI.
         run: node tests/consumer-typecheck/package-shape-gate.mjs
 
-      - name: Legacy public no-growth gates (SD-3176)
+      - name: Public surface no-growth snapshots (SD-3176, SD-3212)
         # Same gate as PR CI. Catches releases that bypass PR CI.
-        run: |
-          node tests/consumer-typecheck/snapshot-super-editor-package-exports.mjs --check
-          node tests/consumer-typecheck/snapshot-superdoc-legacy-exports.mjs --check
-
-      - name: Root no-growth + 4-source inventory (SD-3212 PR A0)
-        # Same gate as PR CI. Catches releases that bypass PR CI.
-        run: node tests/consumer-typecheck/snapshot-superdoc-root-exports.mjs --check
+        # Runs the unified entry point for all three snapshot families
+        # (super-editor-package, legacy, root).
+        run: node tests/consumer-typecheck/snapshot.mjs --all --check
 
       - name: Root classification closure gate (SD-3212 PR A1b)
         # Same gate as PR CI. Catches releases that bypass PR CI.

CONTRIBUTING.md

@@ -233,7 +233,7 @@ If your PR adds a new public export from `superdoc` (a new entry in `packages/su
 The canonical root contract is `packages/superdoc/src/public/index.ts` (per the SD-3175 path-as-contract umbrella, finalized in SD-3212 PR C). Several automated gates enforce consistency on every PR:
 
 - **`verify-public-facade-emit.cjs`** -- verifies the curated `src/public/**` facade matches the emitted `.d.ts` for symbol set, ESM/CJS parity, leak grep, and command-signature compatibility. Adding a new export updates the corresponding `expectedNames` array in this script in the same PR.
-- **`snapshot-superdoc-root-exports.mjs --check`** -- locks the root export inventory across the four `package.json#exports` sources (`types.import`, `types.require`, `import`, `require`). Drift fails CI; run with `--write` to regenerate after an intentional change.
+- **`snapshot.mjs --all --check`** -- unified entry point for the three snapshot families. The `root` family locks the root export inventory across the four `package.json#exports` sources (`types.import`, `types.require`, `import`, `require`); the `legacy` family locks `superdoc/*` subpath resolved exports; the `super-editor-package` family locks `@superdoc/super-editor`'s `package.json#exports` keys. Drift fails CI; run `snapshot.mjs --family <name> --write` to regenerate one family after an intentional change.
 - **`check-root-classification-closure.mjs`** -- enforces the dependency-closure rule: no `supported-root` or `legacy-root` export may reference an `internal-candidate` type in its declared public type. New exports require an entry in `tests/consumer-typecheck/snapshots/superdoc-root-classification.json`.
 - **`typecheck-matrix.mjs`** -- every typed public subpath has at least one matrix scenario. If you add a new subpath, add a fixture under `tests/consumer-typecheck/src/` and a corresponding entry in the matrix, and update the inventory in `docs/architecture/package-boundaries.md`.
 - **`check-all-public-types-fixture.mjs`** -- derives the expected type-only root export list from `superdoc-root-classification.json` (rows with `inDts && !inEsm && !inCjs`) and fails if `src/all-public-types.ts` is missing assertions or has stale ones. Runs before the matrix to catch fixture drift early.

packages/superdoc/AGENTS.md

@@ -255,7 +255,7 @@ When changing the surface, every PR must also update:
 Three CI gates enforce consistency and will fail the build if any of these drift:
 
 - `verify-public-facade-emit.cjs` — symbol set, ESM/CJS parity, leak grep.
-- `snapshot-superdoc-root-exports.mjs --check` — 4-source no-growth lock.
+- `snapshot.mjs --family root --check` — 4-source no-growth lock for the root entry. CI calls `snapshot.mjs --all --check`, which also runs `legacy` and `super-editor-package`.
 - `check-root-classification-closure.mjs` — no supported/legacy export references an internal-candidate type (dependency-closure rule).
 
 For overrides on the closure gate (rare; only DOM globals / upstream / generic utility types), add an entry to `OVERRIDES` in `check-root-classification-closure.mjs` with a reason string ≥ 20 chars.

tests/consumer-typecheck/deep-type-audit.README.md

@@ -165,13 +165,14 @@ default `auto-seeded from inventory` rationale.
 - `typecheck-matrix.mjs`: runs `tsc --noEmit` under N consumer tsconfigs.
   Catches *resolution* errors and *missing exports*. Doesn't see member-level
   `any`.
-- `snapshot-superdoc-root-exports.mjs --check`: locks the root export
-  inventory across the four `package.json#exports` sources independently
-  (types.import, types.require, import, require). Each source has its
-  own baseline — type sources currently 200 names, runtime sources 41 —
-  and drift on any of the four fails the gate. Cross-source mismatches
-  (typed-only, runtime-only, ESM vs CJS) are reported in the companion
-  `.md` as evidence, not blockers.
+- `snapshot.mjs --family root --check`: locks the root export inventory
+  across the four `package.json#exports` sources independently (types.import,
+  types.require, import, require). Each source has its own baseline (type
+  sources currently 200 names, runtime sources 41) and drift on any of the
+  four fails the gate. Cross-source mismatches (typed-only, runtime-only,
+  ESM vs CJS) are reported in the companion `.md` as evidence, not blockers.
+  CI calls the unified `snapshot.mjs --all --check` which runs this family
+  plus the `legacy` and `super-editor-package` families.
 - `verify-public-facade-emit.cjs`: verifies the curated `src/public/**`
   facade matches the emitted `.d.ts` (symbol set, ESM/CJS parity, leak
   grep, command-signature probe).