mandrel 2.59.0 → 2.61.0

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

@@ -1,110 +1,32 @@
 /**
- * lib/cpu-pool.js — Generic worker_threads pool for CPU-bound work.
+ * worker_threads pool for CPU-bound work; results land in input order.
  *
- * `runOnPool(workerScript, items, opts)` spawns up to
- * `resolvePoolConcurrency(opts.concurrency)` persistent workers — an
- * explicit option, else `MANDREL_POOL_CONCURRENCY`, else a clamp of 4 under
- * `node:test`, else `os.availableParallelism()` —
- * 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.
+ * Worker contract: receives `workerData` once; handles `{ item }` by posting
+ * exactly one `{ ok: true, result }` or `{ ok: false, error }`, and
+ * `{ exit: true }` by exiting. A per-item error becomes a `__cpuPoolError`
+ * entry (or rejects with `throwOnItemError === true`); a crash or non-zero
+ * exit rejects the whole pool.
  */
 
 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);
 
 /**
- * Pool-vs-serial cutover for `runOnPool` callers.
- *
- * Below this batch size the pool's worker spawn overhead dominates, so
- * callers fall back to in-process serial scoring. Single-sourced here so the
- * maintainability baseline scan (`maintainability-utils.js`), the CRAP
- * scanner (`crap-utils.js`), and the native review provider
- * (`review-providers/native.js`) cannot silently desynchronize on a retune.
- *
- * **Retuned from 8 to 256 in Story #5109.** The original 8 was set against
- * tmpdir fixtures and never measured against a real batch, so every
- * pre-commit preview — the most frequent path in the framework — paid for a
- * pool it could not amortise. Measured on this repository (18 logical cores,
- * `.agents/scripts` + `bin` + `lib`, MI scoring):
- *
- * ```text
- *   n=16   serial  125 ms   pooled  444 ms
- *   n=64   serial  175 ms   pooled  535 ms
- *   n=128  serial  241 ms   pooled  422 ms
- *   n=256  serial  440 ms   pooled  707 ms   <- still serial-favourable
- *   n=384  serial  943 ms   pooled  782 ms   <- crossover
- *   n=619  serial 1054 ms   pooled  710 ms
- * ```
- *
- * The crossover sits between 256 and 384, so 256 is the last power-of-two
- * step the serial path provably wins. A whole-tree baseline refresh
- * (n≈619) still takes the pool; a diff-scoped preview (n≈50) no longer
- * spawns a worker at all. Scoring output is identical on either path — the
- * worker runs the same scorer — so this is a cost retune, never a verdict
- * change.
+ * Batch size below which callers score serially: measured serial/pooled
+ * crossover lies between 256 and 384 files. Output is identical either way.
+ * Shared by every pooled scanner so they cannot desynchronize.
  */
 export const POOL_SERIAL_THRESHOLD = 256;
 
 /**
- * Hard ceiling on pool width when the process is a `node:test` child.
- *
- * Node's test runner already fans test *files* out across processes, so a
- * pool inside one of them multiplies against that fan-out and can oversubscribe
- * the host by an order of magnitude. Four is wide enough to keep the pooled
- * code path genuinely concurrent (so the scheduling branches under test stay
- * exercised) without letting a suite of parallel test processes each claim
- * every core.
+ * Under `node:test` the runner already fans out across processes; an
+ * unclamped pool in each would oversubscribe the host.
  */
 const NODE_TEST_CONCURRENCY_CLAMP = 4;
 
 /**
- * True when this process was spawned by Node's own test runner, which sets
- * `NODE_TEST_CONTEXT` in every test child.
- *
  * @param {NodeJS.ProcessEnv} env
  * @returns {boolean}
  */
