@blamejs/exceptd-skills 0.19.34 → 0.19.35

package/scripts/check-codebase-patterns.js

@@ -8,9 +8,10 @@
  *   - 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>
  *
- * Owned elsewhere: phase/version vocabulary (check-version-tags.js), CLI-dispatch
- * process.exit (tests/safe-exit-grep.test.js), test assertions
- * (check-test-coverage.js), operator-output path leaks (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");
@@ -209,6 +210,18 @@ function inRanges(ranges, lineNo) {
 // 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"]))) {

package/scripts/check-manifest-snapshot.js

@@ -37,12 +37,47 @@ function captureSurface(manifest) {
   };
 }
 
+// Absent and corrupt are different states and must not collapse into one.
+//
+// ABSENT (key not in the object) is the stale baseline this gate exists to
+// report on: a snapshot committed before a surface field existed carries no key
+// for it, and an absent field is an empty surface, not a crash. Reading it
+// unguarded threw a TypeError that the CLI's outer catch turned into exit 2 with
+// a stack trace instead of an additive-change report.
+//
+// PRESENT-BUT-NOT-AN-ARRAY (a string, an object, null) is corruption. Coercing
+// it to [] would report every live entry as additive and exit 0 — a gate that
+// passes without checking anything. It raises instead, and the outer catch turns
+// that into exit 2 naming the skill and the field.
+function asArray(value, skillName, field) {
+  if (value === undefined) return [];
+  if (Array.isArray(value)) return value;
+  throw new Error(
+    `${skillName}: ${field} is ${value === null ? "null" : typeof value}, not an array. ` +
+    "The baseline or manifest is corrupt, not merely stale — regenerate the baseline " +
+    "with `node scripts/refresh-manifest-snapshot.js` and re-check the manifest."
+  );
+}
+
+// captureSurface() always writes `skills`, so unlike the per-field case above
+// there is no legitimate historical baseline without it: absent and non-array
+// are both corruption here, and treating either as [] would report every skill
+// as added and exit 0.
+function skillList(surface, which) {
+  const skills = surface && surface.skills;
+  if (Array.isArray(skills)) return skills;
+  throw new Error(
+    `${which}.skills is ${skills === null ? "null" : typeof skills}, not an array. ` +
+    "Regenerate the baseline with `node scripts/refresh-manifest-snapshot.js`."
+  );
+}
+
 function diff(baseline, current) {
   const breaking = [];
   const additive = [];
 
-  const bSkills = new Map(baseline.skills.map(s => [s.name, s]));
-  const cSkills = new Map(current.skills.map(s => [s.name, s]));
+  const bSkills = new Map(skillList(baseline, "baseline").map(s => [s.name, s]));
+  const cSkills = new Map(skillList(current, "current").map(s => [s.name, s]));
 
   for (const name of bSkills.keys()) {
     if (!cSkills.has(name)) {
@@ -70,32 +105,38 @@ function diff(baseline, current) {
     }
 
     // Removed trigger keywords break downstream skill matchers.
-    const removedTriggers = b.triggers.filter(t => !c.triggers.includes(t));
+    const bTriggers = asArray(b.triggers, name, "baseline triggers");
+    const cTriggers = asArray(c.triggers, name, "triggers");
+    const removedTriggers = bTriggers.filter(t => !cTriggers.includes(t));
     if (removedTriggers.length > 0) {
       breaking.push(`${name}: removed trigger keywords: ${removedTriggers.join(", ")}`);
     }
-    const addedTriggers = c.triggers.filter(t => !b.triggers.includes(t));
+    const addedTriggers = cTriggers.filter(t => !bTriggers.includes(t));
     if (addedTriggers.length > 0) {
       additive.push(`${name}: added trigger keywords: ${addedTriggers.join(", ")}`);
     }
 
     // Removed data deps break the skill at load time.
-    const removedDeps = b.data_deps.filter(d => !c.data_deps.includes(d));
+    const bDeps = asArray(b.data_deps, name, "baseline data_deps");
+    const cDeps = asArray(c.data_deps, name, "data_deps");
+    const removedDeps = bDeps.filter(d => !cDeps.includes(d));
     if (removedDeps.length > 0) {
       breaking.push(`${name}: removed data deps: ${removedDeps.join(", ")}`);
     }
-    const addedDeps = c.data_deps.filter(d => !b.data_deps.includes(d));
+    const addedDeps = cDeps.filter(d => !bDeps.includes(d));
     if (addedDeps.length > 0) {
       additive.push(`${name}: added data deps: ${addedDeps.join(", ")}`);
     }
 
     // Narrowing the cited surface is deliberate (AGENTS.md #4, #12), so removal is breaking.
     for (const field of ["atlas_refs", "attack_refs", "framework_gaps", "rfc_refs", "cwe_refs", "d3fend_refs", "dlp_refs"]) {
-      const removed = b[field].filter(r => !c[field].includes(r));
+      const bRefs = asArray(b[field], name, `baseline ${field}`);
+      const cRefs = asArray(c[field], name, field);
+      const removed = bRefs.filter(r => !cRefs.includes(r));
       if (removed.length > 0) {
         breaking.push(`${name}: removed ${field}: ${removed.join(", ")}`);
       }
-      const added = c[field].filter(r => !b[field].includes(r));
+      const added = cRefs.filter(r => !bRefs.includes(r));
       if (added.length > 0) {
         additive.push(`${name}: added ${field}: ${added.join(", ")}`);
       }

package/scripts/check-test-coverage.js

@@ -37,10 +37,26 @@ function parseArgs(argv) {
 
 function printHelp() {
   const banner =
+    "check-test-coverage — report changed surface that no test covers.\n" +
+    "\n" +
     "Usage: node scripts/check-test-coverage.js [--base <ref>] [--staged]\n" +
     "                                          [--json] [--warn-only]\n" +
     "\n" +
-    "See file header for full surface + categorization rules.\n";
+    "Flags:\n" +
+    "  --base <ref>   compare against <ref>..HEAD (default: origin/main)\n" +
+    "  --staged       compare the staged set instead of a ref range\n" +
+    "  --json         emit the result as JSON instead of a text report\n" +
+    "  --warn-only    report findings but always exit 0\n" +
+    "\n" +
+    "Surfaces checked: CLI verbs and flags in bin/exceptd.js, exported functions\n" +
+    "in lib / orchestrator / scripts, playbook detect-indicator and look-artifact\n" +
+    "ids, and CVE entries whose iocs changed.\n" +
+    "\n" +
+    "Categorization: docs, tooling dotfiles, tests/ itself and derived indexes are\n" +
+    "allowlisted; workflows, manifests, schemas, SBOM and unclassified files are\n" +
+    "surfaced as manual-review, never auto-green.\n" +
+    "\n" +
+    "Exit codes: 0 clean or --warn-only, 1 uncovered surface, 2 runner error.\n";
   process.stdout.write(banner);
 }
 

package/scripts/refresh-mitre-atlas.js

@@ -4,7 +4,11 @@
  * Thin per-type wrapper for the MITRE ATLAS refresher; the logic lives in
  * scripts/refresh-upstream-catalogs.js#refreshAtlas. Wired as
  * `npm run refresh-mitre-atlas`, and takes --dry-run.
+ *
+ * `CAP=<n>` bounds how many NEW techniques one run may add, matching every
+ * other per-type wrapper. Context backfill onto existing rows is never capped.
  */
 const { refreshAtlas } = require("./refresh-upstream-catalogs.js");
 const dry = process.argv.includes("--dry-run");
-refreshAtlas({ dry }).catch((e) => { console.error("[err]", e); process.exit(1); });
+const cap = Number(process.env.CAP || Infinity);
+refreshAtlas({ dry, cap }).catch((e) => { console.error("[err]", e); process.exit(1); });

package/scripts/refresh-mitre-ics-attack.js

@@ -4,7 +4,11 @@
  * `npm run refresh-mitre-ics-attack [-- --dry-run]` — per-type wrapper for the
  * MITRE ICS-attack STIX refresher; the logic lives in
  * scripts/refresh-upstream-catalogs.js#refreshIcsAttack.
+ *
+ * `CAP=<n>` bounds how many NEW techniques one run may add, matching every
+ * other per-type wrapper. Context backfill onto existing rows is never capped.
  */
 const { refreshIcsAttack } = require("./refresh-upstream-catalogs.js");
 const dry = process.argv.includes("--dry-run");
-refreshIcsAttack({ dry }).catch((e) => { console.error("[err]", e); process.exit(1); });
+const cap = Number(process.env.CAP || Infinity);
+refreshIcsAttack({ dry, cap }).catch((e) => { console.error("[err]", e); process.exit(1); });

package/scripts/refresh-rfc-index.js

@@ -3,7 +3,12 @@
 /**
  * Refreshes only the RFC catalog, leaving ATT&CK / ATLAS / D3FEND untouched.
  * Logic lives in scripts/refresh-upstream-catalogs.js#refreshRfc.
+ *
+ * `CAP=<n>` bounds how many NEW rows one run may add — the upstream RFC index
+ * carries ~9000 entries, so an uncapped first run imports all of them at once.
+ * Context backfill onto rows already curated is never capped.
  */
 const { refreshRfc } = require("./refresh-upstream-catalogs.js");
 const dry = process.argv.includes("--dry-run");
-refreshRfc({ dry }).catch((e) => { console.error("[err]", e); process.exit(1); });
+const cap = Number(process.env.CAP || Infinity);
+refreshRfc({ dry, cap }).catch((e) => { console.error("[err]", e); process.exit(1); });

package/scripts/refresh-upstream-catalogs.js

@@ -14,15 +14,6 @@ const path = require("path");
 const ROOT = path.join(__dirname, "..");
 const TODAY = new Date().toISOString().slice(0, 10);
 
-// Required-context field names come from the audit-catalog-gaps SPEC, never a
-// second hardcoded list that would drift from it.
-const AUDIT_SPEC = require("./audit-catalog-gaps.js").SPEC;
-function specRequiredFields(catalogKey) {
-  const spec = AUDIT_SPEC[catalogKey];
-  if (!spec || !Array.isArray(spec.required_context)) return [];
-  return spec.required_context.map((r) => r.field);
-}
-
 const MAX_REDIRECTS = 5;
 
 // Rejects on anything but a 2xx, so an error body can never reach a consumer as
@@ -186,7 +177,7 @@ function parseRfcEntry(blk) {
   };
 }
 
-async function refreshRfc({ dry = false, _deps = {} } = {}) {
+async function refreshRfc({ dry = false, cap = Infinity, _deps = {} } = {}) {
   const _fetchUrl = _deps.fetchUrl || fetchUrl;
   const _loadCatalog = _deps.loadCatalog || loadCatalog;
   const _writeCatalog = _deps.writeCatalog || writeCatalog;
@@ -254,6 +245,9 @@ async function refreshRfc({ dry = false, _deps = {} } = {}) {
     // Existing rows handled in the first-pass backfill above.
     if (existing.has(id)) continue;
     if (e.status === "UNKNOWN") continue;
+    // The cap bounds new adds only; the backfill pass above is unbounded, so a
+    // capped run still completes context on every row already curated.
+    if (added >= cap) continue;
     const obsoleted = !!e.obsoleted || e.status === "HISTORIC";
     cat[id] = {
       number: e.num,
@@ -479,6 +473,7 @@ async function refreshIcsAttack({ dry = false, cap = Infinity, _deps = {} } = {}
   const local = _loadCatalog("attack-techniques.json");
   const existing = new Set(Object.keys(local).filter((k) => k !== "_meta"));
   let added = 0, backfilled = 0;
+  const skippedNoIcsTactic = [];
   for (const t of techs) {
     const extRef = (t.external_references || []).find((r) => r.source_name === "mitre-ics-attack" || r.source_name === "mitre-attack");
     if (!extRef || !extRef.external_id) continue;
@@ -486,6 +481,17 @@ async function refreshIcsAttack({ dry = false, cap = Infinity, _deps = {} } = {}
     const tactics = (t.kill_chain_phases || [])
       .filter((p) => (p.kill_chain_name || "").includes("ics"))
       .map((p) => ICS_TACTIC_NAME[p.phase_name] || `${p.phase_name} (ICS)`);
+    // The external-reference match above accepts a cross-listed enterprise
+    // reference, while the tactic map keeps ICS kill-chain phases only. An
+    // object matched by the first and not the second would land with
+    // `tactic: []`, which audit-catalog-gaps counts as a missing-context gap
+    // the moment it is written — the import spending gap budget on itself.
+    // Enterprise-only techniques belong to refreshAttack, so skip them here,
+    // and report the count so the omission is observable rather than silent.
+    if (tactics.length === 0) {
+      skippedNoIcsTactic.push(id);
+      continue;
+    }
     const fullDesc = String(t.description || "").replace(/\s+/g, " ").trim();
     let shortDesc = fullDesc.split(/\.\s/)[0];
     if (shortDesc.length > 500) shortDesc = shortDesc.slice(0, 497) + "...";
@@ -514,7 +520,10 @@ async function refreshIcsAttack({ dry = false, cap = Infinity, _deps = {} } = {}
     existing.add(id);
     added++;
   }
-  if (dry) { console.log(`[refresh-upstream:ics-attack] DRY-RUN: +${added} new, ${backfilled} backfills`); return { added, backfilled }; }
+  if (skippedNoIcsTactic.length) {
+    console.log(`[refresh-upstream:ics-attack] skipped ${skippedNoIcsTactic.length} technique(s) with no ICS kill-chain phase (enterprise-only, handled by the ATT&CK refresher): ${skippedNoIcsTactic.slice(0, 10).join(", ")}${skippedNoIcsTactic.length > 10 ? ", ..." : ""}`);
+  }
+  if (dry) { console.log(`[refresh-upstream:ics-attack] DRY-RUN: +${added} new, ${backfilled} backfills`); return { added, backfilled, skipped_no_ics_tactic: skippedNoIcsTactic.length }; }
   const changed = added > 0 || backfilled > 0;
   if (changed) {
     if (local._meta) { local._meta.last_updated = TODAY; local._meta.last_threat_review = TODAY; }
@@ -523,7 +532,7 @@ async function refreshIcsAttack({ dry = false, cap = Infinity, _deps = {} } = {}
   } else {
     console.log("[ok] attack-techniques.json: no upstream ICS changes — file unchanged");
   }
-  return { added, backfilled };
+  return { added, backfilled, skipped_no_ics_tactic: skippedNoIcsTactic.length };
 }
 
 const ATLAS_SRC = "https://raw.githubusercontent.com/mitre-atlas/atlas-navigator-data/main/dist/stix-atlas.json";
@@ -595,7 +604,7 @@ function backfillAtlas(cur, fresh) {
   return touched;
 }
 
-async function refreshAtlas({ dry = false, _deps = {} } = {}) {
+async function refreshAtlas({ dry = false, cap = Infinity, _deps = {} } = {}) {
   const _fetchUrl = _deps.fetchUrl || fetchUrl;
   const _loadCatalog = _deps.loadCatalog || loadCatalog;
   const _writeCatalog = _deps.writeCatalog || writeCatalog;
@@ -637,6 +646,9 @@ async function refreshAtlas({ dry = false, _deps = {} } = {}) {
       if (backfillAtlas(cur, fresh)) { cur.last_verified = TODAY; backfilled++; }
       continue;
     }
+    // Bounds new adds only, matching every other refresher; backfill above runs
+    // on the full upstream set regardless of the cap.
+    if (added >= cap) continue;
     local[id] = atlasEntryFromStix(t, ext);
     existing.add(id);
     added++;

package/scripts/release.js

@@ -14,8 +14,6 @@ var ROOT = path.resolve(__dirname, "..");
 var REPO = "blamejs/exceptd-skills";
 var PKG_NAME = "@blamejs/exceptd-skills";
 
-var RERUN_LIMIT = 2;
-
 // Windows resolves `npm` / `npx` as `.cmd` shims, which child_process can only
 // invoke through a shell; `git`, `gh` and `node` are native exes that spawn directly.
 function _needsShell(cmd) {

package/scripts/run-e2e-scenarios.js

@@ -52,7 +52,7 @@ function stderrBanFailures(expect, stderr) {
 }
 
 // Positive matchers against the parsed JSON body only; the stderr ban is separate.
-function diffExpect(jsonBody, expect, ctx) {
+function diffExpect(jsonBody, expect) {
   const failures = [];
   if (expect.json_path_equals) {
     for (const [p, want] of Object.entries(expect.json_path_equals)) {
@@ -136,7 +136,7 @@ function evaluateScenario(scenario, expect, res) {
   if (!body && hasJsonAssertion) {
     failures.push(`stdout did not parse as JSON; first 200 chars: ${stdout.slice(0, 200)}`);
   }
-  if (body) failures.push(...diffExpect(body, expect, { stdout, stderr, status }));
+  if (body) failures.push(...diffExpect(body, expect));
 
   // Unconditional, outside every `if (body)` branch above.
   failures.push(...stderrBanFailures(expect, stderr));

package/scripts/verify-shipped-tarball.js

@@ -39,7 +39,6 @@ function canonicalizeForTarball(value) {
 function canonicalManifestBytesForTarball(manifest) {
   const clone = Object.assign({}, manifest);
   delete clone.manifest_signature;
-  const cryptoMod = require("crypto"); // eslint-disable-line no-unused-vars
   const json = JSON.stringify(canonicalizeForTarball(clone), null, 2);
   return normalizeSkillBytes(Buffer.from(json, "utf8"));
 }