mandrel 2.25.0 → 2.27.0

package/.agents/scripts/lib/audit-baselines/gate-surface.js

@@ -0,0 +1,63 @@
+/**
+ * gate-surface.js — walk both halves of the baseline surface (Story #4902).
+ *
+ * The closed `delivery.quality.gates` kinds and the out-of-band ratchet
+ * baselines are one surface, and an engine that walks only the first silently
+ * drops the second. This module owns that walk and the file universe an
+ * `ignoreGlobs` entry is checked against; [`surface-entry.js`](surface-entry.js)
+ * turns each kind into its health report.
+ *
+ * @module lib/audit-baselines/gate-surface
+ */
+
+import path from 'node:path';
+import { ALL_KINDS, baselinePathFor, GATE_KINDS } from './kinds.js';
+import { listFilesUnder, readJsonFile } from './read.js';
+import { surfaceEntryFor } from './surface-entry.js';
+
+/**
+ * Every `targetDirs` entry declared by any gate, deduplicated. This is the
+ * file universe an `ignoreGlobs` entry is checked against — a glob that
+ * matches nothing inside the dirs its own gate scans is dead weight.
+ *
+ * @param {object | null | undefined} quality
+ * @returns {string[]}
+ */
+function declaredTargetDirs(quality) {
+  const dirs = new Set();
+  for (const kind of GATE_KINDS) {
+    for (const dir of quality?.gates?.[kind]?.targetDirs ?? []) {
+      if (typeof dir === 'string' && dir.length > 0) dirs.add(dir);
+    }
+  }
+  return [...dirs].sort();
+}
+
+/**
+ * Walk both halves of the gate surface — the closed `delivery.quality.gates`
+ * kinds and the out-of-band ratchet baselines — and report each instrument's
+ * health.
+ *
+ * @param {{ cwd: string, quality: object, now?: Date, run?: Function }} args
+ *   `run` overrides the git spawn; `staleness.js` owns the real default.
+ * @returns {{ entries: object[], baselines: Map<string, object|null> }}
+ *   `baselines` carries each parsed envelope forward so the hotspot, trend,
+ *   and headroom sections never re-read a 650KB file off disk.
+ */
+export function buildGateSurface({ cwd, quality, now = new Date(), run }) {
+  const files = declaredTargetDirs(quality).flatMap((dir) =>
+    listFilesUnder(cwd, dir),
+  );
+  const io = { cwd, run };
+  const entries = [];
+  const baselines = new Map();
+  for (const kind of ALL_KINDS) {
+    const relPath = baselinePathFor(kind, quality);
+    const read = readJsonFile(path.resolve(cwd, relPath));
+    entries.push(
+      surfaceEntryFor({ kind, quality, read, relPath, files, now, io }),
+    );
+    baselines.set(kind, read.parsed);
+  }
+  return { entries, baselines };
+}

package/.agents/scripts/lib/audit-baselines/headroom.js

