@blamejs/exceptd-skills 0.19.33 → 0.19.35

package/scripts/check-codebase-patterns.js

@@ -1,39 +1,17 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * check-codebase-patterns.js — grep-gate enforcement for code-shape bug
- * classes that have recurred across exceptd releases. One run surfaces every
- * class as a single numbered report instead of dying on the first hit.
+ * Grep gate for code-shape bug classes that recur across releases; CLASSES
+ * below is the registry.
  *
- * Shipped v1 classes:
- *   - process-exit-after-stdout-write : a library-callable function writes to
- *       the result channel (process.stdout.write / console.log) and then calls
- *       process.exit(), which truncates the buffered write when stdout is
- *       piped. Route through `safeExit(EXIT_CODES.X); return;` (lib/exit-codes).
- *       This is the stdout-flush-truncation class the validate-cves fix closed by hand.
- *   - dynamic-regex : `new RegExp(<non-literal>)` — a ReDoS sink when the
- *       pattern derives from operator input. Use a static literal, or anchor +
- *       length-cap the input, or mark the site `// allow:dynamic-regex —
- *       <reason>` when the source is a trusted bundled schema.
- *   - orphan-allow-class : an `// allow:<class>` marker whose class is not in
- *       VALID_ALLOW_CLASSES, or is missing the `— <reason>` tail. A typo'd
- *       marker suppresses nothing, so the underlying violation would ship
- *       unflagged — this meta-guard keeps the marker mechanism trustworthy.
- *   - unsorted-marked-array : a flat string array tagged `// keep-sorted` that
- *       drifted out of alphabetical order. Opt-in — only marked arrays are
- *       checked, so a one-time allowlist sort becomes a standing guarantee.
- *   - misaligned-marked-run : a `// keep-aligned` const/weight table whose
- *       `=`/`:` assignment columns are not all equal. Opt-in, same shape.
- *
- * Exceptions live at the violation site, not in this file:
+ * Exceptions live at the violation site:
  *   - file-level, in the first 50 lines:  // codebase-patterns:allow-file <class> — <reason>
  *   - per-line, on the same line or up to 2 lines above:  // allow:<class> — <reason>
  *
- * NOT covered here (owned elsewhere — do not duplicate):
- *   - internal phase/version vocabulary in comments  -> scripts/check-version-tags.js
- *   - process.exit on the top-level CLI dispatch      -> tests/safe-exit-grep.test.js
- *   - anti-coincidence test assertions                -> scripts/check-test-coverage.js
- *   - internal-path leaks in operator output          -> tests/operator-leak-grep.test.js
+ * Owned elsewhere: phase/version vocabulary (check-version-tags.js), test
+ * assertions (check-test-coverage.js), and — both now in tests/cli.test.js,
+ * which absorbed the separate safe-exit-grep and operator-leak-grep files —
+ * the per-file CLI-dispatch process.exit ban and operator-output path leaks.
  */
 
 const fs = require("node:fs");
@@ -41,8 +19,8 @@ const path = require("node:path");
 
 const ROOT = path.resolve(__dirname, "..");
 
