@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/lib/version-pins.js

@@ -1,39 +1,10 @@
 "use strict";
 /**
- * lib/version-pins.js
- *
- * Single source of truth for the canonical MITRE / ATT&CK / ATLAS /
- * D3FEND version pins that operator-facing docs reference.
- *
- * Pre-v0.13.20 history: ATLAS version was pinned to v5.4.0 in 33+
- * locations (READMEs, AGENTS.md, ARCHITECTURE.md, agent personas,
- * skill bodies, schema descriptions, manifest.json). Bumping required
- * a lockstep regex-replace across all 33 files. v0.13.18 bumped to
- * v5.6.0; the regex sweep accidentally touched dates in unrelated
- * paragraphs and only failed-loudly because the tests asserted
- * version drift. v0.13.20 makes the pin schema-driven:
- *
- *   - `data/atlas-ttps.json._meta.atlas_version` is the source of truth.
- *   - `data/attack-techniques.json._meta.attack_version` is too.
- *   - This module reads both, exposes them via getAtlasVersion() and
- *     getAttackVersion() helpers, and is the canonical resolver every
- *     consumer (test runner, doc-currency check, lint, skill-body
- *     scanner) reaches through.
- *
- * The drift-detection tests in tests/atlas-version-canonical.test.js
- * and tests/attack-version-canonical.test.js now compare every
- * operator-facing mention against the value this module returns.
- * A future bump is `node $(exceptd path)/lib/sign.js sign-all` + this
- * module reads the new value; no lockstep doc edit needed except where
- * the mention is
- * a literal-string semantic ("upgrade from v5.4.0 to v5.6.0") that an
- * operator must read.
- *
- * API:
- *   getAtlasVersion() → "2026.06"
- *   getAttackVersion() → "19.1"
- *   getAtlasReleaseDate() → "2026-05-27"
- *   getAllPins() → { atlas_version, atlas_release_date, attack_version, ... }
+ * Canonical resolver for the MITRE ATT&CK / ATLAS version pins. The `_meta`
+ * blocks of data/atlas-ttps.json and data/attack-techniques.json are the source
+ * of truth and every consumer reads them through here, so a pin bump is a data
+ * edit. tests/atlas-version-canonical.test.js and its ATT&CK counterpart
+ * compare each operator-facing mention against what this module returns.
  */
 
 const fs = require("fs");

package/lib/worker-pool.js

@@ -1,28 +1,13 @@
 "use strict";
 /**
- * lib/worker-pool.js
+ * Thin wrapper over vendor/blamejs/worker-pool.js, which supplies the bounded
+ * concurrency, bounded queue, per-task timeout and worker recycling. Added
+ * here: a class around the function-style `create()`, a `runAll()` that owns
+ * and terminates its pool, and DEFAULT_SIZE for callers that size manually.
  *
- * Thin convenience wrapper over the vendored blamejs worker-pool primitive.
- * The vendored module (vendor/blamejs/worker-pool.js) provides:
- *
- *   - bounded concurrency, defaults to max(2, cpus)
- *   - bounded in-memory queue (default 1024 depth)
- *   - per-task timeout (default 5min)
- *   - worker recycle on uncaught error / timeout / exit
- *
- * What this wrapper adds:
- *
- *   - WorkerPool class around the function-style `create()` API for
- *     callers that prefer an instance
- *   - runAll(tasks, opts) helper that runs an array of tasks through a
- *     fresh pool and terminates it when done
- *   - DEFAULT_SIZE re-export for callers that want to size manually
- *
- * Honest framing: at v0.7.0 corpus size (38 skills, 10 catalogs, ~150ms
- * total build time) worker-thread spawn cost is comparable to the work
- * itself. The pool is here so the architecture scales as the corpus
- * grows and so users can experiment with `--parallel`. Sequential builds
- * remain the default.
+ * At current corpus size a worker spawn costs about as much as the work, so
+ * sequential builds stay the default; the pool is here for `--parallel` and
+ * for the corpus growing.
  */
 
 const os = require("os");