@@ -0,0 +1,72 @@
+/**
+ * headroom.js — how much slack sits between each configured floor and the
+ * number actually measured (Story #4902).
+ *
+ * A floor set far from reality is a gate that cannot fail. Headroom is the
+ * distance the measurement could still drift before the gate notices, and it
+ * is the direct input to the only remediation this lens ever recommends:
+ * tighten the floor to what the repo already achieves.
+ *
+ * Both sides come from the repository, never from this module: the floor
+ * from `resolveQuality()` over `.agentrc.json` (so a consumer's own floors
+ * are the ones reported), and the measurement from the committed baseline's
+ * whole-repo rollup. Polarity comes from `axisDirection` in the gate's own
+ * floors phase, so "better" always means the same thing here as it does when
+ * `check-baselines.js` decides pass or fail.
+ *
+ * @module lib/audit-baselines/headroom
+ */
+
+import { axisDirection } from '../orchestration/check-baselines/phases/floors.js';
+import { rollupOf } from './kinds.js';
+
+/**
+ * Signed distance from the floor, positive when the measurement sits on the
+ * good side of it. Null when the baseline carries no value for the axis.
+ *
+ * @param {number | undefined} measured
+ * @param {number} floor
+ * @param {'gte' | 'lte'} direction
+ * @returns {number | null}
+ */
+function headroomFor(measured, floor, direction) {
+  if (typeof measured !== 'number') return null;
+  return direction === 'gte' ? measured - floor : floor - measured;
+}
+
+/**
+ * Build the `headroom[]` section across every configured gate kind.
+ *
+ * @param {{
+ *   kinds: string[],
+ *   quality: object,
+ *   baselines: Map<string, object | null>,
+ * }} args
+ * @returns {Array<object>}
+ */
+export function buildHeadroom({ kinds, quality, baselines }) {
+  const out = [];
+  for (const kind of kinds) {
+    const floors = quality?.gates?.[kind]?.floors?.['*'];
+    if (!floors || typeof floors !== 'object') continue;
+    const rollup = rollupOf(baselines.get(kind) ?? null);
+    for (const [axis, floor] of Object.entries(floors)) {
+      if (typeof floor !== 'number' || !Number.isFinite(floor)) continue;
+      const measured = rollup?.[axis];
+      const direction = axisDirection(kind, axis);
+      out.push({
+        kind,
+        axis,
+        floor,
+        measured: typeof measured === 'number' ? measured : null,
+        direction,
+        // Positive headroom = the measurement is on the good side of the
+        // floor by this much; negative = the floor is already breached.
+        headroom: headroomFor(measured, floor, direction),
+      });
+    }
+  }
+  return out.sort(
+    (a, b) => a.kind.localeCompare(b.kind) || a.axis.localeCompare(b.axis),
+  );
+}

package/.agents/scripts/lib/audit-baselines/hotspots.js

@@ -0,0 +1,69 @@
+/**
+ * hotspots.js — join per-gate outliers into ranked, per-file clusters
+ * (Story #4902).
+ *
+ * The signal a baseline review is looking for is *convergence*: the file that
+ * is simultaneously a CRAP outlier, a maintainability outlier, and a
+ * duplication outlier is a different kind of problem from three unrelated
+ * files each bad at one thing. Reading the baselines one at a time cannot see
+ * it, because each gate's own top-20 is a different list.
+ *
+ * So severity **adds across gate memberships** and the three cost
+ * multipliers apply to the sum. Two gate memberships of severity s therefore
+ * outrank one membership of severity s at equal churn, centrality, and
+ * friction — which is the ranking property this section exists to provide.
+ *
+ * @module lib/audit-baselines/hotspots
+ */
+
+/**
+ * Group per-gate outlier rows by cluster id and rank them.
+ *
+ * @param {{
+ *   outliers: Array<object>,
+ *   weightsFor: (id: string) => {
+ *     churnWeight: number, centralityWeight: number, frictionWeight: number,
+ *   },
+ *   limit?: number,
+ * }} args
+ * @returns {Array<object>} highest rank first
+ */
+export function buildHotspots({ outliers, weightsFor, limit = 50 }) {
+  const clusters = new Map();
+  for (const row of outliers) {
+    let cluster = clusters.get(row.id);
+    if (!cluster) {
+      cluster = { path: row.id, gates: [], severityWeight: 0 };
+      clusters.set(row.id, cluster);
+    }
+    cluster.gates.push({
+      kind: row.kind,
+      metric: row.metric,
+      value: row.value,
+      rowCount: row.rowCount,
+      severityWeight: row.severityWeight,
+    });
+    cluster.severityWeight += row.severityWeight;
+  }
+
+  const ranked = [];
+  for (const cluster of clusters.values()) {
+    const weights = weightsFor(cluster.path);
+    cluster.gates.sort((a, b) => a.kind.localeCompare(b.kind));
+    ranked.push({
+      path: cluster.path,
+      gates: cluster.gates,
+      gateKinds: cluster.gates.map((g) => g.kind),
+      gateCount: cluster.gates.length,
+      severityWeight: cluster.severityWeight,
+      ...weights,
+      rank:
+        cluster.severityWeight *
+        weights.churnWeight *
+        weights.centralityWeight *
+        weights.frictionWeight,
+    });
+  }
+  ranked.sort((a, b) => b.rank - a.rank || a.path.localeCompare(b.path));
+  return ranked.slice(0, Math.max(0, limit));
+}

