@blamejs/exceptd-skills 0.19.33 → 0.19.35

package/scripts/refresh-manifest-snapshot.js

@@ -1,32 +1,16 @@
 "use strict";
 /**
- * scripts/refresh-manifest-snapshot.js
+ * Captures the public skill surface from manifest.json into
+ * manifest-snapshot.json. Run it AFTER an intentional surface change and commit
+ * the new snapshot alongside that change — never to "fix" a failing
+ * check-manifest-snapshot.js gate, whose breaking-change list is the thing to
+ * read first. A breaking change is a surface narrowing every downstream
+ * consumer needs to know about.
  *
- * Captures the current public skill surface from manifest.json and
- * writes it to manifest-snapshot.json. Run this AFTER an intentional
- * surface change (added skill, renamed trigger, refreshed framework
- * refs) and commit the new snapshot alongside the change.
- *
- * Do NOT run this to "fix" a failing check-manifest-snapshot.js gate
- * blindly — read the breaking-change list first. A breaking change is
- * a surface narrowing every downstream consumer needs to know about.
- *
- * commitOnly mode. Pass `--commit-only` (or set the env
- * EXCEPTD_SNAPSHOT_AUDIT_ACK=1) to acknowledge that the operator
- * deliberately wants to overwrite the committed snapshot. When neither
- * flag nor env is set AND the snapshot would actually change, the
- * script refuses and emits a structured diff hint. This stops an
- * accidental `npm run refresh-snapshot` (run as muscle-memory while
- * triaging a failing gate) from masking a real breaking change.
- *
- * Usage:
- *   node scripts/refresh-manifest-snapshot.js              # dry-shows the diff
- *   EXCEPTD_SNAPSHOT_AUDIT_ACK=1 \
- *     node scripts/refresh-manifest-snapshot.js            # writes the new snapshot
- *   node scripts/refresh-manifest-snapshot.js --commit-only   # same thing, on argv
- *
- * The flag is documented in scripts/predeploy.js so contributors see it
- * the moment the snapshot gate fails.
+ * Overwriting an existing snapshot takes `--commit-only` or
+ * EXCEPTD_SNAPSHOT_AUDIT_ACK=1. Without either, a run whose capture differs
+ * refuses and prints a diff hint, so muscle memory cannot mask a real breaking
+ * change. scripts/predeploy.js names the flag where the gate fails.
  */
 
 const fs = require("fs");
@@ -64,18 +48,14 @@ const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, "utf8"));
 const snapshot = captureSurface(manifest);
 const newJson = JSON.stringify(snapshot, null, 2) + "\n";
 
-// F5 — refuse to overwrite an existing snapshot unless the operator
-// has explicitly acknowledged the rewrite (env or --commit-only flag).
 const argv = process.argv.slice(2);
 const commitOnly =
   argv.includes("--commit-only") ||
   process.env.EXCEPTD_SNAPSHOT_AUDIT_ACK === "1";
 
