Found while fixing #10427. Filed unassigned, no pm:queue.
The gap
scripts/js-comment-mask.mjs is described in this tree as "the ONE answer" to comment-vs-code, and #10427 established that its --self-test cases are the contract. That fix also established that the self-test is the weaker of the two instruments available, and the stronger one does not exist in the tree.
The instrument that found #10427 was a corpus sweep: parse every .{ts,tsx,mts,cts,js,mjs,cjs,jsx} file in the repo with @typescript-eslint/parser (already a root dependency), and diff the comment ranges it reports against scanSource's comment array byte for byte. On the tree at the time it named 16 disagreeing files, 15 of them in the FABRICATES direction, up to 10,252 comment bytes in one file. Nothing in scripts/, package.json or .github/workflows/ can re-derive that today — the sweep lived in an agent's scratchpad and left with it.
Why the self-test alone does not cover it
Measured during #10427, and the reason this is worth a card rather than a note. A mutation that deleted the { counting inside ${...} passed all 22 pinned cases and the entire 4,739-file sweep — the tree simply does not write that shape today. The case that now holds it (${fmt({ a: 1 }, \\``)}`) had to be written from the mutation, not from the corpus.
That is the general shape: the self-test pins shapes someone thought of, the sweep finds shapes the tree actually contains, and neither subsumes the other. The module's header now describes the sweep in prose so it can be reconstructed, which is a weaker guarantee than running it.
Note on scope
This is not a duplicate of #10608 (that card is about --self-test entry points, this module's included, running in no workflow — a wiring gap for tests that already exist). This card is about a verification that does not exist in the tree in any form, wired or not. #10608 is the prerequisite in practice: wiring a sweep is pointless while the cheap self-test beside it still runs nowhere.
Worth deciding rather than assuming: a full-corpus parse of ~4,700 files costs real CI time (the sweep took roughly a minute locally), so it may belong on a schedule or a scripts/**-triggered lane rather than every PR — or as an on-demand --sweep flag on the module that a human runs after touching scanSource, which is what its header currently asks for.
Generated by Claude Code
Found while fixing #10427. Filed unassigned, no
pm:queue.The gap
scripts/js-comment-mask.mjsis described in this tree as "the ONE answer" to comment-vs-code, and #10427 established that its--self-testcases are the contract. That fix also established that the self-test is the weaker of the two instruments available, and the stronger one does not exist in the tree.The instrument that found #10427 was a corpus sweep: parse every
.{ts,tsx,mts,cts,js,mjs,cjs,jsx}file in the repo with@typescript-eslint/parser(already a root dependency), and diff the comment ranges it reports againstscanSource'scommentarray byte for byte. On the tree at the time it named 16 disagreeing files, 15 of them in the FABRICATES direction, up to 10,252 comment bytes in one file. Nothing inscripts/,package.jsonor.github/workflows/can re-derive that today — the sweep lived in an agent's scratchpad and left with it.Why the self-test alone does not cover it
Measured during #10427, and the reason this is worth a card rather than a note. A mutation that deleted the
{counting inside${...}passed all 22 pinned cases and the entire 4,739-file sweep — the tree simply does not write that shape today. The case that now holds it (${fmt({ a: 1 }, \\``)}`) had to be written from the mutation, not from the corpus.That is the general shape: the self-test pins shapes someone thought of, the sweep finds shapes the tree actually contains, and neither subsumes the other. The module's header now describes the sweep in prose so it can be reconstructed, which is a weaker guarantee than running it.
Note on scope
This is not a duplicate of #10608 (that card is about
--self-testentry points, this module's included, running in no workflow — a wiring gap for tests that already exist). This card is about a verification that does not exist in the tree in any form, wired or not. #10608 is the prerequisite in practice: wiring a sweep is pointless while the cheap self-test beside it still runs nowhere.Worth deciding rather than assuming: a full-corpus parse of ~4,700 files costs real CI time (the sweep took roughly a minute locally), so it may belong on a schedule or a
scripts/**-triggered lane rather than every PR — or as an on-demand--sweepflag on the module that a human runs after touchingscanSource, which is what its header currently asks for.Generated by Claude Code