mandrel 1.57.0

package/.agents/scripts/lib/baselines/kinds/_shared-metric.js

@@ -0,0 +1,220 @@
+/**
+ * kinds/_shared-metric.js — shared metric helpers for per-kind baseline
+ * modules (Story #3646).
+ *
+ * Both `crap.js` and `maintainability.js` duplicate the same
+ * percentile/rollup/compare/epsilon algorithm verbatim. This module
+ * extracts the parametrised core so each kind imports the factories
+ * and passes only what differs (aggregate fields, identity key function,
+ * better-is-higher polarity, metric field name).
+ *
+ * Exports (all pure, no I/O):
+ *   - percentile(sortedValues, p)                     — verbatim shared
+ *   - makeRollup({ aggregate })                       — rollup factory
+ *   - makeAggregate({ fields })                       — aggregate factory
+ *   - makeCompare({ identity, betterIsHigher })       — compare factory
+ *   - makeEpsilon({ identity, metricField })          — epsilon factory
+ */
+
+import { componentMatches } from '../component-matcher.js';
+
+// ---------------------------------------------------------------------------
+// percentile
+// ---------------------------------------------------------------------------
+
+/**
+ * Nearest-rank percentile over a **pre-sorted** ascending numeric array.
+ * Keeps rollup values integer-friendly without pulling in a stats dep.
+ *
+ * @param {number[]} sortedValues - ascending-sorted array of numbers
+ * @param {number} p - percentile in [0, 100]
+ * @returns {number}
+ */
+export function percentile(sortedValues, p) {
+  if (sortedValues.length === 0) return 0;
+  const idx = Math.min(
+    sortedValues.length - 1,
+    Math.max(0, Math.ceil((p / 100) * sortedValues.length) - 1),
+  );
+  return sortedValues[idx];
+}
+
+// ---------------------------------------------------------------------------
+// makeAggregate
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an aggregate-stats function for a set of metric fields.
+ *
+ * @param {{
+ *   fields: Array<{
+ *     name: string,
+ *     rowKey: string,
+ *     percentiles?: number[],
+ *     extras?: (sorted: number[]) => Record<string, number>
+ *   }>
+ * }} opts
+ * @returns {(rows: object[]) => Record<string, number>}
+ *
+ * Each `fields` entry describes one metric:
+ *   - `name`        — key in the returned stats object (e.g. `'p50'`)
+ *   - `rowKey`      — property name on each row (e.g. `'crap'`, `'mi'`)
+ *   - `percentiles` — list of percentile values to compute (e.g. `[50, 95]`)
+ *   - `extras`      — optional function over the sorted values that returns
+ *                     extra keys (e.g. `{ max, methodsAbove20 }`)
+ *
+ * The return value when `rows` is empty is built from the field list:
+ * every percentile resolves to 0 and every extras key resolves to 0.
+ */
+export function makeAggregate({ fields }) {
+  return function aggregate(rows) {
+    if (!rows || rows.length === 0) {
+      const zero = {};
+      for (const f of fields) {
+        for (const p of f.percentiles ?? []) {
+          const key = p === 50 ? 'p50' : p === 95 ? 'p95' : `p${p}`;
+          zero[key] = 0;
+        }
+        if (f.extras) {
+          const sample = f.extras([]);
+          for (const k of Object.keys(sample)) zero[k] = 0;
+        }
+        if (f.name && !(f.name in zero)) zero[f.name] = 0;
+      }
+      return zero;
+    }
+
+    const out = {};
+    for (const f of fields) {
+      const sorted = [...rows].map((r) => r[f.rowKey]).sort((a, b) => a - b);
+      for (const p of f.percentiles ?? []) {
+        const key = p === 50 ? 'p50' : p === 95 ? 'p95' : `p${p}`;
+        out[key] = percentile(sorted, p);
+      }
+      if (f.extras) {
+        Object.assign(out, f.extras(sorted));
+      }
+    }
+    return out;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// makeRollup
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a rollup function that groups rows by component.
+ *
+ * @param {{ aggregate: (rows: object[]) => Record<string, number> }} opts
+ * @returns {(rows: object[], components?: object[]) => Record<string, object>}
+ */
+export function makeRollup({ aggregate }) {
+  return 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;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// makeCompare
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a compare(head, base) function for a per-kind baseline.
+ *
+ * @param {{
+ *   identity: (row: object) => string,
+ *   betterIsHigher: boolean,
+ *   metricField: string,
+ *   removedIsImprovement?: (row: object) => boolean
+ * }} opts
+ *   - `identity`           — row → composite key string
+ *   - `betterIsHigher`     — when true, delta > 0 is an improvement (MI);
+ *                            when false, delta > 0 is a regression (CRAP)
+ *   - `metricField`        — name of the numeric metric property on each row
+ *   - `removedIsImprovement` — optional predicate deciding whether a removed
+ *                              base row counts as an improvement; defaults to
+ *                              `() => false` (no removal is auto-improvement)
+ * @returns {(head: object, base: object) => {
+ *   regressions: object[], improvements: object[],
+ *   unchanged: object[], additions: object[]
+ * }}
+ */
+export function makeCompare({
+  identity,
+  betterIsHigher,
+  metricField,
+  removedIsImprovement = () => false,
+}) {
+  return 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(identity(r), r);
+    const seen = new Set();
+    const regressions = [];
+    const improvements = [];
+    const unchanged = [];
+    const additions = [];
+    for (const h of headRows) {
+      const key = identity(h);
+      seen.add(key);
+      const b = baseByKey.get(key);
+      if (!b) {
+        additions.push({ key, head: h, base: null });
+        continue;
+      }
+      const delta = (h[metricField] ?? 0) - (b[metricField] ?? 0);
+      const regressed = betterIsHigher ? delta < 0 : delta > 0;
+      const improved = betterIsHigher ? delta > 0 : delta < 0;
+      if (regressed) regressions.push({ key, head: h, base: b });
+      else if (improved) improvements.push({ key, head: h, base: b });
+      else unchanged.push({ key, head: h, base: b });
+    }
+    for (const b of baseRows) {
+      const key = identity(b);
+      if (seen.has(key)) continue;
+      if (removedIsImprovement(b)) {
+        improvements.push({ key, head: null, base: b });
+      } else {
+        unchanged.push({ key, head: null, base: b });
+      }
+    }
+    return { regressions, improvements, unchanged, additions };
+  };
+}
+
+// ---------------------------------------------------------------------------
+// makeEpsilon
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an applyEpsilon(prior, regenerated, epsilon) function.
+ *
+ * @param {{
+ *   identity: (row: object) => string,
+ *   metricField: string
+ * }} opts
+ * @returns {(prior: object[], regenerated: object[], epsilon: number) => object[]}
+ */
+export function makeEpsilon({ identity, metricField }) {
+  return 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(identity(r), r);
+    return regenRows.map((row) => {
+      const p = priorByKey.get(identity(row));
+      if (!p) return row;
+      return Math.abs((row[metricField] ?? 0) - (p[metricField] ?? 0)) <= eps
+        ? p
+        : row;
+    });
+  };
+}

package/.agents/scripts/lib/baselines/kinds/bundle-size.js

@@ -0,0 +1,157 @@
+/**
+ * kinds/bundle-size.js — per-kind module for the bundle-size baseline
+ * (Story #1891). Row shape: `{ bundle, rawKb, gzippedKb }`. Bundle names
+ * are opaque identifiers (`main`, `vendor`, etc.) rather than file paths,
+ * so they bypass the canonicaliser.
+ */
+
+import { mergeRowsByScope } from '../scope.js';
+
+export const name = 'bundle-size';
+export const keyField = 'bundle';
+const KERNEL_VERSION = '1.0.0';
+
+export function kernelVersion() {
+  return KERNEL_VERSION;
+}
+
+export function projectRow(row) {
+  if (typeof row.bundle !== 'string' || row.bundle.length === 0) {
+    throw new Error(
+      `kinds/bundle-size.projectRow: bundle name must be a non-empty string (got ${JSON.stringify(row.bundle)})`,
+    );
+  }
+  return {
+    bundle: row.bundle,
+    rawKb: Number(row.rawKb),
+    gzippedKb: Number(row.gzippedKb),
+  };
+}
+
+export function sortRows(rows) {
+  return [...rows].sort((a, b) => a.bundle.localeCompare(b.bundle));
+}
+
+function aggregate(rows) {
+  if (!rows || rows.length === 0) return { totalKb: 0, gzippedKb: 0 };
+  let totalKb = 0;
+  let gzippedKb = 0;
+  for (const r of rows) {
+    totalKb += r.rawKb ?? 0;
+    gzippedKb += r.gzippedKb ?? 0;
+  }
+  return {
+    totalKb: Number(totalKb.toFixed(2)),
+    gzippedKb: Number(gzippedKb.toFixed(2)),
+  };
+}
+
+/**
+ * Pure compare(head, base) for the bundle-size kind. Diffs rows by
+ * `bundle`. A row regresses when rawKb or gzippedKb increases; improves
+ * when either decreases without the other increasing; otherwise
+ * unchanged. New bundles count as regressions when they carry any size;
+ * removed bundles count as improvements when they had any size.
+ *
+ * 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.bundle, r);
+  const seen = new Set();
+  const regressions = [];
+  const improvements = [];
+  const unchanged = [];
+  for (const h of headRows) {
+    seen.add(h.bundle);
+    const b = baseByKey.get(h.bundle);
+    if (!b) {
+      const total = (h.rawKb ?? 0) + (h.gzippedKb ?? 0);
+      if (total > 0) regressions.push({ key: h.bundle, head: h, base: null });
+      else unchanged.push({ key: h.bundle, head: h, base: null });
+      continue;
+    }
+    const rawDelta = (h.rawKb ?? 0) - (b.rawKb ?? 0);
+    const gzDelta = (h.gzippedKb ?? 0) - (b.gzippedKb ?? 0);
+    if (rawDelta > 0 || gzDelta > 0) {
+      regressions.push({ key: h.bundle, head: h, base: b });
+    } else if (rawDelta < 0 || gzDelta < 0) {
+      improvements.push({ key: h.bundle, head: h, base: b });
+    } else {
+      unchanged.push({ key: h.bundle, head: h, base: b });
+    }
+  }
+  for (const b of baseRows) {
+    if (seen.has(b.bundle)) continue;
+    const total = (b.rawKb ?? 0) + (b.gzippedKb ?? 0);
+    if (total > 0) improvements.push({ key: b.bundle, head: null, base: b });
+    else unchanged.push({ key: b.bundle, head: null, base: b });
+  }
+  return { regressions, improvements, unchanged };
+}
+
+export function rollup(rows, components = []) {
+  const out = { '*': aggregate(rows) };
+  for (const c of components ?? []) {
+    const matched = (rows ?? []).filter(
+      (r) => Array.isArray(c.bundles) && c.bundles.includes(r.bundle),
+    );
+    out[c.name] = aggregate(matched);
+  }
+  return out;
+}
+
+/**
+ * Pure stabilizer for s-stability-epsilon (Story #1964). Bundle-size rows
+ * match by `bundle`. The metric is the maximum absolute KB delta across
+ * `rawKb` and `gzippedKb`. Sub-epsilon deltas resolve to the prior bytes;
+ * missing-prior rows fall through.
+ *
+ * @param {Array<{bundle: string, rawKb: number, gzippedKb: number}>} prior
+ * @param {Array<{bundle: string, rawKb: number, gzippedKb: number}>} regenerated
+ * @param {number} epsilon non-negative absolute tolerance in KB
+ * @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.bundle, r);
+  return regenRows.map((row) => {
+    const p = priorByKey.get(row.bundle);
+    if (!p) return row;
+    const rawDelta = Math.abs((row.rawKb ?? 0) - (p.rawKb ?? 0));
+    const gzDelta = Math.abs((row.gzippedKb ?? 0) - (p.gzippedKb ?? 0));
+    return Math.max(rawDelta, gzDelta) <= eps ? p : row;
+  });
+}
+
+/**
+ * Pure scope-aware merge for s-diff-scoped-writes (Story #1974). Bundle
+ * rows match by `bundle`. In diff mode, rows whose `bundle` name 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: bundle names are not file paths. The scope filter only narrows
+ * naturally when callers seed `scope.files` with bundle names. Auto-
+ * refresh callers using a Story file diff will see no in-scope rows and
+ * therefore preserve every prior row — the safe default for a baseline
+ * whose identity is not file-derived.
+ *
+ * @param {Array<{bundle: string, rawKb: number, gzippedKb: number}>} prior
+ * @param {Array<{bundle: string, rawKb: number, gzippedKb: 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.bundle,
+  });
+}

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

@@ -0,0 +1,194 @@
+/**
+ * kinds/coverage.js — per-kind module for the coverage baseline (Story #1891).
+ *
+ * Row shape: `{ path, lines, branches, functions }` (percentages 0–100).
+ * Rollup math: per-axis denominator-weighted average is overkill for the
+ * foundation — we ship the arithmetic mean across rows for the whole-repo
+ * `*` 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.
+ */
+
+import { componentMatches } from '../component-matcher.js';
+import { canonicalise } from '../path-canon.js';
+import { mergeRowsByScope } from '../scope.js';
+
+export const name = 'coverage';
+export const keyField = 'path';
+const KERNEL_VERSION = '1.0.0';
+
+export function kernelVersion() {
+  return KERNEL_VERSION;
+}
+
+export function projectRow(row) {
+  return {
+    path: canonicalise(row.path),
+    lines: roundPct(row.lines),
+    branches: roundPct(row.branches),
+    functions: roundPct(row.functions),
+  };
+}
+
+function roundPct(v) {
+  if (typeof v !== 'number' || !Number.isFinite(v)) return 0;
+  return Number(v.toFixed(2));
+}
+
+export function sortRows(rows) {
+  return [...rows].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+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)),
+  };
+}
+
+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,
+  });
+}