fix(scripts): six source-scanning gates share one string-aware comment masker

[os-steve]

Fixes#9367

Six source-scanning gates each carried a private stripComments. They now share one
string-, template- and regex-aware scanner in scripts/js-comment-mask.mjs.

What the card assumed, and what measuring found

The card lists six gates "using the vulnerable spelling". Re-derived from the source on
51a46a440, they are not one defect — they are two, failing in opposite directions:

gate	old mechanism	failure direction
check-dispatcher-error-vocabulary.mjs	naive regex	blinds
check-error-code-casing.mjs	naive regex (blanking)	blinds (+ fabricates after a colon)
check-platform-checklist.mjs	naive regex, inline on a slice	blinds
check-error-status-conformance.mjs	char scanner, regex-blind	fabricates
check-examples-live-imports.mjs	char scanner, regex-blind	fabricates
check-test-source-alias.mjs	char scanner + regex, keyword-blind	fabricates

The three the card describes are string-blind, so a /* in a glob or route wildcard, or a
// in a URL, opens a phantom comment that deletes real code. The other three already
track strings — the card's prose is stale for them. Their bug is the mirror image: a regex
literal whose class holds a quote character opens a phantom string, and because a
scanner skips string spans, comments inside one are never removed. Those gates read
commented-out text as live code.

All six are defective; none was already fixed. check-test-source-alias.mjs was closest —
it knew about regex literals, but decided regex-vs-division from the preceding character
alone, which misses the keyword forms -- a regex literal opening right after
return or case, whose character class holds a backtick.

Reachability, per gate — two are latent

Each gate's own strip was run against its own real corpus and diffed against the shared
scanner:

gate	corpus	files where the two disagree
check-dispatcher-error-vocabulary	1852	200
check-error-code-casing	4196	196
check-examples-live-imports	2050	58
check-error-status-conformance	1837	26
check-platform-checklist	8 pinned enum slices	0 — latent
check-test-source-alias	34 vitest configs	0 — latent

So the hazard is live for four gates and latent for two. For check-platform-checklist
all eight pinned enum slices extract an identical member list either way; the earlier
whole-file difference does not reach what the gate actually reads.

The verification that matters

A green run over today's corpus proves only that today's corpus lacks the shape, so each
gate was driven end to end against a planted fixture, once with the new script and once
with the original from 51a46a440:

gate	OLD + fixture	NEW + fixture	direction proven
check-error-code-casing	exit 0 — reports clean	exit 1 — catches it	blinds
check-dispatcher-error-vocabulary	exit 0 — "12 sites, all classified"	exit 1	blinds
check-error-status-conformance	exit 1 — "can emit HTTP 599"	exit 0	fabricates
check-examples-live-imports	exit 1 — demands a registry entry	exit 0	fabricates
check-test-source-alias	exit 1	exit 0	fabricates
check-platform-checklist	exit 1 — "VARIANTS STALE"	exit 0	mis-parse

Every OLD failure above is manufactured out of, or hidden by, a comment. The two
fabrication rows are the sharper result: the old gate fails on source that is correct.

The shapes themselves are pinned as self-test cases in the shared module (15 cases,
node scripts/js-comment-mask.mjs --self-test), driven through both projections, and
each case is valid JavaScript so the expected answer is the language's, not an
implementation's. An earlier draft case was discarded because the reference disagreed with
it — a * + / inside a docblock genuinely does close the comment.

Why the helper moved instead of being imported

The card proposes importing maskComments from scripts/pm/dispatch-gates.mjs. That does
not work: the module runs CLI code at import and calls process.exit(2), so any gate
importing it dies with a usage error. The scanner moved to scripts/js-comment-mask.mjs
with no import-time side effect; dispatch-gates.mjs re-exports maskComments, so its own
260-case self-test still drives the shared masker rather than a copy.

Two projections, and a 51x regression that measuring caught

maskComments blanks comment spans (offsets and line numbers survive). stripComments
deletes the characters but keeps newlines (line numbers survive, offsets do not).

This split is not tidiness. Converting check-test-source-alias.mjs to the blanking
projection alone took it from 6.4s to 5m27s — same verdict, 51x the cost. Its import
matcher is lazy ((?:import|export)\s+([\s\S]*?)\s*from), and a lazy [\s\S]*? dragged
across the whitespace blanking leaves behind is quadratic in the comment bytes. On the
deleting projection it is back to 6.7s. Gates that report a line or an offset take
maskComments; gates that report neither take stripComments.

Scope

Only the six gates the card names, plus the shared module and the dispatch-gates.mjs
re-export the move requires. scripts/docs-audit/affected-docs.mjs is not touched — PR
#9394 holds it. No seventh gate was swept. One more script does carry the same defect class --
scripts/check-org-identifier.mjs truncates each line at the first double slash, so a URL on
that line hides the read it looks for -- and per the card's rulings it is reported, not fixed:
filed as #9444.

Note check:platform-checklist is not a CI gate — lint.yml runs it by maintainer decision,
on demand — so that gate's change is covered by the local run below, not by this PR's checks.

Gates run locally, on 9083e1c75

check:dispatcher-error-vocabulary, check:error-code-casing,
check:error-status-conformance, check:examples-live-imports, check:test-source-alias,
check:pm-dispatch-gates, check:platform-checklist, check:nul-bytes — all exit 0, plus
node scripts/js-comment-mask.mjs --self-test (15 cases). Families re-derived from the
actual changed paths with node scripts/pm/dispatch-gates.mjs.

No changeset: root scripts/ only, nothing published.

Generated by Claude Code

---

Generated by Claude Code