mandrel 2.24.0 → 2.26.0

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

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

@@ -0,0 +1,87 @@
+/**
+ * read.js — tolerant, strictly read-only filesystem access for the baseline
+ * hotspot engine (Story #4902).
+ *
+ * The engine's job is to *report on* the baseline surface, including the
+ * parts of it that are missing or malformed. So no read here throws: a
+ * missing file, an unreadable directory, or a JSON parse error is evidence
+ * the envelope carries, not a crash. Nothing in this module opens a file for
+ * writing — the read-only invariant over `baselines/` starts here.
+ *
+ * @module lib/audit-baselines/read
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Read and parse a JSON file without throwing.
+ *
+ * @param {string} absolutePath
+ * @returns {{ exists: boolean, parsed: object | null, parseError: string | null }}
+ */
+export function readJsonFile(absolutePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(absolutePath, 'utf8');
+  } catch {
+    return { exists: false, parsed: null, parseError: null };
+  }
+  try {
+    return { exists: true, parsed: JSON.parse(raw), parseError: null };
+  } catch (err) {
+    return {
+      exists: true,
+      parsed: null,
+      parseError: err?.message ?? String(err),
+    };
+  }
+}
+
+/**
+ * List every file under `rootDir` as a posix repo-relative path, skipping
+ * `node_modules`, `.git`, and `.worktrees`. Returns `[]` for an absent or
+ * unreadable root rather than throwing.
+ *
+ * @param {string} repoRoot
+ * @param {string} rootDir repo-relative directory to walk
+ * @returns {string[]} sorted repo-relative posix paths
+ */
+export function listFilesUnder(repoRoot, rootDir) {
+  const skip = new Set(['node_modules', '.git', '.worktrees']);
+  const out = [];
+  const walk = (abs) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(abs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (skip.has(entry.name)) continue;
+      const child = path.join(abs, entry.name);
+      if (entry.isDirectory()) {
+        walk(child);
+      } else if (entry.isFile()) {
+        out.push(path.relative(repoRoot, child).split(path.sep).join('/'));
+      }
+    }
+  };
+  walk(path.resolve(repoRoot, rootDir));
+  return out.sort();
+}
+
+/**
+ * Age in whole days between `generatedAt` and `now`. Null when the stamp is
+ * absent or unparseable — the engine reports "unknown", never a fabricated 0.
+ *
+ * @param {unknown} generatedAt
+ * @param {Date} now
+ * @returns {number | null}
+ */
+export function ageInDays(generatedAt, now) {
+  if (typeof generatedAt !== 'string') return null;
+  const then = Date.parse(generatedAt);
+  if (Number.isNaN(then)) return null;
+  return Math.floor((now.getTime() - then) / 86_400_000);
+}

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

