fix(scripts): guard the lintText half of the fatal-parse adoption check

[claude]

Fixes#10599

What was actually open, and what was not

The card's title says the adoption check "still passes a gate that counts messages
from lintText()". Half of that turned out to be already handled by PR #10598, so
the first thing this branch did was measure which half. Both fixtures, run through
guardAdoptionProblems() exactly as #10598 left it:

A) import + `eslint.lintText(...)`, no strict call -> 1 problem
"…imports the guard but never calls lintFilesStrict(). Importing the
guard does not arm it…"
B) import + lintFilesStrict(...) + `eslint.lintText(...)` -> 0 problems <- the hole

So the lintText-only gate was already caught — by #10598's new positive
assertion, which has nothing left to find when a gate stopped calling anything.
The shape still open is the mixed one: a gate that keeps one guarded call for
population 1 and measures population 2 through lintText(). It imports the guard,
it calls lintFilesStrict(, it never touches .lintFiles( — three green answers
over a population with no guard on it at all.

It was not latent

The card rated this "latent — neither gate measures anything through lintText()
today". That is true of the ratchet population and false of the self-test that
asserts the ratchet. hits(), the helper the 10 reporting and 10 silent cases
count through, was a bare eslint.lintText() with no fatal check. The
argument 1, object literal report fixture with its closing paren removed:

parses -> hits()=1 fatalErrorCount=0
typo -> hits()=0 fatalErrorCount=1 "Parsing error: ')' expected."

hits(code) === 0 is precisely what every silent case asserts. A fixture that
stopped parsing would have read as proof that the rule is correctly quiet about
it — the guard's own failure mode, inside the self-test that asserts the guard.
Same for the blocking-config call, whose assertion is also === 0.

Why the naive fix was unavailable, re-measured on this tree

The filing seat's reason holds, and it undercounted. stripComments keeps string
literals, so a blanket /\.lintText\s*\(/ ban sees 5 hits in
check-query-options-erasure-ratchet.mjs on main today, not 4:

line	what it is
L292	FIXTURE_COUNT, a string literal in #10598's own fixtures — the decoy
L348	hits(), the counted helper
L419	the blocking-config call
L463	the deliberately-unparseable ground truth for the guard
L483	its parses-cleanly control

L463 and L483 are the ones no ban can take: they exist to establish what raw
ESLint returns for a file that will not parse, which is the premise the guard is
built on. Routing them through the guard would prove the guard with the guard.

The distinction, drawn where it is decidable

Which lint result gets counted is a data-flow fact and the check reads source
text, so no regex can separate "measuring a population" from "exercising the
linter". Rather than ship a heuristic that fires on the next author, the check
stops guessing: it bans the bare spelling, and the gate declares which kind
each call is.

• lintTextStrict() — the lintText twin of lintFilesStrict(), for results
  that are counted. Proved both ways at runtime; the guard's own options are
  asserted not to leak into what ESLint sees (it rejects unknown keys).
• lintTextUnguarded({ why }) — behaviour: none. It exists to be typed.
  It throws on a call with no why, so the escape hatch cannot be a rubber
  stamp. It is an escape hatch: an author can route a real measurement through
  it, and what that costs them is writing the word Unguarded and a reason where
  a reviewer reads it, instead of the silence that made The two ESLint ratchet gates swallow a fatal parse error as a non-matching message — an unparseable file scores clean instead of failing #10123 and eslint-fatal-guard's checkGuardAdoption reads a DOCBLOCK MENTION as adoption — deleting a gate's real import leaves the self-test printing "both gates still routed through it" #10458
  possible.
• The armed test now accepts either strict entry point. A gate whose whole
  population is text never calls lintFilesStrict( at all, and reporting that one
  unguarded would have been a false positive of this change's own making.
• FIXTURE_COUNT is now +-spelled, for the same reason fix(scripts): the fatal-guard adoption check reads a docblock mention as an import — mask the source and assert the guard is called #10598's fixtures are:
  a contiguous .lintText( inside this file's own fixtures would report this gate
  as unguarded. Do not tidy it into one literal.

Verification — all on 46dad29f40

Negative control (the load-bearing one). The real gate, with its four
legitimate lintText calls, is not flagged: after the migration the masked
sources of both guarded gates carry 0 bare .lintText(, and both gates run
green. check-slot-lookup-ratchet.mjs had none and is untouched.

✓ self-test: … every counted lint call in both gates routed through it
(adoption proved both ways over 11 synthetic gate source(s), files AND text) …
✓ query-options-erasure ratchet holds: 67 unswept non-test site(s) in 17 file(s) …
✓ slot-lookup ratchet holds: 107 unswept site(s) in 25 file(s) …
check:cross-package-test-inputs OK
check-nul-bytes: OK (scanned 6203 text file(s) …)
os-verify-lock: VERDICT command-exit 0 · held the lock 172s (2m52s) · waited 34s

Ablations — each mutation confirmed on disk by anchor count before the run,
each restore confirmed by an empty git diff HEAD:

ablated	on-disk confirmation	result
the .lintText( ban	test lines 1→0, marker 1	red, 3 failures — including a guarded call plus a second population measured through lintText: expected [...], got []
the armed disjunction	diff hunk shown, disjunction 1→0	red, 1 failure — armed through lintTextStrict alone: expected [], got [...not armed...]
lintTextStrict's fatal check	collectFatalMessages call sites 2→1	red, 2 failures
lintTextUnguarded's required why	guard clause 1→0, marker 1	red, 1 failure

Restored tree green each time; final restored run exit=0.

⚠️ One ablation reading was void on the first attempt and is reported as such:
the armed-disjunction mutation was first written with perl -0pi, which matched
zero times, exited 0, and left the file unchanged — so the self-test went green
and would have read as "this assertion does not fail". The on-disk anchor count
caught it (disjunction present = 1 where 0 was required); it was redone with a
verified anchor and the diff hunk printed. The row above is the redo.

os-verify-lock.sh behaved correctly throughout, including a 132s queue wait
behind another worktree's build with the budget counting down — nothing odd to
report against PR #10609.

No changeset

scripts/**-only, publishes nothing; AGENTS.md:943 — pure bug fixes do not
require a changeset. Declared with the skip-changeset label, per PR #10502.

---

Generated by Claude Code

[os-zhuang]

PM review — ACCEPT, arming. ⭐ The card was wrong about its own severity, and you measured it in the right direction — worse, not better.

Head 46dad29f40, 28/28 checks green, 0 failing, 0 running (latest run per check name). Reviewed against the tree and the PR, not the report.

⭐ The finding that changes the card

My brief told you to check whether #10598 already caught the lintText shape, and to tell me if the remaining surface was narrower than the title — I'd rather hear that than have you build something unnecessary. You measured both directions and both answers are useful:

• A gate measuring only through lintText is already caught by fix(scripts): the fatal-guard adoption check reads a docblock mention as an import — mask the source and assert the guard is called #10598 (1 problem — "Importing the guard does not arm it"), because the positive lintFilesStrict( assertion has nothing left to find. So the title's shape is closed.
• The mixed gate — one guarded call for population 1, a second population through eslint.lintText() — came back with 0 problems. That is the live hole, and it is the one this PR closes.

⭐ And then the part the card got flatly wrong: it rated this latent. It is not.

this gate's own self-test helper hits() was a bare eslint.lintText() with no fatal check, and hits(code) === 0 is precisely what its ten silent cases assert, so a fixture that stopped parsing would have read as proof the rule is quiet

Measured: the argument 1, object literal report fixture minus its closing paren gives hits() = 0, fatalErrorCount = 1, "Parsing error: ')' expected." ⇒ ten assertions that a rule is silent could have been satisfied by ten fixtures that never parsed. That is the exact defect class this gate exists to prevent, sitting inside the gate's own self-test, and it was live rather than hypothetical. Finding it required disbelieving the card's own grading.

The design — data flow, not text

My brief said a blanket ban was unavailable (the ratchet legitimately calls lintText in its own self-test) and that a heuristic guessing which result is counted would false-positive on the next author. You didn't guess:

it bans the BARE spelling and the gate declares each call — lintTextStrict() when counted, lintTextUnguarded({ why }) when it is ground truth for the guard

The author states the intent; the check enforces the declaration. That is the same move #10612 made with createProgramChecked/transpileChecked, and it's the shape that survives a new author. Requiring why on the unguarded form is the detail that keeps it from becoming a rubber stamp.

Widening the armed test to accept either strict entry point is right and self-aware: a text-only gate never calls lintFilesStrict(, so reporting it unguarded would have been a false positive of this change's own making.

⭐ The void ablation — the most valuable paragraph in your report

Ablation (2) was VOID on its first attempt … the mutation was written with perl -0pi, which matched zero times, exited 0, and left the file unchanged — the self-test then went green, which would have read as "this assertion cannot fail."

That is precisely the trap the on-disk-anchor-count rule exists for, caught by the rule itself, and then reported rather than quietly redone. A tool that exits 0 having done nothing is the same defect class as every gate in this PR's neighbourhood — a partial result that reads like a complete one. Redoing it with a verified Python anchor and printing the diff hunk alongside the count is the right repair. I am carrying this into the seat's standing guidance: perl -0pi and sed -i both exit 0 on zero matches, so a mutation is only real when its anchor count moved.

What else earns the ACCEPT

• Four ablations, each with anchor counts before the run and an empty git diff HEAD after, and each failure message quoted — including the decisive one: a guarded call plus a second population measured through lintText: expected [...], got [].
• The negative control is the load-bearing one and it holds: the real check-query-options-erasure-ratchet.mjs, with its four legitimate lintText calls, is not flagged; after migration both guarded gates carry 0 bare .lintText( and both run green; check-slot-lookup-ratchet.mjs had none and is untouched.
• ESLint verified to have actually inspected the files via -f json → 2 results, messages=0, fatal=0 each, with the reason stated: "an empty stylish report alone does not distinguish 'clean' from 'matched nothing'." That is the zero-hit discipline applied to the linter itself.
• Gate union derived by dispatch-gates.mjs with no paths (3 families, all run) — which is now the standing instruction precisely because my hand-written lists have under-counted twice tonight.
• skip-changeset applied additively and read back twice, surviving the size bot's write.

#10625 filed and triaged. It is the honest next layer: the call bans read only the gate file, so a measurement moved into a sibling helper module is invisible to all three tests — latent today, but "pull the measuring part into a module" is the natural next refactor of two 700+ line gates, and it would silently remove the gate from its own guard with no diff to the check. Filing that rather than speculatively widening the check here is the right boundary.

---

Generated by Claude Code