fix(devx): check-comment-mask-corpus no longer drops argv[0] when --masker is absent

[baozhoutao]

Closes #16540

The bug

scripts/check-comment-mask-corpus.mjs's main() computed the argv left over after --masker PATH as:

const rest = argv.filter((arg, index) => index !== maskerFlag && index !== maskerFlag + 1);

argv.indexOf('--masker') returns -1 when the flag is absent, and -1 + 1 === 0 — so the filter treated "no --masker anywhere" the same as "drop index 0", removing argv[0] from the very list the unknown-option check reads next. An unknown option typed in first position (--no-such-flag, or any future --json/--shard/--since) was silently dropped, the usage check never fired, and the script fell through to the full 6,484-file sweep and exited 0.

The fix

Extracted the computation into a pure, directly-testable argvAfterMasker(argv, maskerFlag) and guarded the sentinel:

export function argvAfterMasker(argv, maskerFlag) {
  return maskerFlag === -1 ? argv : argv.filter((arg, index) => index !== maskerFlag && index !== maskerFlag + 1);
}

When --masker is absent, rest is now argv itself (same reference), not a filtered copy missing its first element.

--self-test — dead-code check on the issue's suggested patch

The issue's suggested patch appended && arg !== '--self-test' to the unknown-option filter. Measured before writing anything: --self-test is dispatched by the entrypoint block —

if (argv.includes('--self-test')) { /* ... calls selfTest() ... */ }
else await main(argv);

— so main() (where the unknown filter lives) never receives --self-test when invoked via the CLI; that path is prevented from ever reaching main() at all. The clause would be dead code here, so it was not ported.

Before / after measurement

Run in a fresh worktree after pnpm install (@typescript-eslint/parser present), same tree (origin/main @ cca1dc0bfb):

	command	exit code	wall clock
before	node scripts/check-comment-mask-corpus.mjs --no-such-flag	0 (ran the full sweep — 6,484 files, "0 disagree")	51.4s
after	node scripts/check-comment-mask-corpus.mjs --no-such-flag	2 (EXIT_USAGE)	55ms

After:

unknown option(s): --no-such-flag
usage: node scripts/check-comment-mask-corpus.mjs [--self-test] [--masker PATH]

Reverse control — the untouched half did not move

--masker in first position is the one shape the bug never affected (maskerFlag is a real index there, so the filter always behaved). Run both before and after the fix, under this container's shared verify lock (scripts/pm/os-verify-lock.sh), same command:

node scripts/check-comment-mask-corpus.mjs --masker scripts/js-comment-mask.mjs

	exit code	wall clock (shared-box seconds — lock held, not an idle-box reading)	self-test cases reported
before fix	0	53.0s	17
after fix	0	54.2s	26

Same shape (0 disagree, 0 unparseable, EXIT 0) both times — the difference is only the self-test case count, which is the intended change (9 new --self-test cases added for #16540), not a regression. The half this PR didn't touch didn't move.

--self-test

Added 9 cases (floor raised 17 → 26, per this repo's assertion-floor culture, #13799):

• direct, on argvAfterMasker() (no process spawn, fast):
  • rest === argv (same reference) when --masker is absent
  • --masker in first position still drops exactly its flag and value (regression)
  • an unknown option is read from argv[0] with --masker absent
  • an unknown option is read from a middle position with --masker absent
  • an unknown option is read from the last position, after --masker consumes its two slots
• spawned, on a real child process (following the objectui port's approach, so the exit code is pinned as an actual number the OS returned, not a value this file made up):
  • --no-such-flag at argv[0] exits EXIT_USAGE (typeof status === 'number' && status === 2)
  • the usage error names the unknown flag
  • it answers in well under a second — proof it never reaches the sweep
  • an unknown option after --masker also exits EXIT_USAGE as a number

Full run:

$ node scripts/check-comment-mask-corpus.mjs --self-test
...
ok   #16540 -- with --masker absent, rest is argv ITSELF (same reference), not a copy missing argv[0]
ok   #16540 regression -- --masker in FIRST position still drops exactly its flag and value
ok   #16540 -- an unknown option is read from argv[0] when --masker is absent
ok   #16540 -- an unknown option is read from a MIDDLE position, no --masker
ok   #16540 -- an unknown option is read from the LAST position, after --masker consumed its two slots
ok   #16540 spawned -- --no-such-flag at argv[0] exits EXIT_USAGE as a NUMBER (not a full sweep)
ok   ...and the usage error names the unknown flag
ok   ...and it answers in well under a second -- it never reaches the sweep
ok   #16540 spawned -- an unknown option AFTER --masker also exits EXIT_USAGE as a NUMBER
...

All 26 self-test cases passed.

Scope and other gates

Only scripts/check-comment-mask-corpus.mjs was touched. The dispatch-gates.mjs-derived family for this diff is 31 commands; all 31 ran and passed (node scripts/pm/dispatch-gates.mjs --ran FILE → "31 derived famil(ies) accounted for — 31 run, 0 NOT-MEASURED"), including the gate itself (node scripts/check-comment-mask-corpus.mjs — the production sweep, exit 0) and its --self-test.

No package under packages/* publishes anything under scripts/ (measured: no package.json in the workspace has a files[] entry naming a scripts path, and the repo root package.json is "private": true), so this diff carries no published surface.

Changeset

skip-changeset — measured, not assumed: scripts/check-comment-mask-corpus.mjs is a repo-root dev-tooling script, no workspace package's files[] publishes anything under scripts/, and the root package itself is private: true. Nothing shipped moved.

Clause-②: no

---

Generated by Claude Code