package/.agents/scripts/lib/audit-baselines/kinds.js

@@ -0,0 +1,313 @@
+/**
+ * kinds.js — the two halves of the gate surface, and how to read a row out
+ * of each (Story #4902).
+ *
+ * Mandrel's baseline surface is not one list. `delivery.quality.gates` is a
+ * **closed** AJV schema of eight kinds, enforced by `check-baselines.js`.
+ * Alongside it sit out-of-band **ratchet** baselines — dead exports (two
+ * passes), import cycles, context budget — which no gate block declares and
+ * only the CI baselines job runs. An engine that walks one half and calls it
+ * "the baselines" silently drops the other; both halves are enumerated here.
+ *
+ * `GATE_KINDS` is derived from `GATES_SCHEMA` rather than re-typed, so a
+ * ninth gate kind landing in the schema reaches this engine automatically.
+ *
+ * @module lib/audit-baselines/kinds
+ */
+
+import { GATES_SCHEMA } from '../config/gates/index.js';
+
+/** The closed `delivery.quality.gates` kind set, in stable order. */
+export const GATE_KINDS = Object.freeze(
+  Object.keys(GATES_SCHEMA.properties).sort(),
+);
+
+/**
+ * Out-of-band ratchet baselines: committed under `baselines/` and enforced
+ * only by the CI baselines job, never by `check-baselines.js`.
+ */
+const RATCHET_KINDS = Object.freeze([
+  'arch-cycles',
+  'context-budget',
+  'cyclomatic',
+  'dead-exports',
+  'dead-exports-production',
+]);
+
+/** Every kind the engine walks, gates first then ratchets. */
+export const ALL_KINDS = Object.freeze([...GATE_KINDS, ...RATCHET_KINDS]);
+
+/**
+ * Resolve a kind's baseline path from config, falling back to the framework
+ * default layout. Never hardcodes a consumer's location: a repo that moved
+ * `baselines/crap.json` via `gates.crap.baselinePath` is followed.
+ *
+ * @param {string} kind
+ * @param {object | null | undefined} quality resolved `delivery.quality`
+ * @returns {string} repo-relative path
+ */
+export function baselinePathFor(kind, quality) {
+  const configured = quality?.gates?.[kind]?.baselinePath;
+  if (typeof configured === 'string' && configured.length > 0) {
+    return configured;
+  }
+  return `baselines/${kind}.json`;
+}
+
+/**
+ * Flatten `context-budget.json` into `{ id, value }` rows. Its three
+ * sections all measure the same axis (bytes of context a file costs) under
+ * different keys, so they fold into one row set rather than three.
+ *
+ * @param {object} baseline
+ * @returns {Array<{ id: string, value: number }>}
+ */
+function contextBudgetRows(baseline) {
+  const out = [];
+  for (const tier of Object.values(baseline?.tiers ?? {})) {
+    for (const f of tier?.files ?? []) out.push({ id: f.path, value: f.bytes });
+  }
+  for (const f of baseline?.agentBoot?.files ?? []) {
+    out.push({ id: f.path, value: f.bytes });
+  }
+  for (const e of baseline?.workflowClosure?.entryPoints ?? []) {
+    out.push({ id: e.path, value: e.reachableBytes });
+  }
+  return out.filter(
+    (r) => typeof r.id === 'string' && Number.isFinite(r.value),
+  );
+}
+
+/**
+ * Count how many allowlisted cycles each module participates in. A module in
+ * three cycles is a worse architectural hotspot than one in a single cycle.
+ *
+ * @param {object} baseline
+ * @returns {Array<{ id: string, value: number }>}
+ */
+function archCycleRows(baseline) {
+  const counts = new Map();
+  for (const cycle of baseline?.cycles ?? []) {
+    for (const member of new Set(cycle ?? [])) {
+      counts.set(member, (counts.get(member) ?? 0) + 1);
+    }
+  }
+  return [...counts].map(([id, value]) => ({ id, value }));
+}
+
+/**
+ * Count dead exports per file. The row grain is `{ file, symbol }`; the
+ * hotspot grain is the file.
+ *
+ * @param {object} baseline
+ * @returns {Array<{ id: string, value: number }>}
+ */
+function deadExportRows(baseline) {
+  const counts = new Map();
+  for (const row of baseline?.rows ?? []) {
+    if (typeof row?.file !== 'string') continue;
+    counts.set(row.file, (counts.get(row.file) ?? 0) + 1);
+  }
+  return [...counts].map(([id, value]) => ({ id, value }));
+}
+
+/**
+ * Build the `{ id, value }` extractor for an envelope-shaped gate kind.
+ *
+ * @param {string} idKey row property carrying the cluster identity
+ * @param {string} metric row property carrying the measured value
+ * @returns {(baseline: object) => Array<{ id: string, value: number }>}
+ */
+function envelopeRows(idKey, metric) {
+  return (baseline) =>
+    (baseline?.rows ?? [])
+      .map((row) => ({ id: row?.[idKey], value: row?.[metric] }))
+      .filter((r) => typeof r.id === 'string' && Number.isFinite(r.value));
+}
+
+/**
+ * Fold `{ id, value }` rows into one whole-repo number.
+ *
+ * `TOTAL` is for **additive** metrics — dead-export symbols, context bytes,
+ * lint errors — where the sum is the quantity the instrument measures.
+ * `TALLY` is for **non-additive** ones — percentages, indices, scores — where
+ * summing per-file values would fabricate a statistic; the honest whole-repo
+ * number is how many rows are tracked, and the unit name says so.
+ */
+const TOTAL = (rows) => rows.reduce((sum, row) => sum + row.value, 0);
+const TALLY = (rows) => rows.length;
+
+/**
+ * `[unit, fold]` per kind: the unit each kind's whole-repo total is
+ * denominated in, and how its rows fold into it.
+ *
+ * This is the fix for the roll-up that counted **files** for every kind
+ * (Story #4962). `dead-exports-production` moving 590 → 589 *symbols* across
+ * 187 files on both sides read as a delta of 0, and a 421-byte context-budget
+ * growth read as 0 too, because the fallback counted rows — a grain finer than
+ * the file for dead exports and coarser than the byte for context budget.
+ * Naming the unit is half the fix: an axis called `symbols` or `bytes` cannot
+ * be re-read as a file count the way a bare `rowCount` was.
+ */
+const TREND_UNITS = Object.freeze({
+  'bundle-size': ['rawKb', TOTAL],
+  coverage: ['filesTracked', TALLY],
+  crap: ['filesTracked', TALLY],
+  duplication: ['filesTracked', TALLY],
+  lighthouse: ['routesTracked', TALLY],
+  lint: ['errorCount', TOTAL],
+  maintainability: ['filesTracked', TALLY],
+  mutation: ['filesTracked', TALLY],
+  'arch-cycles': ['cycleMemberships', TOTAL],
+  'context-budget': ['bytes', TOTAL],
+  cyclomatic: ['filesTracked', TALLY],
+  'dead-exports': ['symbols', TOTAL],
+  'dead-exports-production': ['symbols', TOTAL],
+});
+
+/**
+ * Per-kind row spec.
+ *
+ * - `metric`  — the axis a hotspot is measured on.
+ * - `worse`   — which end of that axis is the bad end.
+ * - `rows`    — baseline → `{ id, value }` pairs, already aggregated where
+ *               the on-disk grain is finer than the file (dead exports,
+ *               cycles).
+ * - `idKind`  — what the cluster key names. Every kind but `lighthouse`
+ *               (routes) and `bundle-size` (bundle names) keys on a
+ *               repository file path.
+ */
+export const KIND_SPECS = Object.freeze({
+  'bundle-size': {
+    metric: 'rawKb',
+    worse: 'higher',
+    idKind: 'bundle',
+    rows: envelopeRows('bundle', 'rawKb'),
+  },
+  coverage: {
+    metric: 'lines',
+    worse: 'lower',
+    idKind: 'path',
+    rows: envelopeRows('path', 'lines'),
+  },
+  crap: {
+    metric: 'crap',
+    worse: 'higher',
+    idKind: 'path',
+    rows: envelopeRows('path', 'crap'),
+  },
+  duplication: {
+    metric: 'percentage',
+    worse: 'higher',
+    idKind: 'path',
+    rows: envelopeRows('path', 'percentage'),
+  },
+  lighthouse: {
+    metric: 'performance',
+    worse: 'lower',
+    idKind: 'route',
+    rows: envelopeRows('route', 'performance'),
+  },
+  lint: {
+    metric: 'errorCount',
+    worse: 'higher',
+    idKind: 'path',
+    rows: envelopeRows('path', 'errorCount'),
+  },
+  maintainability: {
+    metric: 'mi',
+    worse: 'lower',
+    idKind: 'path',
+    rows: envelopeRows('path', 'mi'),
+  },
+  mutation: {
+    metric: 'score',
+    worse: 'lower',
+    idKind: 'path',
+    rows: envelopeRows('path', 'score'),
+  },
+  'arch-cycles': {
+    metric: 'cycleMemberships',
+    worse: 'higher',
+    idKind: 'path',
+    rows: archCycleRows,
+  },
+  'context-budget': {
+    metric: 'bytes',
+    worse: 'higher',
+    idKind: 'path',
+    rows: contextBudgetRows,
+  },
+  cyclomatic: {
+    metric: 'maxCyclomatic',
+    worse: 'higher',
+    idKind: 'path',
+    rows: envelopeRows('file', 'maxCyclomatic'),
+  },
+  'dead-exports': {
+    metric: 'deadExports',
+    worse: 'higher',
+    idKind: 'path',
+    rows: deadExportRows,
+  },
+  'dead-exports-production': {
+    metric: 'deadExports',
+    worse: 'higher',
+    idKind: 'path',
+    rows: deadExportRows,
+  },
+});
+
+/**
+ * The whole-repo rollup for a kind, or `null` when the kind does not carry
+ * one. Ratchet baselines have no rollup — which is why stub detection asks
+ * for an all-zero rollup rather than merely empty rows: an `arch-cycles`
+ * baseline with zero cycles is a passing gate, not a dead instrument.
+ *
+ * @param {object | null} baseline
+ * @returns {object | null}
+ */
+export function rollupOf(baseline) {
+  const rollup = baseline?.rollup?.['*'];
+  return rollup && typeof rollup === 'object' ? rollup : null;
+}
+
+/**
+ * The whole-repo quantity a kind measures, in the unit it measures it in —
+ * `{ unit, value }`, or `null` when the kind or the baseline is unreadable.
+ *
+ * This sits beside `rowCount` in `gateSurface[]` precisely because the two
+ * disagree: `dead-exports-production` carries 589 rows across 187 files, so a
+ * lone `rowCount: 187` reads as a symbol count and is not one.
+ *
+ * @param {string} kind
+ * @param {object | null} baseline
+ * @returns {{ unit: string, value: number } | null}
+ */
+export function measuredTotalOf(kind, baseline) {
+  const spec = KIND_SPECS[kind];
+  const denomination = TREND_UNITS[kind];
+  if (!baseline || !spec || !denomination) return null;
+  const [unit, fold] = denomination;
+  return { unit, value: fold(spec.rows(baseline)) };
+}
+
+/**
+ * The rollup a trend sample compares on. Gate kinds carry their own, already
+ * axis-named; ratchet baselines carry none, so the whole-repo total stands in
+ * under its own unit — "dead exports went 590 → 589 **symbols**" is exactly
+ * the direction-of-travel question trend answers, and skipping the ratchet
+ * half here would leave it visible in `gateSurface[]` but invisible in
+ * `trend[]`.
+ *
+ * @param {string} kind
+ * @param {object | null} baseline
+ * @returns {object | null}
+ */
+export function trendRollupOf(kind, baseline) {
+  if (!baseline) return null;
+  const declared = rollupOf(baseline);
+  if (declared) return declared;
+  const measured = measuredTotalOf(kind, baseline);
+  return measured ? { [measured.unit]: measured.value } : null;
+}