-// Read the committed snapshot once and branch on the read RESULT rather than
-// an existsSync(SNAPSHOT_PATH)-then-readFileSync probe — the latter is a
-// check-then-use window (CodeQL js/file-system-race) where the existence the
-// guard decides on may not be the file it then reads. ENOENT IS the "no prior
-// snapshot, write a fresh one" signal.
+// Branch on the read RESULT, never on an existsSync-then-read probe: that is a
+// check-then-use window (CodeQL js/file-system-race) where the file the guard
+// decided on need not be the one read. ENOENT IS the "no prior snapshot" signal.
 let current = null;
 try {
   current = fs.readFileSync(SNAPSHOT_PATH, "utf8");
@@ -83,8 +63,7 @@ try {
   if (e.code !== "ENOENT") throw e;
 }
 if (current !== null && !commitOnly) {
-  // Normalise the _generated_at timestamp for comparison — that field
-  // changes every run and shouldn't trigger the guard.
+  // _generated_at changes every run, so it must not trigger the guard.
   const stripGenerated = (s) => s.replace(
     /"_generated_at":\s*"[^"]+",?\s*\n?/, ""
   );
@@ -108,9 +87,8 @@ fs.writeFileSync(SNAPSHOT_PATH, newJson, "utf8");
 console.log(`[refresh-manifest-snapshot] wrote ${snapshot.skill_count} skills to manifest-snapshot.json`);
 console.log("[refresh-manifest-snapshot] commit this file alongside the surface change.");
 
-// write a tracked SHA-256 of the snapshot so the
-// check-manifest-snapshot.js gate can verify integrity (no hand edits
-// after refresh).
+// A tracked SHA-256 lets check-manifest-snapshot.js catch a hand edit made
+// after the refresh.
 const crypto = require("crypto");
 const snapshotSha = crypto.createHash("sha256").update(newJson).digest("hex");
 const snapshotShaPath = path.join(ROOT, "manifest-snapshot.sha256");

package/scripts/refresh-mitre-atlas.js

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * scripts/refresh-mitre-atlas.js
+ * 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.
  *
- * Thin per-type wrapper for the MITRE ATLAS refresher. Logic lives in
- * scripts/refresh-upstream-catalogs.js#refreshAtlas.
- *
- *   node scripts/refresh-mitre-atlas.js [--dry-run]
- *
- * Wired as `npm run refresh-mitre-atlas`.
+ * `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-attack.js

@@ -1,15 +1,8 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * scripts/refresh-mitre-attack.js
- *
- * Thin per-type wrapper for the MITRE ATT&CK refresher. Logic lives in
+ * Refreshes only the MITRE ATT&CK catalog. Logic lives in
  * scripts/refresh-upstream-catalogs.js#refreshAttack.
- *
- *   node scripts/refresh-mitre-attack.js [--dry-run]
- *   CAP=200 node scripts/refresh-mitre-attack.js
- *
- * Wired as `npm run refresh-mitre-attack`.
  */
 const { refreshAttack } = require("./refresh-upstream-catalogs.js");
 const dry = process.argv.includes("--dry-run");

package/scripts/refresh-mitre-d3fend.js

@@ -1,15 +1,9 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * scripts/refresh-mitre-d3fend.js
- *
- * Thin per-type wrapper for the MITRE D3FEND refresher. Logic lives in
- * scripts/refresh-upstream-catalogs.js#refreshD3fend.
- *
- *   node scripts/refresh-mitre-d3fend.js [--dry-run]
- *   CAP=120 node scripts/refresh-mitre-d3fend.js
- *
- * Wired as `npm run refresh-mitre-d3fend`.
+ * Thin wrapper for the MITRE D3FEND refresher; the logic lives in
+ * scripts/refresh-upstream-catalogs.js#refreshD3fend. Wired as
+ * `npm run refresh-mitre-d3fend`.
  */
 const { refreshD3fend } = require("./refresh-upstream-catalogs.js");
 const dry = process.argv.includes("--dry-run");

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

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * scripts/refresh-mitre-ics-attack.js
+ * `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.
  *
- * Thin per-type wrapper for the MITRE ICS-attack STIX refresher. Logic
- * lives in scripts/refresh-upstream-catalogs.js#refreshIcsAttack.
- *
- *   node scripts/refresh-mitre-ics-attack.js [--dry-run]
- *
- * Wired as `npm run refresh-mitre-ics-attack`.
+ * `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-reverse-refs.js

@@ -1,35 +1,12 @@
 #!/usr/bin/env node
 /*
- * scripts/refresh-reverse-refs.js — rebuild reverse references in
- * data/{atlas-ttps,cwe-catalog,d3fend-catalog,rfc-references}.json from
- * the manifest.json forward direction.
- *
- * Background. Each skill in manifest.json declares forward references via
- * atlas_refs / cwe_refs / d3fend_refs / rfc_refs. The four catalogs above
- * carry a denormalised reverse field per entry (`exceptd_skills` for
- * atlas-ttps, `skills_referencing` for the other three) listing every
- * skill that points at that entry. The reverse field drifts whenever a
- * skill adds or removes a forward ref without the catalog being updated
- * in lockstep — this script rebuilds the reverse direction from the
- * forward source of truth so the two never disagree.
- *
- * Behaviour. For each catalog file:
- *   1. Walk every skill's relevant forward-ref array in manifest.json.
- *   2. For every catalog entry, list every skill that references it.
- *   3. Sort the resulting skill list and write it back into the per-entry
- *      reverse field. All other fields are preserved untouched.
- *
- * The script is idempotent: a second run produces no further changes.
- *
- * The script does NOT touch playbooks_referencing — that field carries
- * playbook ids (data/playbooks/*.json), not skill names; it has its own
- * source of truth and is out of scope for this refresh.
- *
- * Run:   node scripts/refresh-reverse-refs.js
- *        npm run refresh-reverse-refs
- *
- * Exit code: 0 always (script is unconditionally write-mode). Use
- * tests/reverse-ref-drift.test.js as the read-only drift detector.
+ * Rebuilds the denormalised reverse-reference fields in the data catalogs from the
+ * forward direction, which is the source of truth: a skill's atlas_refs / cwe_refs
+ * / d3fend_refs / rfc_refs, and a CVE's forward refs. Every other field is
+ * preserved and a second run changes nothing. `playbooks_referencing` is out of
+ * scope — it carries playbook ids, not skill names.
+ * Write-mode only, exit 0 always; the read-only drift detector is
+ * tests/reverse-ref-drift.test.js.
  */
 
 'use strict';
@@ -43,17 +20,12 @@ const CVE_CATALOG_PATH = path.join(REPO_ROOT, 'data', 'cve-catalog.json');
 const DATA_DIR = path.join(REPO_ROOT, 'data');
 
 /* Per-catalog config:
- *   file              relative path under data/
- *   forwardField      source-collection[].* array name
- *   reverseField      per-entry reverse field name in the catalog
- *   source            'manifest.skills' (default) — walk every skill's forward ref
- *                     'cve.entries'   — walk every CVE's forward ref (added in
- *                     v0.12.32); contributes CVE-IDs (skipping `_draft: true`
- *                     entries so the reverse direction tracks operator-queryable
- *                     truth, not in-progress curation state)
- *   entryKey          field on the source object used as the reverse-list value
- *                     ('name' for skills; '<self-id>' for CVE entries via the
- *                     map key, so the helper substitutes the iterating key)
+ *   file          relative path under data/
+ *   forwardField  array (or dict, with forwardFieldShape) on the source object
+ *   reverseField  per-entry field this script overwrites in the catalog
+ *   source        'manifest.skills' walks every skill; 'cve.entries' every
+ *                 non-draft CVE
+ *   entryKey      field used as the reverse-list value; null means the key itself
  */
 const CATALOGS = [
   {
@@ -84,12 +56,7 @@ const CATALOGS = [
     source: 'manifest.skills',
     entryKey: 'name',
   },
-  // v0.12.32: CVE → CWE reverse direction. CWE entries declare
-  // `evidence_cves` as the operator-facing "which CVEs land here" index;
-  // previously hand-maintained and drifted whenever a new CVE landed
-  // without the matching CWE's evidence_cves being updated. Now mirrors
-  // `cve.cwe_refs` → `cwe.evidence_cves` automatically. Drafts excluded
-  // (they're invisible to default consumers anyway).
+  // `evidence_cves` mirrors cve.cwe_refs: which CVEs land on this CWE.
   {
     file: 'cwe-catalog.json',
     forwardField: 'cwe_refs',
@@ -97,14 +64,8 @@ const CATALOGS = [
     source: 'cve.entries',
     entryKey: null, // value is the iterating CVE id
   },
-  // v0.12.40: CVE → framework-gap reverse direction. Resolved 137
-  // directional mismatches between cve.framework_control_gaps (dict-keyed
-  // by gap-id) and gap.evidence_cves (array of CVE ids). The forward
-  // shape on the CVE side is an OBJECT not an array — keys are the gap
-  // ids, values are per-CVE narrative. The reverse direction (which CVEs
-  // cite this gap) is a simple set of CVE ids on the gap entry. The
-  // helper handles the dict-keyed forward field via the
-  // `forwardFieldShape: 'object-keys'` flag.
+  // The forward side here is an OBJECT, not an array: keys are gap ids, values
+  // the per-CVE narrative, hence forwardFieldShape. The reverse is a set of ids.
   {
     file: 'framework-control-gaps.json',
     forwardField: 'framework_control_gaps',
@@ -113,12 +74,7 @@ const CATALOGS = [
     source: 'cve.entries',
     entryKey: null, // value is the iterating CVE id
   },
-  // v0.13.0: ATLAS / ATT&CK back-edge — every ATLAS TTP and ATT&CK
-  // technique gets a `cve_refs` array carrying the CVE ids that cite it.
-  // Pre-v0.13 these catalogs had only forward refs (CVE → TTP); operators
-  // reading an ATLAS / ATT&CK entry could not see which CVEs cite it
-  // without grepping the whole catalog. These back-edges make the
-  // relationship symmetric: a citation is readable from either end.
+  // `cve_refs` back-edges: an ATLAS or ATT&CK entry shows which CVEs cite it.
   {
     file: 'atlas-ttps.json',
     forwardField: 'atlas_refs',
@@ -152,16 +108,9 @@ function buildReverseIndex(skills, forwardField) {
   return index;
 }
 
-// v0.12.32: build a reverse index keyed by catalog ID from the CVE
-// catalog's forward refs. Each CVE entry has cwe_refs / attack_refs
-// arrays; the reverse side is the CVE ID, indexed by the catalog entry.
-// Draft entries are skipped — drafts are invisible to default consumers
-// via cross-ref-api, so the reverse direction should track operator-
-// queryable truth, not in-progress curation state.
-//
-// v0.12.40: forwardFieldShape parameter handles the
-// CVE.framework_control_gaps case where the forward field is a dict
-// (gap-id → narrative) rather than an array.
+// catalogEntryId -> Set<cveId>. Drafts are skipped: they are invisible to default
+// consumers through cross-ref-api. Pass forwardFieldShape 'object-keys' when the
+// forward field is a dict.
 function buildCveReverseIndex(cveCatalog, forwardField, forwardFieldShape) {
   const index = new Map();
   for (const [cveId, entry] of Object.entries(cveCatalog)) {
@@ -221,14 +170,9 @@ function rebuildCatalog(cfg, manifest, cveCatalog) {
     }
   }
 
-  // Surface forward refs that point at catalog entries that don't exist.
-  // Informational only — orphans never change the exit code (this script is
-  // unconditionally write-mode, exit 0 always; see the file header). The
-  // failing gates for the two signals this script can surface live
-  // elsewhere: orphan forward refs are hard-errored by lib/lint-skills.js
-  // ref-resolution ("<id> not present in data/<catalog>"), and reverse-field
-  // drift is hard-failed by tests/reverse-ref-drift.test.js. Do not wire
-  // this script itself as a "reverse refs clean?" check — it always passes.
+  // Orphans — forward refs naming a catalog entry that does not exist — are
+  // reported, never fatal. Never wire this script up as a "reverse refs clean?"
+  // check: the failing gates are lib/lint-skills.js and reverse-ref-drift.test.js.
   for (const id of index.keys()) {
     if (!seenIds.has(id)) orphans.push(id);
   }
@@ -249,15 +193,8 @@ function rebuildCatalog(cfg, manifest, cveCatalog) {
   };
 }
 
-/**
- * v0.13.0: playbook `fed_by` reverse direction. Every playbook declares
- * `feeds_into[]` listing playbook ids it chains TO; `fed_by[]` is the
- * symmetric "which playbooks chain into me." Pre-v0.13 operators reading
- * a playbook couldn't see what fed it without grepping every other
- * playbook's feeds_into. The reverse field lives on the playbook's
- * top-level under `_meta.fed_by` (paired with the existing _meta.feeds_into
- * for shape symmetry).
- */
+// `_meta.fed_by` is the symmetric counterpart of `_meta.feeds_into`: which
+// playbooks chain INTO this one. Writes each playbook file in place.
 function rebuildPlaybookReverse() {
   const playbooksDir = path.join(DATA_DIR, 'playbooks');
   if (!fs.existsSync(playbooksDir)) return { file: 'playbooks/*.json', source: 'playbook.feeds_into', reverseField: 'fed_by', changed: 0, added: 0, removed: 0, unchanged: 0, orphans: [] };
@@ -271,12 +208,8 @@ function rebuildPlaybookReverse() {
     if (!data || !data._meta || !data._meta.id) continue;
     playbookEntries.push({ file: f, filePath, data });
   }
-  // Build reverse index: target-id -> Set<source-id>
-  // feeds_into entries are objects with `playbook_id` + `condition`.
-  // The fed_by reverse is a simple array of source playbook ids (the
-  // condition is per-edge; preserved on feeds_into, not duplicated on
-  // fed_by — operators read fed_by to find candidates, then look at the
-  // source playbook's feeds_into for the gating condition).
+  // targetId -> Set<sourceId>. A feeds_into entry carries `playbook_id` +
+  // `condition`; fed_by keeps only the ids, so the condition is not duplicated.
   const index = new Map();
   for (const { data } of playbookEntries) {
     const meta = data._meta;

package/scripts/refresh-rfc-index.js

@@ -1,17 +1,14 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * scripts/refresh-rfc-index.js
+ * Refreshes only the RFC catalog, leaving ATT&CK / ATLAS / D3FEND untouched.
+ * Logic lives in scripts/refresh-upstream-catalogs.js#refreshRfc.
  *
- * Thin per-type wrapper for the RFC refresher. Logic lives in
- * scripts/refresh-upstream-catalogs.js#refreshRfc. Use this entry when
- * you want to refresh only the RFC catalog without touching ATT&CK /
- * ATLAS / D3FEND.
- *
- *   node scripts/refresh-rfc-index.js [--dry-run]
- *
- * Wired as `npm run refresh-rfc-index`.
+ * `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); });