mandrel 1.57.0

package/.agents/scripts/lib/orchestration/cascade-grouping.js

@@ -0,0 +1,275 @@
+/**
+ * lib/orchestration/cascade-grouping.js — Cascade dispatch helpers.
+ *
+ * Pure helpers used by `cascadeCompletion` (see `./ticketing.js`) to
+ * partition a list of parent tickets into disjoint shared-ancestor groups
+ * and to buffer per-parent log output so parallel dispatch produces a
+ * byte-identical log stream to the serial baseline.
+ *
+ * Pulled out of `ticketing.js` so the cascade orchestrator stays under the
+ * project's per-file maintainability ceiling. No state is held at module
+ * scope — every helper takes its dependencies as arguments.
+ */
+
+/**
+ * Walks `parent: #N` references upward from the given ticket id until no new
+ * ancestors are discovered. Returns the set of every ticket id reachable
+ * along the chain, including the starting id. Cycle-safe by construction —
+ * the visited set acts as the seen guard, so a cyclic `parent: #N` graph
+ * terminates in finite steps without revisiting nodes.
+ *
+ * Pure of side effects beyond the provider reads it issues. Provider
+ * failures on a single hop fall back to "no further ancestors discovered"
+ * for that branch (the chain truncates rather than throwing); this matches
+ * `cascadeCompletion`'s tolerant posture toward transient reads.
+ *
+ * @param {import('../ITicketingProvider.js').ITicketingProvider} provider
+ * @param {number} startId
+ * @param {Map<number, Set<number>>} [cache] - Optional per-call cache of
+ *   already-walked chains keyed by intermediate id. Reused across parents
+ *   in {@link groupByAncestor} to amortise repeat walks.
+ * @returns {Promise<Set<number>>} ancestor set including `startId`.
+ */
+export async function walkAncestorChain(provider, startId, cache) {
+  // Inner DFS with memoisation. `inProgress` guards cycles so a cyclic
+  // `parent: #N` graph terminates without recursion depth issues. Each
+  // visited node gets its own cache entry holding the set of ids reachable
+  // from it (inclusive), so a sibling walk that re-enters this subgraph
+  // can splice the cached set wholesale instead of re-reading the provider.
+  async function visit(id, inProgress) {
+    if (cache?.has(id)) return cache.get(id);
+    if (inProgress.has(id)) {
+      // Cycle: return a singleton so the caller still includes `id` in its
+      // ancestor set without recursing further through this loop. Do NOT
+      // memoise — the partial result is incomplete for `id`'s true chain.
+      return new Set([id]);
+    }
+    inProgress.add(id);
+
+    const set = new Set([id]);
+    let ticket = null;
+    try {
+      ticket = await provider.getTicket(id);
+    } catch {
+      // Provider read failure: truncate the chain branch. Memoise as the
+      // singleton so subsequent walks don't retry an already-failed read.
+      inProgress.delete(id);
+      cache?.set(id, set);
+      return set;
+    }
+
+    if (ticket?.body) {
+      const matches = [...ticket.body.matchAll(/parent:\s*#(\d+)/gi)];
+      for (const m of matches) {
+        const next = Number.parseInt(m[1], 10);
+        if (!Number.isFinite(next)) continue;
+        const subset = await visit(next, inProgress);
+        for (const v of subset) set.add(v);
+      }
+    }
+
+    inProgress.delete(id);
+    cache?.set(id, set);
+    return set;
+  }
+
+  return visit(startId, new Set());
+}
+
+/**
+ * Partitions a list of parent ids into disjoint groups whose members share
+ * at least one ancestor (transitively, via `parent: #N` references walked
+ * to fixpoint).
+ *
+ * Two parents end up in the same group if and only if their ancestor sets
+ * overlap on at least one ticket id. Parents with no shared ancestors end
+ * up in singleton groups. The union of the returned groups equals the
+ * input set; the order of `parents[]` is preserved within each group, and
+ * groups are returned in the order their first member appears in the
+ * input.
+ *
+ * Pure of side effects beyond the provider reads needed to walk chains.
+ * Walked ancestor sets are cached per call so a parent that contributes
+ * to multiple groups is not re-walked. Cycle-safe — see
+ * {@link walkAncestorChain}.
+ *
+ * Used by `cascadeCompletion` to dispatch disjoint groups in parallel
+ * while keeping shared-ancestor groups strictly sequential (concurrent
+ * transitions on the same ancestor would race the "all children done?"
+ * check).
+ *
+ * @param {Array<number>} parents
+ * @param {import('../ITicketingProvider.js').ITicketingProvider} provider
+ * @returns {Promise<Array<Array<number>>>} disjoint groups of parent ids.
+ */
+export async function groupByAncestor(parents, provider) {
+  if (!Array.isArray(parents) || parents.length === 0) return [];
+
+  // Walk each parent's ancestor chain once, sharing a cache so a parent
+  // that re-enters an already-walked subgraph reuses the cached set.
+  const cache = new Map();
+  const ancestorsByParent = new Map();
+  for (const parentId of parents) {
+    const chain = await walkAncestorChain(provider, parentId, cache);
+    ancestorsByParent.set(parentId, chain);
+  }
+
+  return unionFindByAncestor(parents, ancestorsByParent);
+}
+
+/**
+ * Union-Find over `parents`, joined whenever any two parents' ancestor
+ * chains overlap on at least one id. Returns the parents bucketed by
+ * representative, in input order both for the groups themselves and for
+ * members within each group.
+ *
+ * Pulled out of {@link groupByAncestor} to keep that function's CRAP
+ * under the v6 ceiling.
+ *
+ * @param {Array<number>} parents
+ * @param {Map<number, Set<number>>} ancestorsByParent
+ * @returns {Array<Array<number>>}
+ */
+function unionFindByAncestor(parents, ancestorsByParent) {
+  const parentIndex = new Map();
+  parents.forEach((p, i) => {
+    parentIndex.set(p, i);
+  });
+  const uf = parents.map((_, i) => i);
+  const find = (i) => {
+    while (uf[i] !== i) {
+      uf[i] = uf[uf[i]];
+      i = uf[i];
+    }
+    return i;
+  };
+  const union = (a, b) => {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra !== rb) uf[ra] = rb;
+  };
+
+  // For each ancestor id, collect parents whose chain hits it; union them.
+  const ancestorToParents = new Map();
+  for (const [parentId, chain] of ancestorsByParent) {
+    for (const ancestorId of chain) {
+      if (!ancestorToParents.has(ancestorId)) {
+        ancestorToParents.set(ancestorId, []);
+      }
+      ancestorToParents.get(ancestorId).push(parentId);
+    }
+  }
+  for (const sharing of ancestorToParents.values()) {
+    if (sharing.length < 2) continue;
+    const first = parentIndex.get(sharing[0]);
+    for (let i = 1; i < sharing.length; i++) {
+      union(first, parentIndex.get(sharing[i]));
+    }
+  }
+
+  // Bucket parents by representative, preserving first-seen order for
+  // both groups and within-group ordering.
+  const repToGroup = new Map();
+  const groupOrder = [];
+  for (const parentId of parents) {
+    const rep = find(parentIndex.get(parentId));
+    if (!repToGroup.has(rep)) {
+      repToGroup.set(rep, []);
+      groupOrder.push(rep);
+    }
+    repToGroup.get(rep).push(parentId);
+  }
+
+  return groupOrder.map((rep) => repToGroup.get(rep));
+}
+
+/**
+ * Dispatches cascade work across disjoint shared-ancestor groups in
+ * parallel while running each within-group parent sequentially in input
+ * order. Per-parent output is captured into a buffered logger so the
+ * visible log stream is byte-identical to a serial baseline; the buffer
+ * is flushed to `flushLogger` in the original `parsedParents` order
+ * after every group resolves.
+ *
+ * The actual per-parent work is supplied by `processParent` so this
+ * helper stays free of cascade-specific dependencies — its only job is
+ * the parallel-dispatch + ordered-flush scaffolding.
+ *
+ * @template R
+ * @param {Object} args
+ * @param {Array<number>} args.parsedParents - Parent ids in their
+ *   original input order. Drives both the group-membership lookup and
+ *   the post-dispatch log flush order.
+ * @param {Array<Array<number>>} args.groups - Disjoint groups returned
+ *   by {@link groupByAncestor}.
+ * @param {(parentId: number, bufferedLogger: object) => Promise<R>} args.processParent
+ *   Per-parent worker. Receives the parent id and a buffered logger.
+ *   Its resolved value is collected into `args.parsedParents`-ordered
+ *   results.
+ * @param {{ debug: Function, info: Function, warn: Function, error: Function }} args.flushLogger
+ *   Real logger that receives the buffered output after dispatch.
+ * @returns {Promise<Array<R>>} per-parent results in `parsedParents`
+ *   order.
+ */
+export async function dispatchCascadeGroups({
+  parsedParents,
+  groups,
+  processParent,
+  flushLogger,
+}) {
+  const parentLoggers = new Map();
+  const parentResults = new Map();
+  for (const parentId of parsedParents) {
+    parentLoggers.set(parentId, createBufferedLogger());
+  }
+
+  await Promise.all(
+    groups.map(async (group) => {
+      for (const parentId of group) {
+        const logger = parentLoggers.get(parentId);
+        const result = await processParent(parentId, logger);
+        parentResults.set(parentId, result);
+      }
+    }),
+  );
+
+  const results = [];
+  for (const parentId of parsedParents) {
+    const lg = parentLoggers.get(parentId);
+    if (lg) {
+      for (const entry of lg.buffer) {
+        flushLogger[entry.level](entry.message);
+      }
+    }
+    const result = parentResults.get(parentId);
+    if (result !== undefined) results.push(result);
+  }
+  return results;
+}
+
+/**
+ * Buffered logger shaped like the public `Logger` surface. Stores every
+ * emitted line in `buffer[]` instead of writing to the console. Callers
+ * flush the buffer to a real logger after the buffered region completes
+ * so the visible log output is byte-identical to a serial run.
+ *
+ * @returns {{ buffer: Array<{ level: 'debug'|'info'|'warn'|'error', message: string }>, debug: Function, info: Function, warn: Function, error: Function }}
+ */
+export function createBufferedLogger() {
+  const buffer = [];
+  return {
+    buffer,
+    debug(message) {
+      buffer.push({ level: 'debug', message });
+    },
+    info(message) {
+      buffer.push({ level: 'info', message });
+    },
+    warn(message) {
+      buffer.push({ level: 'warn', message });
+    },
+    error(message) {
+      buffer.push({ level: 'error', message });
+    },
+  };
+}

package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js

@@ -0,0 +1,131 @@
+/**
+ * compare.js — Phase 3 of the check-baselines pipeline (Story #2466).
+ *
+ * Owns the head-vs-base compare stage: scope resolution, base-baseline
+ * read, per-kind classifier dispatch, and tolerance application.
+ *
+ * Extracted from `check-baselines.js` without behavior change.
+ *
+ * @module lib/orchestration/check-baselines/phases/compare
+ */
+
+import { readBaseFromGit } from '../../../baselines/git-base.js';
+import { getKindModule } from '../../../baselines/kernel.js';
+import { resolveScope } from '../../../baselines/scope.js';
+import { DEFAULT_BASELINE_PATHS } from './parse-args.js';
+
+function baselineRelativePath(kind, gateBlock) {
+  const configured =
+    typeof gateBlock?.baselinePath === 'string' &&
+    gateBlock.baselinePath.length > 0
+      ? gateBlock.baselinePath
+      : null;
+  return configured ?? DEFAULT_BASELINE_PATHS[kind];
+}
+
+export function resolveDispatchScope({ kind, quality, env }) {
+  const cfg = quality?.gateScoping ?? {};
+  return resolveScope({
+    kind,
+    configScope: cfg.scope,
+    configRef: cfg.diffRef,
+    cliFlags: {
+      envScope: env?.BASELINE_SCOPE,
+      envRef: env?.BASELINE_REF,
+    },
+  });
+}
+
+function emptyCompareResult(baseRef) {
+  return { baseRef, baseRead: false };
+}
+
+function readBaseBaselinePayload(scope, kind, gateBlock, cwd) {
+  const rel = baselineRelativePath(kind, gateBlock);
+  let raw;
+  try {
+    raw = readBaseFromGit(scope.ref, rel, { cwd });
+  } catch {
+    return null;
+  }
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export async function evaluateCompare({ kind, gateBlock, scope, cwd }) {
+  if (scope.mode !== 'diff' || !scope.ref) return emptyCompareResult(null);
+  const basePayload = readBaseBaselinePayload(scope, kind, gateBlock, cwd);
+  if (!basePayload) return emptyCompareResult(scope.ref);
+  const kindModule = getKindModule(kind);
+  if (typeof kindModule.compare !== 'function') {
+    return emptyCompareResult(scope.ref);
+  }
+  return { baseRef: scope.ref, baseRead: true, basePayload, kindModule };
+}
+
+export function runCompareStage(headBaseline, cmp) {
+  const empty = {
+    regressions: [],
+    improvements: [],
+    unchanged: [],
+    additions: [],
+  };
+  if (!cmp.baseRead || !cmp.basePayload || !cmp.kindModule) return empty;
+  try {
+    const baseRows = Array.isArray(cmp.basePayload.rows)
+      ? cmp.basePayload.rows
+      : [];
+    const result = cmp.kindModule.compare(
+      { rows: headBaseline.rows },
+      { rows: baseRows },
+    );
+    return {
+      regressions: result?.regressions ?? [],
+      improvements: result?.improvements ?? [],
+      unchanged: result?.unchanged ?? [],
+      additions: result?.additions ?? [],
+    };
+  } catch {
+    return empty;
+  }
+}
+
+function tolerantNumericFields(head, base) {
+  if (!head || !base) return [];
+  return Object.entries(head)
+    .filter(
+      ([key, h]) => typeof h === 'number' && typeof base[key] === 'number',
+    )
+    .map(([key, h]) => ({ key, head: h, base: base[key] }));
+}
+
+function regressionExceedsTolerance(reg, threshold) {
+  const fields = tolerantNumericFields(reg.head, reg.base);
+  if (fields.length === 0) return true;
+  return fields.some(({ head, base }) => Math.abs(head - base) >= threshold);
+}
+
+/**
+ * Apply per-gate tolerance to raw compare output. `{ kind: 'absolute',
+ * value: N }` demotes near-floor regressions to `unchanged`.
+ */
+export function applyTolerance(compareOutput, tolerance) {
+  if (!tolerance || tolerance.kind !== 'absolute') return compareOutput;
+  const threshold = Number(tolerance.value);
+  if (!Number.isFinite(threshold) || threshold <= 0) return compareOutput;
+  const kept = [];
+  const demoted = [];
+  for (const reg of compareOutput.regressions) {
+    if (regressionExceedsTolerance(reg, threshold)) kept.push(reg);
+    else demoted.push(reg);
+  }
+  return {
+    ...compareOutput,
+    regressions: kept,
+    unchanged: [...compareOutput.unchanged, ...demoted],
+  };
+}

package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js

@@ -0,0 +1,80 @@
+/**
+ * evaluate.js — Phase 4 of the check-baselines pipeline (Story #2466).
+ *
+ * Runs the per-kind pipeline: load → floor → compare → tolerance → report.
+ * Extracted from `check-baselines.js` without behavior change.
+ *
+ * @module lib/orchestration/check-baselines/phases/evaluate
+ */
+
+import { checkKernelVersion } from '../../../baselines/kernel.js';
+import * as reader from '../../../baselines/reader.js';
+import { applyTolerance, evaluateCompare, runCompareStage } from './compare.js';
+import { applyFloors, flattenBreaches } from './floors.js';
+
+function loadHeadBaseline(kind, cwd, configPath) {
+  try {
+    return { baseline: reader.load(kind, { cwd, configPath }) };
+  } catch (err) {
+    const message = err?.message ?? String(err);
+    const tag = /schema validation failed/i.test(message) ? 'schema' : 'read';
+    return { schemaError: { tag, message } };
+  }
+}
+
+function buildGateReport({
+  kind,
+  gateBlock,
+  baseline,
+  findings,
+  breaches,
+  compareOutput,
+  cmp,
+}) {
+  const kernel = checkKernelVersion(kind, baseline.kernelVersion);
+  return {
+    kind,
+    enabled: true,
+    kernelMatch: kernel.match,
+    kernelCurrent: kernel.current,
+    kernelBaseline: baseline.kernelVersion,
+    tolerance: gateBlock.tolerance ?? null,
+    floors: gateBlock.floors ?? {},
+    components: findings,
+    breachCount: breaches.length,
+    breaches,
+    regressions: compareOutput.regressions,
+    improvements: compareOutput.improvements,
+    unchanged: compareOutput.unchanged,
+    additions: compareOutput.additions ?? [],
+    regressionCount: compareOutput.regressions.length,
+    baseRef: cmp.baseRef ?? null,
+    generatedAt: baseline.generatedAt,
+  };
+}
+
+export async function evaluateKind({
+  kind,
+  gateBlock,
+  scope,
+  cwd,
+  configPath,
+}) {
+  const headLoad = loadHeadBaseline(kind, cwd, configPath);
+  if (headLoad.schemaError) return { kind, schemaError: headLoad.schemaError };
+  const baseline = headLoad.baseline;
+  const findings = applyFloors(kind, baseline.rollup, gateBlock.floors ?? {});
+  const breaches = flattenBreaches(findings);
+  const cmp = await evaluateCompare({ kind, gateBlock, scope, cwd });
+  const rawCompare = runCompareStage(baseline, cmp);
+  const compareOutput = applyTolerance(rawCompare, gateBlock.tolerance ?? null);
+  return buildGateReport({
+    kind,
+    gateBlock,
+    baseline,
+    findings,
+    breaches,
+    compareOutput,
+    cmp,
+  });
+}

package/.agents/scripts/lib/orchestration/check-baselines/phases/floors.js

@@ -0,0 +1,132 @@
+/**
+ * floors.js — Phase 2 of the check-baselines pipeline (Story #2466).
+ *
+ * Pure floor-comparison helpers. Extracted verbatim from `check-baselines.js`
+ * so `compareToFloor`, `assertFloorAxesExist`, and `applyFloors` keep their
+ * named-export contracts for the existing unit tests.
+ *
+ * @module lib/orchestration/check-baselines/phases/floors
+ */
+
+import { EXIT_CONFIG } from '../../../baselines/exit-codes.js';
+
+function axisDirection(kind, axis) {
+  if (kind === 'lint') return 'lte';
+  if (kind === 'crap') return 'lte';
+  if (kind === 'bundle-size') return 'lte';
+  if (kind === 'duplication') return 'lte';
+  if (kind === 'mutation') {
+    if (axis === 'survived' || axis === 'noCoverage') return 'lte';
+    return 'gte';
+  }
+  return 'gte';
+}
+
+/**
+ * Compare a single rollup component against a single floor object. Returns
+ * the array of axis violations (empty when every axis meets its floor).
+ */
+export function compareToFloor(kind, aggregate, floor) {
+  const out = [];
+  if (!floor || typeof floor !== 'object') return out;
+  for (const axis of Object.keys(floor)) {
+    const target = floor[axis];
+    if (typeof target !== 'number' || !Number.isFinite(target)) continue;
+    const value = aggregate?.[axis];
+    if (typeof value !== 'number' || !Number.isFinite(value)) continue;
+    const direction = axisDirection(kind, axis);
+    const pass = direction === 'gte' ? value >= target : value <= target;
+    if (!pass) out.push({ axis, value, floor: target, direction });
+  }
+  return out;
+}
+
+/**
+ * Tiny helper to suggest the closest available axis when an operator
+ * misnamed a floor axis. Substring containment is enough.
+ */
+function suggestAxis(unknownAxis, availableKeys) {
+  if (availableKeys.length === 0) return null;
+  const target = unknownAxis.toLowerCase();
+  for (const k of availableKeys) {
+    const candidate = k.toLowerCase();
+    if (target.includes(candidate) || candidate.includes(target)) return k;
+  }
+  return availableKeys[0];
+}
+
+function buildAxisMismatchError({ kind, component, axis, availableKeys }) {
+  const availableList = availableKeys.map((k) => `'${k}'`).join(', ');
+  const suggestion = suggestAxis(axis, availableKeys);
+  const hint = suggestion ? ` (did you mean '${suggestion}'?)` : '';
+  const err = new Error(
+    `[check-baselines:${kind}] configured floor '${axis}' not found in ` +
+      `rollup['${component}']; available keys: ${availableList || '<none>'}` +
+      hint,
+  );
+  err.code = 'EXIT_CONFIG';
+  err.exitCode = EXIT_CONFIG;
+  err.kind = kind;
+  err.component = component;
+  err.axis = axis;
+  err.availableKeys = availableKeys;
+  return err;
+}
+
+/**
+ * Story #2193 / AC-6: fail closed when a configured floor axis is not
+ * present in the rollup. See the original module docstring for the full
+ * rationale (typo in `.agentrc.json` → exit code 3 instead of silent pass).
+ */
+export function assertFloorAxesExist(kind, component, aggregate, floor) {
+  if (!floor || typeof floor !== 'object') return;
+  if (!aggregate || typeof aggregate !== 'object') return;
+  const availableKeys = Object.keys(aggregate).sort();
+  const availableSet = new Set(availableKeys);
+  for (const axis of Object.keys(floor)) {
+    const target = floor[axis];
+    if (typeof target !== 'number' || !Number.isFinite(target)) continue;
+    if (availableSet.has(axis)) continue;
+    throw buildAxisMismatchError({ kind, component, axis, availableKeys });
+  }
+}
+
+function collectComponentNames(rollup, floors) {
+  return new Set([
+    '*',
+    ...Object.keys(floors ?? {}),
+    ...Object.keys(rollup ?? {}),
+  ]);
+}
+
+function evaluateComponentFloor(kind, component, rollup, floors) {
+  const aggregate = rollup?.[component];
+  if (!aggregate || typeof aggregate !== 'object') return null;
+  const floor = floors?.[component] ?? floors?.['*'];
+  assertFloorAxesExist(kind, component, aggregate, floor);
+  const violations = compareToFloor(kind, aggregate, floor);
+  return { component, violations };
+}
+
+/**
+ * Apply the floor policy across every component in a rollup. Pure.
+ */
+export function applyFloors(kind, rollup, floors) {
+  const out = [];
+  for (const component of collectComponentNames(rollup, floors)) {
+    const finding = evaluateComponentFloor(kind, component, rollup, floors);
+    if (finding) out.push(finding);
+  }
+  out.sort((a, b) => {
+    if (a.component === '*') return -1;
+    if (b.component === '*') return 1;
+    return a.component.localeCompare(b.component);
+  });
+  return out;
+}
+
+export function flattenBreaches(findings) {
+  return findings.flatMap((f) =>
+    f.violations.map((v) => ({ ...v, component: f.component })),
+  );
+}