mandrel 1.57.0

package/.agents/scripts/lib/baselines/component-matcher.js

@@ -0,0 +1,21 @@
+/**
+ * component-matcher.js — shared helper for matching a row's key (path or
+ * route) against a components-registry entry's `includes` prefix.
+ *
+ * Hoisted out of six baseline-kind modules (coverage, crap, lint,
+ * maintainability, mutation, lighthouse) which all shipped byte-equivalent
+ * copies of this predicate. See Story #2464.
+ *
+ * @param {{ includes?: string } | null | undefined} component
+ *   A components-registry entry. Treated as non-matching when nullish or
+ *   when `includes` is not a string.
+ * @param {string} p
+ *   The row's key field — `path` for code-shaped rows or `route` for
+ *   lighthouse-shaped rows. The matcher is identity-equal or
+ *   prefix-with-slash; callers normalize the row shape before invoking.
+ * @returns {boolean}
+ */
+export function componentMatches(component, p) {
+  if (!component || typeof component.includes !== 'string') return false;
+  return p === component.includes || p.startsWith(`${component.includes}/`);
+}

package/.agents/scripts/lib/baselines/components.js

@@ -0,0 +1,126 @@
+// .agents/scripts/lib/baselines/components.js
+//
+// Story #1892 / Task #1902 — shared component resolver and row grouper.
+//
+// The "components" model lets a gate slice a baseline into named buckets
+// (e.g. `app`, `worker`, `infra`) so per-component floors and tolerances
+// can be evaluated independently. The shape is:
+//
+//   components: { [name: string]: string[] }   // map of name → glob list
+//
+// The canonical default — used when a gate omits `components` from its
+// agentrc config — is `{ '*': ['**'] }`, meaning "one bucket called `*`
+// matching every row". This keeps backwards compatibility with the
+// pre-components rollup contract: a baseline that ships only `rollup['*']`
+// continues to work without operator intervention.
+//
+// Globs are matched with minimatch. Overlap is allowed by design — a row
+// matched by two components is reported under both. Components keyed by
+// the literal `*` are treated as the whole-repo rollup and always match
+// every row regardless of declared globs.
+
+import { minimatch } from 'minimatch';
+
+/** The default components map, used when a gate omits `components`. */
+const DEFAULT_COMPONENTS = Object.freeze({ '*': Object.freeze(['**']) });
+
+/**
+ * Resolve the components map for a single gate config.
+ *
+ * Behaviour:
+ *   - If the gate config has no `components` key (or it's not a plain
+ *     object), return the default `{ '*': ['**'] }`.
+ *   - If `components` is present but contains no entries, also return the
+ *     default — a writer that emitted an empty `components: {}` is
+ *     functionally equivalent to "no components declared".
+ *   - Otherwise pass the operator-declared map through unchanged. Each
+ *     value MUST be an array of glob strings; non-array values are
+ *     coerced to an empty array so the grouper's caller can't crash on
+ *     malformed input.
+ *
+ * @param {object} [gateConfig]  A single gate config slice, e.g.
+ *   `delivery.quality.gates.coverage`.
+ * @returns {Record<string, string[]>} Components map, never null.
+ */
+export function resolveComponents(gateConfig) {
+  if (!gateConfig || typeof gateConfig !== 'object') {
+    return cloneDefault();
+  }
+  const raw = gateConfig.components;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return cloneDefault();
+  }
+  const entries = Object.entries(raw);
+  if (entries.length === 0) {
+    return cloneDefault();
+  }
+  const out = {};
+  for (const [name, globs] of entries) {
+    out[name] = Array.isArray(globs) ? globs.slice() : [];
+  }
+  return out;
+}
+
+function cloneDefault() {
+  return { '*': ['**'] };
+}
+
+/**
+ * Group rows by component using the resolved components map.
+ *
+ * Matching rules:
+ *   - The component literally named `*` is the whole-repo bucket and
+ *     captures every row regardless of declared globs.
+ *   - For every other component, the row's `keyField` value is matched
+ *     against each declared glob with minimatch (using `dot: true` so
+ *     leading-dot paths participate). A row joins the bucket on first
+ *     match — but a row CAN appear in multiple buckets because we evaluate
+ *     every component (overlap is allowed).
+ *   - Rows whose `keyField` is not a non-empty string never match
+ *     any non-`*` bucket; they still land in `*`.
+ *
+ * @param {Array<Record<string, unknown>>} rows
+ * @param {Record<string, string[]>}       components
+ * @param {string}                         [keyField='path']
+ *   The row field to feed into the matcher. Defaults to `path` (used by
+ *   lint / coverage / crap / maintainability / mutation). Use `'route'`
+ *   for lighthouse and `'bundle'` for bundle-size.
+ * @returns {Record<string, Array<Record<string, unknown>>>}
+ *   Map of component name → matching rows, in input order.
+ */
+export function groupRows(rows, components, keyField = 'path') {
+  const safeRows = Array.isArray(rows) ? rows : [];
+  const safeComponents =
+    components && typeof components === 'object' ? components : cloneDefault();
+  const field =
+    typeof keyField === 'string' && keyField.length > 0 ? keyField : 'path';
+
+  const buckets = {};
+  for (const name of Object.keys(safeComponents)) {
+    buckets[name] = [];
+  }
+
+  for (const row of safeRows) {
+    for (const [name, globs] of Object.entries(safeComponents)) {
+      if (name === '*') {
+        buckets[name].push(row);
+        continue;
+      }
+      const key = row && typeof row === 'object' ? row[field] : undefined;
+      if (typeof key !== 'string' || key.length === 0) continue;
+      const normalized = key.replace(/\\/g, '/');
+      const list = Array.isArray(globs) ? globs : [];
+      for (const glob of list) {
+        if (typeof glob !== 'string' || glob.length === 0) continue;
+        if (minimatch(normalized, glob, { dot: true })) {
+          buckets[name].push(row);
+          break;
+        }
+      }
+    }
+  }
+
+  return buckets;
+}
+
+export const _internals = Object.freeze({ DEFAULT_COMPONENTS });

