mandrel 1.58.0 → 1.59.0

package/.agents/scripts/lib/baselines/kinds/coverage.js

@@ -7,19 +7,22 @@
  * `*` key and each component. Per-row denominators land later when the
  * components resolver and per-component weighting (Story #1902, #1919)
  * arrive; the rollup signature is stable so callers don't churn.
+ *
+ * Higher percentages are better. New paths land in the `additions` bucket
+ * (Story #2012 — partial coverage on a new file must never flip to a
+ * regression); removed paths inherit a perfect head row so any lower base
+ * registers as an improvement. Scaffold (sortRows / rollup / compare /
+ * applyEpsilon / mergeRows) is generated by `makeBaselineKind`
+ * (Story #3983).
  */
 
-import { componentMatches } from '../component-matcher.js';
 import { canonicalise } from '../path-canon.js';
-import { mergeRowsByScope } from '../scope.js';
+import { makeBaselineKind } from './kind-factory.js';
 
 export const name = 'coverage';
 export const keyField = 'path';
-const KERNEL_VERSION = '1.0.0';
 
-export function kernelVersion() {
-  return KERNEL_VERSION;
-}
+const COV_AXES = ['lines', 'branches', 'functions'];
 
 export function projectRow(row) {
   return {
@@ -35,160 +38,41 @@ function roundPct(v) {
   return Number(v.toFixed(2));
 }
 
-export function sortRows(rows) {
-  return [...rows].sort((a, b) => a.path.localeCompare(b.path));
+function meanOf(rows, axis) {
+  let sum = 0;
+  for (const r of rows) sum += r[axis] ?? 0;
+  return Number((sum / rows.length).toFixed(2));
 }
 
 function aggregate(rows) {
   if (!rows || rows.length === 0) {
     return { lines: 0, branches: 0, functions: 0 };
   }
-  let l = 0;
-  let b = 0;
-  let f = 0;
-  for (const row of rows) {
-    l += row.lines ?? 0;
-    b += row.branches ?? 0;
-    f += row.functions ?? 0;
-  }
   return {
-    lines: Number((l / rows.length).toFixed(2)),
-    branches: Number((b / rows.length).toFixed(2)),
-    functions: Number((f / rows.length).toFixed(2)),
+    lines: meanOf(rows, 'lines'),
+    branches: meanOf(rows, 'branches'),
+    functions: meanOf(rows, 'functions'),
   };
 }
 
-export function rollup(rows, components = []) {
-  const out = { '*': aggregate(rows) };
-  for (const c of components ?? []) {
-    const matched = (rows ?? []).filter((r) => componentMatches(c, r.path));
-    out[c.name] = aggregate(matched);
-  }
-  return out;
-}
-
-/**
- * Pure compare(head, base) for the coverage kind. Diffs rows by `path`.
- * Higher percentages are better — a row regresses if any axis (lines,
- * branches, functions) drops vs base; improves if any axis rises with no
- * axis dropping; unchanged otherwise. New paths (head has a row that
- * base lacks) land in the `additions` bucket; absolute-floor enforcement
- * is the unified `check-baselines` gate's job and runs independently.
- * Removed paths inherit a head of 100% so any lower base registers as
- * an improvement.
- *
- * Story #2012 — sibling fix to maintainability.compare. The prior
- * behaviour treated new paths as base=100% on every axis, so any partial
- * coverage on a new file flipped to a regression.
- *
- * No I/O. No process exit. No friction emission.
- */
-const COV_AXES = ['lines', 'branches', 'functions'];
-
-export function compare(head, base) {
-  const headRows = Array.isArray(head?.rows) ? head.rows : [];
-  const baseRows = Array.isArray(base?.rows) ? base.rows : [];
-  const baseByKey = new Map();
-  for (const r of baseRows) baseByKey.set(r.path, r);
-  const seen = new Set();
-  const regressions = [];
-  const improvements = [];
-  const unchanged = [];
-  const additions = [];
-  for (const h of headRows) {
-    seen.add(h.path);
-    const b = baseByKey.get(h.path);
-    if (!b) {
-      additions.push({ key: h.path, head: h, base: null });
-      continue;
-    }
-    classifyCoverage(regressions, improvements, unchanged, h.path, h, b);
-  }
-  for (const b of baseRows) {
-    if (seen.has(b.path)) continue;
-    const h = perfectCoverageRow(b.path);
-    classifyCoverage(regressions, improvements, unchanged, b.path, h, b);
-  }
-  return { regressions, improvements, unchanged, additions };
-}
-
 function perfectCoverageRow(path) {
   return { path, lines: 100, branches: 100, functions: 100 };
 }
 
-function classifyCoverage(
-  regressions,
-  improvements,
-  unchanged,
-  key,
-  head,
-  base,
-) {
-  let down = false;
-  let up = false;
-  for (const axis of COV_AXES) {
-    const delta = (head[axis] ?? 0) - (base[axis] ?? 0);
-    if (delta < 0) down = true;
-    else if (delta > 0) up = true;
-  }
-  if (down) regressions.push({ key, head, base });
-  else if (up) improvements.push({ key, head, base });
-  else unchanged.push({ key, head, base });
-}
-
-/**
- * Pure stabilizer for s-stability-epsilon (Story #1964). Folds sub-epsilon
- * row deltas back to the prior bytes so env variance (e.g. ±0.05% jitter
- * on a coverage axis) does not rewrite the on-disk baseline.
- *
- * For coverage, the comparison metric is the maximum |delta| across the
- * three axes (lines, branches, functions). When the prior row exists and
- * every axis delta is within `epsilon`, the prior row is returned
- * verbatim; otherwise the regenerated row wins. Missing-prior rows always
- * fall through to the regenerated row.
- *
- * No I/O. No mutation of inputs.
- *
- * @param {Array<{path: string, lines: number, branches: number, functions: number}>} prior
- * @param {Array<{path: string, lines: number, branches: number, functions: number}>} regenerated
- * @param {number} epsilon non-negative absolute tolerance (percentage points)
- * @returns {Array<object>}
- */
-export function applyEpsilon(prior, regenerated, epsilon) {
-  const priorRows = Array.isArray(prior) ? prior : [];
-  const regenRows = Array.isArray(regenerated) ? regenerated : [];
-  const eps = Number.isFinite(epsilon) && epsilon >= 0 ? epsilon : 0;
-  const priorByKey = new Map();
-  for (const r of priorRows) priorByKey.set(r.path, r);
-  return regenRows.map((row) => {
-    const p = priorByKey.get(row.path);
-    if (!p) return row;
-    let maxAxisDelta = 0;
-    for (const axis of COV_AXES) {
-      const d = Math.abs((row[axis] ?? 0) - (p[axis] ?? 0));
-      if (d > maxAxisDelta) maxAxisDelta = d;
-    }
-    return maxAxisDelta <= eps ? p : row;
-  });
-}
-
-/**
- * Pure scope-aware merge for s-diff-scoped-writes (Story #1974). Coverage
- * rows match by `path`. In diff mode, rows whose `path` is OUTSIDE
- * `scope.files` are preserved from `prior` verbatim; in-scope rows come
- * from `regenerated`. In full mode (or no scope), regenerated wins
- * everywhere. Pure; downstream `sortRows` re-sorts before write.
- *
- * @param {Array<{path: string, lines: number, branches: number, functions: number}>} prior
- * @param {Array<{path: string, lines: number, branches: number, functions: number}>} regenerated
- * @param {{mode: 'full'|'diff', files: Set<string>}|null|undefined} scope
- * @returns {Array<object>}
- */
-export function mergeRows(prior, regenerated, scope) {
-  return mergeRowsByScope({
-    prior,
-    regenerated,
-    scope,
-    scopeKey: (row) => row.path,
-  });
-}
+export const {
+  kernelVersion,
+  sortRows,
+  rollup,
+  compare,
+  applyEpsilon,
+  mergeRows,
+} = makeBaselineKind({
+  keyField,
+  kernelVersion: '1.0.0',
+  axes: COV_AXES,
+  betterWhen: 'higher',
+  aggregate,
+  missingBasePolicy: 'addition',
+  removedRowPolicy: { kind: 'perfect-head' },
+  perfectRow: perfectCoverageRow,
+});

package/.agents/scripts/lib/baselines/kinds/duplication.js

@@ -11,26 +11,25 @@
  * per-file percentages (which would over-weight small files).
  *
  * Lower duplication is better, so the gate's floor direction is `lte`
- * (see `check-baselines/phases/floors.js#axisDirection`).
+ * (see `check-baselines/phases/floors.js#axisDirection`). New paths land
+ * in the `additions` bucket (Story #2012); removed paths count as
+ * improvements when they carried any duplication — the file is gone, so
+ * its prior debt is gone too.
  *
  * `kernelVersion()` returns a static in-repo semver — the duplication
  * scorer is the in-repo scan + rollup contract (the jscpd output is
  * normalised before it reaches this module), so there is no upstream
  * library version to track the way CRAP/MI track `typhonjs-escomplex`.
- * Bump `KERNEL_VERSION` whenever the row shape or rollup math changes.
+ * Bump the version passed to `makeBaselineKind` whenever the row shape or
+ * rollup math changes. Scaffold is generated by `makeBaselineKind`
+ * (Story #3983).
  */
 
-import { componentMatches } from '../component-matcher.js';
 import { canonicalise } from '../path-canon.js';
-import { mergeRowsByScope } from '../scope.js';
+import { makeBaselineKind } from './kind-factory.js';
 
 export const name = 'duplication';
 export const keyField = 'path';
-const KERNEL_VERSION = '1.0.0';
-
-export function kernelVersion() {
-  return KERNEL_VERSION;
-}
 
 export function projectRow(row) {
   const duplicatedLines = Number(row.duplicatedLines ?? 0);
@@ -47,10 +46,6 @@ export function projectRow(row) {
   };
 }
 
-export function sortRows(rows) {
-  return [...rows].sort((a, b) => a.path.localeCompare(b.path));
-}
-
 /**
  * Exact aggregate duplication ratio: total duplicated lines / total lines
  * across the row set, expressed as a percentage. Averaging per-file
@@ -92,106 +87,22 @@ function roundTo2(value) {
   return Number(value.toFixed(2));
 }
 
-export function rollup(rows, components = []) {
-  const out = { '*': aggregate(rows) };
-  for (const c of components ?? []) {
-    const matched = (rows ?? []).filter((r) => componentMatches(c, r.path));
-    out[c.name] = aggregate(matched);
-  }
-  return out;
-}
-
-/**
- * Pure compare(head, base) for the duplication kind. Diffs rows by `path`.
- *
- * Higher duplication = worse. A row regresses when its `percentage`
- * increases vs base; improves when it decreases; unchanged when equal.
- * New paths (head has a row that base lacks) land in the `additions`
- * bucket — absolute-floor enforcement is the unified `check-baselines`
- * gate's job and runs independently, so a Story that lands a new file
- * never fails through the regression arm (mirrors crap/maintainability,
- * Story #2012). Removed paths (base has a row that head dropped) count as
- * improvements when they carried any duplication; the file is gone, so its
- * prior debt is gone too.
- *
- * No I/O. No process exit. No friction emission.
- */
-export function compare(head, base) {
-  const headRows = Array.isArray(head?.rows) ? head.rows : [];
-  const baseRows = Array.isArray(base?.rows) ? base.rows : [];
-  const baseByKey = new Map();
-  for (const r of baseRows) baseByKey.set(r.path, r);
-  const seen = new Set();
-  const regressions = [];
-  const improvements = [];
-  const unchanged = [];
-  const additions = [];
-  for (const h of headRows) {
-    seen.add(h.path);
-    const b = baseByKey.get(h.path);
-    if (!b) {
-      additions.push({ key: h.path, head: h, base: null });
-      continue;
-    }
-    const delta = (h.percentage ?? 0) - (b.percentage ?? 0);
-    if (delta > 0) regressions.push({ key: h.path, head: h, base: b });
-    else if (delta < 0) improvements.push({ key: h.path, head: h, base: b });
-    else unchanged.push({ key: h.path, head: h, base: b });
-  }
-  for (const b of baseRows) {
-    if (seen.has(b.path)) continue;
-    if ((b.percentage ?? 0) > 0) {
-      improvements.push({ key: b.path, head: null, base: b });
-    } else {
-      unchanged.push({ key: b.path, head: null, base: b });
-    }
-  }
-  return { regressions, improvements, unchanged, additions };
-}
-
-/**
- * Pure stabilizer for s-stability-epsilon (Story #1964). Duplication rows
- * match by `path`. The metric is the absolute `percentage` delta. Sub-
- * epsilon deltas resolve to the prior bytes so env variance never rewrites
- * the on-disk baseline; missing-prior rows fall through.
- *
- * @param {Array<{path: string, percentage: number}>} prior
- * @param {Array<{path: string, percentage: number}>} regenerated
- * @param {number} epsilon non-negative absolute tolerance on percentage
- * @returns {Array<object>}
- */
-export function applyEpsilon(prior, regenerated, epsilon) {
-  const priorRows = Array.isArray(prior) ? prior : [];
-  const regenRows = Array.isArray(regenerated) ? regenerated : [];
-  const eps = Number.isFinite(epsilon) && epsilon >= 0 ? epsilon : 0;
-  const priorByKey = new Map();
-  for (const r of priorRows) priorByKey.set(r.path, r);
-  return regenRows.map((row) => {
-    const p = priorByKey.get(row.path);
-    if (!p) return row;
-    return Math.abs((row.percentage ?? 0) - (p.percentage ?? 0)) <= eps
-      ? p
-      : row;
-  });
-}
-
-/**
- * Pure scope-aware merge for s-diff-scoped-writes (Story #1974).
- * Duplication rows match by `path`. In diff mode, rows whose `path` is
- * OUTSIDE `scope.files` are preserved from `prior` verbatim; in-scope rows
- * come from `regenerated`. In full mode (or no scope), regenerated wins
- * everywhere.
- *
- * @param {Array<{path: string, percentage: number}>} prior
- * @param {Array<{path: string, percentage: number}>} regenerated
- * @param {{mode: 'full'|'diff', files: Set<string>}|null|undefined} scope
- * @returns {Array<object>}
- */
-export function mergeRows(prior, regenerated, scope) {
-  return mergeRowsByScope({
-    prior,
-    regenerated,
-    scope,
-    scopeKey: (row) => row.path,
-  });
-}
+export const {
+  kernelVersion,
+  sortRows,
+  rollup,
+  compare,
+  applyEpsilon,
+  mergeRows,
+} = makeBaselineKind({
+  keyField,
+  kernelVersion: '1.0.0',
+  axes: ['percentage'],
+  betterWhen: 'lower',
+  aggregate,
+  missingBasePolicy: 'addition',
+  removedRowPolicy: {
+    kind: 'improvement-when',
+    when: (b) => (b.percentage ?? 0) > 0,
+  },
+});

package/.agents/scripts/lib/baselines/kinds/kind-factory.js

@@ -0,0 +1,192 @@
+/**
+ * kinds/kind-factory.js — shared scaffold factory for per-kind baseline
+ * modules (Story #3983).
+ *
+ * The five row-metric kinds (coverage, mutation, maintainability,
+ * lighthouse, duplication) used to hand-roll the same scaffold each:
+ * `kernelVersion`, `sortRows`, a component-aware `rollup`, a
+ * `compare(head, base)` that diffs rows by key into
+ * `{regressions, improvements, unchanged, additions}`, an
+ * `applyEpsilon` stabilizer (Story #1964), and a scope-aware
+ * `mergeRows` (Story #1974). Only the axis list, direction-of-better,
+ * aggregate math, and the missing/removed-row policies differ per kind.
+ *
+ * `makeBaselineKind` generates the scaffold once; each kind module stays
+ * a thin parameterization with a byte-identical exported surface. The
+ * Story #2012 class of fix ("new paths must land in `additions`, never
+ * the regression arm") lives here exactly once.
+ *
+ * All generated functions are pure: no I/O, no process exit, no
+ * friction emission.
+ */
+
+import { componentMatches } from '../component-matcher.js';
+import { mergeRowsByScope } from '../scope.js';
+
+/**
+ * Build the shared scaffold for a per-kind baseline module.
+ *
+ * @param {{
+ *   keyField: string,
+ *   kernelVersion: string | (() => string),
+ *   axes: string[],
+ *   betterWhen: 'higher' | 'lower',
+ *   aggregate: (rows: object[]) => Record<string, number>,
+ *   missingBasePolicy?: 'addition' | 'perfect',
+ *   removedRowPolicy?:
+ *     | { kind: 'perfect-head' }
+ *     | { kind: 'improvement-when', when: (row: object) => boolean },
+ *   perfectRow?: (key: string) => object,
+ * }} opts
+ *   - `keyField`          — row identity property (`'path'` or `'route'`)
+ *   - `kernelVersion`     — static semver, or a thunk for kinds that pin
+ *                           to another kind's kernel (MI → CRAP)
+ *   - `axes`              — metric property names compared per row
+ *   - `betterWhen`        — `'higher'` (coverage, MI, …) or `'lower'`
+ *                           (duplication): decides which delta sign is a
+ *                           regression
+ *   - `aggregate`         — per-kind rollup math over a row set
+ *   - `missingBasePolicy` — head row with no base row: `'addition'`
+ *                           (default; Story #2012 bucket) or `'perfect'`
+ *                           (classify against a perfect base — lighthouse,
+ *                           where a new route must meet the bar)
+ *   - `removedRowPolicy`  — base row with no head row: `'perfect-head'`
+ *                           classifies against a perfect head row;
+ *                           `'improvement-when'` pushes an improvement
+ *                           when `when(baseRow)` holds, else unchanged
+ *   - `perfectRow`        — builds the perfect row for the policies above
+ * @returns {{
+ *   kernelVersion: () => string,
+ *   sortRows: (rows: object[]) => object[],
+ *   rollup: (rows: object[], components?: object[]) => Record<string, object>,
+ *   compare: (head: object, base: object) => object,
+ *   applyEpsilon: (prior: object[], regenerated: object[], epsilon: number) => object[],
+ *   mergeRows: (prior: object[], regenerated: object[], scope: object) => object[],
+ * }}
+ */
+export function makeBaselineKind({
+  keyField,
+  kernelVersion,
+  axes,
+  betterWhen,
+  aggregate,
+  missingBasePolicy = 'addition',
+  removedRowPolicy = { kind: 'improvement-when', when: () => false },
+  perfectRow = null,
+}) {
+  const keyOf = (row) => row[keyField];
+  const kernelVersionFn =
+    typeof kernelVersion === 'function' ? kernelVersion : () => kernelVersion;
+
+  function sortRows(rows) {
+    return [...rows].sort((a, b) => keyOf(a).localeCompare(keyOf(b)));
+  }
+
+  function rollup(rows, components = []) {
+    const out = { '*': aggregate(rows) };
+    for (const c of components ?? []) {
+      const matched = (rows ?? []).filter((r) => componentMatches(c, keyOf(r)));
+      out[c.name] = aggregate(matched);
+    }
+    return out;
+  }
+
+  function classify(regressions, improvements, unchanged, key, head, base) {
+    let down = false;
+    let up = false;
+    for (const axis of axes) {
+      const delta = (head[axis] ?? 0) - (base[axis] ?? 0);
+      const worse = betterWhen === 'higher' ? delta < 0 : delta > 0;
+      const better = betterWhen === 'higher' ? delta > 0 : delta < 0;
+      if (worse) down = true;
+      else if (better) up = true;
+    }
+    if (down) regressions.push({ key, head, base });
+    else if (up) improvements.push({ key, head, base });
+    else unchanged.push({ key, head, base });
+  }
+
+  function compare(head, base) {
+    const headRows = Array.isArray(head?.rows) ? head.rows : [];
+    const baseRows = Array.isArray(base?.rows) ? base.rows : [];
+    const baseByKey = new Map();
+    for (const r of baseRows) baseByKey.set(keyOf(r), r);
+    const seen = new Set();
+    const regressions = [];
+    const improvements = [];
+    const unchanged = [];
+    const additions = [];
+    for (const h of headRows) {
+      const key = keyOf(h);
+      seen.add(key);
+      const b = baseByKey.get(key);
+      if (!b) {
+        if (missingBasePolicy === 'addition') {
+          additions.push({ key, head: h, base: null });
+        } else {
+          classify(
+            regressions,
+            improvements,
+            unchanged,
+            key,
+            h,
+            perfectRow(key),
+          );
+        }
+        continue;
+      }
+      classify(regressions, improvements, unchanged, key, h, b);
+    }
+    for (const b of baseRows) {
+      const key = keyOf(b);
+      if (seen.has(key)) continue;
+      if (removedRowPolicy.kind === 'perfect-head') {
+        classify(regressions, improvements, unchanged, key, perfectRow(key), b);
+      } else if (removedRowPolicy.when(b)) {
+        improvements.push({ key, head: null, base: b });
+      } else {
+        unchanged.push({ key, head: null, base: b });
+      }
+    }
+    if (missingBasePolicy === 'addition') {
+      return { regressions, improvements, unchanged, additions };
+    }
+    return { regressions, improvements, unchanged };
+  }
+
+  function applyEpsilon(prior, regenerated, epsilon) {
+    const priorRows = Array.isArray(prior) ? prior : [];
+    const regenRows = Array.isArray(regenerated) ? regenerated : [];
+    const eps = Number.isFinite(epsilon) && epsilon >= 0 ? epsilon : 0;
+    const priorByKey = new Map();
+    for (const r of priorRows) priorByKey.set(keyOf(r), r);
+    return regenRows.map((row) => {
+      const p = priorByKey.get(keyOf(row));
+      if (!p) return row;
+      let maxAxisDelta = 0;
+      for (const axis of axes) {
+        const d = Math.abs((row[axis] ?? 0) - (p[axis] ?? 0));
+        if (d > maxAxisDelta) maxAxisDelta = d;
+      }
+      return maxAxisDelta <= eps ? p : row;
+    });
+  }
+
+  function mergeRows(prior, regenerated, scope) {
+    return mergeRowsByScope({
+      prior,
+      regenerated,
+      scope,
+      scopeKey: keyOf,
+    });
+  }
+
+  return {
+    kernelVersion: kernelVersionFn,
+    sortRows,
+    rollup,
+    compare,
+    applyEpsilon,
+    mergeRows,
+  };
+}