@blamejs/exceptd-skills 0.12.41 → 0.13.0

package/lib/cross-ref-api.js

@@ -37,56 +37,76 @@ const _cache = new Map();
 // can inspect.
 const _loadErrors = [];
 
-function _statMtime(p) {
-  try { return fs.statSync(p).mtimeMs; }
-  catch { return null; }
+/**
+ * v0.13.0: cache invalidation is keyed on (mtimeMs, size). Pre-v0.13 it
+ * was mtime-only, but on filesystems with 1-2s mtime granularity
+ * (FAT32, HFS+ pre-APFS, NFSv3, Docker bind-mounts that proxy mtime)
+ * a rapid refresh-then-reload within the same second served stale
+ * cached data. Adding `size` catches every content change that affects
+ * byte count; mtimeMs catches in-place rewrites that preserve byte
+ * count. Together they cover every realistic catalog-mutation path
+ * without the cost of a per-load SHA computation. SHA-based tier is
+ * available via _statContentHash() when callers want full invalidation
+ * (e.g. long-running daemons against append-only catalogs).
+ */
+function _statSignature(p) {
+  try {
+    const s = fs.statSync(p);
+    return { mtime: s.mtimeMs, size: s.size };
+  } catch { return null; }
+}
+
+function _signatureEquals(a, b) {
+  if (a === null && b === null) return true;
+  if (a === null || b === null) return false;
+  return a.mtime === b.mtime && a.size === b.size;
 }
 
 function loadCatalog(filename) {
   const full = path.join(DATA_DIR, filename);
-  const mtime = _statMtime(full);
+  const sig = _statSignature(full);
   const cached = _cache.get(filename);
-  if (cached && (mtime === null || cached.mtime === mtime)) {
+  if (cached && (sig === null || _signatureEquals(cached.sig, sig))) {
     return cached.value;
   }
   if (!fs.existsSync(full)) {
-    _cache.set(filename, { value: {}, mtime });
+    _cache.set(filename, { value: {}, sig });
     return {};
   }
   try {
     const parsed = JSON.parse(fs.readFileSync(full, 'utf8'));
-    _cache.set(filename, { value: parsed, mtime });
+    _cache.set(filename, { value: parsed, sig });
     return parsed;
   } catch (e) {
     _loadErrors.push({ kind: 'catalog', file: filename, error: e.message });
     const stub = {};
     Object.defineProperty(stub, '_loadError', { value: e.message, enumerable: false });
-    _cache.set(filename, { value: stub, mtime });
+    _cache.set(filename, { value: stub, sig });
     return stub;
   }
 }
 
 function loadIndex(filename) {
   const full = path.join(INDEX_DIR, filename);
-  const mtime = _statMtime(full);
+  const sig = _statSignature(full);
   const key = 'idx:' + filename;
   const cached = _cache.get(key);
-  if (cached && (mtime === null || cached.mtime === mtime)) {
+  if (cached && (sig === null || _signatureEquals(cached.sig, sig))) {
     return cached.value;
   }
   if (!fs.existsSync(full)) {
-    _cache.set(key, { value: {}, mtime });
+    _cache.set(key, { value: {}, sig });
     return {};
   }
   try {
     const parsed = JSON.parse(fs.readFileSync(full, 'utf8'));
-    _cache.set(key, { value: parsed, mtime });
+    _cache.set(key, { value: parsed, sig });
     return parsed;
   } catch (e) {
     _loadErrors.push({ kind: 'index', file: filename, error: e.message });
     const stub = {};
     Object.defineProperty(stub, '_loadError', { value: e.message, enumerable: false });
-    _cache.set(key, { value: stub, mtime });
+    _cache.set(key, { value: stub, sig });
     return stub;
   }
 }

package/lib/cve-curation.js

@@ -637,7 +637,18 @@ function applyAnswersUnderLock(cveId, catalog, catalogPath, answers) {
 
 function writeJsonAtomic(p, obj) {
   const tmpPath = `${p}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
-  fs.writeFileSync(tmpPath, JSON.stringify(obj, null, 2) + "\n", "utf8");
+  // v0.13.0: fsync the tmp file before rename so a power loss between
+  // write and rename leaves the durable destination intact. Without
+  // fsync the data sits in the OS page cache and the rename succeeds
+  // atomically, but the renamed file may be zero-length / partial on
+  // crash. Open + write + fsync + close + rename is the durable idiom.
+  const fd = fs.openSync(tmpPath, 'w');
+  try {
+    fs.writeSync(fd, JSON.stringify(obj, null, 2) + "\n", 0, "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
   try {
     fs.renameSync(tmpPath, p);
   } catch (err) {

package/lib/exit-codes.js

@@ -66,9 +66,38 @@ function listExitCodes() {
   }));
 }
 
+/**
+ * Set the process exit code WITHOUT calling process.exit(). Returns to the
+ * caller so any pending stdout/stderr writes drain on natural event-loop
+ * shutdown.
+ *
+ * `process.exit(N)` terminates the process synchronously, which truncates
+ * buffered async stdout when stdout is piped (CI, test harnesses, --json
+ * consumers). The v0.11.10 CI #100 fix established the exitCode-then-return
+ * idiom for that reason; every subsequent regression that re-introduced
+ * bare process.exit() in the dispatch surface was the same class of bug.
+ *
+ * Callers SHOULD prefer this helper for any exit-after-stdout-write path.
+ * Long-running daemons / tests that need synchronous termination can still
+ * use process.exit() directly — that's intentional and not what this guards.
+ *
+ * @param {number} code Exit code (use the EXIT_CODES constants)
+ * @returns {void}
+ */
+function safeExit(code) {
+  // Only override exitCode when it isn't already set to a non-zero value —
+  // matches the emit() ok:false fallback contract so a caller that already
+  // set BLOCKED (4) before emit() doesn't get overwritten by a later
+  // GENERIC_FAILURE (1).
+  if (!process.exitCode || process.exitCode === 0) {
+    process.exitCode = code;
+  }
+}
+
 module.exports = {
   EXIT_CODES,
   EXIT_CODE_DESCRIPTIONS,
   exitCodeName,
   listExitCodes,
+  safeExit,
 };

package/lib/lint-skills.js

@@ -243,6 +243,11 @@ function extractFrontmatterBlock(content) {
 /* Validate frontmatter object against the codified schema rules. */
 function validateFrontmatter(fm, skillName) {
   const errors = [];
+  // v0.13.0: validateFrontmatter now ALSO surfaces warnings (e.g. the
+  // last_threat_review 180-day soft cap). Return signature changes from
+  // `string[]` to `{ errors: string[], warnings: string[] }` — callers
+  // updated accordingly.
+  const warnings = [];
 
   for (const key of Object.keys(fm)) {
     if (!ALL_KNOWN_FIELDS.has(key)) {
@@ -351,10 +356,25 @@ function validateFrontmatter(fm, skillName) {
       errors.push(
         `frontmatter.last_threat_review "${fm.last_threat_review}" is not an ISO date (YYYY-MM-DD)`,
       );
+    } else {
+      // v0.13.0: Hard Rule #8 forcing function — refuse skills whose
+      // last_threat_review is older than the staleness threshold.
+      // 180-day soft cap (warn), 365-day hard cap (fail). Operators on
+      // older releases who don't refresh fall off the supported window.
+      const days = Math.floor((Date.now() - Date.parse(fm.last_threat_review + 'T00:00:00Z')) / (24 * 60 * 60 * 1000));
+      if (days > 365) {
+        errors.push(
+          `frontmatter.last_threat_review "${fm.last_threat_review}" is ${days} days old — Hard Rule #8 staleness gate (hard fail at >365 days). Refresh the threat review against current intel and bump the date.`,
+        );
+      } else if (days > 180) {
+        warnings.push(
+          `frontmatter.last_threat_review "${fm.last_threat_review}" is ${days} days old — Hard Rule #8 staleness warning (warn at >180 days, hard fail at >365). Schedule a review.`,
+        );
+      }
     }
   }
 
-  return errors;
+  return { errors, warnings };
 }
 
 /* L1 — Heading-anchored section detection.
@@ -460,7 +480,9 @@ function lintSkill(entry, ctx) {
     return { name: entry.name, errors: skillErrors, warnings: skillWarnings };
   }
 
-  skillErrors.push(...validateFrontmatter(fm, entry.name));
+  const fmResult = validateFrontmatter(fm, entry.name);
+  skillErrors.push(...fmResult.errors);
+  skillWarnings.push(...fmResult.warnings);
 
   if (Array.isArray(fm.data_deps)) {
     for (const dep of fm.data_deps) {

package/lib/refresh-external.js

@@ -1066,7 +1066,16 @@ function loadCtx(opts) {
 // worker threads) never collide on the same scratch path.
 function writeJsonAtomic(p, obj) {
   const tmpPath = `${p}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
-  fs.writeFileSync(tmpPath, JSON.stringify(obj, null, 2) + "\n", "utf8");
+  // v0.13.0: fsync the tmp file before rename so a power loss between
+  // write and rename leaves the durable destination intact. See the
+  // matching helper in lib/cve-curation.js for the rationale.
+  const fd = fs.openSync(tmpPath, 'w');
+  try {
+    fs.writeSync(fd, JSON.stringify(obj, null, 2) + "\n", 0, "utf8");
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
   try {
     fs.renameSync(tmpPath, p);
   } catch (err) {

package/lib/scoring.js

@@ -346,6 +346,54 @@ function compare(cveId, catalog, opts) {
   return out;
 }
 
+/**
+ * v0.13.0: detect rwep_factors shape. The catalog historically stored
+ * factors in two distinct shapes that look identical at the field level:
+ *
+ *   Shape A (raw):    `{ cisa_kev: true, blast_radius: 30, ... }`
+ *     - booleans + integers in their natural form
+ *     - score derives from `scoreCustom(factors)` which applies weights
+ *
+ *   Shape B (post-weight): `{ cisa_kev: 25, blast_radius: 30, ... }`
+ *     - integers in their post-weight contribution (cisa_kev: 25 not true)
+ *     - score = sum of values; no second weight pass
+ *
+ * Mixing shapes inside ONE entry silently breaks the sum invariant —
+ * a CVE with `cisa_kev: true, blast_radius: 30` reports rwep 30 (just
+ * blast_radius summed) when the operator-intended score is 55 (KEV + br).
+ * Until v0.13 nothing caught this; v0.13 adds shape detection that fires
+ * an error when the entry mixes booleans with non-trivial numeric weights.
+ *
+ * Returns 'A' for raw, 'B' for post-weight, 'unknown' for empty/edge
+ * cases, or 'mixed' for the violating case.
+ */
+function detectFactorShape(factors) {
+  if (!factors || typeof factors !== 'object') return 'unknown';
+  const boolFields = ['cisa_kev', 'poc_available', 'ai_assisted_weaponization', 'ai_discovered', 'active_exploitation', 'patch_available', 'live_patch_available', 'patch_required_reboot'];
+  let sawBool = false;
+  let sawWeightedInt = false;
+  for (const [k, v] of Object.entries(factors)) {
+    if (k === 'blast_radius') continue; // always integer in both shapes
+    if (typeof v === 'boolean' || v === null) {
+      sawBool = true;
+    } else if (typeof v === 'number' && Math.abs(v) >= 5 && boolFields.includes(k)) {
+      // Field that's nominally boolean carrying a numeric weight (e.g. 25,
+      // 20, 15) — Shape B signature.
+      sawWeightedInt = true;
+    } else if (typeof v === 'number' && (v === 0 || v === 1) && boolFields.includes(k)) {
+      // 0/1 on a boolean-named field could be either shape; ambiguous, ignore.
+      continue;
+    } else if (typeof v === 'string' && boolFields.includes(k)) {
+      // String values (e.g. active_exploitation: 'confirmed') are Shape A.
+      sawBool = true;
+    }
+  }
+  if (sawBool && sawWeightedInt) return 'mixed';
+  if (sawWeightedInt) return 'B';
+  if (sawBool) return 'A';
+  return 'unknown';
+}
+
 function validate(catalog) {
   const errors = [];
   for (const [cveId, entry] of Object.entries(catalog)) {
@@ -371,6 +419,13 @@ function validate(catalog) {
     if (entry.live_patch_available && (!entry.live_patch_tools || entry.live_patch_tools.length === 0)) {
       errors.push(`${cveId}: live_patch_available=true but live_patch_tools is empty`);
     }
+    // v0.13.0: detect Shape A / Shape B / mixed factor shape. A 'mixed'
+    // shape would silently break the sum invariant; refuse it. See
+    // detectFactorShape() doc above for the failure mode.
+    const shape = detectFactorShape(entry.rwep_factors);
+    if (shape === 'mixed') {
+      errors.push(`${cveId}: rwep_factors mixes Shape A (booleans) with Shape B (post-weight integers) — sum invariant cannot hold. Convert factors to a single shape.`);
+    }
     const calculatedRwep = scoreCustom({
       cisa_kev: entry.cisa_kev,
       poc_available: entry.poc_available,