mandrel 2.24.0 → 2.25.0

package/.agents/scripts/lib/baselines/reader.js

@@ -221,6 +221,11 @@ function readAndShape(kind, absolutePath) {
     // dropping it here would make every baseline look unstamped and fail the
     // whole repo closed on a stamp that is actually present on disk.
     scoringSemantics: parsed.scoringSemantics,
+    // Story #4866 — same contract for the transpiler stamp. Dropping it here
+    // would leave the ts-transpiler compat axis reachable but blind: it would
+    // read `undefined` off every loaded envelope and pass vacuously, which is
+    // the exact deadness this Story exists to end.
+    tsTranspilerVersion: parsed.tsTranspilerVersion,
   };
 }
 
@@ -314,6 +319,11 @@ export function loadFile(absolutePath, opts = {}) {
     // dropping it here would make every baseline look unstamped and fail the
     // whole repo closed on a stamp that is actually present on disk.
     scoringSemantics: parsed.scoringSemantics,
+    // Story #4866 — same contract for the transpiler stamp. Dropping it here
+    // would leave the ts-transpiler compat axis reachable but blind: it would
+    // read `undefined` off every loaded envelope and pass vacuously, which is
+    // the exact deadness this Story exists to end.
+    tsTranspilerVersion: parsed.tsTranspilerVersion,
   };
 }
 

package/.agents/scripts/lib/baselines/writer.js

