Found while closing #15487 (PR #15532), which added declarations to
scripts/js-comment-mask.d.mts and therefore had to read it in full. Out of scope
there: that card's scope is the duplicated regex recogniser.
What was measured
scripts/js-comment-mask.d.mts declares:
export function selfTest(): void;
with the JSDoc "Returns nothing: a failing case calls process.exit(1) rather than
reporting a value, so there is no verdict for a caller to forget to read."
The module has not behaved that way since #13798. It returns a verdict sentinel, and
its own CLI dispatch depends on the returned value:
scripts/js-comment-mask.mjs
const SELF_TEST_VERDICT = 'js-comment-mask self-test reached its verdict';
...
return SELF_TEST_VERDICT;
...
if (selfTest() !== SELF_TEST_VERDICT) {
... 'selfTest() returned without reaching its verdict,'
... 'so no success line was printed. Exiting 0 here would report a self-test'
... 'that never finished as a self-test that passed.'
process.exit(1);
}
So the declaration says the exact opposite of what the module does, and the sentence
it says it with — "there is no verdict for a caller to forget to read" — is the
sentence #13798 exists to refute.
Why it is worth a card rather than a silent edit
This is the same failure shape as #15398 (SourceFlags omits the interpolation
array scanSource has returned since #11838), in the same hand-written declaration,
and #15398 is open and covers only scanSource. The two are adjacent but not the
same field, so this is filed rather than folded in — a maintainer may well want to
close both with one pass over the file, and that is a triage decision.
The cost is the one that file's own header names: the declaration is the surface every
TYPE-CHECKED consumer sees, because packages/spec/scripts/ is inside a tsc program
where an untyped .mjs import is TS7016. A gate there that wanted to reproduce the
selfTest() verdict check — the guard against a self-test reporting success without
running — reads void, is told there is no value, and reasonably writes the weaker
selfTest(); // trust the exit code instead. That is precisely the shape #13798
measured and closed.
Suggested fix
Declare the sentinel and the return type, and delete the JSDoc sentence that
contradicts it. scripts/js-comment-mask.d.mts carries the instruction "Keep this
file in step with the module by hand", so the repair belongs there.
Unassigned and unlabeled, for triage.
Generated by Claude Code
Found while closing #15487 (PR #15532), which added declarations to
scripts/js-comment-mask.d.mtsand therefore had to read it in full. Out of scopethere: that card's scope is the duplicated regex recogniser.
What was measured
scripts/js-comment-mask.d.mtsdeclares:with the JSDoc "Returns nothing: a failing case calls
process.exit(1)rather thanreporting a value, so there is no verdict for a caller to forget to read."
The module has not behaved that way since #13798. It returns a verdict sentinel, and
its own CLI dispatch depends on the returned value:
So the declaration says the exact opposite of what the module does, and the sentence
it says it with — "there is no verdict for a caller to forget to read" — is the
sentence #13798 exists to refute.
Why it is worth a card rather than a silent edit
This is the same failure shape as #15398 (
SourceFlagsomits theinterpolationarray
scanSourcehas returned since #11838), in the same hand-written declaration,and #15398 is open and covers only
scanSource. The two are adjacent but not thesame field, so this is filed rather than folded in — a maintainer may well want to
close both with one pass over the file, and that is a triage decision.
The cost is the one that file's own header names: the declaration is the surface every
TYPE-CHECKED consumer sees, because
packages/spec/scripts/is inside a tsc programwhere an untyped
.mjsimport is TS7016. A gate there that wanted to reproduce theselfTest()verdict check — the guard against a self-test reporting success withoutrunning — reads
void, is told there is no value, and reasonably writes the weakerselfTest(); // trust the exit codeinstead. That is precisely the shape #13798measured and closed.
Suggested fix
Declare the sentinel and the return type, and delete the JSDoc sentence that
contradicts it.
scripts/js-comment-mask.d.mtscarries the instruction "Keep thisfile in step with the module by hand", so the repair belongs there.
Unassigned and unlabeled, for triage.
Generated by Claude Code