mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/test-isolate/run-isolate.js

@@ -1,87 +0,0 @@
-/**
- * lib/test-isolate/run-isolate.js — the `test-isolate` orchestration.
- *
- * Story #5316: moved out of `.agents/scripts/test-isolate.js` (CRAP 56 at
- * cyclomatic 7, 0% coverage) so it can be driven from a test. The CLI shell
- * that remains does nothing but call this and translate the exit code.
- *
- * `resolveFiles` and `diagnose` are named seams defaulting to the real
- * implementations, per [`rules/test-seams.md`](../../../rules/test-seams.md):
- * a unit test substitutes them rather than running real suites in child
- * processes, and the production caller passes neither.
- */
-
-import { parseIsolateArgv } from './cli-options.js';
-import { resolveTestFiles as defaultResolveTestFiles } from './list-files.js';
-import { createProgressLogger } from './progress-log.js';
-import { renderReport } from './render-report.js';
-import { diagnoseIsolation as defaultDiagnoseIsolation } from './runner.js';
-
-/**
- * The report shape returned when no file matched the pattern — a real report
- * with nothing in it, so callers never branch on null.
- *
- * @returns {import('./runner.js').IsolateReport}
- */
-function emptyReport() {
-  return {
-    pattern: null,
-    files: [],
-    isolated: [],
-    suite: [],
-    flippers: [],
-    bisections: [],
-    envMutators: [],
-    durationMs: 0,
-  };
-}
-
-/**
- * Run the isolation diagnosis end to end.
- *
- * Exit code is 1 when the run found anything worth an operator's attention —
- * a flipper OR an env mutator — and 0 otherwise. An empty match set is not a
- * failure: nothing was asked of the suite, so nothing can be wrong with it.
- *
- * @param {object} [opts]
- * @param {string[]} [opts.argv]
- * @param {string} [opts.repoRoot]
- * @param {(line: string) => void} [opts.onLog]
- * @param {(args: {pattern: string|undefined, repoRoot: string}) => string[]} [opts.resolveFiles]
- * @param {(args: object) => Promise<import('./runner.js').IsolateReport>} [opts.diagnose]
- * @returns {Promise<{ exitCode: number, report: import('./runner.js').IsolateReport }>}
- */
-export async function runTestIsolate({
-  argv = [],
-  repoRoot,
-  onLog = (s) => process.stdout.write(`${s}\n`),
-  resolveFiles = defaultResolveTestFiles,
-  diagnose = defaultDiagnoseIsolation,
-} = {}) {
-  const options = parseIsolateArgv(argv);
-  const files = resolveFiles({ pattern: options.pattern, repoRoot });
-  if (files.length === 0) {
-    onLog(
-      `[test-isolate] no test files matched pattern: ${options.pattern ?? '<default>'}`,
-    );
-    return { exitCode: 0, report: emptyReport() };
-  }
-
-  if (!options.quiet) {
-    onLog(`[test-isolate] scanning ${files.length} file(s)...`);
-  }
-  const report = await diagnose({
-    repoRoot,
-    files,
-    workers: options.workers,
-    suiteConcurrency: options.suiteConcurrency,
-    maxBisectDepth: options.maxBisectDepth,
-    maxBisectTargets: options.maxBisectTargets,
-    onProgress: options.quiet ? undefined : createProgressLogger(onLog),
-  });
-
-  onLog(options.json ? JSON.stringify(report, null, 2) : renderReport(report));
-
-  const clean = report.flippers.length === 0 && report.envMutators.length === 0;
-  return { exitCode: clean ? 0 : 1, report };
-}

package/.agents/scripts/lib/test-isolate/runner.js

