feat(scripts): wire the comment-mask corpus sweep and correct the header's instrument ordering (#10640)

Author: os-zhuang

.github/workflows/lint.yml

@@ -198,6 +198,45 @@ jobs:
       - name: scripts/ TypeScript parses go through one module
         run: pnpm check:parse-guard
 
+      # The comment-mask CORPUS sweep (#10640) — the other instrument for the
+      # module the two gates above delegate "is this span a comment, or code?"
+      # to. `js-comment-mask.mjs --self-test` pins the SHAPES someone wrote
+      # down; this parses every .{ts,tsx,mts,cts,js,mjs,cjs,jsx} file in the
+      # tree with @typescript-eslint/parser and diffs its comment ranges
+      # against the mask's, byte for byte. Neither subsumes the other, and that
+      # is measured in both directions on this tree rather than assumed:
+      # deleting the `{` counting inside `${...}` fails a pinned case and the
+      # sweep reads 0 disagreements over 4,741 files (the tree does not write
+      # that shape), while dropping `return` from REGEX_AFTER_KEYWORD passes all
+      # 23 pinned cases and the sweep names check-test-source-alias.mjs, where
+      # `return /(^|[^a-z])dist\//` is written today.
+      # The defect this would have caught shipped: 16 files disagreeing, 15 of
+      # them reading commented-out text as live code, 10,252 comment bytes in
+      # one file — and the instrument that found it lived in an agent's
+      # scratchpad, which is why re-deriving it was impossible until this file.
+      # WHY A HARD GATE ON EVERY PR, and not an on-demand flag: the sweep's
+      # verdict depends on the CORPUS as much as on the masker, so a PR that
+      # writes a shape the mask reads wrong turns ~20 source-scanning gates
+      # into liars on that file, on a PR that never touched the masker. That
+      # arrival is not detectable by any convention a human or an agent has to
+      # remember at the right moment — the failure mode this repo has already
+      # paid for at #4690 and again here.
+      # WHY A STEP AND NOT A JOB: a new job's `name:` is a required-context
+      # contract (scripts/check-required-contexts.mjs) that only a
+      # maintainer-present Settings change can enrol, and an unenrolled job is
+      # an advisory gate — #5617 verbatim. This job is already required.
+      # Invoked as `node` rather than `pnpm check:*` for the same reason as the
+      # other `node scripts/…` steps in this lane: that alias is a line in root
+      # package.json, inside the @changesets/cli v3 fence (#9465).
+      # Runs its own comparator self-test first — 12 cases proving the
+      # comparison can still REPORT, because "0 files disagree" and "the
+      # comparison is broken" otherwise print the same line.
+      # Cost, measured on a contended 4-vCPU container: 4,741 files, 72 MB of
+      # source, 45–48 s, of which the parser is 45 s. The step prints CI's own
+      # number on every run.
+      - name: Comment mask agrees with a real parser over the whole corpus
+        run: node scripts/check-comment-mask-corpus.mjs
+
       # Stack-collection enumerations vs the schema (#6242). `stack.zod.ts`
       # decides which collections a stack may declare; eight other enumerations
       # of that same set are hand-maintained (the map-format list, the

scripts/check-comment-mask-corpus.mjs

@@ -372,8 +372,8 @@ async function main(argv) {
       console.error(`      ${row.firstDivergence.excerpt}`);
     }
   }
-  const shown = unparseable.length + disagreements.length;
-  if (shown > ROW_LIMIT * 2) console.error(`  ... and ${shown - ROW_LIMIT * 2} more`);
+  const suppressed = Math.max(0, unparseable.length - ROW_LIMIT) + Math.max(0, disagreements.length - ROW_LIMIT);
+  if (suppressed) console.error(`  ... and ${suppressed} more (the counts below are over ALL files, not just the rows printed)`);
 
   if (disagreements.length || unparseable.length) {
     console.error(

scripts/js-comment-mask.mjs

@@ -61,17 +61,33 @@
  * cause was the template scan above; the same sweep after the fix disagrees on
  * 0 files.
  *
+ * That sweep is a SCRIPT now, not a paragraph (#10640):
+ *
+ *   node scripts/check-comment-mask-corpus.mjs
+ *
+ * It runs in CI on every pull request, and it carries the control that makes
+ * its green mean something -- `--masker <path>` re-derives the 16 files above
+ * against the pre-fix implementation. When this description and that script
+ * disagree, the script is the one that ran.
+ *
  * The lesson is about the claim, not the bug. A failure DIRECTION is a
  * property of an implementation, not of an intention, and this one cannot be
  * read off the code -- it took an independent parser over the whole tree to
  * find out which way the module actually failed. So the honest statement is
  * the one that can be re-derived: the shapes below are pinned, the sweep just
  * described is the way to check the rest, and neither direction is promised by
- * construction. Re-run it after touching `scanSource` -- and note that the
- * sweep is the STRONGER instrument of the two. A mutation that deleted the
- * brace counting inside `${...}` passed every case below AND the whole sweep,
- * because the tree did not happen to write the shape; the case that now holds
- * it was written from the mutation, not from the corpus.
+ * construction. Re-run both after touching `scanSource`.
+ *
+ * Neither is the stronger instrument -- that ordering was claimed here once
+ * and both directions of it have since been measured, on the same tree, in one
+ * sitting (#10640). Deleting the brace counting inside `${...}` fails the case
+ * below that was written from that mutation, and the sweep reads 0
+ * disagreements over 4,741 files, because the tree does not write the shape.
+ * Dropping `return` from `REGEX_AFTER_KEYWORD` passes all 23 cases below, and
+ * the sweep names `scripts/check-test-source-alias.mjs`, where
+ * `return /(^|[^a-z])dist\//` is written today. The self-test pins shapes
+ * someone thought of, the sweep finds shapes the tree actually contains, and
+ * neither substitutes for the other.
  */
 
 /** A character that can end an identifier -- i.e. a value, so `/` is division. */