-// The classes that accept an `// allow:<class>` marker. orphan-allow-class is
-// the meta-guard itself and is intentionally NOT a markable class.
+// Classes that accept an `// allow:<class>` marker. orphan-allow-class is the
+// meta-guard itself, so it is not markable.
 const VALID_ALLOW_CLASSES = Object.freeze({
   "process-exit-after-stdout-write": true,
   "dynamic-regex": true,
@@ -57,8 +35,6 @@ const EXCLUDE_DIRS = new Set([
   "data", ".test-output", ".keys", "keys", "coverage",
 ]);
 
-// ---- file walk -----------------------------------------------------------
-
 function relPath(abs) {
   return path.relative(ROOT, abs).split(path.sep).join("/");
 }
@@ -104,18 +80,15 @@ function readLines(rel) {
   return lines;
 }
 
-// Strip a trailing `//` line comment for code-shape detection (so a class
-// name mentioned in a comment doesn't arm a detector). String-aware: a `//`
-// inside a quoted string (e.g. a `http://` URL) is NOT a comment, so the
-// scanner skips string contents — otherwise the rest of the line, including a
-// real `process.exit(...)` / `new RegExp(...)`, was silently truncated away and
-// the detector never fired.
+// Strip a trailing `//` line comment so a class name mentioned in a comment
+// can't arm a detector. String-aware: a `//` inside a quoted string (a `http://`
+// URL) is not a comment — truncating there hides a real hit later on the line.
 function stripLineComment(line) {
   let inStr = null; // active quote char, or null
   for (let i = 0; i < line.length; i++) {
     const ch = line[i];
     if (inStr) {
-      if (ch === "\\") { i++; continue; } // skip the escaped char
+      if (ch === "\\") { i++; continue; }
       if (ch === inStr) inStr = null;
     } else if (ch === "'" || ch === '"' || ch === "`") {
       inStr = ch;
@@ -126,8 +99,6 @@ function stripLineComment(line) {
   return line;
 }
 
-// ---- allow-marker engine -------------------------------------------------
-
 function hasFileAllow(rel, cls) {
   const head = readLines(rel).slice(0, 50);
   const re = new RegExp("codebase-patterns:allow-file\\s+" + cls + "\\b");
@@ -147,23 +118,10 @@ function filterMarkers(hits, cls) {
   return hits.filter((h) => !hasFileAllow(h.file, cls) && !hasLineAllow(h.file, h.line, cls));
 }
 
-// ---- require.main block ranges -------------------------------------------
-
-// Count `{` / `}` in `line` that are in REAL CODE context, advancing a
-// stateful tokenizer that tracks string / template / comment regions across
-// lines. Braces inside a single/double/template string, a `//` line comment,
-// or a `/* */` block comment do NOT affect depth — otherwise a `{` or `}`
-// typed inside a string literal in the require.main block miscounts the brace
-// balance and the computed block range slides onto an unrelated later function
-// (whose process.exit() is then wrongly treated as a CLI-entry exit and not
-// flagged). `inTemplate` and `inBlockComment` are the cross-line states a
-// per-line stripper cannot model, so the tokenizer state object is threaded
-// line-to-line by the caller.
-//
-// `state` is mutated in place: { inSingle, inDouble, inTemplate, inBlock,
-// templateDepth } — `templateDepth` tracks `${ … }` interpolation nesting so
-// the closing `}` of an interpolation is treated as template punctuation, not
-// a code brace, while braces INSIDE the interpolation expression still count.
+// Counts `{` / `}` in REAL CODE context only: a brace inside a string, template
+// or comment must not move the depth, or the computed require.main range slides
+// onto a later function. `state` is mutated in place and threaded line to line,
+// since `inTemplate` / `inBlock` are cross-line states.
 function countCodeBraces(line, state) {
   let delta = 0;
   for (let i = 0; i < line.length; i++) {
@@ -190,13 +148,12 @@ function countCodeBraces(line, state) {
         // Enter an interpolation expression: braces inside ARE code.
         state.templateExpr.push(0);
         state.inTemplate = false;
-        i++; // skip the `{`; the `${` opener is template punctuation
+        i++;
         continue;
       }
       continue;
     }
-    // Code context (possibly inside a template interpolation expression).
-    if (ch === "/" && next === "/") break; // `//` — rest of the line is a comment
+    if (ch === "/" && next === "/") break;
     if (ch === "/" && next === "*") { state.inBlock = true; i++; continue; }
     if (ch === "'") { state.inSingle = true; continue; }
     if (ch === '"') { state.inDouble = true; continue; }
@@ -222,17 +179,12 @@ function newBraceState() {
   return { inSingle: false, inDouble: false, inTemplate: false, inBlock: false, templateExpr: [] };
 }
 
-// Line ranges (1-based, inclusive) of `if (require.main === module) { ... }`
-// blocks — the dual-mode CLI-entry section where synchronous-print-then-exit
-// is correct. process.exit there is owned by tests/safe-exit-grep.test.js and
-// is not a library-surface concern.
+// Line ranges (1-based, inclusive) of `if (require.main === module) { ... }` blocks,
+// where print-then-exit is correct — owned by tests/safe-exit-grep.test.js.
 function requireMainRanges(lines) {
   const ranges = [];
   for (let i = 0; i < lines.length; i++) {
     if (/\brequire\.main\s*===\s*module\b/.test(lines[i])) {
-      // Find the opening brace (same line or next few), then balance —
-      // string/comment/template-aware so braces inside literals don't skew the
-      // depth (see countCodeBraces).
       let depth = 0;
       let started = false;
       let j = i;
@@ -252,19 +204,24 @@ function inRanges(ranges, lineNo) {
   return ranges.some(([a, b]) => lineNo >= a && lineNo <= b);
 }
 
-// ---- detectors -----------------------------------------------------------
-
-// A line that opens a new function body (so a backward stdout-write scan stops
-// at the enclosing function and doesn't arm an exit from an unrelated earlier
-// function). The bare-identifier (third) alternative matches a declaration /
-// method-shorthand opener (`foo() {`, `async bar() {`), but it must REFUSE
-// control-flow openers (`for (…) {`, `if (…) {`, `while/switch/catch (…) {`):
-// a control-flow block sitting between a stdout write and a process.exit() is
-// inside the SAME function, so stopping the backward scan there would wrongly
-// leave the exit unflagged. The negative lookahead excludes the control-flow
-// keywords; `function` and arrow alternatives are unchanged.
+// Opens a new function body, so the backward stdout-write scan stops at the
+// enclosing function. The bare-identifier alternative must REFUSE control-flow
+// openers (`if (…) {`, `for (…) {`): those sit inside the SAME function, and
+// stopping there leaves a real exit-after-write unflagged.
 const FUNCTION_START = /(^|[^.\w])function\b|=>\s*\{?\s*$|^\s*(async\s+)?(?!(?:if|for|while|switch|catch|do|else|with|finally|return)\b)[A-Za-z_$][\w$]*\s*\([^)]*\)\s*\{/;
 
+// Scope, stated so it is not mistaken for full coverage of the class: the
+// backward scan recognises a result-channel write only where it is written
+// LITERALLY — `process.stdout.write(` or `console.log(`. A write reached
+// INDIRECTLY, through a helper called from the exiting function (`printHelp()`,
+// `renderSummary()`), is invisible to it, so an exit-after-write of that shape
+// passes this gate and has to be caught by review or a per-file test.
+//
+// Not closed by matching call sites of same-file writer functions: measured over
+// lib/, orchestrator/, scripts/ and bin/, that heuristic cannot tell a helper
+// that writes to STDOUT from one that writes to stderr via console.error, and it
+// fires on exits that are correct. Closing it properly needs call-graph
+// resolution of the write target, not another regex.
 function detectProcessExitAfterStdout(files) {
   const hits = [];
   for (const rel of (files || filesUnder(["bin/exceptd.js", "lib", "orchestrator", "scripts"]))) {
@@ -275,8 +232,7 @@ function detectProcessExitAfterStdout(files) {
       if (!/\bprocess\.exit\s*\(/.test(code)) continue;
       const lineNo = i + 1;
       if (inRanges(mainRanges, lineNo)) continue; // CLI-entry block: legitimate
-      // Scan backward within the enclosing function for a result-channel
-      // write (console.log / process.stdout.write). Stop at a function start.
+      // Scan backward within the enclosing function for a result-channel write.
       let sawStdout = false;
       for (let k = i - 1; k >= 0 && k >= i - 60; k--) {
         const prev = stripLineComment(lines[k]);
@@ -291,11 +247,8 @@ function detectProcessExitAfterStdout(files) {
   return filterMarkers(hits, "process-exit-after-stdout-write");
 }
 
-// The first non-whitespace char of the first arg is `"`, `'`, or `/` => a
-// string/regex literal => static, safe. Anything else (an identifier, a `(`,
-// a backtick template) is operator-derivable and flagged. Backtick is NOT
-// exempt — a template literal can interpolate operator input, so it must be
-// flagged the same as a bare identifier.
+// A first arg opening with `"`, `'` or `/` is a literal, so static and safe.
+// Backtick is NOT exempt — a template literal can interpolate operator input.
 function isStaticRegexFirstChar(ch) {
   return ch === '"' || ch === "'" || ch === "/";
 }
@@ -312,23 +265,17 @@ function detectDynamicRegex(files) {
         hits.push({ file: rel, line: i + 1, content: lines[i].trim() });
         continue;
       }
-      // Multi-line form: `new RegExp(` ends the (comment-stripped) line with the
-      // open paren as the last token, and the pattern arg is on a following
-      // line. The single-line match above can't see the first-arg char, so it
-      // would silently pass a dynamic RegExp whose argument starts next line.
-      // Look ahead, skipping blank and comment-only lines (capped at 5), and
-      // inspect the first code line's first non-whitespace char.
+      // Multi-line form: the pattern arg starts on a later line, so look ahead
+      // past blank and comment-only lines, capped at 5.
       if (!/\bnew RegExp\s*\(\s*$/.test(code)) continue;
       let firstChar = null;
       for (let k = i + 1; k <= i + 5 && k < lines.length; k++) {
         const ahead = stripLineComment(lines[k]).replace(/^\s+/, "");
-        if (ahead === "") continue; // blank or comment-only — skip
+        if (ahead === "") continue;
         firstChar = ahead[0];
         break;
       }
-      // A `new RegExp(` with nothing parseable after it within the cap is
-      // suspicious — flag conservatively. Otherwise apply the SAME literal
-      // exemption as the single-line path.
+      // Nothing parseable within the cap is suspicious — flag it.
       if (firstChar !== null && isStaticRegexFirstChar(firstChar)) continue;
       hits.push({ file: rel, line: i + 1, content: lines[i].trim() });
     }
@@ -336,13 +283,9 @@ function detectDynamicRegex(files) {
   return filterMarkers(hits, "dynamic-regex");
 }
 
-// Raw bidi-override / zero-width / invisible / null codepoints embedded as
-// literals in source — the Trojan-Source class (CVE-2021-42574). A literal
-// such codepoint is invisible in review and can reorder or hide code. Source
-// should emit them programmatically (via vendor/blamejs/codepoint-class) or
-// escape them (\uXXXX), never type them literally. The range table holds only
-// numeric codepoints + the regex is built from escapes, so this detector's own
-// source is clean (and the file self-skips below regardless).
+// Raw bidi-override / zero-width / invisible / null codepoints typed as literals
+// — the Trojan-Source class (CVE-2021-42574). Source emits them via
+// vendor/blamejs/codepoint-class or a \uXXXX escape instead.
 const _BIDI_LITERAL_RANGES = [
   [0x202A, 0x202E], [0x2066, 0x2069], 0x200E, 0x200F, 0x061C, // bidi overrides + isolates
   0x200B, 0x200C, 0x200D, 0x00AD, 0x2060, 0xFEFF,             // zero-width / invisible
@@ -378,13 +321,8 @@ function detectOrphanAllowClass(files) {
       const cmt = lines[i].indexOf("//");
       if (cmt === -1) continue;
       const comment = lines[i].slice(cmt);
-      // Validate BOTH marker forms with the same class + reason rules:
-      //   per-line:    allow:<class> — <reason>
-      //   file-level:  codebase-patterns:allow-file <class> — <reason>
-      // The file-level form is the broadest exemption (it suppresses every hit
-      // of its class in the file), so a reason-less or unknown-class file-level
-      // marker must be caught here too — otherwise it would suppress silently
-      // and never reach the per-line orphan check.
+      // Both marker forms carry the same class + reason rules. The file-level
+      // form suppresses every hit of its class, so it must be caught here.
       const fileLevel = comment.match(/\bcodebase-patterns:allow-file\s+([a-z0-9-]+)\b(.*)$/);
       const perLine = comment.match(/\ballow:([a-z0-9-]+)\b(.*)$/);
       const m = fileLevel || perLine;
@@ -402,16 +340,11 @@ function detectOrphanAllowClass(files) {
   return hits;
 }
 
-// ---- opt-in readability detectors (preventative) -------------------------
-// These fire ONLY on sites that explicitly opt in via a marker, so unmarked
-// code is never flagged. They turn a one-time cleanup (sorting an allowlist,
-// aligning a const table) into a standing guarantee: mark the cleaned site and
-// the gate keeps it clean.
+// The two detectors below fire only on sites that opt in via a marker, so
+// unmarked code is never flagged.
 
-// `// keep-sorted` marks a flat string-literal array that must stay
-// alphabetically sorted (e.g. an allowlist). Only arrays whose opening line
-// carries the marker are checked; arrays containing object/nested elements are
-// skipped (not a flat string list).
+// `// keep-sorted` marks a flat string-literal array that must stay alphabetically
+// sorted; an array with object or nested elements is skipped.
 function scanUnsortedMarkedArray(rel, lines) {
   const hits = [];
   for (let i = 0; i < lines.length; i++) {
@@ -428,7 +361,7 @@ function scanUnsortedMarkedArray(rel, lines) {
       body += " " + seg;
       if (started && depth <= 0) break;
     }
-    if (/[{]/.test(body)) continue; // object/nested elements — not a flat string array
+    if (/[{]/.test(body)) continue;
     const strs = [];
     const re = /(['"])((?:\\.|(?!\1).)*)\1/g;
     let m;
@@ -452,9 +385,8 @@ function detectUnsortedMarkedArray(files) {
 }
 
 // `// keep-aligned` marks a contiguous run of `IDENT = value` / `IDENT: value`
-// lines (a const/weight table) whose assignment columns must all line up. The
-// run is the lines immediately after the marker, until a blank or non-assignment
-// line. Opt-in, so only deliberately-aligned tables are enforced.
+// lines whose assignment columns must all line up. The run starts at the line
+// after the marker and ends at the first blank or non-assignment line.
 function scanMisalignedMarkedRun(rel, lines) {
   const hits = [];
   for (let i = 0; i < lines.length; i++) {
@@ -487,22 +419,13 @@ function detectMisalignedMarkedRun(files) {
   return hits;
 }
 
-// ---- hand-rolled SQL in a file that talks to a database ------------------
-//
-// exceptd ships no database today, so this is a FORWARD guard: the moment a
-// file imports a SQL driver, any SQL STATEMENT (`"SELECT …"`) or CLAUSE built
-// by string concatenation (`… + " WHERE " + …`) is a parameterization/injection
-// sink and must use the driver's bound-parameter API instead. The SQL-driver
-// import is the gate — a SQL-looking string in a file with no driver executes
-// nothing, so prose that merely begins with "Update …" / "Delete …" in a
-// non-DB file is never scanned (no false positives). A trusted static DDL
-// string can opt out with `// allow:hand-rolled-sql — <reason>`.
+// Forward guard: the driver import is the gate, so prose merely beginning
+// "Update …" in a non-DB file is never scanned. In a file that does import one,
+// a statement or a concatenated clause is an injection sink.
 const SQL_DRIVER_IMPORT = /require\(\s*["'](?:node:sqlite|better-sqlite3|sqlite3|sqlite|pg|mysql2?|knex|sequelize|drizzle-orm|postgres|@libsql\/[\w.-]+)(?:\/[^"']*)?["']\s*\)|\bfrom\s+["'](?:node:sqlite|better-sqlite3|pg|mysql2?|knex|sequelize|drizzle-orm)(?:\/[^"']*)?["']/;
 const SQL_STMT_START = /(["'`])\s*(?:SELECT\b|INSERT\s+(?:INTO|OR)\b|REPLACE\s+INTO\b|UPDATE\s+["'`]?[A-Za-z_]|DELETE\s+FROM\b|CREATE\s+(?:TABLE|UNIQUE\s+INDEX|INDEX|TRIGGER|VIRTUAL\s+TABLE)\b|ALTER\s+TABLE\b|DROP\s+(?:TABLE|TRIGGER|INDEX)\b|MERGE\s+INTO\b)/i;
-// Trailing-concat form tolerates an embedded SQL string-quote inside the
-// clause (e.g. `" WHERE name = 'x' " + id`) by scanning to the first `+`
-// concatenation operator rather than requiring the clause string to close on
-// the same quote with no interior quotes.
+// The trailing-concat form tolerates a quote inside the clause
+// (`" WHERE name = 'x' " + id`) by scanning to the first `+`.
 const SQL_CLAUSE_FRAG = /(?:\+\s*["'`]\s*(?:SET|FROM|WHERE|VALUES|ORDER\s+BY|GROUP\s+BY|HAVING|RETURNING|LIMIT|OFFSET|ON\s+CONFLICT|(?:INNER\s+|LEFT\s+|RIGHT\s+|CROSS\s+)?JOIN)\b|["'`]\s*(?:SET|FROM|WHERE|VALUES\s*\(|ORDER\s+BY|GROUP\s+BY|HAVING|RETURNING|ON\s+CONFLICT|(?:INNER\s+|LEFT\s+|RIGHT\s+|CROSS\s+)?JOIN)\b[^+]*\+)/i;
 function detectHandRolledSql(files) {
   const hits = [];
@@ -564,11 +487,8 @@ const CLASSES = [
 ];
 
 function main() {
-  // Fail closed if the scan universe is empty. Each detector scopes to a subset
-  // of these roots and silently finds no hits when its root list is
-  // unreadable/empty — so a wholesale missing source tree would make every
-  // class report "clean" and the gate pass without scanning anything (the
-  // absent-input false-pass class). Refuse to call zero-files-scanned "clean".
+  // Fail closed on an empty scan universe: each detector silently finds no hits
+  // when its roots are unreadable. Zero files scanned is not "clean".
   const universe = filesUnder(["bin/exceptd.js", "lib", "orchestrator", "scripts"]);
   if (universe.length === 0) {
     console.error("[check-codebase-patterns] FAIL — zero source files found under bin/lib/orchestrator/scripts; refusing to report clean without scanning anything.");

package/scripts/check-epss-consistency.js

@@ -2,40 +2,10 @@
 "use strict";
 
 /**
- * EPSS score/percentile consistency gate.
+ * EPSS score/percentile consistency gate. Exit 0 consistent, 1 inconsistent.
  *
- * EPSS publishes a score and a percentile for every CVE, refreshed daily. The
- * percentile is the score's RANK within that day's publication: if A scores
- * higher than B on a given day, A's percentile is at least B's. That makes the
- * pair self-checking with no network access — sort a day's entries by score and
- * the percentiles must come out sorted too.
- *
- * The failure this catches is updating one field without the other. A refresh
- * that writes a new score but keeps yesterday's percentile leaves a plausible
- * entry: both numbers are in range, both look like EPSS values, and nothing
- * downstream can tell they describe different days. The result is a CVE ranked
- * as top-decile urgency on a score that no longer supports it, which is exactly
- * the input the prioritisation model trusts most.
- *
- * What the ordering check does and does not establish. Monotonicity is a
- * necessary condition, not a sufficient one: it catches a stale percentile that
- * contradicts the new score's rank, which is what a partial refresh usually
- * produces, but a stale value that happens to preserve the ordering passes.
- * Proving two fields share a publication would require the fetched row, and
- * that is not recoverable from the catalog offline. So this is a corruption
- * detector, not a provenance proof — the provenance guarantee has to come from
- * the write side, by fetching and writing score, percentile and date together.
- *
- * Three checks run:
- *   - within each epss_date, sorting by score must sort by percentile;
- *   - an entry carries both numeric fields or neither;
- *   - epss_note, which is derived text, must restate the current fields.
- *
- * Entries are grouped by epss_date so each publication is checked against
- * itself; comparing across days is meaningless because the whole distribution
- * shifts.
- *
- * Exit codes: 0 consistent, 1 inconsistent.
+ * The percentile is the score's rank within one publication, so a cohort must
+ * sort the same way by both. Monotonicity is necessary, not sufficient.
  */
 
 const fs = require("node:fs");
@@ -44,13 +14,8 @@ const path = require("node:path");
 const ROOT = path.resolve(__dirname, "..");
 
 /**
- * Percentiles are published rounded to five decimals, so two scores that are
- * adjacent in the ranking can round to percentiles that invert by a hair. That
- * is arithmetic, not drift. Real mismatches are pairs pulled from different
- * days, which land orders of magnitude above this: the widest rounding artifact
- * observed in the catalog is 8e-5, while a stale-field mismatch runs 0.05-0.9.
- * The threshold sits between the two, far enough from each that neither
- * classification is a close call.
+ * Percentiles publish rounded to five decimals, so adjacent scores can invert by
+ * a hair. Rounding artifacts reach 8e-5; a stale-field mismatch runs 0.05-0.9.
  */
 const ROUNDING_TOLERANCE = 1e-3;
 
@@ -58,24 +23,10 @@ function loadCatalog(file) {
   return JSON.parse(fs.readFileSync(file, "utf8"));
 }
 
-/**
- * The operator-readable restatement of an entry's EPSS fields. Entries carry it
- * as `epss_note`, and it is derived, not authored — so it must be rebuilt
- * whenever the numbers move.
- *
- * The renderer lives in lib/cve-enrich.js because the refresh writer rebuilds
- * the note from the same definition. A second copy here would let the gate and
- * the writer disagree about the exact wording, which shows up as this gate
- * failing on data that was refreshed correctly.
- */
+/** Shared with the refresh writer so gate and writer cannot disagree on wording. */
 const { renderEpssNote: renderNote } = require("../lib/cve-enrich.js");
 
-/**
- * Group entries by publication date. Entries missing either field are reported
- * separately rather than skipped — a half-populated pair is its own defect, and
- * silently ignoring it would let the gate pass on the very shape it exists to
- * catch.
- */
+/** Group entries by publication date; a half-populated pair is reported, not skipped. */
 function cohorts(catalog) {
   const groups = new Map();
   const incomplete = [];
@@ -101,10 +52,7 @@ function cohorts(catalog) {
   return { groups, incomplete };
 }
 
-/**
- * Sort a cohort by score and report every place the percentile goes backwards
- * by more than rounding can explain.
- */
+/** Sort by score; report every percentile step backwards that rounding cannot explain. */
 function inversions(rows) {
   const sorted = [...rows].sort((a, b) => a.score - b.score);
   const found = [];
@@ -141,10 +89,7 @@ function check(catalogFile) {
     failures.push(`${row.id}: has one EPSS field but not ${row.missing} — write both together or neither`);
   }
 
-  // The prose restatement drifts the same way the percentile does: a refresh
-  // moves the numbers and leaves the sentence describing the previous
-  // publication, so the entry states two different scores as of two different
-  // dates. It is derived text, so it can be checked exactly.
+  // epss_note is derived text, so it can be checked exactly against the fields.
   for (const [id, entry] of Object.entries(catalog)) {
     if (typeof entry.epss_note !== "string") continue;
     if (typeof entry.epss_score !== "number" || typeof entry.epss_percentile !== "number") continue;

package/scripts/check-framework-gap-coverage.js

@@ -1,31 +1,16 @@
 #!/usr/bin/env node
 /*
- * scripts/check-framework-gap-coverage.js
+ * Enforces global-first coverage (AGENTS.md Hard Rule #5): every curated CVE in
+ * data/cve-catalog.json must declare a framework_control_gaps statement for all
+ * five jurisdiction buckets, so a multi-jurisdiction operator reading the
+ * offline catalog gets more than a US-centric subset.
  *
- * AGENTS.md Hard Rule #5 (global-first) enforcement gate. Every curated CVE
- * in data/cve-catalog.json must declare a framework_control_gaps statement
- * for all five jurisdiction buckets:
+ * Draft entries (_auto_imported) are exempt — they carry raw NVD data, and the
+ * curation bar requires promotion before shipping, at which point this applies.
  *
- *   NIST  — NIST-800-53-* / NIST-800-63*
- *   EU    — NIS2-* / DORA-* / EU-AI-* / GDPR-*
- *   UK    — UK-CAF-*
- *   AU    — AU-Essential-8-* / AU-ISM-*
- *   ISO   — ISO-27001-2022-*
- *
- * A multi-jurisdiction operator reading the offline catalog's framework-gap
- * output must get coverage for every required jurisdiction on every CVE, not
- * a US-centric subset. Before this gate, two-thirds of the corpus mapped only
- * a subset; a codex review surfaced it, the corpus was completed, and this
- * gate keeps it from regressing when new CVEs are curated.
- *
- * Draft entries (_auto_imported === true) are exempt — they carry raw NVD
- * data that has not been through curation yet. The curation bar (elsewhere)
- * requires drafts to be promoted before shipping, at which point this gate
- * applies.
- *
- * Exit code: 0 when every curated entry is complete, 1 when any entry omits a
- * required bucket (the list is printed). Uses process.exitCode (not
- * process.exit) so buffered stdout drains before the process ends.
+ * Exits 0 when every curated entry is complete, 1 when any omits a bucket.
+ * `process.exitCode`, never `process.exit()`: the failure list is a buffered
+ * stdout write that the exit can truncate.
  */
 
 'use strict';
@@ -34,19 +19,16 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const ROOT = path.resolve(__dirname, '..');
-// Catalog path is overridable (argv[2]) so the gate's own test can point it at
-// a fixture; defaults to the shipped catalog for the real predeploy run.
+// argv[2] overrides the catalog so the gate's own test can point at a fixture.
 const CATALOG = process.argv[2] || path.join(ROOT, 'data', 'cve-catalog.json');
 
 const REQUIRED = ['NIST', 'EU', 'UK', 'AU', 'ISO'];
 
 function bucketOf(key) {
   if (/^NIST/i.test(key)) return 'NIST';
-  // EU bucket is the security-regulation family AGENTS.md Hard Rule #5 names:
-  // NIS2, DORA, the EU AI Act, and the EU Cyber Resilience Act. GDPR / EU-GDPR
-  // (data-protection) is NOT sufficient on its own — an entry mapped only to
-  // GDPR still owes NIS2/DORA/EU-AI coverage, so GDPR does not satisfy this
-  // bucket. Note EU-AI / EU-CRA match here; EU-GDPR deliberately does not.
+  // The EU bucket is the security-regulation family Hard Rule #5 names. GDPR is
+  // data protection and does NOT satisfy it: an entry mapped only to GDPR still
+  // owes NIS2/DORA/EU-AI coverage, so EU-GDPR must not match here.
   if (/^(NIS2|DORA|EU-AI|EU-CRA)/i.test(key)) return 'EU';
   if (/^UK-CAF/i.test(key)) return 'UK';
   if (/^(AU-Essential-?8|AU-ISM|Essential-?8)/i.test(key)) return 'AU';