package/.agents/scripts/lib/baselines/diff-scope-cli.js

@@ -0,0 +1,203 @@
+/**
+ * lib/baselines/diff-scope-cli.js — shared `--diff-scope <ref>` parser for
+ * the manual baseline-update CLIs (Story #1974 / Task #1986, Epic #1943).
+ *
+ * `update-coverage-baseline.js`, `update-crap-baseline.js`,
+ * `update-maintainability-baseline.js`, and `update-mutation-baseline.js`
+ * all accept an opt-in `--diff-scope <ref>` flag. When supplied, the
+ * baseline write narrows to files changed since `<ref>` (resolved via
+ * `git diff --name-only <ref>...HEAD`). Out-of-scope rows are preserved
+ * verbatim from the prior on-disk baseline via the per-kind `mergeRows`.
+ *
+ * When the flag is absent, the CLIs behave exactly as they did before
+ * #1974 — full regenerate + write — preserving operator workflows that
+ * intentionally rewrite the whole baseline.
+ *
+ * The helper is shared to keep the flag's contract identical across the
+ * four scripts: same argv parser, same git invocation, same forward-slash
+ * path normalisation. The four CLIs differ only in how they pipe the
+ * resolved scope through to their writer.
+ */
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { parseNameOnlyStdout } from '../changed-files.js';
+
+/**
+ * Parse `--diff-scope <ref>` (and the legacy `--diff-scope=<ref>` form)
+ * from an argv slice. Returns `null` when the flag is absent. Throws a
+ * TypeError when the flag is supplied without a value.
+ *
+ * Pure; no I/O.
+ *
+ * @param {string[]} argv
+ * @returns {string | null}
+ */
+export function parseDiffScopeFlag(argv = []) {
+  for (let i = 0; i < argv.length; i += 1) {
+    const tok = argv[i];
+    if (tok === '--diff-scope') {
+      const next = argv[i + 1];
+      if (typeof next !== 'string' || next.length === 0) {
+        throw new TypeError(
+          '[diff-scope-cli] --diff-scope requires a non-empty <ref> argument',
+        );
+      }
+      return next;
+    }
+    if (typeof tok === 'string' && tok.startsWith('--diff-scope=')) {
+      const ref = tok.slice('--diff-scope='.length);
+      if (ref.length === 0) {
+        throw new TypeError(
+          '[diff-scope-cli] --diff-scope= requires a non-empty <ref> value',
+        );
+      }
+      return ref;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the file footprint of `git diff --name-only <ref>...HEAD`.
+ * Returns a `Set<string>` of repo-relative paths with forward-slash
+ * normalisation. Returns an empty Set when the diff is empty or git
+ * exits non-zero (best-effort; a missing-ref or corrupt repo is the
+ * operator's signal to inspect the working tree).
+ *
+ * The `spawnImpl` seam exists for unit tests — production callers omit it.
+ *
+ * @param {{ ref: string, cwd?: string, spawnImpl?: typeof spawnSync }} args
+ * @returns {Set<string>}
+ */
+export function resolveDiffScopeFiles({
+  ref,
+  cwd = process.cwd(),
+  spawnImpl = spawnSync,
+} = {}) {
+  if (typeof ref !== 'string' || ref.length === 0) return new Set();
+  const res = spawnImpl('git', ['diff', '--name-only', `${ref}...HEAD`], {
+    cwd,
+    encoding: 'utf8',
+  });
+  if (!res || res.status !== 0) return new Set();
+  return new Set(parseNameOnlyStdout(res.stdout));
+}
+
+/**
+ * Convenience: parse `--diff-scope` and resolve files in one call.
+ * Returns `null` when the flag is absent (so the caller can branch on
+ * "scope was opted in?"); otherwise returns
+ * `{ ref, files: Set<string>, scope: { mode: 'diff', files } }` ready to
+ * pass into `writer.write({ scope })`.
+ *
+ * @param {{ argv: string[], cwd?: string, spawnImpl?: typeof spawnSync }} args
+ * @returns {{ ref: string, files: Set<string>, scope: {mode: 'diff', files: Set<string>} } | null}
+ */
+export function resolveDiffScope({ argv, cwd, spawnImpl } = {}) {
+  const ref = parseDiffScopeFlag(argv);
+  if (ref === null) return null;
+  const files = resolveDiffScopeFiles({ ref, cwd, spawnImpl });
+  return { ref, files, scope: { mode: 'diff', files } };
+}
+
+/**
+ * Read + parse the prior baseline at `absBaselinePath` and return the
+ * canonical `rows[]` array (per-kind row shape with `path:` keys, as
+ * expected by the per-kind `mergeRows` / `applyEpsilon` helpers from
+ * Story #1974). Returns `null` when the file is absent, malformed, or
+ * missing a `rows[]` envelope; the caller treats `null` as "skip the
+ * merge" (regression-fail-safe — equivalent to a fresh write).
+ *
+ * Pure-by-design (file I/O through the injected `fsImpl` seam).
+ *
+ * @param {{ kind: 'maintainability' | 'crap', absBaselinePath: string, fsImpl?: typeof fs }} args
+ * @returns {Array<object> | null}
+ */
+// Read + JSON-parse a baseline file. Returns `null` on any I/O or parse
+// failure (the caller treats "no prior" the same as "unreadable prior").
+function readBaselineJson(absBaselinePath, fsImpl) {
+  let raw;
+  try {
+    raw = fsImpl.readFileSync(absBaselinePath, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// CRAP path: envelope `rows[]` only; rows already carry canonical `path:`.
+function readCrapPriorRows(parsed) {
+  if (!Array.isArray(parsed.rows)) return null;
+  return parsed.rows;
+}
+
+// Maintainability path: envelope `rows[]` only; rows already carry
+// canonical `path:` + `mi:`.
+function readMaintainabilityPriorRows(parsed) {
+  if (!Array.isArray(parsed.rows)) return null;
+  return parsed.rows.filter(
+    (r) => r && typeof r.path === 'string' && typeof r.mi === 'number',
+  );
+}
+
+export function readPriorBaselineRows({ kind, absBaselinePath, fsImpl = fs }) {
+  const parsed = readBaselineJson(absBaselinePath, fsImpl);
+  if (!parsed) return null;
+  if (kind === 'crap') return readCrapPriorRows(parsed);
+  return readMaintainabilityPriorRows(parsed);
+}
+
+/**
+ * Compose the full Story #1974 write-side payload for a manual baseline
+ * CLI: read prior rows, resolve `--diff-scope`, log the scope decision,
+ * and return the four params (`prior`, `epsilon`, `scope`, plus the
+ * resolved `diffScope` for caller-side logging) that the CLI feeds into
+ * `writer.write({ ..., prior, epsilon, scope })`.
+ *
+ * Returns a flat record so each CLI can spread it into the writer call.
+ *
+ * @param {{
+ *   kind: 'maintainability' | 'crap',
+ *   absBaselinePath: string,
+ *   epsilon: number,
+ *   argv?: string[],
+ *   cwd?: string,
+ *   logger?: { info?: (msg: string) => void },
+ *   logTag: string,
+ * }} args
+ * @returns {{
+ *   prior: Array<object> | undefined,
+ *   epsilon: number | undefined,
+ *   scope: {mode: 'diff', files: Set<string>} | undefined,
+ *   diffScope: {ref: string, files: Set<string>, scope: object} | null,
+ * }}
+ */
+export function buildWriterScopeArgs({
+  kind,
+  absBaselinePath,
+  epsilon,
+  argv = process.argv.slice(2),
+  cwd,
+  logger,
+  logTag,
+}) {
+  const prior = readPriorBaselineRows({ kind, absBaselinePath });
+  const diffScope = resolveDiffScope({ argv, cwd });
+  if (diffScope && logger?.info) {
+    logger.info(
+      `${logTag} --diff-scope ${diffScope.ref}: ${diffScope.files.size} file(s) in scope; out-of-scope rows preserved verbatim.`,
+    );
+  }
+  return {
+    prior: prior ?? undefined,
+    epsilon: prior ? epsilon : undefined,
+    scope: diffScope?.scope,
+    diffScope,
+  };
+}

package/.agents/scripts/lib/baselines/duplication-scanner.js

@@ -0,0 +1,220 @@
+/**
+ * duplication-scanner.js — code-duplication (DRY) scanner for the
+ * duplication baseline (Story #3664).
+ *
+ * Wraps the jscpd clone detector behind two pure-ish seams so the
+ * refresh script and its unit tests can exercise the parse→envelope path
+ * without spawning a real scan:
+ *
+ *   - `buildDuplicationRows(clones, fileLineCounts, cwd)` — PURE. Folds
+ *     jscpd's clone-pair output into per-file `{ path, duplicatedLines,
+ *     totalLines, percentage }` rows. Overlapping clones on the same file
+ *     are unioned (line-set), so a line duplicated by two different clones
+ *     counts once. Every file the scan visited gets a row — files with no
+ *     clones land at `duplicatedLines: 0` so the baseline records the full
+ *     denominator and a later regression on a previously-clean file is
+ *     visible.
+ *
+ *   - `scanDuplication({ targetDirs, cwd, minTokens, detect, readLineCount })`
+ *     — the I/O wrapper. Walks `targetDirs`, runs the injected `detect`
+ *     (jscpd's `detectClones` by default), reads per-file line counts, and
+ *     returns the projected rows. The `detect` and `readLineCount` seams
+ *     are injectable so tests run fully offline.
+ *
+ * Lower duplication is better — see `kinds/duplication.js` and the gate's
+ * `lte` floor direction in `check-baselines/phases/floors.js`.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_MIN_TOKENS = 50;
+const DEFAULT_FORMATS = Object.freeze(['javascript']);
+
+/**
+ * Normalise a jscpd `sourceId` (or any path) to a canonical POSIX
+ * repo-relative path. jscpd already emits cwd-relative paths, but a future
+ * jscpd bump (or an absolute `sourceId`) is defended against here.
+ *
+ * @param {string} sourceId
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function relativisePath(sourceId, cwd) {
+  if (typeof sourceId !== 'string' || sourceId.length === 0) return sourceId;
+  const rel = path.isAbsolute(sourceId)
+    ? path.relative(cwd, sourceId)
+    : sourceId;
+  return rel.split(path.sep).join('/');
+}
+
+/**
+ * Count the inclusive line span a clone covers: `end.line - start.line + 1`.
+ * jscpd reports 1-based line numbers; a single-line clone spans one line.
+ *
+ * @param {{ start?: { line?: number }, end?: { line?: number } }} dup
+ * @returns {Array<number>} the 1-based line numbers the clone covers
+ */
+function cloneLineNumbers(dup) {
+  const start = dup?.start?.line;
+  const end = dup?.end?.line;
+  if (!Number.isInteger(start) || !Number.isInteger(end)) return [];
+  const lo = Math.min(start, end);
+  const hi = Math.max(start, end);
+  const lines = [];
+  for (let n = lo; n <= hi; n += 1) lines.push(n);
+  return lines;
+}
+
+/**
+ * PURE: fold jscpd clone pairs + per-file line counts into canonical
+ * duplication rows. Both sides of every clone pair (`duplicationA` and
+ * `duplicationB`) contribute their covered lines to their respective
+ * file's duplicated-line set, so a file that is only ever the "B" side of
+ * a clone still accrues duplication.
+ *
+ * @param {Array<{duplicationA?: object, duplicationB?: object}>} clones
+ * @param {Map<string, number>|Record<string, number>} fileLineCounts
+ *   per-file total line counts keyed by canonical POSIX repo-relative path
+ * @param {string} [cwd] used to relativise absolute sourceIds
+ * @returns {Array<{path: string, duplicatedLines: number, totalLines: number, percentage: number}>}
+ */
+export function buildDuplicationRows(
+  clones,
+  fileLineCounts,
+  cwd = process.cwd(),
+) {
+  const counts = toLineCountMap(fileLineCounts);
+  const dupLinesByFile = new Map();
+  // Seed every visited file with an empty set so clean files get a 0-row.
+  for (const file of counts.keys()) {
+    dupLinesByFile.set(file, new Set());
+  }
+  for (const clone of clones ?? []) {
+    for (const side of [clone?.duplicationA, clone?.duplicationB]) {
+      if (!side) continue;
+      const file = relativisePath(side.sourceId, cwd);
+      if (!file) continue;
+      const set = dupLinesByFile.get(file) ?? new Set();
+      for (const line of cloneLineNumbers(side)) set.add(line);
+      dupLinesByFile.set(file, set);
+    }
+  }
+  const rows = [];
+  for (const [file, lineSet] of dupLinesByFile) {
+    const totalLines = counts.get(file) ?? 0;
+    const duplicatedLines = lineSet.size;
+    const percentage =
+      totalLines > 0 ? (duplicatedLines / totalLines) * 100 : 0;
+    rows.push({
+      path: file,
+      duplicatedLines,
+      totalLines,
+      percentage: Number(percentage.toFixed(2)),
+    });
+  }
+  return rows;
+}
+
+function toLineCountMap(fileLineCounts) {
+  if (fileLineCounts instanceof Map) return fileLineCounts;
+  const map = new Map();
+  if (fileLineCounts && typeof fileLineCounts === 'object') {
+    for (const [k, v] of Object.entries(fileLineCounts)) {
+      map.set(k, Number(v) || 0);
+    }
+  }
+  return map;
+}
+
+/**
+ * Default per-file line counter — reads the file off disk and counts
+ * newline-delimited lines. Injectable via `scanDuplication`'s
+ * `readLineCount` seam so tests never touch the filesystem.
+ *
+ * @param {string} absPath
+ * @returns {number}
+ */
+export function readLineCount(absPath) {
+  const text = readFileSync(absPath, 'utf8');
+  if (text.length === 0) return 0;
+  const lines = text.split(/\r\n|\r|\n/);
+  // A trailing newline produces a final empty element — drop it so the
+  // count matches the editor's line count.
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  return lines.length;
+}
+
+/**
+ * Run a duplication scan over `targetDirs` and return canonical rows.
+ *
+ * @param {{
+ *   targetDirs: string[],
+ *   cwd?: string,
+ *   minTokens?: number,
+ *   formats?: string[],
+ *   ignoreGlobs?: string[],
+ *   detect: (opts: object) => Promise<Array<object>>,
+ *   readLineCount?: (absPath: string) => number,
+ * }} params
+ * @returns {Promise<Array<{path: string, duplicatedLines: number, totalLines: number, percentage: number}>>}
+ */
+export async function scanDuplication({
+  targetDirs,
+  cwd = process.cwd(),
+  minTokens = DEFAULT_MIN_TOKENS,
+  formats = DEFAULT_FORMATS,
+  ignoreGlobs = [],
+  detect,
+  readLineCount: readLineCountFn = readLineCount,
+}) {
+  if (typeof detect !== 'function') {
+    throw new TypeError('scanDuplication: detect must be a function');
+  }
+  const dirs = Array.isArray(targetDirs) ? targetDirs : [];
+  const clones = await detect({
+    path: dirs,
+    cwd,
+    silent: true,
+    gitignore: false,
+    reporters: [],
+    format: formats,
+    minTokens,
+    ignore: Array.isArray(ignoreGlobs) ? ignoreGlobs : [],
+  });
+  const visited = collectVisitedFiles(clones, cwd);
+  const fileLineCounts = new Map();
+  for (const rel of visited) {
+    const abs = path.isAbsolute(rel) ? rel : path.resolve(cwd, rel);
+    try {
+      fileLineCounts.set(rel, readLineCountFn(abs));
+    } catch {
+      // Unreadable file — record 0 so it never poisons the denominator.
+      fileLineCounts.set(rel, 0);
+    }
+  }
+  return buildDuplicationRows(clones, fileLineCounts, cwd);
+}
+
+/**
+ * Collect the set of files that appear on either side of any clone pair.
+ * jscpd's `detectClones` only reports files that participate in at least
+ * one clone, so the scanned-but-clean files are not enumerable from the
+ * clone list alone — the baseline therefore records exactly the files
+ * with detected duplication. Pure helper, exported for tests.
+ *
+ * @param {Array<object>} clones
+ * @param {string} cwd
+ * @returns {string[]} canonical POSIX repo-relative paths, deduped + sorted
+ */
+export function collectVisitedFiles(clones, cwd = process.cwd()) {
+  const set = new Set();
+  for (const clone of clones ?? []) {
+    for (const side of [clone?.duplicationA, clone?.duplicationB]) {
+      if (!side) continue;
+      const file = relativisePath(side.sourceId, cwd);
+      if (file) set.add(file);
+    }
+  }
+  return [...set].sort();
+}