@@ -0,0 +1,123 @@
+/**
+ * staleness.js — the two clocks a baseline is stale against (Story #4962).
+ *
+ * Wall-clock age answers the wrong question on a busy repository.
+ * `coverage.json` and `maintainability.json` both read `staleDays: 0` while
+ * already predating merges that had rescored files they still carry rows for:
+ * refreshed an hour ago, and behind already. The second clock is the one that
+ * matters — how many commits have touched the **measured surface** since the
+ * baseline was last committed. A baseline older than the surface it scores is
+ * stale at zero wall-clock days.
+ *
+ * Read-only and degrading, like the rest of this engine: a shallow clone, an
+ * untracked baseline, or a surface that is not path-keyed all report `null`.
+ * Unknown is never rounded down to a reassuring 0.
+ *
+ * @module lib/audit-baselines/staleness
+ */
+
+import { execFileSync } from 'node:child_process';
+import { KIND_SPECS } from './kinds.js';
+import { ageInDays } from './read.js';
+
+/**
+ * Run a git command under `cwd`, returning trimmed stdout, or `null` on any
+ * failure or empty result.
+ *
+ * @param {string[]} args
+ * @param {{ cwd: string, run?: Function }} io
+ * @returns {string | null}
+ */
+function git(args, { cwd, run = execFileSync }) {
+  try {
+    const stdout = String(
+      run('git', args, {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: 16 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }),
+    ).trim();
+    return stdout.length > 0 ? stdout : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The repo-relative paths whose commits would invalidate this baseline: the
+ * gate's declared `targetDirs` when it has them, else the baseline's own row
+ * ids — which are file paths for every kind but `lighthouse` (routes) and
+ * `bundle-size` (bundle names). Those two get an empty surface rather than a
+ * route name handed to git as a pathspec.
+ *
+ * @param {{ kind: string, gateBlock: object | null, rows: Array<{id: string}> }} args
+ * @returns {string[]}
+ */
+function measuredSurfaceOf({ kind, gateBlock, rows }) {
+  const dirs = (gateBlock?.targetDirs ?? []).filter(
+    (dir) => typeof dir === 'string' && dir.length > 0,
+  );
+  if (dirs.length > 0) return dirs;
+  if (KIND_SPECS[kind]?.idKind !== 'path') return [];
+  return [...new Set(rows.map((row) => row.id))];
+}
+
+/**
+ * Commits touching `surfacePaths` since `relPath` was last committed. An
+ * empty surface yields `null` too: nothing was checked, so nothing can be
+ * claimed.
+ *
+ * @param {{ relPath: string, surfacePaths: string[], io: object }} args
+ * @returns {number | null}
+ */
+function commitsSinceBaseline({ relPath, surfacePaths, io }) {
+  if (surfacePaths.length === 0) return null;
+  const writtenAt = git(['log', '-n1', '--format=%H', '--', relPath], io);
+  if (!writtenAt) return null;
+  const counted = git(
+    ['rev-list', '--count', `${writtenAt}..HEAD`, '--', ...surfacePaths],
+    io,
+  );
+  const commits = Number.parseInt(counted ?? '', 10);
+  return Number.isInteger(commits) ? commits : null;
+}
+
+/**
+ * The four staleness fields of one `gateSurface[]` entry, on both clocks.
+ *
+ * @param {{
+ *   kind: string, gateBlock: object | null, rows: Array<{id: string}>,
+ *   relPath: string, baseline: object | null, now: Date,
+ *   io: { cwd: string, run?: Function },
+ * }} args
+ * @returns {{
+ *   generatedAt: string | null, staleDays: number | null,
+ *   staleCommits: number | null, surfaceStale: boolean | null,
+ * }}
+ */
+export function stalenessOf({
+  kind,
+  gateBlock,
+  rows,
+  relPath,
+  baseline,
+  now,
+  io,
+}) {
+  const generatedAt =
+    typeof baseline?.generatedAt === 'string' ? baseline.generatedAt : null;
+  const staleCommits = baseline
+    ? commitsSinceBaseline({
+        relPath,
+        surfacePaths: measuredSurfaceOf({ kind, gateBlock, rows }),
+        io,
+      })
+    : null;
+  return {
+    generatedAt,
+    staleDays: ageInDays(generatedAt, now),
+    staleCommits,
+    surfaceStale: staleCommits === null ? null : staleCommits > 0,
+  };
+}

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

@@ -0,0 +1,106 @@
+/**
+ * surface-entry.js — the health report for one measuring instrument
+ * (Story #4902, split out in #4962).
+ *
+ * A baseline review that only reads the numbers cannot see the failure mode
+ * that matters most: an instrument that is not measuring anything. A gate can
+ * be unconfigured, its baseline file can be missing, it can be a **stub**
+ * (committed with no rows and an all-zero rollup, so it passes every run
+ * vacuously), it can be stale on either clock, and its `ignoreGlobs` can name
+ * paths that no longer exist — each of which reads as "green" from the gate's
+ * exit code. This module turns all of that into declarative fields for one
+ * kind; [`gate-surface.js`](gate-surface.js) walks the kinds and
+ * [`staleness.js`](staleness.js) owns the two clocks.
+ *
+ * @module lib/audit-baselines/surface-entry
+ */
+
+import picomatch from 'picomatch';
+import { GATE_KINDS, KIND_SPECS, measuredTotalOf, rollupOf } from './kinds.js';
+import { stalenessOf } from './staleness.js';
+
+/**
+ * True when every numeric leaf of the rollup is zero. A rollup with no
+ * numeric leaves at all is not all-zero — it carries no measurement to call
+ * zero, and treating it as such would flag shapes this engine cannot read.
+ *
+ * @param {object | null} rollup
+ * @returns {boolean}
+ */
+function isAllZeroRollup(rollup) {
+  if (!rollup || typeof rollup !== 'object') return false;
+  const numbers = Object.values(rollup).filter((v) => typeof v === 'number');
+  return numbers.length > 0 && numbers.every((v) => v === 0);
+}
+
+/**
+ * A **stub instrument**: zero rows AND an all-zero rollup. Both halves are
+ * required. Ratchet baselines carry no rollup, so a clean `arch-cycles`
+ * allowlist — genuinely zero cycles, the success state — is never mistaken
+ * for a dead instrument.
+ *
+ * @param {{ rowCount: number, rollup: object | null }} args
+ * @returns {boolean}
+ */
+function isStubInstrument({ rowCount, rollup }) {
+  return rowCount === 0 && isAllZeroRollup(rollup);
+}
+
+/**
+ * Which of a gate's configured `ignoreGlobs` match zero files on disk.
+ *
+ * @param {string[]} ignoreGlobs
+ * @param {string[]} files repo-relative posix paths
+ * @returns {string[]}
+ */
+function findDeadIgnoreGlobs(ignoreGlobs, files) {
+  const dead = [];
+  for (const glob of ignoreGlobs ?? []) {
+    if (typeof glob !== 'string' || glob.length === 0) continue;
+    const isMatch = picomatch(glob, { dot: true });
+    if (!files.some((f) => isMatch(f))) dead.push(glob);
+  }
+  return dead;
+}
+
+/**
+ * Assemble one `gateSurface[]` entry from an already-read baseline.
+ *
+ * `rowCount` and `measured` both appear because they legitimately disagree:
+ * rows are counted after the kind's per-file aggregation, while `measured` is
+ * the quantity the instrument reports in its own unit — 589 dead-export
+ * symbols sit in 187 files.
+ *
+ * @param {{
+ *   kind: string, quality: object, read: object, relPath: string,
+ *   files: string[], now: Date, io: { cwd: string, run?: Function },
+ * }} args
+ * @returns {object}
+ */
+export function surfaceEntryFor({
+  kind,
+  quality,
+  read,
+  relPath,
+  files,
+  now,
+  io,
+}) {
+  const gateBlock = quality?.gates?.[kind] ?? null;
+  const { exists, parsed: baseline, parseError } = read;
+  const rows = baseline ? KIND_SPECS[kind].rows(baseline) : [];
+  const rollup = rollupOf(baseline);
+  return {
+    kind,
+    surface: GATE_KINDS.includes(kind) ? 'gate' : 'ratchet',
+    baselinePath: relPath,
+    configured: gateBlock !== null && typeof gateBlock === 'object',
+    baselineExists: exists,
+    stub: isStubInstrument({ rowCount: rows.length, rollup }),
+    rowCount: rows.length,
+    measured: measuredTotalOf(kind, baseline),
+    ...stalenessOf({ kind, gateBlock, rows, relPath, baseline, now, io }),
+    deadIgnoreGlobs: findDeadIgnoreGlobs(gateBlock?.ignoreGlobs, files),
+    parseError,
+  };
+}

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

@@ -0,0 +1,125 @@
+/**
+ * trend.js — per-kind rollup deltas read out of each baseline file's own git
+ * history (Story #4902).
+ *
+ * A ratchet only tells you whether today is worse than yesterday. The
+ * question a baseline review asks is the other one: which direction has this
+ * number been moving, and is the ratchet actually ratcheting? That answer is
+ * already committed — every baseline refresh is a commit against the same
+ * path — so it is read with `git log` + `git show`, never recomputed by
+ * re-running an instrument.
+ *
+ * Degradation: any git failure (shallow clone, no history for the path, not
+ * a work tree) yields an empty `trend[]` and exit 0. A missing history is
+ * missing evidence, not an error.
+ *
+ * @module lib/audit-baselines/trend
+ */
+
+import { execFileSync } from 'node:child_process';
+import { trendRollupOf } from './kinds.js';
+
+/**
+ * List the most recent commits touching `relPath`, newest first.
+ *
+ * @param {{ cwd: string, relPath: string, limit: number, run?: Function }} args
+ * @returns {Array<{ sha: string, committedAt: string }>}
+ */
+function listCommits({ cwd, relPath, limit, run = execFileSync }) {
+  let stdout;
+  try {
+    stdout = run(
+      'git',
+      ['log', `-n${limit}`, '--format=%H %cI', '--', relPath],
+      { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+  } catch {
+    return [];
+  }
+  return String(stdout)
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.includes(' '))
+    .map((line) => {
+      const [sha, committedAt] = line.split(' ');
+      return { sha, committedAt };
+    });
+}
+
+/**
+ * Read the comparable rollup of a baseline as it existed at `sha`.
+ *
+ * @param {{ cwd: string, kind: string, sha: string, relPath: string, run?: Function }} args
+ * @returns {object | null}
+ */
+function rollupAt({ cwd, kind, sha, relPath, run = execFileSync }) {
+  let stdout;
+  try {
+    stdout = run('git', ['show', `${sha}:${relPath}`], {
+      cwd,
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch {
+    return null;
+  }
+  try {
+    return trendRollupOf(kind, JSON.parse(stdout));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Numeric axis-by-axis difference `to - from`. Axes missing from either side
+ * are omitted rather than defaulted — a rollup that gained an axis has no
+ * delta on it, and inventing one would read as a regression.
+ *
+ * @param {object} from
+ * @param {object} to
+ * @returns {Record<string, number>}
+ */
+function rollupDelta(from, to) {
+  const deltas = {};
+  for (const [axis, current] of Object.entries(to ?? {})) {
+    const previous = from?.[axis];
+    if (typeof current === 'number' && typeof previous === 'number') {
+      deltas[axis] = current - previous;
+    }
+  }
+  return deltas;
+}
+
+/**
+ * Build the `trend[]` section: newest-vs-previous rollup deltas per kind.
+ *
+ * @param {{
+ *   cwd: string, kinds: string[], pathFor: (kind: string) => string,
+ *   depth?: number, run?: Function,
+ * }} args
+ * @returns {Array<object>}
+ */
+export function buildTrend({ cwd, kinds, pathFor, depth = 5, run }) {
+  const out = [];
+  for (const kind of kinds) {
+    const relPath = pathFor(kind);
+    const commits = listCommits({ cwd, relPath, limit: depth, run });
+    const samples = [];
+    for (const commit of commits) {
+      const rollup = rollupAt({ cwd, kind, sha: commit.sha, relPath, run });
+      if (rollup) samples.push({ ...commit, rollup });
+    }
+    if (samples.length < 2) continue;
+    const [current, previous] = samples;
+    out.push({
+      kind,
+      baselinePath: relPath,
+      sampleCount: samples.length,
+      from: { sha: previous.sha, committedAt: previous.committedAt },
+      to: { sha: current.sha, committedAt: current.committedAt },
+      deltas: rollupDelta(previous.rollup, current.rollup),
+    });
+  }
+  return out;
+}