@@ -115,21 +37,8 @@ function inNodeTestContext(env) {
 }
 
 /**
- * Resolve the requested pool width, in strict precedence order:
- *
- *   1. an explicit `opts.concurrency` — the caller knows its own budget;
- *   2. `MANDREL_POOL_CONCURRENCY` — the operator/CI override, so a
- *      constrained runner can bound every pool in the process tree at once;
- *   3. `NODE_TEST_CONCURRENCY_CLAMP` when running under `node:test`;
- *   4. `os.availableParallelism()`.
- *
- * Only *finite, positive* values are honoured at each step; anything else
- * falls through to the next, so a typo in the env var degrades to the
- * default rather than collapsing the pool to a single worker.
- *
- * Module-private on purpose: `runOnPool` is the only caller, and the
- * precedence is pinned through its observable worker count rather than by
- * an export whose sole importer would be a test.
+ * Explicit option, then `MANDREL_POOL_CONCURRENCY`, then the `node:test`
+ * clamp, then available parallelism. Non-positive values fall through.
  *
  * @param {number|undefined} explicit
  * @param {NodeJS.ProcessEnv} [env]
@@ -182,12 +91,8 @@ export async function runOnPool(workerScript, items, opts = {}) {
 
   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.
+    // A persistent listener: a once('exit') added in `finally` could miss an
+    // exit that already fired and never resolve.
     let workerExited = false;
     worker.on('exit', () => {
       workerExited = true;
@@ -225,18 +130,12 @@ export async function runOnPool(workerScript, items, opts = {}) {
         } 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.
+          // Never unref: an idle-looking loop trips test-runner cancellation.
           await Promise.race([
             exited,
             new Promise((resolve) => setTimeout(resolve, 1000)),
@@ -257,12 +156,7 @@ export async function runOnPool(workerScript, items, opts = {}) {
   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.
- */
+/** Never throws; a host-level fault resolves `{ kind: 'fatal', error }`. */
 function dispatchOne(worker, item) {
   return new Promise((resolve) => {
     const cleanup = () => {

package/.agents/scripts/lib/crap-baseline-join.js

@@ -1,18 +1,6 @@
 /**
- * crap-baseline-join.js — the incremental-coverage CRAP join (Story #4981),
- * end to end: the method-identity key, the per-file baseline index, the
- * per-file queue wiring, and the join itself.
- *
- * Story #4981 landed those four concerns as three files
- * (`crap-baseline-index.js`, `crap-utils-incremental.js`, and this one) so
- * the work would land as new code rather than same-file expansions. Story
- * #5002 folded them back together: they were one cohesive unit split only
- * for that scoring reason, and the split cost two import hops and two
- * modules whose whole content was five short pure functions.
- *
- * Imports its coordinate/formula primitives from `crap-coordinates.js` (not
- * `crap-engine.js`) so this file stays a one-directional consumer with no
- * edge back into the scoring kernel — `crap-engine.js` imports FROM here.
+ * The incremental-coverage CRAP join. Imports primitives from
+ * `crap-coordinates.js`, never `crap-engine.js`, which imports from here.
  */
 import {
   COORDINATE_ORIGINAL,
@@ -21,10 +9,7 @@ import {
 } from './crap-coordinates.js';
 
 /**
- * Per-file half of the method-identity key `baselines/kinds/crap.js`'s
- * `crapRowKey` composes with the file path (`${path}::${method}@${startLine}`).
- * The path component is redundant once a row set is already narrowed to one
- * file, which is exactly what `indexBaselineRowsByFile` does below.
+ * Per-file half of `crapRowKey` (`${path}::${method}@${startLine}`).
  *
  * @param {{method: string, startLine: number}} row
  * @returns {string}
@@ -34,11 +19,7 @@ function methodIdentityKey(row) {
 }
 
 /**
- * Index baseline rows (accepts either the `{file, method, startLine, crap}`
- * legacy shape `compareCrap`/`scanAndScore` use, or the on-disk `{path, ...}`
- * shape) by file, then by `methodIdentityKey`, for O(1) per-method lookup —
- * exactly the shape `finalizeMethodRowsWithBaseline`'s `baselineByKey`
- * expects.
+ * Accepts both the in-memory `{file}` and on-disk `{path}` row shapes.
  *
  * @param {Array<{file?: string, path?: string, method: string, startLine: number, crap: number}>} baselineRows
  * @returns {Map<string, Map<string, {crap: number}>>} file → (method@startLine → row)
@@ -55,10 +36,7 @@ function indexBaselineRowsByFile(baselineRows) {
 }
 
 /**
- * Resolve `crap-utils.js#scanAndScore`'s `incremental` option into the two
- * lookup structures the per-file queue build needs. Both are `null` when
- * `incremental` is absent (full-scope, the default) — every downstream
- * consumer treats a `null` context as "not incremental".
+ * Both fields `null` means "not incremental".
  *
  * @param {{ touchedFiles?: Set<string>|string[], baselineRows?: Array<object> } | null} incremental
  * @returns {{ touchedFiles: Set<string>|null, baselineByFile: Map<string, Map<string, object>>|null }}
@@ -76,10 +54,7 @@ export function resolveIncrementalContext(incremental) {
 }
 
 /**
- * Merge one queued file's `touched` flag and per-file `baselineByKey` map
- * (resolved from the `resolveIncrementalContext` output) onto its base queue
- * item. `touched` defaults to `true` (every file is "touched" outside
- * incremental mode, matching `finalizeMethodRowsWithBaseline`'s own default).
+ * Outside incremental mode every file is `touched`.
  *
  * @param {object} item Base queue item (`{ abs, relPath, requireCoverage, coverageAvailable }`).
  * @param {{ touchedFiles: Set<string>|null, baselineByFile: Map<string, Map<string, object>>|null }} ctx
@@ -97,10 +72,6 @@ export function resolveQueueIncrementalFields(
 }
 
 /**
- * True when a file's methods should resolve from the baseline rather than
- * from a fresh coverage entry — an untouched file with at least one indexed
- * baseline row.
- *
  * @param {boolean} touched
  * @param {Map<string, object>|null} baselineByKey
  * @returns {boolean}
@@ -110,10 +81,6 @@ function isIncrementalJoinActive(touched, baselineByKey) {
 }
 
 /**
- * `crap-utils.js#scoreFileSerial`'s file-level skip decision, factored out
- * whole so the incremental exception lives with the rest of the join rather
- * than inflating the cyclomatic complexity of the pre-#4981 caller.
- *
  * @param {boolean} requireCoverage
  * @param {object|null} entry Istanbul coverage entry for this file.
  * @param {boolean} touched
@@ -134,23 +101,17 @@ export function shouldSkipFileForNoCoverage(
 }
 
 /**
- * Apply the standard `requireCoverage` policy to a single raw method row.
- * The per-row half of `crap-engine.js#finalizeMethodRows`'s loop body,
- * extracted (Story #4981) so `finalizeMethodRowsWithBaseline`, below, can
- * apply the exact same per-row policy to a method whose file was NOT in the
- * diff scope but whose baseline row could not be found — the fail-closed
- * path AC-3 requires.
+ * The per-row `requireCoverage` policy, shared by both finalize paths.
  *
  * @param {object} mr A raw row from `methodRowsFromReport`.
  * @param {{requireCoverage: boolean, coverageAvailable: boolean}} opts
- * @returns {{ resolved: boolean, row: object | null }} `row: null` means the
- *   method is skipped-and-counted; `resolved` tracks the join outcome
- *   (independent of whether the row survives the skip policy).
+ * @returns {{ resolved: boolean, row: object | null }} `row: null` means
+ *   skipped-and-counted; `resolved` tracks the join alone.
  */
 export function resolveRawRow(mr, { requireCoverage, coverageAvailable }) {
   const unresolved = mr.crap === null || mr.coverage === null;
   const resolved = !unresolved;
-  // Unjoinable is not untested (Story #4901).
+  // Unjoinable (transpiled) is not untested.
   if (
     mr.coordinateSystem === COORDINATE_TRANSPILED ||
     (unresolved && (requireCoverage || !coverageAvailable))
@@ -159,11 +120,7 @@ export function resolveRawRow(mr, { requireCoverage, coverageAvailable }) {
   }
   const coverage = unresolved ? 0 : mr.coverage;
   const crap = unresolved ? crapFormula(mr.cyclomatic, 0) : mr.crap;
-  // Everything the scan decided is carried forward; this step overrides only
-  // what its own policy resolves. Spreading rather than re-listing each field
-  // is why the row's identity marker (Story #4969) and its provenance
-  // (Story #4866) survive the step without a line each to remember them —
-  // a hand-rebuilt row is how a marker silently stops reaching the baseline.
+  // Spread, never rebuild: a hand-listed row silently drops markers.
   return {
     resolved,
     row: {
@@ -176,38 +133,11 @@ export function resolveRawRow(mr, { requireCoverage, coverageAvailable }) {
 }
 
 /**
- * Baseline-join mode (Story #4981; gated by
- * `incrementalCoverage.baselineJoin` since Story #5173): resolve a file's raw
- * method rows against its committed CRAP-baseline rows instead of requiring
- * fresh coverage, for a file the diff did NOT touch.
- *
- * Rationale: when the capture was skipped because nothing under
- * `crap.targetDirs` changed, the coverage artifact on disk is whatever the
- * last run left — so an untouched file's coverage entry may legitimately be
- * absent even though nothing about that file's methods changed. (The capture
- * run itself is never narrowed: a capture that *does* happen is the ordinary
- * full suite — Story #5065.) Requiring a fresh join for it would either
- * (a) skip-and-count
- * every one of its methods under `requireCoverage: true`, weakening the
- * gate's signal for the vast majority of the tree on every run, or (b) score
- * them at an invented 0% under `requireCoverage: false`, manufacturing a
- * maximal CRAP for code the diff never touched. Neither is a measurement.
- *
- * The join key is `${method}@${startLine}` — the per-file half of the
- * composite identity `kinds/crap.js#crapRowKey` uses for the full baseline
- * compare (`${path}::${method}@${startLine}`); callers pass in a
- * per-file-scoped `baselineByKey` map so this function stays path-agnostic.
- *
- * **Fail-closed (AC-3).** `touched: true` (the file WAS in the diff) or a
- * missing/empty `baselineByKey` reproduces `crap-engine.js#finalizeMethodRows`
- * exactly — this is the pre-#4981 per-row policy, so a caller that never
- * opts in sees byte-identical behaviour (AC-5). For an untouched file, a
- * method whose baseline row cannot be found (new method, moved line, or a
- * baseline that simply never carried it) is NOT invented — it falls back to
- * the same per-row `requireCoverage` skip-and-count policy, via the shared
- * `resolveRawRow`. A method whose coordinate system is transpiled is never
- * resolved from the baseline either, for the same un-joinable reason
- * `resolveRawRow` excludes it (Story #4901).
+ * For a file the diff did not touch, resolve methods from committed baseline
+ * rows: a skipped capture leaves its coverage entry legitimately absent, and
+ * neither skip-and-count nor an invented 0% would be a measurement. Touched
+ * files, an empty baseline, a missing row or a transpiled line all fall back
+ * to `resolveRawRow` — never an invented verdict.
  *
  * @param {Array<object>} rawRows Rows from `methodRowsFromReport`, all for
  *   the SAME file.
@@ -257,8 +187,6 @@ export function finalizeMethodRowsWithBaseline(
         continue;
       }
     }
-    // Touched file, no baseline scope, or no baseline row for this method —
-    // fail closed to the standard policy rather than inventing a verdict.
     const resolution = resolveRawRow(mr, {
       requireCoverage,
       coverageAvailable,

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

@@ -1,37 +1,18 @@
 /**
- * crap-coordinates.js — the CRAP kernel's two line-coordinate-system
- * constants and the CRAP formula itself.
- *
- * Deliberately dependency-free (Story #4981 split, pulled out of
- * `crap-engine.js`): both `crap-engine.js` and `crap-baseline-join.js`
- * need these, and having either import them from the other would close a
- * cycle. `crap-engine.js` re-exports the two constants so its existing
- * importers (`baselines/kinds/crap.js`, `crap-utils.js`, tests) are
- * unaffected.
+ * Dependency-free so `crap-engine.js` and `crap-baseline-join.js` can share
+ * these without an import cycle.
  */
 
 /**
- * The two line coordinate systems a CRAP row's `startLine` can be expressed
- * in (Story #4866).
- *
- * `original` — the coordinates of the file a reader can open, and the ones
- * istanbul's `fnMap` is keyed against. A JavaScript source is already in this
- * system; a TS/TSX source reaches it only through a successful sourcemap
- * lookup.
- *
- * `transpiled` — escomplex's own coordinates over the emitted JavaScript,
- * kept only when the sourcemap has no entry originating on the method's
- * generated line. Such a row is NOT an original-source coordinate and must
- * never be presented as one: it cannot be joined to coverage, and it cannot
- * be compared against a baseline row carrying the other provenance.
+ * A row's `startLine` system. `original` is the readable file's (and
+ * istanbul's). `transpiled` is kept only when the sourcemap cannot map the
+ * line; such a row can neither join coverage nor compare against an
+ * `original` baseline row.
  */
 export const COORDINATE_ORIGINAL = 'original';
 export const COORDINATE_TRANSPILED = 'transpiled';
 
 /**
- * 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}