@blamejs/exceptd-skills 0.19.32 → 0.19.34

package/lib/id-validation.js

@@ -1,31 +1,13 @@
 'use strict';
 
 /**
- * Shared validation for path-component-shaped operator inputs.
+ * Validation for path-component-shaped operator inputs — `--session-id`,
+ * `--playbook`, attestation and `--evidence-dir` filenames. The one definition
+ * for every such site in `bin/exceptd.js`; a second copy drifts. Callers
+ * propagate the returned {ok, reason} pair to their emit-error path.
  *
- * Six sites in `bin/exceptd.js` previously hand-rolled regexes of the form
- * /^[A-Za-z0-9._-]{1,64}$/ for `--session-id`, `--playbook`, attestation
- * filenames, and `--evidence-dir` filenames. Each regex was slightly
- * different in character class ordering; each grew its own follow-on checks
- * (all-dots refusal, length cap, leading-dot refusal) at different rates.
- *
- * This module is the single source of truth. Adding a new path-component
- * input means calling `validateIdComponent(value, role)` and propagating
- * the returned {ok, reason} pair to the caller's emit-error path.
- *
- * Three role types, three character classes:
- *   - 'session'  — sessions live under `.exceptd/attestations/<sid>/`. Allow
- *                  lower+upper alpha, digit, dot, underscore, hyphen, 1-64
- *                  chars. Refuse all-dots.
- *   - 'playbook' — playbook ids index `data/playbooks/<id>.json`. Stricter:
- *                  lowercase-only, must start with a letter, no dots (all
- *                  catalogued playbook ids match `/^[a-z][a-z0-9-]{0,63}$/`).
- *   - 'filename' — attestation filename inside a session directory. Same
- *                  charset as 'session' but length cap reflects filename
- *                  policy (no path separators ever).
- *
- * The function never reads the filesystem; combine with realpathSync at
- * the caller for full path-traversal defense.
+ * Never reads the filesystem — pair it with realpathSync at the caller for
+ * full path-traversal defense.
  */
 
 const SESSION_RE = /^[A-Za-z0-9._-]{1,64}$/;
@@ -61,8 +43,7 @@ function validateIdComponent(value, role) {
   if (!re.test(value)) {
     return { ok: false, reason: `must match ${constraint}` };
   }
-  // All-dots refusal applies after the character-class regex because the
-  // session/filename classes admit any string of dots (`.`, `..`, `...`),
+  // The session/filename classes admit any string of dots (`.`, `..`, `...`),
   // each of which path-resolves into or above the intended directory.
   if (ALL_DOTS_RE.test(value)) {
     return { ok: false, reason: 'must not consist entirely of dots' };
@@ -70,10 +51,8 @@ function validateIdComponent(value, role) {
   return { ok: true };
 }
 
-/**
- * Cheap typed-throw wrapper for callers that prefer exceptions over result
- * objects (lib/playbook-runner.js uses this shape for loadPlaybook).
- */
+// Throwing counterpart to validateIdComponent; the error carries
+// code `EXCEPTD_INVALID_ID`.
 function assertIdComponent(value, role) {
   const r = validateIdComponent(value, role);
   if (!r.ok) {

package/lib/job-queue.js

@@ -1,21 +1,8 @@
 "use strict";
 /**
- * lib/job-queue.js
- *
- * Async job queue specialized for exceptd's upstream-fetch workloads. The
- * generic retry semantics (HTTP + Node net classifier, exponential
- * backoff with crypto jitter, AbortSignal-aware sleep) live in the
- * vendored blamejs retry primitive — this module wraps it with the
- * per-source concurrency caps + token-bucket rate limits + priority
- * ordering specific to the KEV / EPSS / NVD / IETF / GitHub workloads.
- *
- *   - per-source concurrency caps (max in-flight)
- *   - token-bucket rate limiting (max requests per window)
- *   - priority ordering (higher number = sooner)
- *   - retry classification + backoff delegated to vendor/blamejs/retry.js
- *   - per-source stats (queued / in_flight / completed / failed / retried)
- *
- * No npm deps. Node 24 stdlib + vendored retry.js.
+ * Async job queue for exceptd's upstream fetches: per-source concurrency caps,
+ * token-bucket rate limits and priority ordering (higher number runs sooner).
+ * Retry classification and backoff come from vendor/blamejs/retry.js.
  */
 
 const retry = require("../vendor/blamejs/retry");
@@ -36,12 +23,9 @@ class TokenBucket {
     if (add >= 1) {
       const whole = Math.floor(add);
       this.tokens = Math.min(this.capacity, this.tokens + whole);
-      // Advance lastRefill by the time the whole tokens we just granted
-      // consumed, NOT to `now`. Snapping to `now` discards the sub-interval
-      // remainder (`elapsed % refillIntervalMs`), so the bucket refills
-      // slightly slower than the configured rate and under-utilizes the
-      // budget over many refills. Crediting only the consumed time keeps
-      // the long-run refill rate exactly tokens/windowMs.
+      // Credit only the time the granted tokens consumed; snapping lastRefill
+      // to `now` drops the sub-interval remainder, so the bucket refills
+      // slower than the configured tokens/windowMs.
       this.lastRefill += whole * this.refillIntervalMs;
     }
   }
@@ -59,9 +43,8 @@ class JobQueue {
   constructor(options = {}) {
     const defaults = { concurrency: 4 };
     this.sources = options.sources || { default: defaults };
-    // Retry options forwarded to vendored withRetry. Defaults are tighter
-    // than withRetry's own DEFAULT_RETRY so a network blip on KEV/EPSS
-    // doesn't stall the whole refresh by 80s.
+    // Forwarded to the vendored withRetry, tighter than its own defaults so a
+    // network blip on one source does not stall the whole refresh.
     this.retry = {
       maxAttempts: 3,
       baseDelayMs: 200,
@@ -69,9 +52,7 @@ class JobQueue {
       jitterFactor: 0.5,
       ...options.retry,
     };
-    // Caller may override the retry classifier. Default is the vendored
-    // blamejs classifier (HTTP 408/425/429/5xx + Node net codes), which
-    // matches everything the upstream sources emit.
+    // Defaults to the vendored classifier: HTTP 408/425/429/5xx + Node net codes.
     this.isRetryable = options.isRetryable || retry.isRetryable;
     this._perSource = {};
     for (const [name, cfg] of Object.entries(this.sources)) {
@@ -88,14 +69,10 @@ class JobQueue {
   }
 
   /**
-   * Enqueue a job.
-   * @param {object} job
-   *   - source:   source key from the sources map (default: "default")
-   *   - priority: integer; higher runs sooner within a source
-   *   - run:      async () => result
-   *   - signal:   optional AbortSignal forwarded to retry.withRetry sleep
-   *   - retry:    per-job retry override (merged onto queue defaults)
-   *   - meta:     freeform metadata attached to stats / errors
+   * Enqueues { source, priority, run, signal, retry, meta }. `priority` orders
+   * within a source, higher first; `retry` merges onto the queue defaults;
+   * `signal` reaches the retry sleep. Resolves with run()'s result, or rejects
+   * with the last error, carrying source + meta on its `queue_meta`.
    */
   add(job) {
     if (this._closed) return Promise.reject(new Error("JobQueue is closed"));