@@ -1,483 +0,0 @@
-import { spawn } from 'node:child_process';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { parseSingleFileTap, parseSuiteTap } from './parse-tap.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const ENV_LOADER = path.resolve(__dirname, 'env-snapshot-loader.js');
-
-const NODE_TEST_BASE = [
-  '--experimental-test-module-mocks',
-  '--test',
-  '--test-reporter=tap',
-];
-
-/**
- * @typedef {{ added: string[], removed: string[], changed: string[] }} EnvDiff
- *
- * @typedef {{
- *   file: string,
- *   status: 'pass' | 'fail',
- *   failingTests: string[],
- *   envDiff: EnvDiff | null,
- *   durationMs: number,
- * }} IsolatedResult
- *
- * @typedef {{
- *   file: string,
- *   status: 'pass' | 'fail' | 'missing',
- *   failingTests: string[],
- * }} SuiteResult
- *
- * @typedef {{
- *   file: string,
- *   suspects: string[],
- *   inconclusive: boolean,
- * }} BisectionResult
- *
- * @typedef {{
- *   pattern: string,
- *   files: string[],
- *   isolated: IsolatedResult[],
- *   suite: SuiteResult[],
- *   flippers: string[],
- *   bisections: BisectionResult[],
- *   envMutators: { file: string, envDiff: EnvDiff }[],
- *   durationMs: number,
- * }} IsolateReport
- */
-
-/**
- * @param {object} opts
- * @param {string} opts.repoRoot
- * @param {string} opts.file
- * @param {string} [opts.envOutDir]  Directory for env-diff output files.
- * @param {number} [opts.timeoutMs]
- * @param {typeof spawn} [opts.spawnFn]
- * @returns {Promise<IsolatedResult>}
- */
-function runFileIsolated({
-  repoRoot,
-  file,
-  envOutDir,
-  timeoutMs = 120_000,
-  spawnFn = spawn,
-}) {
-  return new Promise((resolve) => {
-    const started = Date.now();
-    const envOutPath = envOutDir
-      ? path.join(envOutDir, `${file.replace(/[\\/]/g, '__')}.env-diff`)
-      : null;
-    if (envOutPath) {
-      cleanupEnvSidecars(envOutPath);
-    }
-    const args = [...NODE_TEST_BASE, '--test-concurrency=1', file];
-    const nodeOptions = envOutPath
-      ? `--import ${pathToFileUrl(ENV_LOADER)}`
-      : '';
-    const child = spawnFn(process.execPath, args, {
-      cwd: repoRoot,
-      env: {
-        ...sanitizeEnv(process.env),
-        NODE_OPTIONS: nodeOptions,
-        TEST_ISOLATE_ENV_OUT: envOutPath ?? '',
-        FORCE_COLOR: '0',
-        NO_COLOR: '1',
-        SKIP_PREFLIGHT: '1',
-      },
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (d) => {
-      stdout += d.toString('utf8');
-    });
-    child.stderr.on('data', (d) => {
-      stderr += d.toString('utf8');
-    });
-    const timer = setTimeout(() => {
-      child.kill('SIGKILL');
-    }, timeoutMs);
-    child.on('close', (code) => {
-      clearTimeout(timer);
-      const parsed = parseSingleFileTap(stdout + stderr, code ?? 1);
-      const envDiff = readEnvDiff(envOutPath);
-      resolve({
-        file,
-        status: parsed.status,
-        failingTests: parsed.failingTests,
-        envDiff,
-        durationMs: Date.now() - started,
-      });
-    });
-  });
-}
-
-function readEnvDiff(envOutPath) {
-  if (!envOutPath) return null;
-  const dir = path.dirname(envOutPath);
-  const base = path.basename(envOutPath);
-  let merged = null;
-  try {
-    if (!fs.existsSync(dir)) return null;
-    for (const entry of fs.readdirSync(dir)) {
-      if (!entry.startsWith(`${base}.`) || !entry.endsWith('.json')) continue;
-      try {
-        /** @type {EnvDiff} */
-        const parsed = JSON.parse(
-          fs.readFileSync(path.join(dir, entry), 'utf8'),
-        );
-        merged = mergeEnvDiffs(merged, parsed);
-      } catch {
-        // skip unreadable sidecar
-      }
-    }
-  } catch {
-    return null;
-  }
-  return merged;
-}
-
-function mergeEnvDiffs(a, b) {
-  if (!a) return b;
-  const dedupe = (arr) => Array.from(new Set(arr));
-  return {
-    added: dedupe([...(a.added ?? []), ...(b.added ?? [])]),
-    removed: dedupe([...(a.removed ?? []), ...(b.removed ?? [])]),
-    changed: dedupe([...(a.changed ?? []), ...(b.changed ?? [])]),
-  };
-}
-
-function cleanupEnvSidecars(envOutPath) {
-  const dir = path.dirname(envOutPath);
-  const base = path.basename(envOutPath);
-  if (!fs.existsSync(dir)) return;
-  for (const entry of fs.readdirSync(dir)) {
-    if (entry.startsWith(`${base}.`) && entry.endsWith('.json')) {
-      try {
-        fs.rmSync(path.join(dir, entry), { force: true });
-      } catch {
-        // ignore
-      }
-    }
-  }
-}
-
-function pathToFileUrl(p) {
-  return pathToFileURL(p).href;
-}
-
-/**
- * Strip env vars that signal "I am a node:test worker" so spawned child
- * `node --test` processes don't refuse to run with "node:test run() is
- * being called recursively". This lets `test-isolate` itself be exercised
- * from inside the project's own test suite.
- */
-function sanitizeEnv(source) {
-  const out = { ...source };
-  for (const key of Object.keys(out)) {
-    if (key.startsWith('NODE_TEST_CONTEXT')) delete out[key];
-  }
-  delete out.NODE_TEST_CONTEXT;
-  return out;
-}
-
-/**
- * Run a list of test files inside a single `node --test` invocation at the
- * given concurrency. Returns per-file pass/fail parsed from TAP.
- *
- * @param {object} opts
- * @param {string} opts.repoRoot
- * @param {string[]} opts.files
- * @param {number} [opts.concurrency]
- * @param {number} [opts.timeoutMs]
- * @param {typeof spawn} [opts.spawnFn]
- * @returns {Promise<{ results: SuiteResult[], exitCode: number, stdout: string, stderr: string }>}
- */
-function runSuite({
-  repoRoot,
-  files,
-  concurrency = 8,
-  timeoutMs = 5 * 60 * 1000,
-  spawnFn = spawn,
-}) {
-  return new Promise((resolve) => {
-    if (files.length === 0) {
-      resolve({ results: [], exitCode: 0, stdout: '', stderr: '' });
-      return;
-    }
-    const args = [
-      ...NODE_TEST_BASE,
-      `--test-concurrency=${concurrency}`,
-      ...files,
-    ];
-    const child = spawnFn(process.execPath, args, {
-      cwd: repoRoot,
-      env: {
-        ...sanitizeEnv(process.env),
-        FORCE_COLOR: '0',
-        NO_COLOR: '1',
-        SKIP_PREFLIGHT: '1',
-      },
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (d) => {
-      stdout += d.toString('utf8');
-    });
-    child.stderr.on('data', (d) => {
-      stderr += d.toString('utf8');
-    });
-    const timer = setTimeout(() => {
-      child.kill('SIGKILL');
-    }, timeoutMs);
-    child.on('close', (code) => {
-      clearTimeout(timer);
-      const parsed = parseSuiteTap(stdout + stderr);
-      // Node's TAP reporter prints subtest names using the host path
-      // separator (backslashes on Windows). Look up both forms.
-      const results = files.map((file) => {
-        const winForm = file.replace(/\//g, '\\');
-        const entry = parsed.get(file) ?? parsed.get(winForm);
-        if (!entry) {
-          return { file, status: 'missing', failingTests: [] };
-        }
-        return {
-          file,
-          status: entry.status,
-          failingTests: entry.failingTests,
-        };
-      });
-      resolve({ results, exitCode: code ?? 1, stdout, stderr });
-    });
-  });
-}
-
-/**
- * Run isolated runs in parallel across a worker pool.
- *
- * @param {object} opts
- * @param {string} opts.repoRoot
- * @param {string[]} opts.files
- * @param {string} [opts.envOutDir]
- * @param {number} [opts.workers]
- * @param {number} [opts.timeoutMs]
- * @param {(r: IsolatedResult) => void} [opts.onResult]
- * @returns {Promise<IsolatedResult[]>}
- */
-async function runIsolatedPool({
-  repoRoot,
-  files,
-  envOutDir,
-  workers = Math.max(2, Math.min(os.cpus().length, 8)),
-  timeoutMs = 120_000,
-  onResult,
-}) {
-  const queue = [...files];
-  const results = [];
-  const workerCount = Math.min(workers, queue.length);
-  await Promise.all(
-    Array.from({ length: workerCount }, async () => {
-      while (queue.length > 0) {
-        const file = queue.shift();
-        if (!file) return;
-        const r = await runFileIsolated({
-          repoRoot,
-          file,
-          envOutDir,
-          timeoutMs,
-        });
-        results.push(r);
-        if (onResult) onResult(r);
-      }
-    }),
-  );
-  return results;
-}
-
-/**
- * Bisect to find the smallest candidate subset (down to a single file) whose
- * presence alongside `target` reproduces `target` failing.
- *
- * Strategy: binary halving. Run `[half, target]` at full concurrency. If
- * `target` fails, recurse into `half`; else recurse into the other half. The
- * search depth is capped — when both halves keep failing or neither
- * reproduces, the bisection is marked inconclusive and the residual
- * candidate set returned as suspects.
- *
- * @param {object} opts
- * @param {string} opts.repoRoot
- * @param {string} opts.target           File that flipped (passed alone, failed in suite).
- * @param {string[]} opts.candidates     All other files in the suite.
- * @param {number} [opts.concurrency]
- * @param {number} [opts.maxDepth]
- * @param {(stage: string, payload: object) => void} [opts.onProgress]
- * @returns {Promise<BisectionResult>}
- */
-export async function bisectFlipper({
-  repoRoot,
-  target,
-  candidates,
-  concurrency = 8,
-  maxDepth = 8,
-  onProgress,
-  runSuiteFn = runSuite,
-}) {
-  let pool = [...candidates];
-  let depth = 0;
-  let inconclusive = false;
-
-  while (pool.length > 1 && depth < maxDepth) {
-    const mid = Math.ceil(pool.length / 2);
-    const half = pool.slice(0, mid);
-    const { results } = await runSuiteFn({
-      repoRoot,
-      files: [...half, target],
-      concurrency,
-    });
-    const targetResult = results.find((r) => r.file === target);
-    if (onProgress) {
-      onProgress('probe', {
-        target,
-        depth,
-        candidates: half.length,
-        targetStatus: targetResult?.status,
-      });
-    }
-    if (targetResult?.status === 'fail') {
-      pool = half;
-    } else {
-      const other = pool.slice(mid);
-      const r2 = await runSuiteFn({
-        repoRoot,
-        files: [...other, target],
-        concurrency,
-      });
-      const t2 = r2.results.find((r) => r.file === target);
-      if (onProgress) {
-        onProgress('probe', {
-          target,
-          depth: depth + 0.5,
-          candidates: other.length,
-          targetStatus: t2?.status,
-        });
-      }
-      if (t2?.status === 'fail') {
-        pool = other;
-      } else {
-        inconclusive = true;
-        break;
-      }
-    }
-    depth += 1;
-  }
-
-  return {
-    file: target,
-    suspects: pool,
-    inconclusive: inconclusive || pool.length > 1,
-  };
-}
-
-/**
- * Drive the full isolation diagnosis.
- *
- * @param {object} opts
- * @param {string} opts.repoRoot
- * @param {string[]} opts.files
- * @param {number} [opts.suiteConcurrency]
- * @param {number} [opts.workers]
- * @param {number} [opts.maxBisectTargets]
- * @param {number} [opts.maxBisectDepth]
- * @param {(stage: string, payload?: object) => void} [opts.onProgress]
- * @returns {Promise<IsolateReport>}
- */
-export async function diagnoseIsolation({
-  repoRoot,
-  files,
-  suiteConcurrency = 8,
-  workers,
-  maxBisectTargets = 5,
-  maxBisectDepth = 8,
-  onProgress = () => {},
-}) {
-  const started = Date.now();
-  const envOutDir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-isolate-env-'));
-
-  onProgress('isolated:start', { count: files.length });
-  const isolated = await runIsolatedPool({
-    repoRoot,
-    files,
-    envOutDir,
-    workers,
-    onResult: (r) =>
-      onProgress('isolated:file', {
-        file: r.file,
-        status: r.status,
-        durationMs: r.durationMs,
-      }),
-  });
-  onProgress('isolated:done', { count: isolated.length });
-
-  onProgress('suite:start', { count: files.length });
-  const { results: suite } = await runSuite({
-    repoRoot,
-    files,
-    concurrency: suiteConcurrency,
-  });
-  onProgress('suite:done', { count: suite.length });
-
-  const suiteByFile = new Map(suite.map((s) => [s.file, s]));
-  const isolatedByFile = new Map(isolated.map((s) => [s.file, s]));
-
-  const flippers = files.filter((f) => {
-    const iso = isolatedByFile.get(f);
-    const ste = suiteByFile.get(f);
-    return iso?.status === 'pass' && ste?.status === 'fail';
-  });
-
-  const bisectTargets = flippers.slice(0, maxBisectTargets);
-  const bisections = [];
-  for (const target of bisectTargets) {
-    const candidates = files.filter((f) => f !== target);
-    onProgress('bisect:start', { target });
-    const result = await bisectFlipper({
-      repoRoot,
-      target,
-      candidates,
-      concurrency: suiteConcurrency,
-      maxDepth: maxBisectDepth,
-      onProgress,
-    });
-    bisections.push(result);
-    onProgress('bisect:done', { target, suspects: result.suspects });
-  }
-
-  const envMutators = isolated
-    .filter((r) => {
-      const d = r.envDiff;
-      return (
-        d &&
-        (d.added.length > 0 || d.removed.length > 0 || d.changed.length > 0)
-      );
-    })
-    .map((r) => ({ file: r.file, envDiff: r.envDiff }));
-
-  try {
-    fs.rmSync(envOutDir, { recursive: true, force: true });
-  } catch {
-    // ignore
-  }
-
-  return {
-    pattern: files.length === 1 ? files[0] : null,
-    files,
-    isolated,
-    suite,
-    flippers,
-    bisections,
-    envMutators,
-    durationMs: Date.now() - started,
-  };
-}

package/.agents/scripts/lib/test-profile/parse-tap.js

@@ -1,136 +0,0 @@
-/**
- * Parse Node.js `node --test --test-reporter tap` output into structured
- * timing rows plus footer aggregates.
- */
-
-const SUBTEST_RE = /^(\s*)# Subtest:\s*(.+)$/;
-const RESULT_RE = /^(\s*)(ok|not ok)\s+\d+\s+-\s+(.+)$/;
-const DURATION_RE = /^\s*duration_ms:\s*([\d.]+)/;
-const FOOTER_TESTS_RE = /^# tests\s+(\d+)/;
-const FOOTER_SUITES_RE = /^# suites\s+(\d+)/;
-const FOOTER_DURATION_RE = /^# duration_ms\s+([\d.]+)/;
-
-/**
- * @typedef {'test' | 'suite'} TapEntryKind
- * @typedef {{
- *   kind: TapEntryKind,
- *   name: string,
- *   path: string,
- *   durationMs: number,
- * }} TapTimingEntry
- * @typedef {{
- *   totalDurationMs: number | null,
- *   testCount: number | null,
- *   suiteCount: number | null,
- *   entries: TapTimingEntry[],
- * }} TapProfile
- */
-
-/**
- * @param {string} tapText
- * @returns {TapProfile}
- */
-export function parseTapOutput(tapText) {
-  const lines = tapText.replace(/\r\n/g, '\n').split('\n');
-  const suiteStack = [];
-  const entries = [];
-  let pending = null;
-  let totalDurationMs = null;
-  let testCount = null;
-  let suiteCount = null;
-
-  for (const line of lines) {
-    const subtest = line.match(SUBTEST_RE);
-    if (subtest) {
-      const depth = Math.floor(subtest[1].length / 4);
-      const name = subtest[2].trim();
-      suiteStack.length = depth;
-      suiteStack[depth] = name;
-      continue;
-    }
-
-    const result = line.match(RESULT_RE);
-    if (result) {
-      pending = {
-        depth: Math.floor(result[1].length / 4),
-        name: result[3].trim(),
-        kind: null,
-        durationMs: null,
-      };
-      continue;
-    }
-
-    if (pending) {
-      const duration = line.match(DURATION_RE);
-      if (duration) {
-        pending.durationMs = Number(duration[1]);
-        continue;
-      }
-      if (line.trim() === "type: 'test'") {
-        pending.kind = 'test';
-        continue;
-      }
-      if (line.trim() === "type: 'suite'") {
-        pending.kind = 'suite';
-        continue;
-      }
-      if (line.trim() === '---') {
-        continue;
-      }
-      if (line.trim() === '...') {
-        if (pending.durationMs != null && pending.kind) {
-          flushPending();
-        }
-        continue;
-      }
-    }
-
-    const footerTests = line.match(FOOTER_TESTS_RE);
-    if (footerTests) {
-      testCount = Number(footerTests[1]);
-      continue;
-    }
-    const footerSuites = line.match(FOOTER_SUITES_RE);
-    if (footerSuites) {
-      suiteCount = Number(footerSuites[1]);
-      continue;
-    }
-    const footerDuration = line.match(FOOTER_DURATION_RE);
-    if (footerDuration) {
-      totalDurationMs = Number(footerDuration[1]);
-    }
-  }
-
-  if (pending?.durationMs != null && pending.kind) {
-    flushPending();
-  }
-
-  return {
-    totalDurationMs,
-    testCount,
-    suiteCount,
-    entries,
-  };
-
-  function flushPending() {
-    const pathParts = suiteStack.slice(0, pending.depth).concat(pending.name);
-    entries.push({
-      kind: pending.kind,
-      name: pending.name,
-      path: pathParts.join(' › '),
-      durationMs: pending.durationMs,
-    });
-    pending = null;
-  }
-}
-
-/**
- * @param {TapTimingEntry[]} entries
- * @param {number} [topN=20]
- * @returns {TapTimingEntry[]}
- */
-export function selectSlowestEntries(entries, topN = 20) {
-  return [...entries]
-    .sort((a, b) => b.durationMs - a.durationMs)
-    .slice(0, topN);
-}