@blamejs/exceptd-skills 0.15.47 → 0.15.49

package/scripts/check-codebase-patterns.js

@@ -0,0 +1,296 @@
+#!/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.
+ *
+ * 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.
+ *
+ * Exceptions live at the violation site, not in this file:
+ *   - 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
+ */
+
+const fs = require("node:fs");
+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.
+const VALID_ALLOW_CLASSES = Object.freeze({
+  "process-exit-after-stdout-write": true,
+  "dynamic-regex": true,
+});
+
+const EXCLUDE_DIRS = new Set([
+  "node_modules", "vendor", ".git", ".cache", ".scratch",
+  "data", ".test-output", ".keys", "keys", "coverage",
+]);
+
+// ---- file walk -----------------------------------------------------------
+
+function relPath(abs) {
+  return path.relative(ROOT, abs).split(path.sep).join("/");
+}
+
+function walk(dir, out) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch (_e) { return out; }
+  for (const e of entries) {
+    const abs = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (EXCLUDE_DIRS.has(e.name)) continue;
+      walk(abs, out);
+    } else if (e.isFile() && /\.(c|m)?js$/.test(e.name) && !/\.test\.js$/.test(e.name)) {
+      out.push(abs);
+    }
+  }
+  return out;
+}
+
+// Source files under the given top-level roots, as repo-relative POSIX paths.
+function filesUnder(roots) {
+  const out = [];
+  for (const r of roots) {
+    const abs = path.join(ROOT, r);
+    try {
+      const st = fs.statSync(abs);
+      if (st.isDirectory()) walk(abs, out);
+      else if (st.isFile()) out.push(abs);
+    } catch (_e) { /* missing root — skip */ }
+  }
+  return out.map(relPath).sort();
+}
+
+const _lineCache = new Map();
+function readLines(rel) {
+  if (_lineCache.has(rel)) return _lineCache.get(rel);
+  const abs = path.isAbsolute(rel) ? rel : path.join(ROOT, rel);
+  let lines;
+  try { lines = fs.readFileSync(abs, "utf8").split(/\r?\n/); }
+  catch (_e) { lines = []; }
+  _lineCache.set(rel, lines);
+  return lines;
+}
+
+// Strip a trailing `//` line comment for code-shape detection (so a class
+// name mentioned in a comment doesn't arm a detector). Leaves string contents
+// alone enough for the coarse line-level checks here.
+function stripLineComment(line) {
+  const idx = line.indexOf("//");
+  return idx === -1 ? line : line.slice(0, idx);
+}
+
+// ---- 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");
+  return head.some((l) => re.test(l));
+}
+
+function hasLineAllow(rel, lineNo /* 1-based */, cls) {
+  const lines = readLines(rel);
+  const re = new RegExp("//.*\\ballow:" + cls + "\\b");
+  for (let n = lineNo; n >= lineNo - 2 && n >= 1; n--) {
+    if (re.test(lines[n - 1] || "")) return true;
+  }
+  return false;
+}
+
+function filterMarkers(hits, cls) {
+  return hits.filter((h) => !hasFileAllow(h.file, cls) && !hasLineAllow(h.file, h.line, cls));
+}
+
+// ---- require.main block ranges -------------------------------------------
+
+// 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.
+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.
+      let depth = 0;
+      let started = false;
+      let j = i;
+      for (; j < lines.length; j++) {
+        for (const ch of lines[j]) {
+          if (ch === "{") { depth++; started = true; }
+          else if (ch === "}") { depth--; }
+        }
+        if (started && depth <= 0) break;
+      }
+      if (started) ranges.push([i + 1, j + 1]);
+    }
+  }
+  return ranges;
+}
+
+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).
+const FUNCTION_START = /(^|[^.\w])function\b|=>\s*\{?\s*$|^\s*(async\s+)?[A-Za-z_$][\w$]*\s*\([^)]*\)\s*\{/;
+
+function detectProcessExitAfterStdout(files) {
+  const hits = [];
+  for (const rel of (files || filesUnder(["lib", "orchestrator"]))) {
+    const lines = readLines(rel);
+    const mainRanges = requireMainRanges(lines);
+    for (let i = 0; i < lines.length; i++) {
+      const code = stripLineComment(lines[i]);
+      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.
+      let sawStdout = false;
+      for (let k = i - 1; k >= 0 && k >= i - 60; k--) {
+        const prev = stripLineComment(lines[k]);
+        if (/\bprocess\.stdout\.write\s*\(/.test(prev) || /\bconsole\.log\s*\(/.test(prev)) {
+          sawStdout = true; break;
+        }
+        if (FUNCTION_START.test(prev)) break; // left the function body
+      }
+      if (sawStdout) hits.push({ file: rel, line: lineNo, content: lines[i].trim() });
+    }
+  }
+  return filterMarkers(hits, "process-exit-after-stdout-write");
+}
+
+function detectDynamicRegex(files) {
+  const hits = [];
+  for (const rel of (files || filesUnder(["lib", "orchestrator", "bin/exceptd.js"]))) {
+    const lines = readLines(rel);
+    for (let i = 0; i < lines.length; i++) {
+      const code = stripLineComment(lines[i]);
+      const m = code.match(/\bnew RegExp\s*\(\s*(.)/);
+      if (!m) continue;
+      // Literal first arg => a quote or a `/` regex literal => static, safe.
+      const firstChar = m[1];
+      if (firstChar === '"' || firstChar === "'" || firstChar === "/") continue;
+      hits.push({ file: rel, line: i + 1, content: lines[i].trim() });
+    }
+  }
+  return filterMarkers(hits, "dynamic-regex");
+}
+
+function detectOrphanAllowClass(files) {
+  const hits = [];
+  for (const rel of (files || filesUnder(["bin/exceptd.js", "lib", "orchestrator", "scripts"]))) {
+    if (rel === "scripts/check-codebase-patterns.js") continue; // holds the registry + regexes
+    const lines = readLines(rel);
+    for (let i = 0; i < lines.length; i++) {
+      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.
+      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;
+      if (!m) continue;
+      const cls = m[1];
+      const tail = m[2];
+      const label = fileLevel ? `allow-file ${cls}` : `allow:${cls}`;
+      if (!VALID_ALLOW_CLASSES[cls]) {
+        hits.push({ file: rel, line: i + 1, content: lines[i].trim(), why: `unknown allow-class "${cls}"` });
+      } else if (!/[—-]\s*\S/.test(tail)) {
+        hits.push({ file: rel, line: i + 1, content: lines[i].trim(), why: `${label} is missing the "— <reason>" tail` });
+      }
+    }
+  }
+  return hits;
+}
+
+const CLASSES = [
+  {
+    id: "process-exit-after-stdout-write",
+    run: detectProcessExitAfterStdout,
+    warnOnly: false,
+    hint: "use `safeExit(EXIT_CODES.X); return;` (lib/exit-codes.js) — process.exit() truncates buffered stdout when piped",
+  },
+  {
+    id: "dynamic-regex",
+    run: detectDynamicRegex,
+    warnOnly: true, // flip to false next release once the known sites carry markers
+    hint: "RegExp from operator input is a ReDoS sink — anchor + length-cap, or `// allow:dynamic-regex — <reason>` when the pattern is a trusted bundled schema",
+  },
+  {
+    id: "orphan-allow-class",
+    run: detectOrphanAllowClass,
+    warnOnly: false,
+    hint: "a typo'd or reason-less `// allow:<class>` suppresses nothing — fix the class id or add `— <reason>`",
+  },
+];
+
+function main() {
+  let hardFail = 0;
+  let warnTotal = 0;
+  let n = 0;
+  for (const c of CLASSES) {
+    const hits = c.run();
+    if (!hits.length) { console.log(`  ok ${c.id}: clean`); continue; }
+    for (const h of hits) {
+      n++;
+      const tag = c.warnOnly ? "[warn]" : "FAIL";
+      const extra = h.why ? `  (${h.why})` : "";
+      console.error(`  ${n}. ${tag} ${c.id}  ${h.file}:${h.line}: ${String(h.content).slice(0, 110)}${extra}`);
+    }
+    console.error(`     -> ${c.hint}`);
+    if (c.warnOnly) warnTotal += hits.length; else hardFail += hits.length;
+  }
+  if (hardFail === 0) {
+    console.log(`[check-codebase-patterns] ok${warnTotal ? ` (${warnTotal} warning(s))` : ""}`);
+    process.exitCode = 0;
+    return;
+  }
+  console.error(`[check-codebase-patterns] FAIL — ${hardFail} blocking violation(s).`);
+  process.exitCode = 1;
+}
+
+module.exports = {
+  VALID_ALLOW_CLASSES,
+  CLASSES,
+  detectProcessExitAfterStdout,
+  detectDynamicRegex,
+  detectOrphanAllowClass,
+  filesUnder,
+};
+
+if (require.main === module) main();

package/scripts/predeploy.js

@@ -236,6 +236,19 @@ const GATES = [
     args: [path.join(ROOT, "scripts", "check-agents-md-collectors.js")],
     ciJobName: "Data integrity (catalog + manifest snapshot)",
   },
+  {
+    // Codebase-pattern gate. Blocks the code-shape bug classes that
+    // recurred across releases: a library-callable function that writes to
+    // stdout then calls process.exit() (truncates the buffered write when
+    // piped — the stdout-flush-truncation class), and a stale/typo'd `// allow:` marker.
+    // dynamic-RegExp construction is surfaced warn-only this release. The
+    // exception mechanism + the "owned elsewhere" boundary are documented in
+    // the script header.
+    name: "Codebase-pattern gates (process-exit-after-stdout-write, dynamic RegExp)",
+    command: process.execPath,
+    args: [path.join(ROOT, "scripts", "check-codebase-patterns.js")],
+    ciJobName: "Data integrity (catalog + manifest snapshot)",
+  },
 ];
 
 function runGate(gate) {