mandrel 2.31.0 → 2.33.0

package/.agents/scripts/lib/mutation/stryker-runner.js

@@ -1,306 +0,0 @@
-/**
- * lib/mutation/stryker-runner.js — Invoke Stryker and parse the mutation
- * report (Story #1736, Task #1754).
- *
- * The runner is dependency-injection-friendly so unit tests never have to
- * spawn a real Stryker process. The default `spawnFn` is
- * `child_process.spawnSync`, the default `fsImpl` is `node:fs`, and the
- * default `clock` is `Date.now`.
- *
- * Output contract:
- *
- *   { ok: true, mutationScore: <number>, byWorkspace: { "*": <number>, ... },
- *     reportPath, durationMs }
- *   { ok: false, skipped: true, reason: <string> }
- *   { ok: false, skipped: false, error: <string>, durationMs }
- *
- * Stryker writes its JSON report by default to `reports/mutation/mutation.json`.
- * Consumers that relocate the report can pass `reportPath`. We never parse
- * the much larger per-mutant HTML report — only the JSON summary.
- *
- * `timeoutMs` is honoured via `spawnSync`'s `timeout` option; on TIMEOUT
- * we surface an `ok: false` result rather than throwing so the caller can
- * fold the failure into a single uniform "[mutation] failed" gate line.
- */
-
-import { spawnSync as defaultSpawnSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-
-import { detectStrykerConfig as defaultDetectStrykerConfig } from './config-detector.js';
-
-/** Default per-gate timeout when none is supplied (15 minutes). */
-export const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
-
-/** Default Stryker JSON report path (mirrors the Stryker default). */
-export const DEFAULT_REPORT_PATH = 'reports/mutation/mutation.json';
-
-/**
- * @typedef {Object} RunResult
- * @property {boolean} ok
- * @property {boolean} [skipped]
- * @property {string} [reason]
- * @property {string} [error]
- * @property {number} [mutationScore]
- * @property {Record<string, number>} [byWorkspace]
- * @property {string} [reportPath]
- * @property {number} [durationMs]
- * @property {number} [exitCode]
- */
-
-/**
- * Run Stryker and return a normalised summary.
- *
- * @param {{
- *   cwd?: string,
- *   configPath?: string | null,
- *   reportPath?: string,
- *   timeoutMs?: number,
- *   workspace?: string,
- *   spawnFn?: typeof defaultSpawnSync,
- *   fsImpl?: typeof fs,
- *   clock?: () => number,
- *   strykerCmd?: string,
- *   strykerArgs?: string[],
- *   detectFn?: typeof defaultDetectStrykerConfig,
- *   skipDetect?: boolean,
- * }} [opts]
- * @returns {Promise<RunResult>}
- */
-export async function runStryker(opts = {}) {
-  const cwd = opts.cwd ?? process.cwd();
-  const reportPath = opts.reportPath ?? DEFAULT_REPORT_PATH;
-  const timeoutMs = Number.isFinite(opts.timeoutMs)
-    ? opts.timeoutMs
-    : DEFAULT_TIMEOUT_MS;
-  const workspace = opts.workspace ?? '*';
-  const spawnFn = opts.spawnFn ?? defaultSpawnSync;
-  const fsImpl = opts.fsImpl ?? fs;
-  const clock = opts.clock ?? (() => Date.now());
-  const detectFn = opts.detectFn ?? defaultDetectStrykerConfig;
-
-  // Detection short-circuit: the runner is the single point of "no
-  // Stryker config → skip" so callers can fold the same result into a
-  // uniform "[mutation] skipped" gate line. `skipDetect` is the escape
-  // hatch for tests and for callers that have already detected.
-  let resolvedConfigPath = opts.configPath ?? null;
-  if (!opts.skipDetect) {
-    const detection = detectFn({
-      cwd,
-      configPath: resolvedConfigPath,
-      fsImpl,
-    });
-    if (!detection.found) {
-      return {
-        ok: false,
-        skipped: true,
-        reason:
-          detection.reason ??
-          'no Stryker config found. Run `npx stryker init` to enable.',
-      };
-    }
-    resolvedConfigPath = detection.path;
-  }
-
-  // Default to `npx stryker run` — works whether Stryker is a local devDep
-  // or a one-shot install. Consumers with a pinned executable can override.
-  const cmd = opts.strykerCmd ?? 'npx';
-  const args =
-    opts.strykerArgs ??
-    (resolvedConfigPath
-      ? ['stryker', 'run', '--configFile', resolvedConfigPath]
-      : ['stryker', 'run']);
-
-  const startedAt = clock();
-  const spawnResult = spawnFn(cmd, args, {
-    cwd,
-    encoding: 'utf-8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-    timeout: timeoutMs,
-    shell: process.platform === 'win32',
-  });
-  const durationMs = clock() - startedAt;
-
-  // spawnSync sets `signal` to 'SIGTERM' when the timeout fires.
-  if (
-    spawnResult.signal === 'SIGTERM' ||
-    spawnResult.error?.code === 'ETIMEDOUT'
-  ) {
-    return {
-      ok: false,
-      skipped: false,
-      error: `Stryker timed out after ${timeoutMs}ms`,
-      durationMs,
-      exitCode: spawnResult.status ?? -1,
-    };
-  }
-
-  if (spawnResult.error) {
-    return {
-      ok: false,
-      skipped: false,
-      error: `failed to invoke Stryker: ${spawnResult.error.message}`,
-      durationMs,
-    };
-  }
-
-  if (spawnResult.status !== 0) {
-    return {
-      ok: false,
-      skipped: false,
-      error: `Stryker exited with status ${spawnResult.status}: ${
-        spawnResult.stderr?.trim() || spawnResult.stdout?.trim() || 'no output'
-      }`,
-      durationMs,
-      exitCode: spawnResult.status,
-    };
-  }
-
-  const absReportPath = path.isAbsolute(reportPath)
-    ? reportPath
-    : path.resolve(cwd, reportPath);
-
-  if (!fsImpl.existsSync(absReportPath)) {
-    return {
-      ok: false,
-      skipped: false,
-      error: `Stryker report not found at ${reportPath} — expected JSON reporter to be enabled`,
-      durationMs,
-    };
-  }
-
-  let parsed;
-  try {
-    parsed = JSON.parse(fsImpl.readFileSync(absReportPath, 'utf8'));
-  } catch (err) {
-    return {
-      ok: false,
-      skipped: false,
-      error: `failed to parse Stryker report at ${reportPath}: ${err instanceof Error ? err.message : String(err)}`,
-      durationMs,
-    };
-  }
-
-  const summary = summariseReport(parsed, { workspace });
-  if (!summary.ok) {
-    return {
-      ok: false,
-      skipped: false,
-      error: summary.error,
-      durationMs,
-    };
-  }
-
-  return {
-    ok: true,
-    mutationScore: summary.mutationScore,
-    byWorkspace: summary.byWorkspace,
-    reportPath: absReportPath,
-    durationMs,
-  };
-}
-
-/**
- * Pure: parse a Stryker mutation-report payload and return the overall
- * mutation score plus per-workspace breakdown. Exposed for unit testing.
- *
- * The Stryker JSON report shape includes a top-level `files` map keyed by
- * source path, where each entry carries an array of `mutants` with a
- * `status` field. The "mutation score" is the percentage of killed +
- * covered+failed-by-test mutants over the total tested mutants.
- *
- * Status values that count toward the score numerator: `Killed`.
- * Status values that count toward the denominator: `Killed`, `Survived`,
- * `Timeout`, `CompileError`, `RuntimeError`, `NoCoverage`.
- *
- * Stryker also exposes a precomputed `schema.MutationScoreResult` /
- * `metrics.mutationScore` in its `mutation-testing-elements` reports;
- * when present, prefer it over a hand-roll so we never disagree with the
- * Stryker dashboard. The hand-roll is the fallback for older reports
- * that omit the metrics block.
- *
- * @param {unknown} report
- * @param {{ workspace?: string }} [opts]
- * @returns {{ ok: true, mutationScore: number, byWorkspace: Record<string, number> } | { ok: false, error: string }}
- */
-export function summariseReport(report, opts = {}) {
-  const workspace = opts.workspace ?? '*';
-
-  if (!report || typeof report !== 'object' || Array.isArray(report)) {
-    return { ok: false, error: 'Stryker report must be a JSON object' };
-  }
-
-  const reportObj = /** @type {Record<string, unknown>} */ (report);
-
-  // Prefer Stryker's precomputed metrics block when present.
-  const metrics = /** @type {Record<string, unknown> | undefined} */ (
-    reportObj.metrics
-  );
-  if (
-    metrics &&
-    typeof metrics === 'object' &&
-    typeof metrics.mutationScore === 'number' &&
-    Number.isFinite(metrics.mutationScore)
-  ) {
-    return {
-      ok: true,
-      mutationScore: metrics.mutationScore,
-      byWorkspace: { [workspace]: metrics.mutationScore },
-    };
-  }
-
-  const files = /** @type {Record<string, unknown> | undefined} */ (
-    reportObj.files
-  );
-  if (!files || typeof files !== 'object') {
-    return {
-      ok: false,
-      error: "Stryker report missing 'files' map",
-    };
-  }
-
-  let killed = 0;
-  let total = 0;
-  for (const entry of Object.values(files)) {
-    if (!entry || typeof entry !== 'object') continue;
-    const mutants = /** @type {{ mutants?: Array<{ status?: string }> }} */ (
-      entry
-    ).mutants;
-    if (!Array.isArray(mutants)) continue;
-    for (const m of mutants) {
-      const status = m?.status;
-      if (typeof status !== 'string') continue;
-      if (countsTowardDenominator(status)) total += 1;
-      if (status === 'Killed') killed += 1;
-    }
-  }
-
-  if (total === 0) {
-    return {
-      ok: false,
-      error: 'Stryker report has no scored mutants',
-    };
-  }
-
-  const score = (killed / total) * 100;
-  return {
-    ok: true,
-    mutationScore: round2(score),
-    byWorkspace: { [workspace]: round2(score) },
-  };
-}
-
-function countsTowardDenominator(status) {
-  return (
-    status === 'Killed' ||
-    status === 'Survived' ||
-    status === 'Timeout' ||
-    status === 'CompileError' ||
-    status === 'RuntimeError' ||
-    status === 'NoCoverage'
-  );
-}
-
-function round2(n) {
-  return Math.round(n * 100) / 100;
-}

package/.agents/scripts/lib/mutation/survivor-report.js

@@ -1,160 +0,0 @@
-/**
- * lib/mutation/survivor-report.js — enumerate actionable surviving mutants
- * from a Stryker JSON report (Story #3428).
- *
- * The mutation gate (`stryker-runner.js` → `summariseReport`) collapses the
- * report into a single score. That score tells you *whether* the suite is
- * leaky, not *where*. This helper does the complementary job: it walks the
- * same `files[].mutants[].status` surface and enumerates the mutants that
- * the suite failed to kill — `Survived` (a mutation that the tests ran over
- * but never caught) and `NoCoverage` (a mutation in a line no test exercises
- * at all) — grouped per file so the survivor-kill loop has concrete targets.
- *
- * It is **pure**: no network, no child process, no filesystem reads. The
- * caller hands in an already-parsed report object (the same JSON that
- * `stryker-runner.js` reads from `reports/mutation/mutation.json`). This
- * keeps the helper trivially unit-testable with inline fixtures and lets
- * remediation tooling reuse a report it already loaded for scoring.
- *
- * Output contract:
- *
- *   {
- *     ok: true,
- *     totals: { survived, noCoverage, actionable, files },
- *     files: [
- *       {
- *         file: "src/a.js",
- *         survived: [{ id, line, mutatorName, status, ... }],
- *         noCoverage: [{ ... }],
- *         count: <survived.length + noCoverage.length>,
- *       },
- *       ...
- *     ],
- *   }
- *   { ok: false, error: <string> }
- *
- * Files with no actionable survivors are omitted from `files`. The `files`
- * array is sorted by descending actionable count (worst offenders first),
- * ties broken by file path for stable output.
- */
-
-/** Mutant statuses this helper treats as actionable survivors. */
-export const ACTIONABLE_STATUSES = Object.freeze(['Survived', 'NoCoverage']);
-
-/**
- * Fields copied verbatim from each Stryker mutant onto the enumerated
- * survivor record. We deliberately keep a fixed allowlist (rather than
- * spreading the raw mutant) so the output shape is stable and never leaks
- * unexpected report internals.
- */
-const MUTANT_FIELDS = Object.freeze([
-  'id',
-  'mutatorName',
-  'status',
-  'location',
-  'replacement',
-]);
-
-/**
- * Pure: enumerate `Survived` and `NoCoverage` mutants per file from a
- * parsed Stryker mutation report.
- *
- * @param {unknown} report Parsed Stryker JSON report (an object with a
- *   top-level `files` map). Passing the raw JSON string is **not**
- *   supported — parse it first (mirrors `summariseReport`).
- * @returns {(
- *   { ok: true, totals: { survived: number, noCoverage: number, actionable: number, files: number }, files: Array<{ file: string, survived: object[], noCoverage: object[], count: number }> }
- *   | { ok: false, error: string }
- * )}
- */
-export function enumerateSurvivors(report) {
-  if (!report || typeof report !== 'object' || Array.isArray(report)) {
-    return { ok: false, error: 'Stryker report must be a JSON object' };
-  }
-
-  const files = /** @type {Record<string, unknown> | undefined} */ (
-    /** @type {Record<string, unknown>} */ (report).files
-  );
-  if (!files || typeof files !== 'object' || Array.isArray(files)) {
-    return { ok: false, error: "Stryker report missing 'files' map" };
-  }
-
-  const perFile = [];
-  let survivedTotal = 0;
-  let noCoverageTotal = 0;
-
-  for (const [filePath, entry] of Object.entries(files)) {
-    if (!entry || typeof entry !== 'object') continue;
-    const mutants = /** @type {{ mutants?: unknown }} */ (entry).mutants;
-    if (!Array.isArray(mutants)) continue;
-
-    const survived = [];
-    const noCoverage = [];
-    for (const mutant of mutants) {
-      if (!mutant || typeof mutant !== 'object') continue;
-      const status = /** @type {{ status?: unknown }} */ (mutant).status;
-      if (status === 'Survived') {
-        survived.push(pickMutant(mutant));
-      } else if (status === 'NoCoverage') {
-        noCoverage.push(pickMutant(mutant));
-      }
-    }
-
-    if (survived.length === 0 && noCoverage.length === 0) continue;
-
-    survivedTotal += survived.length;
-    noCoverageTotal += noCoverage.length;
-    perFile.push({
-      file: filePath,
-      survived,
-      noCoverage,
-      count: survived.length + noCoverage.length,
-    });
-  }
-
-  perFile.sort((a, b) => b.count - a.count || a.file.localeCompare(b.file));
-
-  return {
-    ok: true,
-    totals: {
-      survived: survivedTotal,
-      noCoverage: noCoverageTotal,
-      actionable: survivedTotal + noCoverageTotal,
-      files: perFile.length,
-    },
-    files: perFile,
-  };
-}
-
-/**
- * Copy the stable allowlist of fields off a raw Stryker mutant. The `line`
- * convenience field is derived from `location.start.line` when present so
- * callers can sort/print without re-walking the nested location shape.
- *
- * @param {Record<string, unknown>} mutant
- * @returns {Record<string, unknown>}
- */
-function pickMutant(mutant) {
-  const out = {};
-  for (const field of MUTANT_FIELDS) {
-    if (mutant[field] !== undefined) out[field] = mutant[field];
-  }
-  const line = extractLine(mutant.location);
-  if (line !== null) out.line = line;
-  return out;
-}
-
-/**
- * Pull the 1-based start line out of a Stryker `location` object, or null
- * when the shape is missing or malformed.
- *
- * @param {unknown} location
- * @returns {number | null}
- */
-function extractLine(location) {
-  if (!location || typeof location !== 'object') return null;
-  const start = /** @type {{ start?: unknown }} */ (location).start;
-  if (!start || typeof start !== 'object') return null;
-  const line = /** @type {{ line?: unknown }} */ (start).line;
-  return typeof line === 'number' && Number.isFinite(line) ? line : null;
-}

package/.agents/scripts/lib/observability/active-story-env.js

@@ -1,170 +0,0 @@
-/**
- * Active-Story env-var propagation (Epic #1030 Story #1043 / Task #1061).
- *
- * The PreToolUse / PostToolUse trace hook in
- * `lib/observability/tool-trace-hook.js` resolves the active Story from
- * `process.env.CC_STORY_ID`. This module is the single writer/clearer of
- * that var:
- *
- *   - `setActiveStoryEnv({ storyId, workCwd })` is called from
- *     `single-story-init.js` after the worktree is materialised. It sets the
- *     var on the current `process.env` (so any child commands the
- *     orchestrator spawns inherit it) and exports it to a sibling
- *     `.env.local` inside the worktree. The harness re-spawns the
- *     agent with that file's contents loaded, so the trace hook fires
- *     with the right ids on the *next* tool call after init returns.
- *
- *   - `clearActiveStoryEnv({ workCwd })` is called from
- *     `story-close/post-merge-close.js` after the merge lands. It
- *     deletes the env vars from `process.env` and removes the
- *     `.env.local` file. Tooling invoked outside an active Story —
- *     planning, dispatch, ad-hoc CLI — must NOT pollute random
- *     `traces.ndjson` files; the hook's no-op contract relies on the
- *     vars being absent at that point.
- *
- * Both functions are best-effort and never throw on fs failures. The
- * trace hook is itself best-effort, so a stale `.env.local` would at
- * worst cause one extra trace line to land in a stale `temp/.../`
- * directory — annoying but not a correctness bug. We log warnings via
- * the caller's logger when provided.
- */
-
-import nodeFs from 'node:fs';
-import nodePath from 'node:path';
-
-const ENV_LOCAL_BASENAME = '.env.local';
-
-/**
- * Names of the env vars we own. Keeping the list central makes the
- * round-trip (set on init, clear on close) trivially auditable —
- * grep `CC_STORY_ID` / `CC_EPIC_ID` to find every read site.
- *
- * `CC_STORY_ID` is the one var this module writes. `CC_EPIC_ID` is retained
- * on the CLEAR path only: v2 has no Epics and nothing here sets it, but
- * `tool-trace-hook.js`'s `resolveActiveStory` still reads it, so wiping it at
- * close keeps the trace path's "no stale context past close" contract honest
- * against a value that leaked in from outside (a pre-upgrade `.env.local` the
- * harness already loaded, or an operator's shell).
- *
- * `CC_SLICE_ID` / `CC_OPERATOR` were removed with the heartbeat substrate:
- * their only writer was the never-called `setActiveSliceEnv` and their only
- * reader the deleted `hook-heartbeat.js`.
- */
-export const ACTIVE_STORY_ENV_KEYS = ['CC_EPIC_ID', 'CC_STORY_ID'];
-
-/**
- * Render the `.env.local` body. One `KEY=value` line per var, LF
- * line endings (the harness's dotenv parser tolerates CRLF too but LF
- * keeps the file deterministic across Windows / macOS / Linux).
- *
- * Only `CC_STORY_ID` is emitted: v2 Stories are standalone, so there is no
- * parent Epic to key. The trace hook's no-op contract reads "var absent from
- * env" as the signal, so no `CC_EPIC_ID=` line is written at all — an empty
- * one would set the var to the empty string and change the contract.
- *
- * Exported for testing.
- *
- * @param {{ storyId: number }} input
- * @returns {string}
- */
-export function renderActiveStoryEnvFile({ storyId }) {
-  return [
-    '# Auto-managed by .agents/scripts/lib/observability/active-story-env.js',
-    '# Re-generated on every story-init; deleted on story-close.',
-    `CC_STORY_ID=${storyId}`,
-    '',
-  ].join('\n');
-}
-
-/**
- * Set `CC_STORY_ID` on the current process and (when `workCwd` is provided)
- * export it to `<workCwd>/.env.local`.
- *
- * Idempotent: re-running with the same id is a no-op on disk; with a
- * different id the `.env.local` is overwritten.
- *
- * v2 Stories are standalone — there is no parent Epic — so `CC_EPIC_ID` is
- * never set, and any pre-existing value is removed: the trace hook's
- * `resolveActiveStory` no-op contract is keyed on the var's absence, and a
- * stale epic id would key this Story's traces to a foreign Epic directory.
- *
- * @param {{ storyId: number, workCwd?: string,
- *           env?: NodeJS.ProcessEnv, fs?: typeof nodeFs,
- *           logger?: { warn?: (m: string) => void } }} args
- * @returns {{ envSet: boolean, fileWritten: boolean, filePath: string|null }}
- */
-export function setActiveStoryEnv({
-  storyId,
-  workCwd,
-  env = process.env,
-  fs = nodeFs,
-  logger,
-} = {}) {
-  if (!Number.isInteger(storyId) || storyId <= 0) {
-    throw new Error(
-      `[active-story-env] storyId must be a positive integer; got ${storyId}`,
-    );
-  }
-
-  if ('CC_EPIC_ID' in env) delete env.CC_EPIC_ID;
-  env.CC_STORY_ID = String(storyId);
-
-  let fileWritten = false;
-  let filePath = null;
-  if (typeof workCwd === 'string' && workCwd.length > 0) {
-    filePath = nodePath.join(workCwd, ENV_LOCAL_BASENAME);
-    try {
-      fs.writeFileSync(filePath, renderActiveStoryEnvFile({ storyId }), {
-        encoding: 'utf8',
-      });
-      fileWritten = true;
-    } catch (err) {
-      logger?.warn?.(
-        `[active-story-env] Failed to write ${filePath}: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-    }
-  }
-  return { envSet: true, fileWritten, filePath };
-}
-
-/**
- * Delete `CC_EPIC_ID` / `CC_STORY_ID` from the current process env and
- * remove `<workCwd>/.env.local` when present. Best-effort; a missing
- * file is not an error.
- *
- * @param {{ workCwd?: string, env?: NodeJS.ProcessEnv,
- *           fs?: typeof nodeFs,
- *           logger?: { warn?: (m: string) => void } }} args
- * @returns {{ envCleared: boolean, fileRemoved: boolean, filePath: string|null }}
- */
-export function clearActiveStoryEnv({
-  workCwd,
-  env = process.env,
-  fs = nodeFs,
-  logger,
-} = {}) {
-  for (const k of ACTIVE_STORY_ENV_KEYS) {
-    if (k in env) delete env[k];
-  }
-
-  let fileRemoved = false;
-  let filePath = null;
-  if (typeof workCwd === 'string' && workCwd.length > 0) {
-    filePath = nodePath.join(workCwd, ENV_LOCAL_BASENAME);
-    try {
-      if (fs.existsSync(filePath)) {
-        fs.unlinkSync(filePath);
-        fileRemoved = true;
-      }
-    } catch (err) {
-      logger?.warn?.(
-        `[active-story-env] Failed to remove ${filePath}: ${
-          err instanceof Error ? err.message : String(err)
-        }`,
-      );
-    }
-  }
-  return { envCleared: true, fileRemoved, filePath };
-}