@@ -32,9 +17,8 @@ const DEFAULT_SIZE = Math.max(1, Math.min(8, os.cpus()?.length || 4));
 
 class WorkerPool {
   /**
-   * @param {object} opts
-   *   - runnerPath: absolute path to the worker script (required)
-   *   - size, maxQueueDepth, taskTimeoutMs, onExit — forwarded to vendored.create
+   * `opts.runnerPath` — absolute path to the worker script — is required; size,
+   * maxQueueDepth, taskTimeoutMs and onExit forward to vendored.create.
    */
   constructor(opts = {}) {
     if (!opts.runnerPath) throw new Error("WorkerPool: runnerPath is required");
@@ -56,9 +40,7 @@ class WorkerPool {
   }
 }
 
-/**
- * Run a list of tasks against a fresh pool, await all results, terminate.
- */
+/** Runs the tasks on a fresh pool, awaits every result, then terminates it. */
 async function runAll(tasks, opts = {}) {
   const pool = new WorkerPool(opts);
   try {
@@ -72,8 +54,7 @@ module.exports = {
   WorkerPool,
   runAll,
   DEFAULT_SIZE,
-  // Re-export vendored primitives for callers that prefer the function-style API
-  // or need the size constants.
+  // For callers that prefer the function-style API or need the size constants.
   create:                  vendored.create,
   MIN_SIZE:                vendored.MIN_SIZE,
   MAX_SIZE:                vendored.MAX_SIZE,

package/lib/xml-tokenizer.js

@@ -1,49 +1,16 @@
 "use strict";
 /**
- * lib/xml-tokenizer.js
+ * Minimal XML/RSS/Atom tokenizer with no runtime dependencies.
  *
- * Minimal but proper XML/RSS/Atom tokenizer. Replaces the regex-based
- * parser in lib/source-advisories.js. The regex approach silently
- * failed on:
- *   - XML namespaces (`<atom:entry>` vs `<entry>`)
- *   - Nested CDATA
- *   - Self-closing `<link href="..."/>` vs container `<link>...</link>`
- *   - HTML-escaped entities inside titles
- *   - Multi-line title content
+ *   parseFeed(xmlString) → [{title, link, published, body}, ...]
+ *   tokenize(xml, { onTagOpen, onTagClose, onText, onCData })
  *
- * Failures returned `[]` silently — operators never saw the parser was
- * broken on a given feed. This module fails loudly via tokenizer
- * errors so a parser regression is visible in the refresh report.
- *
- * Design constraints:
- *   - Zero runtime dependencies (the project ships with no deps).
- *   - Streaming-friendly via a callback API (does not buffer the whole
- *     DOM — relevant for the 15 MB IETF RFC index).
- *   - Namespace-aware via element-localname matching (the local-name
- *     of `<atom:entry>` is `entry`).
- *   - CDATA-correct: `<![CDATA[...]]>` content is passed through verbatim
- *     including unescaped `<` and `&`.
- *   - Entity-correct: the five named XML entities (lt, gt, amp, apos,
- *     quot) plus numeric character references (`&#NNN;`, `&#xHH;`)
- *     are decoded. Other named entities pass through unchanged (HTML
- *     entities in RSS bodies are a recoverable variant we tolerate).
- *
- * Not designed for: DTD parsing, XInclude, XSLT, or any external-entity
- * resolution. Feeds that need those features are outside the scope of
- * a security-tooling intake pipeline.
- *
- * API:
- *   const { parseFeed } = require("./xml-tokenizer");
- *   const items = parseFeed(xmlString);  // returns [{title, link, published, body}, ...]
- *
- * For lower-level use, the underlying tokenizer is exported too:
- *   const { tokenize } = require("./xml-tokenizer");
- *   tokenize(xml, { onTagOpen, onTagClose, onText, onCData });
+ * Streams through callbacks rather than a buffered DOM, which matters for the
+ * 15 MB IETF RFC index. Elements match on local-name, so `<atom:entry>` and
+ * `<entry>` are the same element. No DTD parsing, XInclude, XSLT, or
+ * external-entity resolution.
  */
 
-// Decode the five canonical XML entities + numeric character references.
-// Unknown named entities pass through unchanged (we're tolerant of
-// HTML-style entities that legitimately appear in RSS body text).
 function decodeEntities(s) {
   if (typeof s !== "string") return s;
   return s.replace(/&(#x[0-9a-fA-F]+|#[0-9]+|[a-zA-Z]+);/g, (m, ref) => {
@@ -65,7 +32,6 @@ function decodeEntities(s) {
   });
 }
 
-// Strip the optional `prefix:` from a namespaced element/attribute name.
 function localName(qname) {
   const idx = qname.indexOf(":");
   return idx === -1 ? qname : qname.slice(idx + 1);
@@ -74,8 +40,7 @@ function localName(qname) {
 function parseAttrs(rawAttrs) {
   const out = {};
   if (!rawAttrs) return out;
-  // Walk character-by-character so quoted values can contain `=` and
-  // whitespace without confusing a regex.
+  // Character-by-character, so a quoted value may contain `=` and whitespace.
   let i = 0;
   const len = rawAttrs.length;
   while (i < len) {
@@ -95,7 +60,6 @@ function parseAttrs(rawAttrs) {
     while (i < len && /\s/.test(rawAttrs[i])) i++;
     const quote = rawAttrs[i];
     if (quote !== '"' && quote !== "'") {
-      // Unquoted value — read until whitespace or end.
       const valStart = i;
       while (i < len && !/\s/.test(rawAttrs[i])) i++;
       out[localName(name)] = decodeEntities(rawAttrs.slice(valStart, i));
@@ -111,13 +75,9 @@ function parseAttrs(rawAttrs) {
 }
 
 /**
- * Emit the character-data of a raw-text leaf element span `[start, end)`.
- *
- * CDATA sections inside the span are emitted verbatim (onCData if present,
- * else onText) exactly like the main loop's CDATA fast-path; all other bytes
- * — including a stray unescaped '<' or inline HTML — are entity-decoded and
- * emitted via onText. Keeping the CDATA contract here means a `<![CDATA[...]]>`
- * title still surfaces only its inner text, not the literal markers.
+ * Emits the character data of a raw-text leaf element span `[start, end)`. CDATA
+ * inside the span goes out verbatim (onCData, else onText); every other byte —
+ * a stray unescaped '<' or inline HTML included — is entity-decoded via onText.
  */
 function emitRawText(xml, start, end, H) {
   let p = start;
@@ -133,8 +93,7 @@ function emitRawText(xml, start, end, H) {
       if (chunk.length && H.onText) H.onText(decodeEntities(chunk));
     }
     const cend = xml.indexOf("]]>", c + 9);
-    // findRawTextEnd already guaranteed a terminated CDATA before the close
-    // tag, so cend is within range; guard anyway.
+    // findRawTextEnd guarantees a terminated CDATA here; guarded anyway.
     const inner = cend === -1 || cend > end ? xml.slice(c + 9, end) : xml.slice(c + 9, cend);
     if (H.onCData) H.onCData(inner);
     else if (H.onText) H.onText(inner);
@@ -143,17 +102,11 @@ function emitRawText(xml, start, end, H) {
 }
 
 /**
- * Locate the matching close tag of a raw-text leaf element.
- *
- * Scans `xml` from `start` (the byte after the leaf open tag's `>`) for the
- * first close tag `</...name>` whose local-name (namespace prefix stripped)
- * equals `name`. CDATA sections are skipped verbatim so a `</title>` that
- * legitimately appears inside `<![CDATA[ ... ]]>` is treated as literal text,
- * not as the element's terminator.
- *
- * Returns { contentEnd, next } on success — `contentEnd` is the index of the
- * close tag's leading `<`, `next` is the index just past its `>`. Returns null
- * when no matching close tag exists before EOF (genuinely truncated input).
+ * Finds the close tag of a raw-text leaf element, scanning from `start` (the byte
+ * after the open tag's `>`) for the first `</...name>` whose local-name is `name`.
+ * CDATA is skipped, so a `</title>` inside `<![CDATA[ ... ]]>` is literal text.
+ * Returns `{ contentEnd, next }` — the index of the close tag's `<`, and the index
+ * just past its `>` — or null when no close tag exists before EOF.
  */
 function findRawTextEnd(xml, start, name) {
   const len = xml.length;
@@ -161,8 +114,6 @@ function findRawTextEnd(xml, start, name) {
   while (j < len) {
     const lt = xml.indexOf("<", j);
     if (lt === -1) return null;
-    // Step over a CDATA section so its contents (which may contain "</name>"
-    // literally) cannot satisfy the close-tag match.
     if (xml.startsWith("<![CDATA[", lt)) {
       const cend = xml.indexOf("]]>", lt + 9);
       if (cend === -1) return null; // unterminated CDATA → truncated
@@ -179,16 +130,15 @@ function findRawTextEnd(xml, start, name) {
       j = gt + 1;
       continue;
     }
-    // Any other '<' (stray literal '<', or an inner open tag like <b>) is part
-    // of the leaf's character data — advance past it without classifying.
+    // Any other '<' is part of the leaf's character data — advance past it.
     j = lt + 1;
   }
   return null;
 }
 
 /**
- * Streaming tokenizer. Calls handlers in document order. Returns no
- * value — accumulation is the caller's responsibility.
+ * Streaming tokenizer. Calls handlers in document order. Returns no value —
+ * accumulation is the caller's responsibility.
  *
  * Handlers (all optional):
  *   onTagOpen(name, attrs, selfClosing)
@@ -199,16 +149,9 @@ function findRawTextEnd(xml, start, name) {
  *   onPI(name, content)  processing instructions (<?xml-stylesheet?>)
  *   onError(message, position)
  *
- * Options (second-position fields on the handlers object):
- *   rawTextElements   Set<string> of leaf-element local-names whose content
- *                     is #PCDATA — once such an element opens, every byte up
- *                     to the matching `</name>` close tag is treated as
- *                     character data (entities decoded, then onText), exactly
- *                     like the CDATA fast-path. This makes leaf fields tolerant
- *                     of stray unescaped '<' (e.g. "affects versions < 5.0"),
- *                     which real RSS/Atom routinely emits, instead of letting a
- *                     recoverable lexical glitch silently drop the whole field.
- *                     Structural parsing stays strict for container elements.
+ * `rawTextElements`, a Set of local-names on the same object, marks leaf elements
+ * whose content is #PCDATA: every byte up to the matching `</name>` is character
+ * data, so a stray unescaped '<' does not drop the field. Containers stay strict.
  */
 function tokenize(xml, handlers) {
   const H = handlers || {};
@@ -219,16 +162,11 @@ function tokenize(xml, handlers) {
   const rawTextElements = H.rawTextElements instanceof Set ? H.rawTextElements : null;
   const len = xml.length;
   let i = 0;
-  // Open-tag stack — surfaces EOF-with-unclosed-elements as an error
-  // instead of silently dropping the residual content. This is the
-  // observability gap the v0.13.17 regex parser had: a malformed feed
-  // (truncated mid-element) returned `[]` with no signal that the
-  // parser had given up.
+  // The open-tag stack turns unclosed-at-EOF into an error, not dropped content.
   const openStack = [];
   while (i < len) {
     const next = xml.indexOf("<", i);
     if (next === -1) {
-      // Trailing text — flush.
       const tail = xml.slice(i);
       if (tail.length && H.onText) H.onText(decodeEntities(tail));
       if (openStack.length && H.onError) {
@@ -240,7 +178,6 @@ function tokenize(xml, handlers) {
       const text = xml.slice(i, next);
       if (text.length && H.onText) H.onText(decodeEntities(text));
     }
-    // Now at `<` — classify the construct.
     if (xml.startsWith("<!--", next)) {
       const end = xml.indexOf("-->", next + 4);
       if (end === -1) {
@@ -295,7 +232,6 @@ function tokenize(xml, handlers) {
       i = j + 1;
       continue;
     }
-    // Element tag — open / close / self-closing.
     const close = xml.indexOf(">", next);
     if (close === -1) {
       if (H.onError) H.onError("unterminated element tag", next);
@@ -307,7 +243,6 @@ function tokenize(xml, handlers) {
     if (inner.startsWith("/")) { isClose = true; inner = inner.slice(1); }
     if (inner.endsWith("/")) { selfClose = true; inner = inner.slice(0, -1); }
     inner = inner.trim();
-    // Split name and attrs at the first whitespace.
     const wsAt = inner.search(/\s/);
     const rawName = wsAt === -1 ? inner : inner.slice(0, wsAt);
     const rawAttrs = wsAt === -1 ? "" : inner.slice(wsAt + 1);
@@ -321,17 +256,11 @@ function tokenize(xml, handlers) {
       if (selfClose) {
         if (H.onTagClose) H.onTagClose(name);
       } else if (rawTextElements && rawTextElements.has(name)) {
-        // Raw-text leaf element (title/summary/description/...). Its content
-        // is #PCDATA: scan to the matching `</name>` and treat the whole span
-        // as character data — only the matching close tag terminates it. Any
-        // inner '<...>' (a stray unescaped '<', or inline HTML like <b>) is
-        // preserved as text and normalized later by stripHtml(), instead of
-        // being misclassified as markup and silently dropping the field.
+        // A raw-text leaf: only the matching `</name>` terminates it. Inner
+        // '<...>' stays text for stripHtml(), rather than being classified as markup.
         const span = findRawTextEnd(xml, close + 1, name);
         if (span === null) {
-          // Genuinely truncated: the leaf never closes before EOF. Surface
-          // the loud-error contract just like the structural path would, then
-          // flush the residual as text and stop.
+          // Never closes before EOF: report as the structural path does, flush, stop.
           if (H.onError) H.onError("unterminated element at EOF: " + name, len);
           const tail = xml.slice(close + 1);
           if (tail.length && H.onText) H.onText(decodeEntities(tail));
@@ -352,39 +281,28 @@ function tokenize(xml, handlers) {
   }
 }
 
-// Leaf-element local-names whose content is character-data (#PCDATA). When
-// one of these opens, the tokenizer runs in raw-text mode until the matching
-// close tag, so a stray unescaped '<' inside the field (e.g. "affects
-// versions < 5.0") is preserved as text instead of being misclassified as
-// markup and silently dropping the whole field.
+// The leaf elements parsed in raw-text mode — see tokenize()'s rawTextElements.
 const LEAF_FIELDS = new Set([
   "title", "link", "pubDate", "published", "updated",
   "description", "content", "summary",
 ]);
 
 // rel-rank for Atom <link> sibling selection. RFC 4287: a <link> with no rel
-// defaults to rel="alternate", the canonical article URL. A non-alternate rel
-// (self / replies / edit / enclosure) should never clobber an alternate.
+// defaults to rel="alternate", so a non-alternate must never clobber one.
 function relRank(rel) {
   if (rel == null || rel === "" || String(rel).toLowerCase() === "alternate") return 2;
   return 1;
 }
 
 /**
- * Parse an RSS / Atom feed, always collecting parse errors.
- *
- * Returns { items, errors } where errors is an array of
- * { message, position } records. This is the channel a caller cannot forget
- * to opt into — parseFeed() below is a thin back-compat wrapper.
- *
- *   items: [{ title, link, published, body }, ...]
+ * Parses an RSS / Atom feed into `{ items, errors }`, where items are
+ * `{ title, link, published, body }` and errors are `{ message, position }`.
+ * The errors channel cannot be opted out of, so prefer this over parseFeed().
  */
 function parseFeedDetailed(xml) {
   const items = [];
   const errors = [];
-  // Stack of "in-progress item" contexts. RSS uses <item>; Atom uses
-  // <entry>; both nest title / link / pubDate / published / updated /
-  // description / content / summary.
+  // RSS uses <item>, Atom uses <entry>; both nest the same leaf fields.
   const ITEM_LOCALS = new Set(["item", "entry"]);
   const FIELD_MAP = {
     title: "title",
@@ -414,23 +332,17 @@ function parseFeedDetailed(xml) {
       if (FIELD_MAP[name]) {
         activeField = FIELD_MAP[name];
         buffer = "";
-        // Remember this link element's rel so its element-text close (below) is
-        // ranked the same way the attribute path is — a non-alternate link with
-        // text must not clobber a captured rel=alternate.
+        // Remembered so the close below ranks the link as this path does.
         if (name === "link") linkRel = attrs ? attrs.rel : null;
-        // Atom <link href="..."/> — rel-aware selection. Only let an
-        // alternate / rel-absent link upgrade the captured value, and never
-        // let a non-alternate rel (self/replies/edit) clobber an alternate
-        // already in hand. First-alternate-wins, independent of document
-        // order.
+        // Only an alternate or rel-absent link upgrades the captured value,
+        // whatever the document order.
         if (name === "link" && attrs && attrs.href) {
           const r = relRank(attrs.rel);
           if (r > linkRank) {
             current.link = attrs.href;
             linkRank = r;
           }
-          // The link value has been resolved from the attribute — there is
-          // no element-text close to wait for.
+          // Resolved from the attribute — no element-text close to wait for.
           if (selfClosing) activeField = null;
         }
       }
@@ -447,12 +359,8 @@ function parseFeedDetailed(xml) {
       if (!current) return;
       if (FIELD_MAP[name] && activeField === FIELD_MAP[name]) {
         const value = buffer.trim();
-        // <link>...</link> element text — ranked by the link's rel, the SAME
-        // gate the attribute path uses, so a non-alternate (self/replies/edit)
-        // link with text cannot clobber a captured rel=alternate. RSS links
-        // carry no rel, and relRank(undefined) === 2, so RSS element-text links
-        // keep their previous authoritative rank. An empty element-text link
-        // falls back to whatever attribute capture onTagOpen already recorded.
+        // Element text goes through the same rel gate as the attribute path; RSS
+        // links carry no rel, so relRank(undefined) is 2 and they keep the top rank.
         if (name === "link") {
           const r = relRank(linkRel);
           if (value && r > linkRank) {
@@ -461,12 +369,8 @@ function parseFeedDetailed(xml) {
           }
           linkRel = null;
         } else if (activeField === "body" || activeField === "title") {
-          // Strip HTML tags from title + description / content / summary.
-          // Many feeds embed inline HTML (<b>, <em>, <a>) in titles for
-          // emphasis; the operational consumer wants plain text. CDATA
-          // content reaches here verbatim, so this also strips HTML
-          // that was wrapped in CDATA to dodge entity-encoding. A stray
-          // unescaped '<' that survived raw-text mode collapses here too.
+          // Feeds embed inline HTML in titles and bodies. CDATA reaches here
+          // verbatim, so HTML wrapped in CDATA to dodge encoding is stripped too.
           current[activeField] = stripHtml(value);
         } else {
           current[activeField] = value;
@@ -490,13 +394,9 @@ function parseFeedDetailed(xml) {
 }
 
 /**
- * Parse an RSS / Atom feed into a flat array of items. Returns:
- *   [{ title, link, published, body }, ...]
- *
- * Empty array on parse failure. Errors are ALWAYS collected internally; the
- * optional `errors` array is filled for callers that pass one (back-compat).
- * Prefer parseFeedDetailed(xml) for new callers — it returns the errors
- * channel unconditionally so it cannot be silently dropped.
+ * Parses an RSS / Atom feed into `[{ title, link, published, body }, ...]`, or an
+ * empty array on parse failure. Errors are copied into the optional `errors` array
+ * when a caller passes one and dropped otherwise: prefer parseFeedDetailed().
  */
 function parseFeed(xml, errors = null) {
   const { items, errors: collected } = parseFeedDetailed(xml);
@@ -508,14 +408,9 @@ function parseFeed(xml, errors = null) {
 
 function stripHtml(s) {
   if (typeof s !== "string") return "";
-  // Single-pass tag strip. A backtracking /<[^>]+>/g is O(n^2) on
-  // attacker-controlled feed text with many '<' and no '>' (a ~150 KB
-  // <title>/<description> of bare '<' froze the refresh worker for seconds —
-  // a ReDoS-class DoS, since parseFeed() runs on network-fetched RSS/Atom
-  // bodies). Walk '<'..'>' instead, preserving the prior contract exactly: a
-  // real `<...>` becomes a space; a stray '<' with no closing '>' and an empty
-  // '<>' survive as literal text (the `[^>]+` quantifier required >=1 char, so
-  // neither matched). Then collapse whitespace as before.
+  // Single-pass, because a backtracking /<[^>]+>/g is O(n^2) on feed text with many
+  // '<' and no '>' — a ReDoS-class DoS, since parseFeed() runs on network-fetched
+  // bodies. A stray '<' with no closing '>' and an empty '<>' survive as text.
   let out = "";
   let i = 0;
   while (i < s.length) {