mandrel 2.25.0 → 2.26.0

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

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

@@ -0,0 +1,193 @@
+/**
+ * weights.js — the three ranking multipliers, and their degradations
+ * (Story #4902).
+ *
+ * A hotspot's severity says how bad the code measures. These three say how
+ * much that badness costs: how often the file changes (churn), how much of
+ * the repository depends on it (import in-degree), and how often agents have
+ * actually tripped over it (friction signals).
+ *
+ * All three are **optional inputs**. A shallow clone has no git history, a
+ * fresh checkout has no friction ledger, and a consumer whose sources live
+ * outside the scanned roots has no resolvable import graph. Each degrades to
+ * a neutral multiplier of exactly 1.0 — never 0 (which would erase the
+ * hotspot) and never a guess. The engine exits 0 in every degraded case.
+ *
+ * @module lib/audit-baselines/weights
+ */
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { computeInDegree, resolveRepoGraph } from '../import-graph.js';
+
+/** Neutral multiplier every degraded weight collapses to. */
+const NEUTRAL_WEIGHT = 1.0;
+
+/**
+ * Saturating count → multiplier in `[1, 2)`. Zero observations gives exactly
+ * `NEUTRAL_WEIGHT`, so "no signal" and "signal says nothing notable" are the
+ * same number — the degradation is indistinguishable from an honest zero,
+ * which is the point: neither should move the ranking.
+ *
+ * @param {number} count
+ * @param {number} half count at which the multiplier reaches 1.5
+ * @returns {number}
+ */
+function saturate(count, half) {
+  if (!Number.isFinite(count) || count <= 0) return NEUTRAL_WEIGHT;
+  return NEUTRAL_WEIGHT + count / (count + half);
+}
+
+/**
+ * Count commits touching each file in the recent history window.
+ *
+ * @param {{ cwd: string, windowDays?: number, run?: Function }} args
+ * @returns {{ counts: Map<string, number>, degraded: boolean }}
+ *   `degraded` is true when git could not answer at all — not a git work
+ *   tree, no commits yet, or the binary is unavailable.
+ */
+export function readChurn({ cwd, windowDays = 180, run = execFileSync }) {
+  let stdout;
+  try {
+    stdout = run(
+      'git',
+      [
+        'log',
+        `--since=${windowDays}.days.ago`,
+        '--name-only',
+        '--pretty=format:',
+        '--no-renames',
+      ],
+      {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+        // git narrates "not a git repository" on stderr; the degradation is
+        // reported in the envelope, not shouted at the operator.
+        stdio: ['ignore', 'pipe', 'ignore'],
+      },
+    );
+  } catch {
+    return { counts: new Map(), degraded: true };
+  }
+  const counts = new Map();
+  for (const line of String(stdout).split('\n')) {
+    const file = line.trim();
+    if (file.length === 0) continue;
+    counts.set(file, (counts.get(file) ?? 0) + 1);
+  }
+  return { counts, degraded: false };
+}
+
+/**
+ * Import in-degree per module, keyed by repo-relative posix path.
+ *
+ * @param {{ cwd: string, graph?: Map<string, string[]> | null }} args
+ * @returns {{ degrees: Map<string, number>, degraded: boolean }}
+ */
+export function readCentrality({ cwd, graph }) {
+  const resolved = graph === undefined ? resolveRepoGraph(cwd) : graph;
+  if (!resolved) return { degrees: new Map(), degraded: true };
+  return { degrees: computeInDegree(resolved), degraded: false };
+}
+
+/** Path tokens that look like repository files, harvested from signal text. */
+const PATH_TOKEN_RE = /[\w@][\w./@-]*\.(?:js|mjs|cjs|ts|tsx|json|md)\b/g;
+
+/**
+ * Collect every `signals.ndjson` under `tempRoot`. Absent tree → empty list.
+ *
+ * @param {string} tempRootAbs
+ * @returns {string[]} absolute paths
+ */
+function findSignalStreams(tempRootAbs) {
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > 6) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const child = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(child, depth + 1);
+      else if (entry.name === 'signals.ndjson') out.push(child);
+    }
+  };
+  walk(tempRootAbs, 0);
+  return out.sort();
+}
+
+/**
+ * Count friction signals blaming each file.
+ *
+ * Signal records carry no dedicated path field — the blamed file surfaces
+ * inside free-form `details` / `emitter.command` text — so paths are
+ * harvested by token scan over each record's serialized form. A malformed
+ * line is skipped, never fatal.
+ *
+ * @param {{ tempRootAbs: string, kinds?: Set<string> }} args
+ * @returns {{ counts: Map<string, number>, degraded: boolean, streams: number }}
+ */
+export function readFriction({
+  tempRootAbs,
+  kinds = new Set(['friction', 'hotspot', 'rework', 'churn', 'retry']),
+}) {
+  const streams = findSignalStreams(tempRootAbs);
+  if (streams.length === 0) {
+    return { counts: new Map(), degraded: true, streams: 0 };
+  }
+  const counts = new Map();
+  for (const stream of streams) {
+    let raw;
+    try {
+      raw = fs.readFileSync(stream, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const line of raw.split('\n')) {
+      if (line.trim().length === 0) continue;
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (!kinds.has(record?.kind)) continue;
+      const text =
+        JSON.stringify(record.details ?? {}) + (record?.emitter?.command ?? '');
+      for (const token of text.match(PATH_TOKEN_RE) ?? []) {
+        counts.set(token, (counts.get(token) ?? 0) + 1);
+      }
+    }
+  }
+  return { counts, degraded: false, streams: streams.length };
+}
+
+/**
+ * Bundle the three weight lookups into one resolver the hotspot builder can
+ * call per cluster id, plus the degradation flags the envelope reports.
+ *
+ * @param {{
+ *   churn: { counts: Map<string, number>, degraded: boolean },
+ *   centrality: { degrees: Map<string, number>, degraded: boolean },
+ *   friction: { counts: Map<string, number>, degraded: boolean },
+ * }} sources
+ * @returns {(id: string) => { churnWeight: number, centralityWeight: number, frictionWeight: number }}
+ */
+export function makeWeightResolver({ churn, centrality, friction }) {
+  return (id) => ({
+    churnWeight: churn.degraded
+      ? NEUTRAL_WEIGHT
+      : saturate(churn.counts.get(id) ?? 0, 12),
+    centralityWeight: centrality.degraded
+      ? NEUTRAL_WEIGHT
+      : saturate(centrality.degrees.get(id) ?? 0, 8),
+    frictionWeight: friction.degraded
+      ? NEUTRAL_WEIGHT
+      : saturate(friction.counts.get(id) ?? 0, 4),
+  });
+}

package/.agents/scripts/lib/audit-suite/index.js

@@ -27,15 +27,10 @@ export {
 } from './lens-diff-floor.js';
 export { runAuditSuite } from './runner.js';
 export {
-  GLOBAL_LENS_ALLOWLIST,
-  isGlobalLens,
   LENS_TIERS,
   matchesAnyFilePattern,
   matchesFilePattern,
-  NAVIGABILITY_LENS,
   resolveLensTier,
-  resolveNavigabilityRouteGlobs,
-  routesNavigabilityLens,
   selectAudits,
   selectLocalLenses,
 } from './selector.js';