mandrel 2.24.0 → 2.26.0

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

@@ -4,7 +4,11 @@ import escomplex from 'typhonjs-escomplex';
 import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
 import { findCoverageEntry } from './coverage-utils.js';
 import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
-import { finalizeMethodRows, methodRowsFromReport } from './crap-engine.js';
+import {
+  COORDINATE_ORIGINAL,
+  finalizeMethodRows,
+  methodRowsFromReport,
+} from './crap-engine.js';
 import { Logger } from './Logger.js';
 import { scanDirectory } from './maintainability-utils.js';
 import {
@@ -97,11 +101,19 @@ function resolveBaselinePath({ cwd = process.cwd(), baselinePath } = {}) {
 /**
  * Story #1895: shipped baseline switched to the canonical envelope shape
  * (`$schema`, `kernelVersion`, `generatedAt`, `rollup`, `rows` keyed on
- * `path`). Backfill the legacy `escomplexVersion`/`tsTranspilerVersion`
- * version fields from the running scorer and re-key rows by `file` so
- * existing comparators keep working until Story #1912 lands the unified
- * gate. Detection probes the first row for the new `path` key — the
- * legacy envelope also carries `$schema` but keys rows by `file`.
+ * `path`). Backfill the legacy `escomplexVersion` field from the running
+ * scorer and re-key rows by `file` so existing comparators keep working
+ * until Story #1912 lands the unified gate. Detection probes the first row
+ * for the new `path` key — the legacy envelope also carries `$schema` but
+ * keys rows by `file`.
+ *
+ * **Compat stamps survive the projection (Story #4866).** `scoringSemantics`
+ * and `tsTranspilerVersion` are *baseline* facts, and the projection used to
+ * drop the first and overwrite the second with the RUNNING value — which made
+ * every compat axis reading them either unstamped or vacuously self-equal.
+ * They are carried verbatim now, `null` when the envelope never stamped them,
+ * so an axis can tell "written by a different transpiler" apart from "written
+ * before the stamp existed" instead of guessing.
  */
 function projectCrapEnvelopeToLegacy(parsed) {
   if (
@@ -114,12 +126,25 @@ function projectCrapEnvelopeToLegacy(parsed) {
   return {
     kernelVersion: parsed.kernelVersion,
     escomplexVersion: resolveEscomplexVersion(),
-    tsTranspilerVersion: resolveTsTranspilerVersion(),
+    tsTranspilerVersion:
+      typeof parsed.tsTranspilerVersion === 'string'
+        ? parsed.tsTranspilerVersion
+        : null,
+    scoringSemantics: parsed.scoringSemantics ?? null,
     rows: parsed.rows.map((row) => ({
       crap: row.crap,
       file: row.path,
       method: row.method,
       startLine: row.startLine,
+      ...(row.coordinateSystem === undefined
+        ? {}
+        : { coordinateSystem: row.coordinateSystem }),
+      // Story #4969, same reason as the stamps above: `anonymous` is a
+      // BASELINE fact. Dropping it here left every re-keyed row looking like
+      // an unmarked anonymous one, which is precisely the shape the
+      // `anon-identity-unstamped` axis fails closed — the projection would
+      // have manufactured the very defect the axis exists to catch.
+      ...(row.anonymous === undefined ? {} : { anonymous: row.anonymous }),
     })),
   };
 }
@@ -196,11 +221,31 @@ export function buildBaselineEnvelope({
       file: r.file,
       method: r.method,
       startLine: r.startLine,
+      ...(r.anonymous === undefined ? {} : { anonymous: r.anonymous }),
     })),
     tsTranspilerVersion,
   };
 }
 
+/**
+ * True when a coverage artifact was actually loaded for this scan.
+ *
+ * Story #4871: "the tests ran and never reached this method" is a measurement
+ * and the CRAP formula's 0%-covered arm is the right answer for it. "No
+ * coverage run happened at all" — a freshly initialized story worktree with no
+ * `coverage/` directory — is an *absent* observation, and filling it with 0%
+ * drives every method to `c² + c`, failing the first commit on files the
+ * change never touched. Resolved once per scan and carried on each queue item
+ * so the pool workers, which only ever receive their own file's coverage
+ * entry, can still tell the two apart.
+ *
+ * @param {object|null|undefined} coverage Parsed `coverage-final.json` map.
+ * @returns {boolean}
+ */
+function isCoverageArtifactPresent(coverage) {
+  return coverage !== null && coverage !== undefined;
+}
+
 /**
  * How many files to name when reporting the worst unresolved offenders. Long
  * enough to point at a pattern, short enough to stay a readable CLI message.
@@ -421,12 +466,13 @@ export async function scanAndScore({
   // inside `.worktrees/<workspace>/` (with cwd pointing at the main
   // checkout) cannot leak the worktree prefix into the on-disk baseline's
   // `file` / `path` keys downstream.
+  const coverageAvailable = isCoverageArtifactPresent(coverage);
   const queue = [];
   for (const abs of files) {
     const rawRel = path.relative(cwd, abs).replace(/\\/g, '/');
     const relPath = canonicalisePath(rawRel);
     if (scopeSet && !scopeSet.has(relPath)) continue;
-    queue.push({ abs, relPath, requireCoverage });
+    queue.push({ abs, relPath, requireCoverage, coverageAvailable });
   }
   const scannedFiles = queue.length;
 
@@ -462,10 +508,14 @@ export async function scanAndScore({
       rows.push({
         file: item.relPath,
         method: mr.method,
+        // Story #4969: `method` may be a derived anonymous identity; the flag
+        // is what lets the persisted row say so.
+        anonymous: mr.anonymous === true,
         startLine: mr.startLine,
         cyclomatic: mr.cyclomatic,
         coverage: mr.coverage,
         crap: mr.crap,
+        coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
       });
     }
   }
@@ -494,7 +544,10 @@ export async function scanAndScore({
  * Uses `analyzeOnce` so the source is parsed a single time and both the
  * CRAP rows and the MI score are derived from the same escomplex report.
  */
-function scoreFileSerial({ abs, relPath, requireCoverage }, coverage) {
+function scoreFileSerial(
+  { abs, relPath, requireCoverage, coverageAvailable = true },
+  coverage,
+) {
   const entry = findCoverageEntry(coverage, relPath);
   if (requireCoverage && entry === null) {
     return {
@@ -522,7 +575,10 @@ function scoreFileSerial({ abs, relPath, requireCoverage }, coverage) {
     prepared.mapLine,
   );
   if (parseError) return dropped;
-  const finalized = finalizeMethodRows(crapRows, { requireCoverage });
+  const finalized = finalizeMethodRows(crapRows, {
+    requireCoverage,
+    coverageAvailable,
+  });
   return {
     skippedFileNoCoverage: false,
     hasCoverageEntry: entry !== null,
@@ -568,7 +624,10 @@ async function scoreFilesViaPool(queue, coverage) {
  *     file), `[]` when coverage-skipped, otherwise the scored method rows.
  *   - `skippedFileNoCoverage` / `skippedMethodsNoCoverage` — CRAP counters.
  */
-function scoreFileCombinedSerial({ abs, relPath, requireCoverage }, coverage) {
+function scoreFileCombinedSerial(
+  { abs, relPath, requireCoverage, coverageAvailable = true },
+  coverage,
+) {
   const entry = findCoverageEntry(coverage, relPath);
   const prepared = prepareSourceForScoring(abs);
   if (prepared.error) {
@@ -613,7 +672,10 @@ function scoreFileCombinedSerial({ abs, relPath, requireCoverage }, coverage) {
     };
   }
   const { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods } =
-    finalizeMethodRows(rawCrapRows, { requireCoverage });
+    finalizeMethodRows(rawCrapRows, {
+      requireCoverage,
+      coverageAvailable,
+    });
   return {
     relPath,
     miScore,
@@ -730,12 +792,19 @@ export async function scanAndScoreCombined({
   // Build the work queue. Each item carries both the canonicalised relPath
   // (CRAP's key + scope filter, matching scanAndScore) and the raw relPath
   // (MI's key, matching calculateAll's `path.relative(cwd, p)` shape).
+  const coverageAvailable = isCoverageArtifactPresent(coverage);
   const queue = [];
   for (const abs of files) {
     const rawRel = path.relative(cwd, abs).replace(/\\/g, '/');
     const relPath = canonicalisePath(rawRel);
     if (scopeSet && !scopeSet.has(relPath)) continue;
-    queue.push({ abs, relPath, miRel: rawRel, requireCoverage });
+    queue.push({
+      abs,
+      relPath,
+      miRel: rawRel,
+      requireCoverage,
+      coverageAvailable,
+    });
   }
   const scannedFiles = queue.length;
 
@@ -785,10 +854,14 @@ export async function scanAndScoreCombined({
       crapRows.push({
         file: item.relPath,
         method: mr.method,
+        // Story #4969: `method` may be a derived anonymous identity; the flag
+        // is what lets the persisted row say so.
+        anonymous: mr.anonymous === true,
         startLine: mr.startLine,
         cyclomatic: mr.cyclomatic,
         coverage: mr.coverage,
         crap: mr.crap,
+        coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
       });
     }
   }

package/.agents/scripts/lib/cyclomatic-ceiling.js

@@ -0,0 +1,265 @@
+/**
+ * cyclomatic-ceiling.js — the enforcing core behind
+ * `delivery.quality.codingGuardrails.cyclomaticMustFix` (Story #4923).
+ *
+ * The two `codingGuardrails` cyclomatic knobs shipped schema-validated,
+ * bootstrap-defaulted and resolver-resolved, and were then read by nothing:
+ * `cyclomaticMustFix` had no consumer at all, and `cyclomaticFlag` was
+ * shadowed by a hardcoded `8` in a `quality-preview` display column. A ceiling
+ * nothing enforces is worse than no ceiling, because the workflow docs promise
+ * the merge will be refused.
+ *
+ * This module is that enforcement, shaped as a **ratchet** rather than a
+ * cliff. The repository already carries dozens of functions above the
+ * must-fix ceiling; failing every one of them at once would have made the
+ * gate un-landable and it would have been disabled the same day. So the
+ * committed `baselines/cyclomatic.json` records the existing breaches per
+ * file, and the gate fails only when a change **adds** an over-ceiling
+ * function to a file that had none, adds one **beyond** that file's recorded
+ * count, or pushes a file's worst function **higher** than recorded. Burning
+ * the recorded breaches down is a separate, always-permitted motion — a
+ * shrinking baseline is the success signal.
+ *
+ * Scope: the module walks the `maintainability` gate's `targetDirs` /
+ * `ignoreGlobs`. Both instruments read the same coverage-free escomplex
+ * surface, so re-declaring the scope under `codingGuardrails` would have
+ * added two config keys whose only correct value is "whatever maintainability
+ * says".
+ *
+ * @module lib/cyclomatic-ceiling
+ */
+
+import path from 'node:path';
+import { calculateReportForFile } from './maintainability-engine.js';
+import { isIgnoredByGlobs, scanDirectory } from './maintainability-utils.js';
+
+/** Default location of the committed breach baseline. */
+export const DEFAULT_CYCLOMATIC_BASELINE = 'baselines/cyclomatic.json';
+
+/** Baseline `$schema` marker, matching the sibling ratchet baselines. */
+const CYCLOMATIC_BASELINE_SCHEMA =
+  'https://mandrel.dev/baselines/cyclomatic.schema.json';
+
+/**
+ * Resolve the enforcement policy from a resolved `delivery.quality` block.
+ *
+ * `mustFix` and `flag` come straight from `resolveCodingGuardrails`, so a
+ * consumer that tunes either knob tunes this gate — which is the whole point
+ * of the Story. `targetDirs` / `ignoreGlobs` are borrowed from the
+ * maintainability gate (see the module note).
+ *
+ * @param {object | null | undefined} quality resolved `delivery.quality`
+ * @returns {{ mustFix: number, flag: number, targetDirs: string[], ignoreGlobs: string[] }}
+ */
+export function resolveCyclomaticPolicy(quality) {
+  const guardrails = quality?.codingGuardrails ?? {};
+  const mi = quality?.maintainability ?? {};
+  return {
+    mustFix: Number(guardrails.cyclomaticMustFix ?? 12),
+    flag: Number(guardrails.cyclomaticFlag ?? 8),
+    targetDirs: Array.isArray(mi.targetDirs) ? mi.targetDirs : [],
+    ignoreGlobs: Array.isArray(mi.ignoreGlobs) ? mi.ignoreGlobs : [],
+  };
+}
+
+/**
+ * Reduce one file's escomplex method list to a breach row, or `null` when the
+ * file carries no function above `ceiling`.
+ *
+ * Pure. Module-private: tests reach it through `scanCyclomatic`'s `scoreFile`
+ * seam, which keeps the row math exercised without adding an export whose only
+ * importer is a test (the `--production` dead-export pass discounts those).
+ *
+ * @param {string} file repo-relative POSIX path
+ * @param {Array<{ cyclomatic?: number }>} methods
+ * @param {number} ceiling
+ * @returns {{ file: string, methodsAboveCeiling: number, maxCyclomatic: number } | null}
+ */
+function breachRowFor(file, methods, ceiling) {
+  let count = 0;
+  let max = 0;
+  for (const method of methods ?? []) {
+    const c = Number(method?.cyclomatic ?? 0);
+    if (!Number.isFinite(c)) continue;
+    if (c > ceiling) count += 1;
+    if (c > max) max = c;
+  }
+  return count === 0
+    ? null
+    : { file, methodsAboveCeiling: count, maxCyclomatic: max };
+}
+
+/**
+ * Walk the configured scope and score every file, returning the breach rows
+ * sorted by path.
+ *
+ * `scoreFile` is a seam so tests can drive the reduction without the kernel;
+ * production callers omit it.
+ *
+ * @param {{
+ *   targetDirs: string[],
+ *   ignoreGlobs?: string[],
+ *   ceiling: number,
+ *   cwd?: string,
+ *   scoreFile?: (absPath: string) => { methods?: Array<{ cyclomatic?: number }>, parseError?: boolean },
+ * }} args
+ * @returns {{ rows: Array<object>, scannedFiles: number, parseErrors: number }}
+ */
+export function scanCyclomatic({
+  targetDirs,
+  ignoreGlobs = [],
+  ceiling,
+  cwd = process.cwd(),
+  scoreFile = calculateReportForFile,
+}) {
+  const files = [];
+  for (const dir of targetDirs ?? []) {
+    const abs = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+    scanDirectory(abs, files, { cwd, ignoreGlobs });
+  }
+  files.sort();
+  const rows = [];
+  let parseErrors = 0;
+  for (const abs of files) {
+    if (isIgnoredByGlobs(abs, ignoreGlobs, cwd)) continue;
+    const report = scoreFile(abs);
+    if (!report || report.parseError) {
+      parseErrors += 1;
+      continue;
+    }
+    const rel = path.relative(cwd, abs).split(path.sep).join('/');
+    const row = breachRowFor(rel, report.methods, ceiling);
+    if (row) rows.push(row);
+  }
+  rows.sort((a, b) => a.file.localeCompare(b.file));
+  return { rows, scannedFiles: files.length, parseErrors };
+}
+
+/**
+ * Diff current breach rows against the committed baseline.
+ *
+ * Four buckets, only the first two of which fail the gate:
+ *
+ *   - `added`    — a file whose over-ceiling function count rose (including
+ *                  0 → 1, i.e. a brand-new breach in new or changed code).
+ *   - `worsened` — a file whose worst function got worse than recorded.
+ *   - `removed`  — a file that no longer breaches at all.
+ *   - `improved` — a file that breaches less than recorded.
+ *
+ * Pure; identity is the repo-relative file path.
+ *
+ * @param {Array<{file: string, methodsAboveCeiling: number, maxCyclomatic: number}>} baselineRows
+ * @param {Array<{file: string, methodsAboveCeiling: number, maxCyclomatic: number}>} currentRows
+ * @returns {{ added: Array<object>, worsened: Array<object>, removed: Array<object>, improved: Array<object> }}
+ */
+export function diffCyclomaticRows(baselineRows, currentRows) {
+  const base = new Map(
+    (baselineRows ?? [])
+      .filter((r) => typeof r?.file === 'string')
+      .map((r) => [r.file, r]),
+  );
+  const added = [];
+  const worsened = [];
+  const improved = [];
+  const seen = new Set();
+  for (const row of currentRows ?? []) {
+    if (typeof row?.file !== 'string') continue;
+    seen.add(row.file);
+    const prior = base.get(row.file);
+    const priorCount = Number(prior?.methodsAboveCeiling ?? 0);
+    const priorMax = Number(prior?.maxCyclomatic ?? 0);
+    if (row.methodsAboveCeiling > priorCount) {
+      added.push({ ...row, baselineCount: priorCount });
+      continue;
+    }
+    if (row.maxCyclomatic > priorMax) {
+      worsened.push({ ...row, baselineMax: priorMax });
+      continue;
+    }
+    if (row.methodsAboveCeiling < priorCount || row.maxCyclomatic < priorMax) {
+      improved.push({
+        ...row,
+        baselineCount: priorCount,
+        baselineMax: priorMax,
+      });
+    }
+  }
+  const removed = (baselineRows ?? []).filter(
+    (r) => typeof r?.file === 'string' && !seen.has(r.file),
+  );
+  const byFile = (a, b) => a.file.localeCompare(b.file);
+  return {
+    added: added.sort(byFile),
+    worsened: worsened.sort(byFile),
+    removed: removed.sort(byFile),
+    improved: improved.sort(byFile),
+  };
+}
+
+/**
+ * Assemble the committed baseline envelope. The rollup is deliberately
+ * derived, never hand-written: a zero-row baseline here reports zero breaches
+ * because the repository has none, not because nobody produced it.
+ *
+ * @param {{ rows: Array<object>, ceiling: number, generatedAt?: string }} args
+ * @returns {object}
+ */
+export function buildCyclomaticEnvelope({ rows, ceiling, generatedAt }) {
+  const safeRows = rows ?? [];
+  let methods = 0;
+  let max = 0;
+  for (const row of safeRows) {
+    methods += Number(row.methodsAboveCeiling ?? 0);
+    if (Number(row.maxCyclomatic ?? 0) > max) max = Number(row.maxCyclomatic);
+  }
+  return {
+    $schema: CYCLOMATIC_BASELINE_SCHEMA,
+    generatedAt: generatedAt ?? new Date().toISOString(),
+    ceiling,
+    rollup: {
+      '*': {
+        filesAboveCeiling: safeRows.length,
+        methodsAboveCeiling: methods,
+        maxCyclomatic: max,
+      },
+    },
+    rows: safeRows,
+  };
+}
+
+/**
+ * Render the human-readable diff. Emits a summary line even on a clean run so
+ * operators see the "no drift" signal rather than silence.
+ *
+ * @param {{ added: Array, worsened: Array, removed: Array, improved: Array }} diff
+ * @param {number} ceiling
+ * @returns {string}
+ */
+export function renderCyclomaticDiff(diff, ceiling) {
+  const lines = [];
+  for (const r of diff.added) {
+    lines.push(
+      `+ ${r.file}: ${r.methodsAboveCeiling} function(s) over c=${ceiling} (recorded ${r.baselineCount}), worst c=${r.maxCyclomatic}`,
+    );
+  }
+  for (const r of diff.worsened) {
+    lines.push(
+      `! ${r.file}: worst function c=${r.maxCyclomatic} (recorded ${r.baselineMax})`,
+    );
+  }
+  for (const r of diff.improved) {
+    lines.push(
+      `~ ${r.file}: ${r.methodsAboveCeiling} over c=${ceiling} (recorded ${r.baselineCount}), worst c=${r.maxCyclomatic} (recorded ${r.baselineMax})`,
+    );
+  }
+  for (const r of diff.removed) {
+    lines.push(`- ${r.file}: no longer over c=${ceiling}`);
+  }
+  const failing = diff.added.length + diff.worsened.length;
+  lines.push(
+    `[cyclomatic] ceiling=${ceiling} added=${diff.added.length} worsened=${diff.worsened.length} improved=${diff.improved.length} removed=${diff.removed.length} ${
+      failing > 0 ? '(gate fail)' : '(ok)'
+    }`,
+  );
+  return lines.join('\n');
+}

package/.agents/scripts/lib/env-loader.js

@@ -2,6 +2,51 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Logger } from './Logger.js';
 
+/**
+ * Parse the right-hand side of a `KEY=` line into its value.
+ *
+ * Two rules, and the quoting decides which one applies:
+ *
+ *  - **Quoted** (`"…"` / `'…'`): the contents between the opening quote and
+ *    its matching closing quote are kept **verbatim** — a `#` inside quotes is
+ *    part of the value, not a comment. Anything after the closing quote is
+ *    trailing commentary and is discarded.
+ *  - **Unquoted**: the value ends at the first **unescaped** `#`. A `\#`
+ *    escape emits a literal `#` and keeps the scan going, so a value that
+ *    genuinely contains a hash can still be written without quotes.
+ *
+ * An opening quote with no closing partner is not a quoted value — it falls
+ * through to the unquoted rule so a malformed line still yields something
+ * rather than swallowing the rest of the file's intent.
+ *
+ * @param {string} raw — the text after the `=`, unparsed.
+ * @returns {string} The value with any inline comment removed.
+ */
+function parseEnvValue(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return '';
+
+  const quote = trimmed.charAt(0);
+  if (quote === '"' || quote === "'") {
+    const closing = trimmed.indexOf(quote, 1);
+    // Verbatim contents: no comment stripping, no unescaping.
+    if (closing !== -1) return trimmed.slice(1, closing);
+  }
+
+  let value = '';
+  for (let i = 0; i < trimmed.length; i += 1) {
+    const char = trimmed.charAt(i);
+    if (char === '\\' && trimmed.charAt(i + 1) === '#') {
+      value += '#';
+      i += 1;
+      continue;
+    }
+    if (char === '#') break;
+    value += char;
+  }
+  return value.trim();
+}
+
 /**
  * Auto-load .env from the project root if it exists
  */
@@ -31,22 +76,7 @@ export function loadEnv(projectRoot) {
     const match = line.match(/^\s*([\w.-]+)\s*=\s*(.*)?\s*$/);
     if (match) {
       const key = match[1];
-      let value = (match[2] || '').trim();
-      // Remove quotes if present
-      if (
-        value.length > 0 &&
-        value.charAt(0) === '"' &&
-        value.charAt(value.length - 1) === '"'
-      ) {
-        value = value.substring(1, value.length - 1);
-      } else if (
-        value.length > 0 &&
-        value.charAt(0) === "'" &&
-        value.charAt(value.length - 1) === "'"
-      ) {
-        value = value.substring(1, value.length - 1);
-      }
-      process.env[key] = value;
+      process.env[key] = parseEnvValue(match[2] || '');
     }
   });
 }

package/.agents/scripts/lib/feedback-loop/audit-results-graduator.js

@@ -333,5 +333,3 @@ export async function graduateAuditResults(opts = {}) {
     },
   });
 }
-
-export default graduateAuditResults;

package/.agents/scripts/lib/feedback-loop/prior-feedback-fetcher.js

@@ -307,5 +307,3 @@ export async function fetchPriorFeedback({
 
   return envelope;
 }
-
-export default fetchPriorFeedback;

package/.agents/scripts/lib/feedback-loop/retro-proposals-graduator.js

@@ -495,5 +495,3 @@ export async function fileRetroProposals({
   );
   return { routedProposals: enriched, summary };
 }
-
-export default graduateRetroProposals;