mandrel 2.28.0 → 2.30.0

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

@@ -1,24 +1,21 @@
 import escomplex from 'typhonjs-escomplex';
 import { coverageForMethodInEntry } from './coverage-utils.js';
+// `finalizeMethodRowsWithBaseline` (Story #4981) lives in
+// crap-baseline-join.js — `resolveRawRow`, the per-row policy it shares with
+// `finalizeMethodRows` below, is imported from there so the two stay a
+// single implementation.
+import { resolveRawRow } from './crap-baseline-join.js';
+// `COORDINATE_ORIGINAL` / `COORDINATE_TRANSPILED` / `crapFormula` (Story
+// #4866 / this module's original home) now live in crap-coordinates.js —
+// re-exported here so every existing importer of this module is unaffected.
+import {
+  COORDINATE_ORIGINAL,
+  COORDINATE_TRANSPILED,
+  crapFormula,
+} from './crap-coordinates.js';
 import { deriveMethodIdentities } from './crap-method-identity.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';
+export { COORDINATE_ORIGINAL, COORDINATE_TRANSPILED, crapFormula };
 
 /**
  * Derive the raw per-method CRAP rows from an escomplex report.
@@ -170,33 +167,25 @@ export function finalizeMethodRows(
   let totalMethods = 0;
   for (const mr of rawRows ?? []) {
     totalMethods += 1;
-    const unresolved = mr.crap === null || mr.coverage === null;
-    if (!unresolved) resolvedMethods += 1;
-    // Unjoinable is not untested (Story #4901) — see the block comment above.
-    if (
-      mr.coordinateSystem === COORDINATE_TRANSPILED ||
-      (unresolved && (requireCoverage || !coverageAvailable))
-    ) {
+    const resolution = resolveRawRow(mr, {
+      requireCoverage,
+      coverageAvailable,
+    });
+    if (resolution.resolved) resolvedMethods += 1;
+    if (resolution.row === null) {
       skippedMethodsNoCoverage += 1;
       continue;
     }
-    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.
-    rows.push({
-      ...mr,
-      coverage,
-      crap,
-      coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
-    });
+    rows.push(resolution.row);
   }
   return { rows, skippedMethodsNoCoverage, resolvedMethods, totalMethods };
 }
 
+// The incremental-mode join (Story #4981) lives in crap-baseline-join.js;
+// re-exported here so it stays reachable from the scoring kernel's existing
+// public surface.
+export { finalizeMethodRowsWithBaseline } from './crap-baseline-join.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`
@@ -243,20 +232,6 @@ export function calculateCrapForSource(
   return methodRowsFromReport(report, coverageForFile, mapLine);
 }
 
-/**
- * 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.

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

@@ -0,0 +1,113 @@
+/**
+ * crap-utils-incremental.js — small pure helpers that wire the incremental
+ * CRAP join (Story #4981) into `crap-utils.js#scanAndScore`'s per-file work
+ * queue. Split into their own file so the wiring lands as new code rather
+ * than a same-file expansion of `scanAndScore` / `scoreFileSerial`.
+ */
+import { indexBaselineRowsByFile } from './crap-baseline-index.js';
+
+/**
+ * Resolve `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".
+ *
+ * @param {{ touchedFiles?: Set<string>|string[], baselineRows?: Array<object> } | null} incremental
+ * @returns {{ touchedFiles: Set<string>|null, baselineByFile: Map<string, Map<string, object>>|null }}
+ */
+export function resolveIncrementalContext(incremental) {
+  const touchedFiles = incremental?.touchedFiles
+    ? incremental.touchedFiles instanceof Set
+      ? incremental.touchedFiles
+      : new Set(incremental.touchedFiles)
+    : null;
+  const baselineByFile = incremental
+    ? indexBaselineRowsByFile(incremental.baselineRows)
+    : null;
+  return { touchedFiles, baselineByFile };
+}
+
+/**
+ * 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
+ * `crap-baseline-join.js#finalizeMethodRowsWithBaseline`'s own default).
+ *
+ * @param {object} item Base queue item (`{ abs, relPath, requireCoverage, coverageAvailable }`).
+ * @param {{ touchedFiles: Set<string>|null, baselineByFile: Map<string, Map<string, object>>|null }} ctx
+ * @returns {object} `item` plus `{ touched, baselineByKey }`.
+ */
+export function resolveQueueIncrementalFields(
+  item,
+  { touchedFiles, baselineByFile },
+) {
+  const touched = touchedFiles ? touchedFiles.has(item.relPath) : true;
+  const baselineByKey = baselineByFile
+    ? (baselineByFile.get(item.relPath) ?? new Map())
+    : null;
+  return { ...item, touched, baselineByKey };
+}
+
+/**
+ * True when `scoreFileSerial` should resolve a file's methods from the
+ * baseline rather than requiring 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}
+ */
+function isIncrementalJoinActive(touched, baselineByKey) {
+  return !touched && baselineByKey != null && baselineByKey.size > 0;
+}
+
+/**
+ * `scoreFileSerial`'s file-level skip decision, factored out whole so the
+ * incremental exception lives with the rest of this Story's branching
+ * 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
+ * @param {Map<string, object>|null} baselineByKey
+ * @returns {boolean}
+ */
+export function shouldSkipFileForNoCoverage(
+  requireCoverage,
+  entry,
+  touched,
+  baselineByKey,
+) {
+  return (
+    requireCoverage &&
+    entry === null &&
+    !isIncrementalJoinActive(touched, baselineByKey)
+  );
+}
+
+/**
+ * `scanAndScore`'s serial-vs-pool routing decision. Incremental mode always
+ * routes serial (see `isIncrementalJoinActive`'s doc for why the baseline
+ * lookup Maps don't cross the worker boundary); otherwise unchanged from the
+ * pre-#4981 queue-length cutover.
+ *
+ * @param {number} queueLength
+ * @param {unknown} incremental
+ * @param {number} serialThreshold
+ * @returns {boolean}
+ */
+export function shouldRunSerial(queueLength, incremental, serialThreshold) {
+  return queueLength < serialThreshold || Boolean(incremental);
+}
+
+/**
+ * Project the `resolvedFromBaseline` marker onto a `scanAndScore` result row
+ * — present only when true, so a full-scope scan's rows are unaffected.
+ *
+ * @param {{ resolvedFromBaseline?: boolean }} mr
+ * @returns {{ resolvedFromBaseline: true } | {}}
+ */
+export function resolvedFromBaselineFlag(mr) {
+  return mr.resolvedFromBaseline === true ? { resolvedFromBaseline: true } : {};
+}

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

