mandrel 1.57.0

package/.agents/scripts/lib/coverage-utils.js

@@ -0,0 +1,239 @@
+import fs from 'node:fs';
+
+const COVERAGE_INDEX = Symbol('coverage-utils.coverage-index');
+const ENTRY_INDEX = Symbol('coverage-utils.entry-index');
+
+/**
+ * Load and parse an istanbul/c8 `coverage-final.json` artifact.
+ *
+ * Returns the parsed object (keyed by absolute file path) on success, or
+ * `null` when the file is missing, unreadable, non-JSON, or structurally
+ * unusable. Never throws — consumers treat a null map as "no coverage
+ * available" and apply their own `requireCoverage` policy.
+ *
+ * @param {string} coveragePath
+ * @returns {object|null}
+ */
+export function loadCoverage(coveragePath) {
+  try {
+    if (!coveragePath || !fs.existsSync(coveragePath)) return null;
+    const raw = fs.readFileSync(coveragePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeSep(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+function stripLeadingDotSlash(p) {
+  return p.replace(/^\.\/+/, '').replace(/^\/+/, '');
+}
+
+/**
+ * Build a single-pass index over a parsed `coverage-final.json` map.
+ *
+ * Returns `{map, byNormalizedSuffix}` where `byNormalizedSuffix` is a
+ * `Map<string, object>` keyed by the POSIX-normalized form of each original
+ * key. Lookups that need exact-equality or `/`-bounded suffix matching
+ * consult that Map without re-enumerating `Object.keys(map)` on every call.
+ *
+ * @param {object|null} map
+ * @returns {{map: object|null, byNormalizedSuffix: Map<string, object>}}
+ */
+export function buildCoverageIndex(map) {
+  const byNormalizedSuffix = new Map();
+  if (map && typeof map === 'object' && !Array.isArray(map)) {
+    for (const key of Object.keys(map)) {
+      byNormalizedSuffix.set(normalizeSep(key), map[key]);
+    }
+  }
+  return { map, byNormalizedSuffix };
+}
+
+function getCoverageIndex(map) {
+  if (!map || typeof map !== 'object' || Array.isArray(map)) return null;
+  const cached = map[COVERAGE_INDEX];
+  if (cached) return cached;
+  const idx = buildCoverageIndex(map);
+  Object.defineProperty(map, COVERAGE_INDEX, {
+    value: idx,
+    enumerable: false,
+    configurable: true,
+    writable: false,
+  });
+  return idx;
+}
+
+/**
+ * Locate the coverage entry for a repo-relative path.
+ *
+ * `coverage-final.json` keys are typically absolute, platform-specific paths,
+ * while callers pass POSIX-ish repo-relative strings. Match by exact equality
+ * or by `/`-bounded suffix so we tolerate both Windows and POSIX producers.
+ * If two distinct keys both end with the same `/`-bounded suffix (duplicate
+ * basenames in different trees), the suffix is ambiguous — return null
+ * rather than picking the first iteration-order hit and silently scoring
+ * the wrong file.
+ */
+function findFileEntry(map, relPath) {
+  if (!map || !relPath) return null;
+  const suffix = stripLeadingDotSlash(normalizeSep(relPath));
+  if (!suffix) return null;
+  const idx = getCoverageIndex(map);
+  if (!idx) return null;
+  const direct = idx.byNormalizedSuffix.get(suffix);
+  if (direct !== undefined) return direct ?? null;
+  const needle = `/${suffix}`;
+  let match = null;
+  for (const [norm, entry] of idx.byNormalizedSuffix) {
+    if (!norm.endsWith(needle)) continue;
+    if (match !== null) return null; // ambiguous suffix — refuse to guess
+    match = entry ?? null;
+  }
+  return match;
+}
+
+export { findFileEntry as findCoverageEntry };
+
+/**
+ * Does the map contain any entry whose path matches `relPath`?
+ *
+ * @param {object|null} map
+ * @param {string} relPath
+ * @returns {boolean}
+ */
+export function hasCoverageFor(map, relPath) {
+  return findFileEntry(map, relPath) !== null;
+}
+
+/**
+ * Build a per-entry index that turns method-coverage lookups from
+ * `O(fnCount + statementCount)` per call into `O(method-line-span)`.
+ *
+ * - `fnByStartLine`: maps either `decl.start.line` or `loc.start.line` to the
+ *   raw `fnMap` entry — so callers may key by the escomplex `lineStart`
+ *   (which can match either, depending on producer).
+ * - `fnLocByStartLine`: same keying, value is `{fnStart, fnEnd}` derived once.
+ * - `statementsByLine`: `Map<line, {total, covered}>` so range scans don't
+ *   re-walk the full statement map.
+ *
+ * @param {object|null} entry One inner value from a `coverage-final.json` map.
+ */
+export function buildEntryIndex(entry) {
+  const fnByStartLine = new Map();
+  const fnLocByStartLine = new Map();
+  const statementsByLine = new Map();
+  if (!entry || typeof entry !== 'object') {
+    return { fnByStartLine, fnLocByStartLine, statementsByLine };
+  }
+  const fnMap = entry.fnMap ?? {};
+  const statementMap = entry.statementMap ?? {};
+  const statementHits = entry.s ?? {};
+
+  for (const fnId of Object.keys(fnMap)) {
+    const f = fnMap[fnId];
+    const declLine = f?.decl?.start?.line;
+    const locLine = f?.loc?.start?.line;
+    const fnStart = locLine ?? declLine ?? null;
+    const fnEnd = f?.loc?.end?.line ?? null;
+    const loc = { fnStart, fnEnd };
+    if (typeof declLine === 'number' && !fnByStartLine.has(declLine)) {
+      fnByStartLine.set(declLine, f);
+      fnLocByStartLine.set(declLine, loc);
+    }
+    if (typeof locLine === 'number' && !fnByStartLine.has(locLine)) {
+      fnByStartLine.set(locLine, f);
+      fnLocByStartLine.set(locLine, loc);
+    }
+  }
+
+  for (const stmtId of Object.keys(statementMap)) {
+    const stmt = statementMap[stmtId];
+    const sLine = stmt?.start?.line;
+    if (typeof sLine !== 'number') continue;
+    let bucket = statementsByLine.get(sLine);
+    if (!bucket) {
+      bucket = { total: 0, covered: 0 };
+      statementsByLine.set(sLine, bucket);
+    }
+    bucket.total += 1;
+    if ((statementHits[stmtId] ?? 0) > 0) bucket.covered += 1;
+  }
+
+  return { fnByStartLine, fnLocByStartLine, statementsByLine };
+}
+
+function getEntryIndex(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const cached = entry[ENTRY_INDEX];
+  if (cached) return cached;
+  const idx = buildEntryIndex(entry);
+  Object.defineProperty(entry, ENTRY_INDEX, {
+    value: idx,
+    enumerable: false,
+    configurable: true,
+    writable: false,
+  });
+  return idx;
+}
+
+/**
+ * Compute the statement-coverage ratio for a single method inside a single
+ * file's coverage entry.
+ *
+ * The ratio is the fraction of statements whose `start.line` falls within the
+ * function's `loc` range that were executed at least once. An empty range
+ * returns 0. A missing / malformed entry or no matching function returns
+ * `null` so the caller can distinguish "no data" from "tested zero times."
+ *
+ * The first call on a given entry builds and caches a per-entry index via a
+ * non-enumerable Symbol property; consecutive method lookups in the same
+ * file pay the build cost exactly once.
+ *
+ * @param {object|null} entry One inner value from a `coverage-final.json` map.
+ * @param {number} startLine The escomplex `lineStart` for the method.
+ * @returns {number|null}
+ */
+export function coverageForMethodInEntry(entry, startLine) {
+  if (!entry || typeof entry !== 'object') return null;
+  const idx = getEntryIndex(entry);
+  if (!idx.fnByStartLine.has(startLine)) return null;
+  const loc = idx.fnLocByStartLine.get(startLine);
+  if (!loc) return null;
+  const { fnStart, fnEnd } = loc;
+  if (fnStart === null || fnEnd === null) return null;
+
+  let total = 0;
+  let covered = 0;
+  for (let line = fnStart; line <= fnEnd; line += 1) {
+    const bucket = idx.statementsByLine.get(line);
+    if (!bucket) continue;
+    total += bucket.total;
+    covered += bucket.covered;
+  }
+
+  if (total === 0) return 0;
+  return covered / total;
+}
+
+/**
+ * Look up per-method coverage in a full coverage map.
+ *
+ * @param {object|null} map Parsed `coverage-final.json`.
+ * @param {string} relPath Repo-relative path of the source file.
+ * @param {number} startLine The escomplex `lineStart` for the method.
+ * @returns {number|null} Coverage in [0, 1], or null when the file or method
+ *   is absent.
+ */
+export function coverageByMethod(map, relPath, startLine) {
+  const entry = findFileEntry(map, relPath);
+  if (!entry) return null;
+  return coverageForMethodInEntry(entry, startLine);
+}

package/.agents/scripts/lib/cpu-pool.js

@@ -0,0 +1,223 @@
+/**
+ * lib/cpu-pool.js — Generic worker_threads pool for CPU-bound work.
+ *
+ * `runOnPool(workerScript, items, opts)` spawns up to
+ * `opts.concurrency ?? os.availableParallelism()` persistent workers,
+ * dispatches `items` to whichever worker is idle, and resolves with an
+ * array of per-item results in input order. The queue is bounded by
+ * worker count — we only have N items in flight at once, where N =
+ * concurrency, so back-pressure is implicit.
+ *
+ * Determinism:
+ *   - The returned `results` array is indexed by input position. Workers
+ *     race on dispatch but each result lands at its source index, so
+ *     callers that need deterministic output order can either consume
+ *     `results` directly (already in input order) or apply a stable
+ *     sort by file path / id of their choosing after the pool drains.
+ *
+ * Failure handling:
+ *   - The worker contract is: emit `{ ok: true, result }` per item, or
+ *     `{ ok: false, error: string }` for a per-item failure. The default
+ *     is to capture per-item failures as `{ __cpuPoolError: true,
+ *     message }` entries at the corresponding result index so one bad
+ *     input does not abort the run. Pass `opts.throwOnItemError === true`
+ *     (an explicit `true`, not just truthy) to flip to the abort-on-first
+ *     mode, which rejects the whole `runOnPool` call.
+ *   - A worker that crashes (`error` event) or exits non-zero rejects
+ *     the whole pool — that is not a per-item failure, it is a host-level
+ *     fault and must surface.
+ *
+ * Worker-side contract:
+ *   - The worker entry receives `workerData` (passed once at spawn).
+ *   - It listens on `parentPort` for messages of shape `{ item }` for
+ *     work dispatch, or `{ exit: true }` to drain and exit cleanly.
+ *   - It must `parentPort.postMessage({ ok, result | error })` exactly
+ *     once per `{ item }` it receives.
+ *
+ * No project config or git access is loaded here — the pool itself is
+ * a thin scheduler so workers stay cheap to spawn.
+ *
+ * Worker injection (testability):
+ *   - The worker handle is produced by `opts.workerFactory(script, options)`,
+ *     defaulting to `(script, options) => new Worker(script, options)`. The
+ *     factory must return an EventEmitter-shaped handle exposing the subset
+ *     of the `worker_threads.Worker` surface the scheduler uses: `on`,
+ *     `off`, `once`, `postMessage`, and a thenable `terminate()`. Injecting
+ *     a synchronous fake factory lets unit tests drive the scheduling,
+ *     ordering, and exit-race branches in-process without spawning a real
+ *     OS thread.
+ */
+
+import os from 'node:os';
+import { Worker } from 'node:worker_threads';
+
+/** Default factory: spawn a real `worker_threads.Worker`. */
+const defaultWorkerFactory = (script, options) => new Worker(script, options);
+
+/**
+ * @template TItem, TResult
+ * @param {string|URL} workerScript - File URL or path to the worker entry.
+ * @param {TItem[]} items
+ * @param {{
+ *   concurrency?: number,
+ *   workerData?: unknown,
+ *   throwOnItemError?: boolean,
+ *   workerFactory?: (
+ *     script: string|URL,
+ *     options: { workerData?: unknown },
+ *   ) => import('node:events').EventEmitter & {
+ *     postMessage: (msg: unknown) => void,
+ *     terminate: () => Promise<unknown> | unknown,
+ *   },
+ * }} [opts]
+ * @returns {Promise<Array<TResult | { __cpuPoolError: true, message: string }>>}
+ */
+export async function runOnPool(workerScript, items, opts = {}) {
+  const itemsArr = [...items];
+  if (itemsArr.length === 0) return [];
+
+  const requested = opts.concurrency ?? os.availableParallelism();
+  const concurrency = Math.max(1, Math.min(requested, itemsArr.length));
+  const workerData = opts.workerData;
+  const throwOnItemError = opts.throwOnItemError === true;
+  const workerFactory = opts.workerFactory ?? defaultWorkerFactory;
+
+  const results = new Array(itemsArr.length);
+  let nextIndex = 0;
+  let firstFatalError = null;
+
+  async function runWorker() {
+    const worker = workerFactory(workerScript, { workerData });
+    // Track exit at worker scope so the finally block can short-circuit
+    // when the worker has already gone away (e.g. mid-dispatch
+    // process.exit). Registering a single persistent listener here also
+    // sidesteps the race where worker.once('exit', ...) added inside
+    // finally arrives after the 'exit' event has already fired and
+    // therefore never resolves.
+    let workerExited = false;
+    worker.on('exit', () => {
+      workerExited = true;
+    });
+    try {
+      while (firstFatalError === null) {
+        const myIndex = nextIndex++;
+        if (myIndex >= itemsArr.length) break;
+        const item = itemsArr[myIndex];
+        // eslint-disable-next-line no-await-in-loop
+        const outcome = await dispatchOne(worker, item);
+        if (outcome.kind === 'ok') {
+          results[myIndex] = outcome.result;
+        } else if (outcome.kind === 'item-error') {
+          if (throwOnItemError) {
+            firstFatalError = new Error(
+              `cpu-pool item failure: ${outcome.message}`,
+            );
+            break;
+          }
+          results[myIndex] = {
+            __cpuPoolError: true,
+            message: outcome.message,
+          };
+        } else {
+          // host-level fault: worker crashed or emitted bad shape.
+          if (firstFatalError === null) firstFatalError = outcome.error;
+          break;
+        }
+      }
+    } finally {
+      if (!workerExited) {
+        try {
+          worker.postMessage({ exit: true });
+        } catch {
+          // worker may already be terminating
+        }
+        // Wait briefly for clean exit, then force-terminate. Re-check
+        // workerExited because the dispatch loop may have observed the
+        // exit between the guard above and here.
+        if (!workerExited) {
+          const exited = new Promise((resolve) => {
+            if (workerExited) resolve();
+            else worker.once('exit', resolve);
+          });
+          // Do NOT .unref() the fallback timer: an unrefed timer lets
+          // the event loop appear idle while this promise is pending,
+          // which trips Node's test runner cancellation under cold-CI
+          // conditions.
+          await Promise.race([
+            exited,
+            new Promise((resolve) => setTimeout(resolve, 1000)),
+          ]);
+        }
+      }
+      try {
+        await worker.terminate();
+      } catch {
+        // already gone
+      }
+    }
+  }
+
+  await Promise.all(Array.from({ length: concurrency }, () => runWorker()));
+
+  if (firstFatalError !== null) throw firstFatalError;
+  return results;
+}
+
+/**
+ * Round-trip a single item through `worker`, resolving to a tagged
+ * outcome. Never throws: a host-level fault is reported as
+ * `{ kind: 'fatal', error }` so `runOnPool` can record it as the first
+ * fatal error and stop dispatching.
+ */
+function dispatchOne(worker, item) {
+  return new Promise((resolve) => {
+    const cleanup = () => {
+      worker.off('message', onMessage);
+      worker.off('error', onError);
+      worker.off('exit', onExit);
+    };
+    const onMessage = (msg) => {
+      cleanup();
+      if (msg && msg.ok === true) {
+        resolve({ kind: 'ok', result: msg.result });
+        return;
+      }
+      if (msg && msg.ok === false) {
+        resolve({
+          kind: 'item-error',
+          message: typeof msg.error === 'string' ? msg.error : 'unknown',
+        });
+        return;
+      }
+      resolve({
+        kind: 'fatal',
+        error: new Error(
+          `cpu-pool: malformed worker message: ${JSON.stringify(msg)}`,
+        ),
+      });
+    };
+    const onError = (err) => {
+      cleanup();
+      resolve({ kind: 'fatal', error: err });
+    };
+    const onExit = (code) => {
+      cleanup();
+      if (code !== 0) {
+        resolve({
+          kind: 'fatal',
+          error: new Error(`cpu-pool: worker exited with code ${code}`),
+        });
+        return;
+      }
+      // Clean exit mid-dispatch: treat as fatal so the item is not silently lost.
+      resolve({
+        kind: 'fatal',
+        error: new Error('cpu-pool: worker exited mid-dispatch'),
+      });
+    };
+    worker.on('message', onMessage);
+    worker.on('error', onError);
+    worker.on('exit', onExit);
+    worker.postMessage({ item });
+  });
+}

package/.agents/scripts/lib/crap-engine.js

@@ -0,0 +1,119 @@
+import escomplex from 'typhonjs-escomplex';
+import { coverageForMethodInEntry } from './coverage-utils.js';
+
+/**
+ * Score each method in a JavaScript source for Change Risk Anti-Patterns
+ * (CRAP): `c² · (1 − cov)³ + c`, where `c` is cyclomatic complexity and `cov`
+ * is the per-method statement-coverage ratio in [0, 1].
+ *
+ * Kernel contract:
+ *   - Pure (no I/O, no AST parse beyond the one delegated to escomplex via
+ *     `analyzeModule`).
+ *   - Methods whose coverage cannot be resolved from `coverageForFile`
+ *     produce `coverage: null` and `crap: null`. Callers apply their own
+ *     `requireCoverage` policy at the scanner level; this kernel never
+ *     decides to skip.
+ *   - A parse error returns an empty array — the file is unscorable, not
+ *     zero-complexity.
+ *
+ * @param {string} source JavaScript source text.
+ * @param {object|null} coverageForFile The inner value from a
+ *   `coverage-final.json` map keyed by this file's path, or null when no
+ *   coverage data is available for this file.
+ * @returns {Array<{
+ *   method: string,
+ *   startLine: number,
+ *   cyclomatic: number,
+ *   coverage: number|null,
+ *   crap: number|null,
+ * }>}
+ */
+export function calculateCrapForSource(source, coverageForFile) {
+  let report;
+  try {
+    report = escomplex.analyzeModule(source);
+  } catch {
+    return [];
+  }
+  const methods = report?.methods ?? [];
+  const rows = [];
+  for (const m of methods) {
+    const startLine = m?.lineStart;
+    if (typeof startLine !== 'number') continue;
+    const cyclomatic = m?.cyclomatic ?? 0;
+    const coverage = coverageForFile
+      ? coverageForMethodInEntry(coverageForFile, startLine)
+      : null;
+    const crap = coverage === null ? null : crapFormula(cyclomatic, coverage);
+    rows.push({
+      method: m.name,
+      startLine,
+      cyclomatic,
+      coverage,
+      crap,
+    });
+  }
+  return rows;
+}
+
+/**
+ * CRAP formula, exported for callers that need to derive target scores or
+ * `fixGuidance` values without re-scoring source.
+ *
+ * @param {number} cyclomatic
+ * @param {number} coverage In [0, 1].
+ * @returns {number}
+ */
+export function crapFormula(cyclomatic, coverage) {
+  const c = Number(cyclomatic) || 0;
+  const cov = Math.max(0, Math.min(1, Number(coverage) || 0));
+  return c * c * (1 - cov) ** 3 + c;
+}
+
+/**
+ * Derive the deterministic single-axis fixes that would bring a method at
+ * cyclomatic complexity `c` at or under the `target` CRAP score.
+ *
+ * Two orthogonal remediations are surfaced:
+ *   - `minComplexityAt100Cov`: branch count a refactor must reach so that,
+ *     even untested, the method would pass (`CRAP@cov=1 = c` → `c ≤ target`).
+ *     Computed as `floor(sqrt(target))`.
+ *   - `minCoverageAtCurrentComplexity`: ratio a test-addition must reach at
+ *     the current complexity to pass, derived by inverting the formula:
+ *     `cov = 1 − ((target − c) / c²)^(1/3)`. Null when unachievable — i.e.
+ *     `c > target` (CRAP at 100% coverage still exceeds the target) or when
+ *     `c ≤ 0` (no branches; coverage is meaningless).
+ *
+ * Callers apply the target convention: `baseline` for regressions,
+ * `newMethodCeiling` for new violations. The helper stays scalar so it can
+ * be re-used by MI-parity output or future guidance surfaces.
+ *
+ * @param {{ cyclomatic: number, target: number }} params
+ * @returns {{
+ *   crapCeiling: number,
+ *   minComplexityAt100Cov: number,
+ *   minCoverageAtCurrentComplexity: number | null,
+ * } | null}
+ */
+export function deriveFixGuidance({ cyclomatic, target } = {}) {
+  const c = Number(cyclomatic);
+  const t = Number(target);
+  if (!Number.isFinite(c) || !Number.isFinite(t) || t < 0) return null;
+
+  const minComplexityAt100Cov = Math.max(0, Math.floor(Math.sqrt(t)));
+
+  let minCoverageAtCurrentComplexity = null;
+  if (c > 0 && t >= c) {
+    // `(t - c) / c²` lies in `[0, 1]` for `t ∈ [c, c + c²]`; Math.cbrt stays
+    // real-valued for any input so a numeric clamp is the only safeguard.
+    const ratio = (t - c) / (c * c);
+    const minCov = 1 - Math.cbrt(ratio);
+    minCoverageAtCurrentComplexity = Math.max(0, Math.min(1, minCov));
+  }
+
+  return {
+    crapCeiling: t,
+    minComplexityAt100Cov,
+    minCoverageAtCurrentComplexity,
+  };
+}