mandrel 1.58.0 → 1.60.0

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,
+  };
+}

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

@@ -3,19 +3,22 @@
  * (Story #1891). Row shape: `{ route, performance, accessibility,
  * bestPractices, seo }`. The key field is `route` (a path-like string that
  * still passes the path-canon checks for absolute / `..` rejection).
+ *
+ * Higher score = better. New routes inherit a base of 100 for each axis
+ * (so lower scores register as regressions — a new route must meet the
+ * bar); dropped routes inherit a head of 100 (so a higher base registers
+ * as an improvement). Unlike the file-derived kinds, compare emits no
+ * `additions` bucket. 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 = 'lighthouse';
 export const keyField = 'route';
-const KERNEL_VERSION = '1.0.0';
 
-export function kernelVersion() {
-  return KERNEL_VERSION;
-}
+const LH_AXES = ['performance', 'accessibility', 'bestPractices', 'seo'];
 
 function canonRoute(route) {
   // Routes look like `/`, `/dashboard`, or `pricing` — strip the leading
@@ -36,75 +39,24 @@ export function projectRow(row) {
   };
 }
 
-export function sortRows(rows) {
-  return [...rows].sort((a, b) => a.route.localeCompare(b.route));
+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 { performance: 0, accessibility: 0, bestPractices: 0, seo: 0 };
   }
-  const sum = { performance: 0, accessibility: 0, bestPractices: 0, seo: 0 };
-  for (const r of rows) {
-    sum.performance += r.performance ?? 0;
-    sum.accessibility += r.accessibility ?? 0;
-    sum.bestPractices += r.bestPractices ?? 0;
-    sum.seo += r.seo ?? 0;
-  }
   return {
-    performance: Number((sum.performance / rows.length).toFixed(2)),
-    accessibility: Number((sum.accessibility / rows.length).toFixed(2)),
-    bestPractices: Number((sum.bestPractices / rows.length).toFixed(2)),
-    seo: Number((sum.seo / rows.length).toFixed(2)),
+    performance: meanOf(rows, 'performance'),
+    accessibility: meanOf(rows, 'accessibility'),
+    bestPractices: meanOf(rows, 'bestPractices'),
+    seo: meanOf(rows, 'seo'),
   };
 }
 
-export function rollup(rows, components = []) {
-  const out = { '*': aggregate(rows) };
-  for (const c of components ?? []) {
-    const matched = (rows ?? []).filter((r) => componentMatches(c, r.route));
-    out[c.name] = aggregate(matched);
-  }
-  return out;
-}
-
-/**
- * Pure compare(head, base) for the lighthouse kind. Diffs rows by `route`.
- *
- * Higher score = better. A row regresses when any of performance,
- * accessibility, bestPractices, or seo decreases vs the base. An
- * improvement requires at least one score to increase and none to
- * decrease. Otherwise the row is unchanged. New routes inherit a base of
- * 100 for each axis (so lower scores register as regressions); dropped
- * routes inherit a head of 100 (so a higher base registers as an
- * improvement).
- *
- * No I/O. No process exit. No friction emission.
- */
-const LH_AXES = ['performance', 'accessibility', 'bestPractices', 'seo'];
-
-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.route, r);
-  const seen = new Set();
-  const regressions = [];
-  const improvements = [];
-  const unchanged = [];
-  for (const h of headRows) {
-    seen.add(h.route);
-    const b = baseByKey.get(h.route) ?? perfectLighthouseRow(h.route);
-    classify(regressions, improvements, unchanged, h.route, h, b);
-  }
-  for (const b of baseRows) {
-    if (seen.has(b.route)) continue;
-    const h = perfectLighthouseRow(b.route);
-    classify(regressions, improvements, unchanged, b.route, h, b);
-  }
-  return { regressions, improvements, unchanged };
-}
-
 function perfectLighthouseRow(route) {
   return {
     route,
@@ -115,71 +67,20 @@ function perfectLighthouseRow(route) {
   };
 }
 
-function classify(regressions, improvements, unchanged, key, head, base) {
-  let down = false;
-  let up = false;
-  for (const axis of LH_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). Lighthouse rows
- * match by `route`. The metric is the maximum absolute delta across the
- * four scoring axes. Sub-epsilon deltas resolve to the prior bytes;
- * missing-prior rows fall through.
- *
- * @param {Array<{route: string, performance: number, accessibility: number, bestPractices: number, seo: number}>} prior
- * @param {Array<{route: string, performance: number, accessibility: number, bestPractices: number, seo: number}>} regenerated
- * @param {number} epsilon non-negative absolute tolerance per axis
- * @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.route, r);
-  return regenRows.map((row) => {
-    const p = priorByKey.get(row.route);
-    if (!p) return row;
-    let maxAxisDelta = 0;
-    for (const axis of LH_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). Lighthouse
- * rows match by `route`. In diff mode, rows whose `route` is OUTSIDE
- * `scope.files` are preserved from `prior` verbatim; in-scope rows come
- * from `regenerated`. In full mode (or no scope), regenerated wins
- * everywhere.
- *
- * Note: lighthouse routes are not file paths, so the scope filter only
- * narrows naturally when callers seed `scope.files` with route strings.
- * Auto-refresh callers using a Story file diff will see no in-scope rows
- * and therefore preserve every prior row — which is the safe default for
- * a baseline that is not file-derived.
- *
- * @param {Array<{route: string, performance: number, accessibility: number, bestPractices: number, seo: number}>} prior
- * @param {Array<{route: string, performance: number, accessibility: number, bestPractices: number, seo: 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.route,
-  });
-}
+export const {
+  kernelVersion,
+  sortRows,
+  rollup,
+  compare,
+  applyEpsilon,
+  mergeRows,
+} = makeBaselineKind({
+  keyField,
+  kernelVersion: '1.0.0',
+  axes: LH_AXES,
+  betterWhen: 'higher',
+  aggregate,
+  missingBasePolicy: 'perfect',
+  removedRowPolicy: { kind: 'perfect-head' },
+  perfectRow: perfectLighthouseRow,
+});