@@ -4,11 +4,19 @@ 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 { finalizeMethodRowsWithBaseline } from './crap-baseline-join.js';
 import {
   COORDINATE_ORIGINAL,
   finalizeMethodRows,
   methodRowsFromReport,
 } from './crap-engine.js';
+import {
+  resolvedFromBaselineFlag,
+  resolveIncrementalContext,
+  resolveQueueIncrementalFields,
+  shouldRunSerial,
+  shouldSkipFileForNoCoverage,
+} from './crap-utils-incremental.js';
 import { Logger } from './Logger.js';
 import { scanDirectory } from './maintainability-utils.js';
 import {
@@ -98,6 +106,73 @@ function resolveBaselinePath({ cwd = process.cwd(), baselinePath } = {}) {
  *   rows: Array<{file: string, method: string, startLine: number, crap: number}>,
  * }|null}
  */
+/**
+ * The envelope-level fields the CRAP compat axes read off a *loaded* baseline
+ * — the set every read path owes `assertBaselineCompatible`.
+ *
+ * It exists because there are TWO read paths and they have now diverged three
+ * times. `check-baselines` loads through `baselines/reader.js`; the
+ * `quality-preview` pre-commit arm loads through `projectCrapEnvelopeToLegacy`
+ * below. Both are ALLOW-LISTS, both feed the same axes, and a stamp added to
+ * one and not the other yields two opposite verdicts on one file: Story #4866
+ * (`scoringSemantics`, `tsTranspilerVersion`), Story #4969 (`rows[].anonymous`)
+ * and Story #4986 (`provenanceStamped`, half-fixed by #4973) were each that
+ * same half-landing.
+ *
+ * Every one of those axes keys on a POSITIVE marker, so a dropped field reads
+ * `undefined` and fails the baseline closed with a remedy that cannot work —
+ * re-deriving it writes the stamp the read path then discards. The projection
+ * below is DERIVED from this list rather than repeating it, so a new stamp is
+ * carried here the moment it is named; a parity test holds the reader to the
+ * same set and names whichever path forgot one.
+ *
+ * Row-level markers are deliberately out: they are projected per-row, not as
+ * envelope stamps.
+ *
+ * Deliberately module-local, mirroring `SCORING_SEMANTICS` in
+ * `baselines/kinds/crap.js`: the writer's `envelopeExtras()` is the single
+ * production door to the stamp set, and exporting this list would add a second
+ * one that only a test reaches. The parity test holds this projection to
+ * `Object.keys(envelopeExtras())` instead, so a stamp the writer starts
+ * emitting fails the test here until it is named — which is the enforcement
+ * this list needs, not an export.
+ */
+const COMPAT_STAMP_FIELDS = Object.freeze([
+  'scoringSemantics',
+  'tsTranspilerVersion',
+  'provenanceStamped',
+]);
+
+/**
+ * Per-stamp coercion applied on the way through the legacy projection. A field
+ * with no entry is carried VERBATIM, which is the correct default: the axes
+ * distinguish "stamped" from "absent", so inventing a value for a stamp the
+ * envelope never wrote is the one thing a read path must not do.
+ */
+const COMPAT_STAMP_NORMALIZERS = {
+  // `null` (not the running value) when unstamped, so `ts-transpiler-drift`
+  // can tell "written by a different transpiler" from "written before the
+  // stamp existed" instead of comparing a value against itself.
+  tsTranspilerVersion: (value) => (typeof value === 'string' ? value : null),
+  scoringSemantics: (value) => value ?? null,
+};
+
+/**
+ * Project the compat stamps off a v2 envelope, driven by
+ * `COMPAT_STAMP_FIELDS`.
+ *
+ * @param {Record<string, unknown>} parsed
+ * @returns {Record<string, unknown>}
+ */
+function projectCompatStamps(parsed) {
+  const stamps = {};
+  for (const field of COMPAT_STAMP_FIELDS) {
+    const normalize = COMPAT_STAMP_NORMALIZERS[field];
+    stamps[field] = normalize ? normalize(parsed[field]) : parsed[field];
+  }
+  return stamps;
+}
+
 /**
  * Story #1895: shipped baseline switched to the canonical envelope shape
  * (`$schema`, `kernelVersion`, `generatedAt`, `rollup`, `rows` keyed on
@@ -114,6 +189,16 @@ function resolveBaselinePath({ cwd = process.cwd(), baselinePath } = {}) {
  * 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.
+ *
+ * **This projection is one of TWO (Story #4986).** `check-baselines` reads a
+ * baseline through `baselines/reader.js`; `quality-preview` reads the same file
+ * through here. Both feed `assertBaselineCompatible`, so a stamp added to one
+ * allow-list and not the other produces two opposite verdicts on one envelope —
+ * which is what happened to `provenanceStamped`: #4973 added it to the reader
+ * and left this projection dropping it, so the pre-commit CRAP arm rejected
+ * every stamped baseline with an un-satisfiable "re-seed" remedy while the
+ * authoritative gate passed. The stamp block is derived from
+ * `COMPAT_STAMP_FIELDS` above so this projection cannot fall behind again.
  */
 function projectCrapEnvelopeToLegacy(parsed) {
   if (
@@ -126,11 +211,7 @@ function projectCrapEnvelopeToLegacy(parsed) {
   return {
     kernelVersion: parsed.kernelVersion,
     escomplexVersion: resolveEscomplexVersion(),
-    tsTranspilerVersion:
-      typeof parsed.tsTranspilerVersion === 'string'
-        ? parsed.tsTranspilerVersion
-        : null,
-    scoringSemantics: parsed.scoringSemantics ?? null,
+    ...projectCompatStamps(parsed),
     rows: parsed.rows.map((row) => ({
       crap: row.crap,
       file: row.path,
@@ -409,6 +490,10 @@ export function analyzeOnce(source, coverageForFile, mapLine = null) {
  * `regenerateMainFromTree`) SHOULD pass the MI scan's file list here so the
  * tree is walked only once per run.
  *
+ * `incremental` (Story #4981) resolves an untouched file's methods from
+ * `crap-baseline-join.js#finalizeMethodRowsWithBaseline` instead of
+ * requiring fresh coverage; omitted (the default), behaviour is unchanged.
+ *
  * @param {{
  *   targetDirs: string[],
  *   coverage: object|null,
@@ -416,6 +501,7 @@ export function analyzeOnce(source, coverageForFile, mapLine = null) {
  *   cwd?: string,
  *   scopeFiles?: Set<string>|string[]|null,
  *   preScannedFiles?: string[]|null,
+ *   incremental?: { touchedFiles: Set<string>|string[], baselineRows: Array<object> } | null,
  * }} params
  * @returns {{
  *   rows: Array<{
@@ -439,6 +525,7 @@ export async function scanAndScore({
   scopeFiles = null,
   ignoreGlobs = [],
   preScannedFiles = null,
+  incremental = null,
 }) {
   if (!Array.isArray(targetDirs)) {
     throw new TypeError('scanAndScore: targetDirs must be an array');
@@ -460,6 +547,8 @@ export async function scanAndScore({
   }
   files.sort();
 
+  const incrementalCtx = resolveIncrementalContext(incremental);
+
   // Build the work-queue first so scopeFile filtering happens before
   // any I/O / IPC. `scannedFiles` is the in-scope count.
   // Story #2079: route every relPath through path-canon so a scan from
@@ -472,14 +561,18 @@ export async function scanAndScore({
     const rawRel = path.relative(cwd, abs).replace(/\\/g, '/');
     const relPath = canonicalisePath(rawRel);
     if (scopeSet && !scopeSet.has(relPath)) continue;
-    queue.push({ abs, relPath, requireCoverage, coverageAvailable });
+    queue.push(
+      resolveQueueIncrementalFields(
+        { abs, relPath, requireCoverage, coverageAvailable },
+        incrementalCtx,
+      ),
+    );
   }
   const scannedFiles = queue.length;
 
-  const perFile =
-    queue.length < SERIAL_THRESHOLD
-      ? queue.map((item) => ({ item, result: scoreFileSerial(item, coverage) }))
-      : await scoreFilesViaPool(queue, coverage);
+  const perFile = shouldRunSerial(queue.length, incremental, SERIAL_THRESHOLD)
+    ? queue.map((item) => ({ item, result: scoreFileSerial(item, coverage) }))
+    : await scoreFilesViaPool(queue, coverage);
 
   const rows = [];
   let skippedFilesNoCoverage = 0;
@@ -516,6 +609,7 @@ export async function scanAndScore({
         coverage: mr.coverage,
         crap: mr.crap,
         coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
+        ...resolvedFromBaselineFlag(mr),
       });
     }
   }
@@ -545,11 +639,20 @@ export async function scanAndScore({
  * CRAP rows and the MI score are derived from the same escomplex report.
  */
 function scoreFileSerial(
-  { abs, relPath, requireCoverage, coverageAvailable = true },
+  {
+    abs,
+    relPath,
+    requireCoverage,
+    coverageAvailable = true,
+    touched = true,
+    baselineByKey = null,
+  },
   coverage,
 ) {
   const entry = findCoverageEntry(coverage, relPath);
-  if (requireCoverage && entry === null) {
+  if (
+    shouldSkipFileForNoCoverage(requireCoverage, entry, touched, baselineByKey)
+  ) {
     return {
       skippedFileNoCoverage: true,
       rows: [],
@@ -575,9 +678,11 @@ function scoreFileSerial(
     prepared.mapLine,
   );
   if (parseError) return dropped;
-  const finalized = finalizeMethodRows(crapRows, {
+  const finalized = finalizeMethodRowsWithBaseline(crapRows, {
     requireCoverage,
     coverageAvailable,
+    touched,
+    baselineByKey,
   });
   return {
     skippedFileNoCoverage: false,

package/docs/CHANGELOG.md

@@ -15,6 +15,20 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.30.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.29.0...mandrel-v2.30.0) (2026-08-04)
+
+
+### Fixed
+
+* **baselines:** carry provenanceStamped through the legacy CRAP projection ([#4986](https://github.com/dsj1984/mandrel/issues/4986)) ([#4987](https://github.com/dsj1984/mandrel/issues/4987)) ([921b521](https://github.com/dsj1984/mandrel/commit/921b521f2094c961fec84acca1f90e068cb77798))
+
+## [2.29.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.28.0...mandrel-v2.29.0) (2026-08-03)
+
+
+### Added
+
+* incremental coverage-capture: scope the close-time coverage run to the Story diff and join unchanged files from the committed CRAP baseline ([#4981](https://github.com/dsj1984/mandrel/issues/4981)) ([#4982](https://github.com/dsj1984/mandrel/issues/4982)) ([3d73875](https://github.com/dsj1984/mandrel/commit/3d73875deb170edf69f6f480d5d1abfffebcb47d))
+
 ## [2.28.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.27.0...mandrel-v2.28.0) (2026-08-03)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.28.0",
+  "version": "2.30.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",