@@ -262,9 +262,10 @@ export function writeFile(absPath, envelope, opts = {}) {
   // declaration order; the row sort is done by `sortRows()`.
   //
   // Story #4775: the projection is deliberately explicit, so any per-kind
-  // envelope stamp (`scoringSemantics`) must be carried through by name or it
-  // is silently dropped on the way to disk — the stamp would then be present
-  // in memory, validated, and absent from the file it exists to protect.
+  // envelope stamp (`scoringSemantics`, and `tsTranspilerVersion` since Story
+  // #4866) must be carried through by name or it is silently dropped on the
+  // way to disk — the stamp would then be present in memory, validated, and
+  // absent from the file it exists to protect.
   const canonical = {
     $schema: envelope.$schema,
     kernelVersion: envelope.kernelVersion,
@@ -272,6 +273,9 @@ export function writeFile(absPath, envelope, opts = {}) {
     ...(envelope.scoringSemantics === undefined
       ? {}
       : { scoringSemantics: envelope.scoringSemantics }),
+    ...(envelope.tsTranspilerVersion === undefined
+      ? {}
+      : { tsTranspilerVersion: envelope.tsTranspilerVersion }),
     rollup: envelope.rollup,
     rows: envelope.rows,
   };

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -214,12 +214,17 @@ const ROUTING_SCHEMA = {
 // the merge/CI watch poll loop; `autoMerge` selects the merge posture.
 // Retired: `earlyPr` (Epic early-PR warmup) and `requireChecks` (no
 // AutomergePredicate reader on v2).
+// Story #4890 added `attachWindowMs`: how long the watch keeps re-resolving an
+// EMPTY required-check set before it stops waiting for one. This block is
+// `additionalProperties: false`, so the knob is inert unless it lands here AND
+// in the `.agents/schemas/agentrc.schema.json` mirror.
 const CI_WATCH_SCHEMA = {
   type: 'object',
   properties: {
     pollIntervalMs: { type: 'integer', minimum: 1 },
     maxPolls: { type: 'integer', minimum: 1 },
     maxResumes: { type: 'integer', minimum: 0 },
+    attachWindowMs: { type: 'integer', minimum: 1 },
   },
   additionalProperties: false,
 };

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

@@ -1,6 +1,24 @@
 import escomplex from 'typhonjs-escomplex';
 import { coverageForMethodInEntry } from './coverage-utils.js';
 
+/**
+ * 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.
+ */
+export const COORDINATE_ORIGINAL = 'original';
+export const COORDINATE_TRANSPILED = 'transpiled';
+
 /**
  * Derive the raw per-method CRAP rows from an escomplex report.
  *
@@ -9,15 +27,20 @@ import { coverageForMethodInEntry } from './coverage-utils.js';
  * method's line is remapped or its coverage joined — the parity the
  * combined-parity suite asserts.
  *
- * **Coordinates (Story #4775).** `mapLine` translates escomplex's
- * `lineStart` — which is in *transpiled* coordinates for a TS/TSX source —
- * into the *original source* coordinates istanbul's `fnMap` uses. Without it
- * the join compares two different coordinate systems and either misses or,
- * worse, collides with an unrelated function. A `null` mapper means the two
- * coordinate systems already coincide (plain JavaScript), and a line the map
- * cannot resolve falls back to the un-remapped value rather than dropping the
- * method outright. The remapped line is also what the row reports, so a
- * persisted row points at a line the reader can actually open.
+ * **Coordinates (Story #4775, corrected by Story #4866).** `mapLine`
+ * translates escomplex's `lineStart` — which is in *transpiled* coordinates
+ * for a TS/TSX source — into the *original source* coordinates istanbul's
+ * `fnMap` uses. A `null` mapper means the two coordinate systems already
+ * coincide (plain JavaScript).
+ *
+ * #4775 let an unresolvable line fall back to the un-remapped value, which
+ * made one scan emit rows in two coordinate systems with nothing on the row
+ * saying which. Each row now records its own `coordinateSystem`, and an
+ * un-remapped row joins no coverage at all: joining a transpiled line against
+ * an original-source `fnMap` does not merely miss, it can land inside an
+ * unrelated function's range and mis-attribute that function's coverage. An
+ * honest `coverage: null` lets the scanner's `requireCoverage` policy decide,
+ * exactly as it does for a genuinely uninstrumented method.
  *
  * @param {object|null} report An `escomplex.analyzeModule` report.
  * @param {object|null} coverageForFile Istanbul coverage entry for this file.
@@ -28,22 +51,55 @@ import { coverageForMethodInEntry } from './coverage-utils.js';
  *   cyclomatic: number,
  *   coverage: number|null,
  *   crap: number|null,
+ *   coordinateSystem: 'original'|'transpiled',
  * }>}
  */
+/**
+ * Resolve one method's line into a coordinate and the provenance of that
+ * coordinate — the single place the rule lives.
+ *
+ * No mapper means the source was never transpiled, so its line already IS an
+ * original-source coordinate. A mapper that resolves yields one. A mapper
+ * that does not leaves the transpiled line, said so.
+ *
+ * @param {number} rawStartLine escomplex's `lineStart`.
+ * @param {((line: number) => number|null)|null} mapLine
+ * @returns {{startLine: number, coordinateSystem: 'original'|'transpiled'}}
+ */
+function resolveCoordinate(rawStartLine, mapLine) {
+  if (typeof mapLine !== 'function') {
+    return { startLine: rawStartLine, coordinateSystem: COORDINATE_ORIGINAL };
+  }
+  const mapped = mapLine(rawStartLine);
+  return typeof mapped === 'number'
+    ? { startLine: mapped, coordinateSystem: COORDINATE_ORIGINAL }
+    : { startLine: rawStartLine, coordinateSystem: COORDINATE_TRANSPILED };
+}
+
 export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
   const methods = report?.methods ?? [];
   const rows = [];
   for (const m of methods) {
     const rawStartLine = m?.lineStart;
     if (typeof rawStartLine !== 'number') continue;
-    const mapped = typeof mapLine === 'function' ? mapLine(rawStartLine) : null;
-    const startLine = typeof mapped === 'number' ? mapped : rawStartLine;
+    const { startLine, coordinateSystem } = resolveCoordinate(
+      rawStartLine,
+      mapLine,
+    );
     const cyclomatic = m?.cyclomatic ?? 0;
-    const coverage = coverageForFile
-      ? coverageForMethodInEntry(coverageForFile, startLine)
-      : null;
+    const coverage =
+      coverageForFile && coordinateSystem === COORDINATE_ORIGINAL
+        ? coverageForMethodInEntry(coverageForFile, startLine)
+        : null;
     const crap = coverage === null ? null : crapFormula(cyclomatic, coverage);
-    rows.push({ method: m.name, startLine, cyclomatic, coverage, crap });
+    rows.push({
+      method: m.name,
+      startLine,
+      cyclomatic,
+      coverage,
+      crap,
+      coordinateSystem,
+    });
   }
   return rows;
 }
@@ -63,13 +119,26 @@ export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
  *     dropped, which made it a no-op for baseline population — the caller
  *     asked for "score it anyway" and got silence.
  *
+ * **Absent coverage is not zero coverage (Story #4871).** The 0%-covered
+ * inference above is only defensible when a coverage **artifact** exists and
+ * simply reports nothing for this method — "the tests ran and never reached
+ * it" is a measurement. When no artifact was produced at all — a freshly
+ * initialized story worktree, whose `coverage/` directory does not exist —
+ * nothing was measured, and filling the gap with 0% manufactures a maximal
+ * CRAP out of an absent observation, failing the first commit on files the
+ * change never touched. `coverageAvailable: false` therefore makes such a
+ * method **unscorable** under either policy: skipped and counted, never
+ * filled. It is deliberately keyed on the artifact, not the per-file entry,
+ * so `requireCoverage: false` keeps meaning "score untested code" whenever a
+ * real coverage run stands behind the verdict.
+ *
  * `resolvedMethods` / `totalMethods` count the *join*, not the fill: a
  * method scored 0% because its coverage was unresolved counts as
  * unresolved. That is what makes them usable as a health signal for the
  * updater's fail-closed resolution-rate floor.
  *
  * @param {Array<object>} rawRows Rows from `methodRowsFromReport`.
- * @param {{requireCoverage?: boolean}} [opts]
+ * @param {{requireCoverage?: boolean, coverageAvailable?: boolean}} [opts]
  * @returns {{
  *   rows: Array<object>,
  *   skippedMethodsNoCoverage: number,
@@ -77,7 +146,10 @@ export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
  *   totalMethods: number,
  * }}
  */
-export function finalizeMethodRows(rawRows, { requireCoverage = true } = {}) {
+export function finalizeMethodRows(
+  rawRows,
+  { requireCoverage = true, coverageAvailable = true } = {},
+) {
   const rows = [];
   let skippedMethodsNoCoverage = 0;
   let resolvedMethods = 0;
@@ -86,7 +158,7 @@ export function finalizeMethodRows(rawRows, { requireCoverage = true } = {}) {
     totalMethods += 1;
     const unresolved = mr.crap === null || mr.coverage === null;
     if (!unresolved) resolvedMethods += 1;
-    if (unresolved && requireCoverage) {
+    if (unresolved && (requireCoverage || !coverageAvailable)) {
       skippedMethodsNoCoverage += 1;
       continue;
     }
@@ -98,6 +170,10 @@ export function finalizeMethodRows(rawRows, { requireCoverage = true } = {}) {
       cyclomatic: mr.cyclomatic,
       coverage,
       crap,
+      // Provenance survives the policy step (Story #4866): a row scored 0%
+      // under `requireCoverage: false` may still be carrying a transpiled
+      // coordinate, and the compare needs to know that before it keys on it.
+      coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
     });
   }
   return { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods };
@@ -111,7 +187,8 @@ export function finalizeMethodRows(rawRows, { requireCoverage = true } = {}) {
  * 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`
+ *   - Methods whose coverage cannot be resolved from `coverageForFile` —
+ *     including every method whose line stayed in transpiled coordinates —
  *     produce `coverage: null` and `crap: null`. Callers apply their own
  *     `requireCoverage` policy at the scanner level (`finalizeMethodRows`);
  *     this kernel never decides to skip.
@@ -130,6 +207,7 @@ export function finalizeMethodRows(rawRows, { requireCoverage = true } = {}) {
  *   cyclomatic: number,
  *   coverage: number|null,
  *   crap: number|null,
+ *   coordinateSystem: 'original'|'transpiled',
  * }>}
  */
 export function calculateCrapForSource(

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,19 @@ 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 }),
     })),
   };
 }
@@ -201,6 +220,25 @@ export function buildBaselineEnvelope({
   };
 }
 
+/**
+ * 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 +459,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;
 
@@ -466,6 +505,7 @@ export async function scanAndScore({
         cyclomatic: mr.cyclomatic,
         coverage: mr.coverage,
         crap: mr.crap,
+        coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
       });
     }
   }
@@ -494,7 +534,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 +565,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 +614,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 +662,10 @@ function scoreFileCombinedSerial({ abs, relPath, requireCoverage }, coverage) {
     };
   }
   const { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods } =
-    finalizeMethodRows(rawCrapRows, { requireCoverage });
+    finalizeMethodRows(rawCrapRows, {
+      requireCoverage,
+      coverageAvailable,
+    });
   return {
     relPath,
     miScore,
@@ -730,12 +782,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;
 
@@ -789,6 +848,7 @@ export async function scanAndScoreCombined({
         cyclomatic: mr.cyclomatic,
         coverage: mr.coverage,
         crap: mr.crap,
+        coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
       });
     }
   }

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] || '');
     }
   });
 }