@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/lib/ttp-mapper.js

@@ -8,10 +8,8 @@
 const hasOwn = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
 
 function map(controlId, gapCatalog) {
-  // hasOwnProperty guard: a bare gapCatalog[controlId] dereferences inherited
-  // Object.prototype members, so controlId='__proto__' / 'toString' /
-  // 'constructor' returned found:true for a key that is not a real catalog
-  // entry. Only own enumerable keys are catalog controls.
+  // hasOwn, not a bare gapCatalog[controlId]: '__proto__' / 'toString' /
+  // 'constructor' otherwise resolve an inherited member and report found:true.
   if (!gapCatalog || !hasOwn(gapCatalog, controlId)) {
     return { control_id: controlId, found: false, message: 'Control not in gap catalog' };
   }
@@ -45,43 +43,35 @@ function gapsFor(attackPattern, gapCatalog, atlasCatalog) {
 }
 
 function coverage(frameworkId, ttpId, gapCatalog, atlasCatalog) {
-  // Input guard before any deref — an empty / non-string frameworkId
-  // yielded frameworkPrefix='' which matched EVERY control via
-  // includes(''), and null/undefined threw on .split(). Match the
-  // { found:false } contract already used for an unknown TTP. Surface
-  // partially_covered_by / not_covered_by as an explicit null (not absent)
-  // so the no-match outcome is observable rather than a silent universal
-  // match.
+  // Guard before any deref: an empty frameworkId yields a prefix of '' that
+  // matches every control, and a non-string throws on .split().
+  // partially_covered_by / not_covered_by come back explicitly null, so the
+  // no-match outcome is observable rather than a silent universal match.
   if (typeof frameworkId !== 'string' || frameworkId.trim() === '') {
     return { ttp_id: ttpId, found: false, error: 'frameworkId required', partially_covered_by: null, not_covered_by: null };
   }
 
-  // hasOwnProperty guard: ttpId='__proto__' / 'toString' / 'constructor'
-  // would otherwise resolve to an inherited Object.prototype member and be
-  // treated as a real ATLAS technique. Only own keys are catalog techniques.
+  // Same guard for ttpId: an inherited Object.prototype member would otherwise
+  // be treated as a real ATLAS technique.
   if (!atlasCatalog || !hasOwn(atlasCatalog, ttpId)) {
     return { ttp_id: ttpId, found: false };
   }
   const ttp = atlasCatalog[ttpId];
   if (!ttp) return { ttp_id: ttpId, found: false };
 
-  // atlas-ttps.json uses controls_that_partially_help / controls_that_dont_help / framework_gap_detail
   const partialControls = ttp.controls_that_partially_help || [];
   const noHelpControls = ttp.controls_that_dont_help || [];
   const gapDetail = ttp.framework_gap_detail || '';
   const hasFrameworkGap = ttp.framework_gap === true;
 
-  // Check if the requested framework has any coverage in the partially-helpful
-  // controls. Match on the first hyphen-delimited segment of the control id
-  // (token-boundary), NOT bare substring containment: a bare includes() let
-  // 'IS' match 'NIST' and '' match everything. A control id matches when it
-  // begins with the prefix and the next char is a segment boundary (-, .) or
-  // end-of-string, so 'soc2' still matches 'soc2-z' but 'is' never matches
-  // 'nist-...'.
+  // Match the first hyphen-delimited segment of a control id, not bare
+  // containment: includes() lets 'IS' match 'NIST' and '' match everything. A
+  // control matches when it starts with the prefix and the next character ends
+  // the segment (-, . or end), so 'soc2' still matches 'soc2-z'.
   const frameworkPrefix = frameworkId.split('-')[0].toLowerCase();
   if (frameworkPrefix.length === 0) {
-    // frameworkId is a hyphen-led string (e.g. "-" or "-X") whose first
-    // segment is empty — same universal-match hazard, same fail-closed result.
+    // A hyphen-led frameworkId ("-X") has an empty first segment — the same
+    // universal-match hazard, so the same fail-closed result.
     return { ttp_id: ttpId, found: false, error: 'frameworkId required', partially_covered_by: null, not_covered_by: null };
   }
   const segMatch = (c) => {

package/lib/upstream-check-cli.js

@@ -2,23 +2,11 @@
 "use strict";
 
 /**
- * lib/upstream-check-cli.js
- *
- * Small wrapper that calls lib/upstream-check.fetchLatestPublished() and
- * emits the freshness report as JSON to stdout. Used internally by:
- *   - `exceptd doctor --registry-check`
- *   - `exceptd run --upstream-check`
- *   - `exceptd refresh --network`
- *
- * Runs in a child process so the parent verb stays synchronous and the
- * network timeout is bounded by the spawnSync timeout.
- *
- * Output: one JSON line to stdout. Exits 0 even when the registry is
- * unreachable (offline ≠ error — the freshness signal degrades gracefully).
- *
- * Flags:
- *   --timeout <ms>   override the default 5000 ms network timeout
- *   --raw            emit raw registry response instead of freshness report
+ * Emits lib/upstream-check's freshness report as one JSON line on stdout.
+ * Spawned as a child process so the calling verb stays synchronous and the
+ * network timeout is bounded by the spawnSync timeout. Exits 0 even when the
+ * registry is unreachable: callers parse the envelope off stdout, and absent
+ * freshness data is a degraded signal rather than an error.
  */
 
 const path = require("path");
@@ -54,11 +42,8 @@ function readManifest() {
 
 (async () => {
   const opts = parseArgs(process.argv);
-  // Air-gap short-circuit — the registry probe is a network operation. When
-  // the operator has declared air-gapped mode (env var OR --air-gap), emit a
-  // structured `skipped` envelope and exit 0. Exit 0 because, like the
-  // existing "offline" path, missing freshness data is a graceful degradation
-  // — it is NOT an error condition for downstream callers.
+  // The registry probe is a network call, so air-gap mode answers with a
+  // `skipped` envelope instead. `ok: null` is neither pass nor fail.
   if (process.env.EXCEPTD_AIR_GAP === "1" || opts.airGap) {
     process.stdout.write(JSON.stringify({
       ok: null,
@@ -81,12 +66,9 @@ function readManifest() {
   });
   process.stdout.write(JSON.stringify(report) + "\n");
 })().catch((err) => {
-  // Any unexpected throw still yields one parseable JSON line on stdout and a
-  // clean exit, consistent with this probe's offline-degradation contract
-  // (missing freshness data is not an error for downstream callers, which parse
-  // res.stdout for the envelope). String(...) coerces the error to a primitive,
-  // so this JSON.stringify itself cannot throw. Exit 0 is the default — no prior
-  // non-zero exitCode is set on this path.
+  // Any throw still yields one parseable JSON line and exit 0, per the
+  // degradation contract above. String(...) coerces the error to a primitive so
+  // this JSON.stringify cannot itself throw.
   process.stdout.write(JSON.stringify({
     ok: false,
     error: String((err && err.message) || err),

package/lib/upstream-check.js

@@ -1,19 +1,11 @@
 "use strict";
 
 /**
- * lib/upstream-check.js
- *
- * Shared helper used by `doctor --registry-check`, `run --upstream-check`,
- * and `refresh --network`. Queries the npm registry for the package's
- * latest published version + publish timestamp. Operator opts in — never
- * fired automatically on every CLI invocation.
- *
- * Trust model: the registry call is a freshness signal, not a trust
- * anchor. The Ed25519-signed skill catalog shipped in the operator's
- * installed package remains the source of truth. This helper only
- * reports "you're N days behind" — does not auto-update anything.
- *
- * Zero npm deps. Node 24 stdlib only.
+ * Queries the npm registry for the package's latest published version and
+ * publish time, for `doctor --registry-check`, `run --upstream-check` and
+ * `refresh --network`. The registry call is a freshness signal, not a trust
+ * anchor: the Ed25519-signed local catalog stays the source of truth, and this
+ * reports how far behind it is without updating anything.
  */
 
 const https = require("https");
@@ -23,21 +15,14 @@ const PKG_NAME = "@blamejs/exceptd-skills";
 const REQUEST_TIMEOUT_MS = 5000;
 
 /**
- * Fetch the latest version + publish time from the npm registry.
- *
- * Returns:
- *   { ok: true,  version: "0.11.14", published_at: ISO_STRING, source: "npm-registry" }
- *   { ok: false, error: "timeout" | "offline" | "parse" | string, source: "offline" }
- *
- * Honors EXCEPTD_REGISTRY_FIXTURE env var for offline testing — value is
- * a path to a JSON file with { version, time: { <ver>: ISO } } shape.
+ * Returns { ok: true, version, published_at, source: "npm-registry" }, or
+ * { ok: false, error, source: "offline" } — never throws, so a caller treats an
+ * absent freshness signal as absent rather than as an error.
+ * EXCEPTD_REGISTRY_FIXTURE points at a JSON file shaped
+ * { version, time: { <ver>: ISO } } for offline runs.
  */
 async function fetchLatestPublished({ timeoutMs = REQUEST_TIMEOUT_MS, pkgName = PKG_NAME } = {}) {
-  // Air-gap refusal — registry probes are a network operation and must never
-  // be issued when the operator has declared an air-gapped environment.
-  // Returning a structured refusal (instead of throwing) lets callers degrade
-  // gracefully the same way they handle `offline` — the freshness signal is
-  // intentionally absent, not in error.
+  // A network operation: air-gap gets a structured refusal, as `offline` does.
   if (process.env.EXCEPTD_AIR_GAP === "1") {
     return { ok: false, error: "air-gap-blocked", source: "fetchLatestPublished" };
   }
@@ -47,11 +32,8 @@ async function fetchLatestPublished({ timeoutMs = REQUEST_TIMEOUT_MS, pkgName =
       const fs = require("fs");
       const fixture = JSON.parse(fs.readFileSync(process.env.EXCEPTD_REGISTRY_FIXTURE, "utf8"));
       const version = fixture["dist-tags"]?.latest || fixture.version;
-      // Same guard the network branch applies: a fixture with neither
-      // dist-tags.latest nor a top-level version yields no freshness signal.
-      // Returning ok:true with version:undefined would let an undefined
-      // version leak into buildFreshnessReport's semver compare and the
-      // operator-facing hint. Degrade to an explicit offline refusal.
+      // Same guard as the network branch: ok:true with version undefined leaks
+      // into buildFreshnessReport's semver compare and its hint.
       if (!version) {
         return { ok: false, error: "fixture missing dist-tags.latest / version", source: "offline" };
       }
@@ -99,9 +81,8 @@ async function fetchLatestPublished({ timeoutMs = REQUEST_TIMEOUT_MS, pkgName =
 }
 
 /**
- * Semver compare (returns -1, 0, 1). Accepts canonical N.N.N strings only;
- * pre-release tags are ignored (rare on this package, and operators behind
- * a pre-release would explicitly opt in).
+ * Semver compare, returning -1, 0 or 1. Canonical N.N.N only; a pre-release tag
+ * is ignored rather than ordered.
  */
 function semverCmp(a, b) {
   const pa = String(a).split(".").map((n) => parseInt(n, 10) || 0);
@@ -113,10 +94,7 @@ function semverCmp(a, b) {
   return 0;
 }
 
-/**
- * Build the operator-facing freshness report. Pure function — takes the
- * registry response and the local version/manifest, returns the report.
- */
+/** Operator-facing freshness report. Pure — no I/O of its own. */
 function buildFreshnessReport({ localVersion, registry, localManifest }) {
   if (!registry || !registry.ok) {
     return {
@@ -128,16 +106,13 @@ function buildFreshnessReport({ localVersion, registry, localManifest }) {
     };
   }
   const cmp = semverCmp(localVersion, registry.version);
-  // Parse the publish timestamp once and validate it. A non-empty but
-  // unparseable date string (e.g. a malformed registry `time` value) makes
-  // `new Date(...).getTime()` return NaN, which would otherwise propagate
-  // NaN into days_since_latest_publish. Degrade an unparseable date to the
-  // explicit null (signal-absent) branch instead of emitting NaN.
+  // An unparseable registry `time` yields NaN from getTime(); it degrades to the
+  // explicit null signal-absent branch rather than reaching the report.
   const publishedTs = registry.published_at ? new Date(registry.published_at).getTime() : NaN;
   const daysBehind = Number.isFinite(publishedTs)
     ? Math.max(0, Math.floor((Date.now() - publishedTs) / (24 * 3600 * 1000)))
     : null;
-  // Manifest's last_threat_review (per-skill) — surface the most stale.
+  // last_threat_review is per-skill; the report surfaces the most stale.
   let oldestReview = null;
   if (localManifest && Array.isArray(localManifest.skills)) {
     for (const s of localManifest.skills) {

package/lib/validate-catalog-meta.js

@@ -1,29 +1,10 @@
 #!/usr/bin/env node
 /*
- * lib/validate-catalog-meta.js — assert every data/*.json carries the
- * source-trust + freshness fields required by the audit follow-up:
- *
- *   _meta.tlp                 — Traffic Light Protocol marking
- *   _meta.source_confidence   — Admiralty scheme (A-F + 1-6), with
- *                                default rating and per-entry override note
- *   _meta.freshness_policy    — review cadence + decay thresholds
- *
- * Per AGENTS.md rule #10 (no placeholder language), this validator
- * rejects empty strings and the usual placeholder tokens. Rule #12
- * (external data version pinning) is enforced informally — every catalog
- * still needs its existing schema_version / last_updated fields, but
- * those are validated by the existing per-catalog validators.
- *
- * Usage:
- *   node lib/validate-catalog-meta.js
- *   node lib/validate-catalog-meta.js --quiet
- *
- * Exit code:
- *   0  all catalogs have the required _meta fields
- *   1  one or more catalogs missing a required field
- *   2  argv error
- *
- * No external dependencies. Node 24 stdlib only.
+ * Asserts every data/*.json carries its source-trust and freshness fields:
+ * _meta.tlp (TLP marking), _meta.source_confidence (Admiralty scheme) and
+ * _meta.freshness_policy. Empty strings and placeholder tokens are rejected.
+ * Exits 0 when every catalog passes, 1 on a missing or malformed field, 2 on an
+ * argv error. --strict promotes freshness warnings to errors.
  */
 
 'use strict';
@@ -85,14 +66,10 @@ function containsPlaceholder(s) {
   return PLACEHOLDER_TOKENS.some((re) => re.test(s));
 }
 
-// Round-trip ISO calendar-date check. Returns a Date for a real YYYY-MM-DD
-// calendar date, or null for anything malformed. Unlike a shape-only regex,
-// this rejects impossible dates (2026-13-99, 2026-04-31, 2026-02-29 in a
-// non-leap year): `new Date('2026-02-30T00:00:00Z')` does NOT throw — it rolls
-// over to March 2 with a valid getTime() — so the parsed Y-M-D must round-trip
-// back to the input components. Deliberately carries NO year-floor business
-// rule (a valid-but-old 1900-01-01 stays a valid date so the staleness branch,
-// not the validity branch, reports it).
+// A Date for a real YYYY-MM-DD calendar date, null for anything else. The
+// round-trip is what rejects an impossible date: `new Date('2026-02-30')` does
+// not throw, it rolls over to March 2. No year-floor rule here — a
+// valid-but-ancient date stays valid so the staleness branch reports it.
 function parseIsoDateStrict(v) {
   if (typeof v !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(v)) return null;
   const d = new Date(v + 'T00:00:00Z');
@@ -115,19 +92,12 @@ function validateMeta(catalogPath, opts) {
   const meta = data._meta;
 
   if (!meta || typeof meta !== 'object') {
-    // Honor both return contracts. The rest of the body dereferences
-    // `meta.tlp` / `meta.source_confidence` / `meta.freshness_policy`, so it
-    // must NOT run when `meta` is absent or non-object. Return early in the
-    // SAME shape the caller asked for: includeWarnings callers (main()) get
-    // `{errors, warnings}` so `result.errors` is a real array and the loop
-    // reports a clean FAIL + continues; no-opts callers still get a non-empty
-    // `string[]`. This still FAILS — it only removes the uncaught TypeError.
+    // Must return here — everything below dereferences `meta.*`.
     errors.push('missing _meta block');
     if (opts && opts.includeWarnings) return { errors, warnings };
     return errors;
   }
 
-  /* tlp */
   if (typeof meta.tlp !== 'string') {
     errors.push('_meta.tlp is missing or not a string');
   } else if (!REQUIRED_TLP_VALUES.has(meta.tlp)) {
@@ -136,7 +106,6 @@ function validateMeta(catalogPath, opts) {
     );
   }
 
-  /* source_confidence */
   const sc = meta.source_confidence;
   if (!sc || typeof sc !== 'object') {
     errors.push('_meta.source_confidence is missing or not an object');
@@ -157,7 +126,6 @@ function validateMeta(catalogPath, opts) {
     }
   }
 
-  /* freshness_policy */
   const fp = meta.freshness_policy;
   if (!fp || typeof fp !== 'object') {
     errors.push('_meta.freshness_policy is missing or not an object');
@@ -179,8 +147,6 @@ function validateMeta(catalogPath, opts) {
     } else if (containsPlaceholder(fp.note)) {
       errors.push('_meta.freshness_policy.note contains placeholder language');
     }
-    /* Soft check: cadence < stale < rebuild. Catches an obvious copy-paste
-     * mistake without being a hard schema constraint. */
     if (
       typeof fp.default_review_cadence_days === 'number' &&
       typeof fp.stale_after_days === 'number' &&
@@ -198,15 +164,8 @@ function validateMeta(catalogPath, opts) {
       }
     }
 
-    /* freshness enforcement. When both meta.last_updated and
-     * freshness_policy.stale_after_days are present, surface a warning if
-     * (now - last_updated) > stale_after_days. Emitted at WARN level by
-     * default (does not fail validation).
-     *
-     * Optional `opts.strict` (or `opts.errorOnStale`) promotes the warning
-     * to an error; the predeploy gate runs --strict, plain validation keeps
-     * the warning posture.
-     */
+    /* Staleness is a warning by default; `opts.strict` or `opts.errorOnStale`
+     * promotes it to an error, and the predeploy gate runs --strict. */
     if (
       meta.last_updated !== undefined &&
       typeof fp.stale_after_days === 'number' &&
@@ -214,10 +173,8 @@ function validateMeta(catalogPath, opts) {
     ) {
       const lu = parseIsoDateStrict(meta.last_updated);
       if (lu === null) {
-        // Fail-closed on a malformed date instead of silently skipping the
-        // freshness gate. A NaN/impossible/wrong-shape last_updated is
-        // "invalid input" (error under --strict, warning by default), NOT
-        // "no opinion" — otherwise the staleness check fails open.
+        // A malformed last_updated is invalid input, not "no opinion":
+        // skipping it here would let the staleness check fail open.
         const msg =
           `_meta.last_updated ${JSON.stringify(meta.last_updated)} is not a valid ISO date ` +
           `(YYYY-MM-DD calendar date) — cannot evaluate freshness. ` +
@@ -244,9 +201,8 @@ function validateMeta(catalogPath, opts) {
     }
   }
 
-  // Warnings are appended after errors when callers ask for the combined
-  // shape via opts.includeWarnings. Default return is errors only so the
-  // public function signature is unchanged for existing callers.
+  // Two return shapes: `{errors, warnings}` under opts.includeWarnings,
+  // otherwise a bare string[] of errors.
   if (opts && opts.includeWarnings) {
     return { errors, warnings };
   }
@@ -291,7 +247,7 @@ function main() {
   console.log(
     `\n${passed}/${total} catalogs validated${warnSuffix}${failSuffix}.`,
   );
-  // process.exitCode + return so buffered writes drain.
+  // process.exitCode, not process.exit() — the exit can truncate a piped write.
   process.exitCode = failed === 0 ? 0 : 1;
 }