package/.agents/scripts/lib/audit-baselines/outliers.js

@@ -0,0 +1,100 @@
+/**
+ * outliers.js — bounded top-N outlier extraction per gate (Story #4902).
+ *
+ * `baselines/crap.json` alone is ~650KB of per-method rows. The engine must
+ * never embed a whole baseline in its envelope, so every kind is narrowed to
+ * at most `topN` rows here, before anything downstream sees them.
+ *
+ * Narrowing happens in two steps:
+ *
+ *   1. **Aggregate to the cluster grain.** Baseline rows are per-method
+ *      (crap) or per-symbol (dead exports); hotspots are per-file. Each id
+ *      keeps its single worst value, plus how many rows it contributed.
+ *   2. **Score, then cut.** `severityWeight` is the row's position in its
+ *      own kind's distribution, from 0 (the best value present) to 1 (the
+ *      worst). Scoring within the kind is what makes CRAP 29 and MI 74
+ *      comparable at all — the two axes share no unit, and the whole point
+ *      of a cluster is to add them up.
+ *
+ * @module lib/audit-baselines/outliers
+ */
+
+import { KIND_SPECS } from './kinds.js';
+
+/** Default bound on rows extracted per gate. */
+export const DEFAULT_TOP_N = 20;
+
+/**
+ * Fold `{ id, value }` rows to one entry per id, keeping the worst value.
+ *
+ * @param {Array<{ id: string, value: number }>} rows
+ * @param {'higher' | 'lower'} worse
+ * @returns {Array<{ id: string, value: number, rowCount: number }>}
+ */
+function aggregateById(rows, worse) {
+  const byId = new Map();
+  for (const { id, value } of rows) {
+    const prev = byId.get(id);
+    if (prev === undefined) {
+      byId.set(id, { id, value, rowCount: 1 });
+      continue;
+    }
+    prev.rowCount += 1;
+    const isWorse =
+      worse === 'higher' ? value > prev.value : value < prev.value;
+    if (isWorse) prev.value = value;
+  }
+  return [...byId.values()];
+}
+
+/**
+ * Position of `value` in `[min, max]` normalized so 1 is always the worst
+ * end. A degenerate distribution (every value identical) scores 1 for every
+ * row: they are all equally the worst, and equally the best.
+ *
+ * @param {number} value
+ * @param {number} min
+ * @param {number} max
+ * @param {'higher' | 'lower'} worse
+ * @returns {number} 0..1
+ */
+function normalizeSeverity(value, min, max, worse) {
+  if (!(max > min)) return 1;
+  const ratio = (value - min) / (max - min);
+  return worse === 'higher' ? ratio : 1 - ratio;
+}
+
+/**
+ * Extract the bounded worst-N rows for one kind.
+ *
+ * @param {{ kind: string, baseline: object | null, topN?: number }} args
+ * @returns {Array<{
+ *   kind: string, id: string, metric: string, value: number,
+ *   rowCount: number, severityWeight: number,
+ * }>} worst first
+ */
+export function extractOutliers({ kind, baseline, topN = DEFAULT_TOP_N }) {
+  const spec = KIND_SPECS[kind];
+  if (!spec || !baseline) return [];
+  const aggregated = aggregateById(spec.rows(baseline), spec.worse);
+  if (aggregated.length === 0) return [];
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  for (const row of aggregated) {
+    if (row.value < min) min = row.value;
+    if (row.value > max) max = row.value;
+  }
+  return aggregated
+    .map((row) => ({
+      kind,
+      id: row.id,
+      metric: spec.metric,
+      value: row.value,
+      rowCount: row.rowCount,
+      severityWeight: normalizeSeverity(row.value, min, max, spec.worse),
+    }))
+    .sort(
+      (a, b) => b.severityWeight - a.severityWeight || a.id.localeCompare(b.id),
+    )
+    .slice(0, Math.max(0, topN));
+}