Observation filed while closing the conditional import leak in scripts/objectui-range.mjs (#10667, PR #11951). Not fixed there — out of that card's scope, and cosmetic rather than a correctness defect.
What it does
--help / -h builds its usage text by reading this file back and keeping every line that starts with // at column 0:
readFileSync(fileURLToPath(import.meta.url), 'utf8')
.split('\n')
.filter((l) => l.startsWith('//'))
.map((l) => l.slice(3))
.join('\n')The intent is sound — usage text and header comment cannot drift when they are the same bytes. But the filter has no notion of "the header": it takes all 79 column-0 // lines in the file, and six of them are not header.
Measured on main (ce744bcdf)
node scripts/objectui-range.mjs --help is 4693 bytes, and these lines are in it:
129: // Resolve the objectui SHA pinned at a given framework rev (or the working tree).
333: // ---------------------------------------------------------------------------
334: // Self-test (#4843) — the repo idiom for a `scripts/` gate: build a throwaway
335: // git repo carrying the exact shapes measured on the real range, run the real
336: // code over it, assert the ARTIFACT (the markdown a maintainer pastes).
337: // ---------------------------------------------------------------------------
A reader asking for usage gets a note about an internal helper and the self-test's section banner appended to it.
Why it is worth recording rather than shrugging at
The failure is silent and open-ended: the help text is a function of every column-0 // line anyone adds to this file later, anywhere in it. A contributor writing an ordinary implementation comment at column 0 rewrites the CLI's usage output and nothing anywhere says so. PR #11951 had to work around exactly this — its new rationale is a /** */ block specifically so --help would stay byte-identical, and it pins the column-0 // count at 79 to prove it.
Possible shapes (not a decision, just what the options look like)
- Stop at the first non-
// line — the header is a prefix of the file, so takeWhile rather than filter says what is meant. Cheapest, and it makes the "add a comment anywhere" hazard structurally impossible.
- Delimit the header explicitly (a sentinel line) and slice between the markers.
- Leave it, and treat "no column-0
// outside the header" as a rule for this file — which is the status quo, unenforced.
Option 1 changes the current --help output by removing the six lines above; that is the whole behaviour change, and it would need the same cmp treatment any edit to this file needs.
No assignee — recording, not claiming.
Generated by Claude Code
Observation filed while closing the conditional import leak in
scripts/objectui-range.mjs(#10667, PR #11951). Not fixed there — out of that card's scope, and cosmetic rather than a correctness defect.What it does
--help/-hbuilds its usage text by reading this file back and keeping every line that starts with//at column 0:The intent is sound — usage text and header comment cannot drift when they are the same bytes. But the filter has no notion of "the header": it takes all 79 column-0
//lines in the file, and six of them are not header.Measured on
main(ce744bcdf)node scripts/objectui-range.mjs --helpis 4693 bytes, and these lines are in it:A reader asking for usage gets a note about an internal helper and the self-test's section banner appended to it.
Why it is worth recording rather than shrugging at
The failure is silent and open-ended: the help text is a function of every column-0
//line anyone adds to this file later, anywhere in it. A contributor writing an ordinary implementation comment at column 0 rewrites the CLI's usage output and nothing anywhere says so. PR #11951 had to work around exactly this — its new rationale is a/** */block specifically so--helpwould stay byte-identical, and it pins the column-0//count at 79 to prove it.Possible shapes (not a decision, just what the options look like)
//line — the header is a prefix of the file, sotakeWhilerather thanfiltersays what is meant. Cheapest, and it makes the "add a comment anywhere" hazard structurally impossible.//outside the header" as a rule for this file — which is the status quo, unenforced.Option 1 changes the current
--helpoutput by removing the six lines above; that is the whole behaviour change, and it would need the samecmptreatment any edit to this file needs.No assignee — recording, not claiming.
Generated by Claude Code