test(hygiene): declare the source-hygiene gate's scan surface once

[os-trump]

Fixes #1314

The three sandbox suites that run scripts/check-source-hygiene.mjs each
declared their own hand-copied copy of the gate's three surface constants, and
nothing checked any copy against the gate. They now import all three from one
producer, scripts/lib/source-hygiene-surface.mjs.

Measured on 49bd297.

Route taken, decided against the current tree

Route 1, in its sibling-module form — the card's own "export the constants
from the gate, or a tiny sibling module the gate imports".

The cost that used to rule route 1 out is gone, as the dispatch note says:
#1321 landed allowJs repo-wide and test/source-token-ratchet.test.ts already
imports constants from a gate .mjs under strict with tsc --noEmit green.
So the choice was never TS7016 — it is top-level side effects, and that is
what decided it:

• check-source-hygiene.mjs runs its five checks at module top level and calls
  process.exit(1). A suite that imported it would run the whole gate over
  the real repo at import time and could take a vitest worker down with it.
• Making that safe means wrapping ~90 lines of top-level statements in a
  main() behind isMainModule() — which re-indents the banner line. That
  line is The hygiene banner binds the wrong count to the marker and header checks — it says 339 + 3 where those checks read allTs = 329, and two cards this round were told to trust that line as the producer #1339's, serialised behind this card on this same file, so this PR
  must not move it. Confirmed untouched: git diff contains zero occurrences of
  codeFiles.length.
• A data module with no top-level side effects is importable by
  construction: no guard to get wrong (scripts/lib/main-module.mjs exists
  because that comparison was hand-rolled wrong twice, The source-token-ratchet gate silently no-ops (and exits 0) when invoked through a symlinked path — 10 of its own tests fail on every macOS checkout #1252), no output, no
  exit, and the gate's executable body is untouched.

Routes 2 and 3 were rejected against this same tree: a source parser (2) is a
maintenance surface the card itself flags, and a --print-surface flag (3)
would add a test-only seam to production tooling and still need a parser on the
reading side. Neither buys anything over an import that already typechecks.

⛔ The gate is still runnable as bare node scripts/check-source-hygiene.mjs
with no build step, which is how both workflows invoke it. Verified directly.

No surface moved

The three lists were moved byte-for-byte, doc comments included; the only
textual change is the export keyword on three const lines. Proved by
diffing the extracted region against HEAD:

git show HEAD:scripts/check-source-hygiene.mjs | sed -n '510,638p'   vs
scripts/lib/source-hygiene-surface.mjs (export stripped)   ->  identical

The gate's banner reports the same surface before and after: 3 root .ts files,
16 root files, the same five text trees.

Acceptance: the load-bearing proof, not a green suite

All three suites are green today with hand-copied lists, so today's green proves
nothing. Both directions were mutated on origin/main (control, 08613ad) and on
this branch (treatment). Every mutation was proved on disk by blob hash before
any verdict was read, restored with git checkout HEAD -- PATH, and the restore
proved by an empty git diff HEAD; every anchor was match-counted first, so a
zero-match no-op could not be read as green.

mutation of the gate's real list	origin/main — hand-copied	this branch — derived
ADD a 4th root .ts	all 3 suites RED, every failure reading scanned root file(s) missing: eslint.config.ts	all 3 green, and the suite grows a case: 53 to 54 tests — the new file automatically gets its own control-byte case
REMOVE a root .ts	scan-surface RED; size-advisory GREEN, header-position GREEN — both went on materialising a file the gate no longer reads	mirrors follow: scan-surface 31 to 30 cases; the single red is DOES extend the marker and header checks to the root .ts files (#1236), which names vitest.config.ts literally — red naming the drift, which is the acceptance's second branch
ADD a 5th tree to SCANNED	(same shape as row 1)	all 3 green, 53 tests — including this PR's newly derived ${CODE_TREES.length} violation(s) assertion

⚠️ The card's premise needs one correction

The card says an added root .ts "leaves all three suites still green while
silently not exercising the new file", and that the gate's missing-file guard
"cannot fire on this". Measured, that is not what happens in the ADD
direction. In a sandbox, a stale mirror means the file is genuinely absent
from disk, which is exactly what that guard fires on — so all three suites went
red, loudly. What was wrong with it was the message: it names a missing
fixture, sending the reader to create a file, rather than saying a mirror is
stale.

The genuinely silent direction is removal, and it is two suites of three,
not three: dropping a root .ts from the gate's list left size-advisory and
header-position green while both kept materialising a file the gate no longer
reads. scan-surface caught it only by accident of asserting the banner's root
count.

The card is still worth doing, and the fix is unchanged — this only narrows the
claim it rests on.

Notes

• The third suite's REQUIRED_TREES / REQUIRED_ROOT_FILES naming is kept —
  those names say what that file needs the lists for. Only the values derive
  now. REQUIRED_TREES is [...SCANNED, ...TEXT_SCANNED], which is what it
  always was by hand.
• Each suite gains a one-element GATE_DEPENDENCIES, matching
  test/source-token-ratchet.test.ts:77 one file away. It is hand-maintained
  and safe to be: an import the sandbox does not carry makes the spawned gate
  die with ERR_MODULE_NOT_FOUND and takes every case in the file with it, so
  it cannot rot quietly.
• ROOT_EXCLUDED_FILES (the two lock files) stays hand-written on purpose — it
  is an anti-list, pinning files deliberately absent from the gate's
  constants, so there is nothing to derive it from.
• Changeset has empty frontmatter: tooling and tests only, nothing published.

Verification

pnpm verify green end to end on this tree, quoting each gate's own verdict line:

✓ i18n lint gate: 0 `i18n/missing-*` issues
Source hygiene — 340 files under src, test, e2e, scripts, plus 3 root .ts file(s)
  in the marker and header checks; the control-byte scan adds 348 under
  content, .changeset, docs, .github, .claude and 16 root file(s)
✓ source hygiene clean
✓ source token ratchet clean
✓ Build complete (1552ms)
Test Files  142 passed (142)
Tests  2997 passed | 1 skipped (2998)

Re-run on the final commit 49bd297: pnpm hygiene exit 0, pnpm hygiene:tokens
exit 0, pnpm typecheck exit 0, and the six directly adjacent suites
(three hygiene suites, script-main-guard, source-token-ratchet,
verify-log-decoy-pin) 86 passed. tsc --noEmit --listFiles confirms the new
.mjs is genuinely in the typecheck program rather than silently excluded.

Generated by Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Aug 27, 2026 2:01am