mandrel 1.57.0

package/.agents/scripts/lib/mutation/baseline-snapshot.js

@@ -0,0 +1,238 @@
+/**
+ * lib/mutation/baseline-snapshot.js — Read/write the mutation baseline file
+ * consumed by the story-close mutation gate (Story #1736, Epic #1720).
+ *
+ * The baseline file lives at the path configured by
+ * `delivery.quality.gates.mutation.baselinePath` (default
+ * `baselines/mutation.json`) and conforms to:
+ *
+ *   {
+ *     "generatedAt": "<ISO-8601 timestamp>",
+ *     "tolerancePct": <number, mutation-score percent points>,
+ *     "workspaces": {
+ *       "*": <number, mutation-score percent points 0–100>,
+ *       "<workspace-name>": <number>
+ *     }
+ *   }
+ *
+ * The `"*"` catch-all key handles single-workspace consumers; real
+ * workspace names handle monorepo consumers. Generic applier code reads
+ * `workspaces[name] ?? workspaces['*']`.
+ *
+ * `tolerancePct` carries the per-workspace mutation-score drop tolerance
+ * in percent points (matches the `delivery.quality.gates.mutation.tolerance`
+ * resolver default of 0). When a workspace's measured score is below
+ * `baseline - tolerancePct`, the gate fails.
+ *
+ * This module mirrors the dependency-injection style used by
+ * `lib/baseline-snapshot.js`: the fs surface and the clock are injected so
+ * unit tests never touch real files. The two writer paths
+ * (`readBaseline`, `writeBaseline`) are split because the typical caller
+ * sequence is read-then-merge-then-write — for instance,
+ * `update-mutation-baseline.js` reads the prior baseline to preserve the
+ * configured `tolerancePct` if the Stryker run does not override it.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Default tolerance in percent points. Matches the framework-default
+ * tolerance value resolved from `delivery.quality.gates.mutation.tolerance`
+ * (`{ kind: 'absolute', value: 0 }`). A drop of 0% pts means any
+ * regression below the recorded baseline trips the gate.
+ */
+export const DEFAULT_TOLERANCE_PCT = 0;
+
+/**
+ * Default baseline file path, relative to the repo root. Mirrors the
+ * resolver default in `lib/config/quality.js`.
+ */
+export const DEFAULT_BASELINE_PATH = 'baselines/mutation.json';
+
+/**
+ * Read the mutation baseline at `baselinePath`. Returns `null` when the
+ * file does not exist so the caller can distinguish "no baseline yet"
+ * (the gate self-skips with an explanatory line) from a parse error.
+ *
+ * Throws when the file exists but is malformed (invalid JSON, missing
+ * required keys, wrong types) — silent corruption must not relax the gate.
+ *
+ * @param {string} baselinePath  Absolute or cwd-relative path.
+ * @param {{ cwd?: string, fsImpl?: { existsSync: typeof fs.existsSync, readFileSync: typeof fs.readFileSync } }} [opts]
+ * @returns {{ generatedAt: string, tolerancePct: number, workspaces: Record<string, number> } | null}
+ */
+export function readBaseline(baselinePath, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const fsImpl = opts.fsImpl ?? fs;
+  const abs = path.isAbsolute(baselinePath)
+    ? baselinePath
+    : path.resolve(cwd, baselinePath);
+  if (!fsImpl.existsSync(abs)) return null;
+  const raw = fsImpl.readFileSync(abs, 'utf8');
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `[mutation/baseline-snapshot] failed to parse ${baselinePath}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return validateBaseline(parsed, baselinePath);
+}
+
+/**
+ * Atomically rewrite the mutation baseline at `baselinePath` from
+ * `payload`. "Atomic" here means write-temp-then-rename, so a SIGKILL
+ * mid-write never leaves a half-written baseline file on disk.
+ *
+ * The on-disk shape is canonicalised: `workspaces` keys are sorted
+ * alphabetically (with `"*"` always first) and the file ends with a
+ * trailing newline. This produces a byte-stable serialisation, which
+ * the `update-mutation-baseline.js` entry-point relies on to detect
+ * "no change" runs (skip the baseline-refresh commit when re-running
+ * Stryker produces an identical baseline).
+ *
+ * @param {string} baselinePath
+ * @param {{ generatedAt?: string, tolerancePct?: number, workspaces: Record<string, number> }} payload
+ * @param {{ cwd?: string, fsImpl?: object, clock?: () => Date }} [opts]
+ * @returns {{ path: string, bytes: string, didChange: boolean }}
+ */
+export function writeBaseline(baselinePath, payload, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const fsImpl = opts.fsImpl ?? fs;
+  const clock = opts.clock ?? (() => new Date());
+  const abs = path.isAbsolute(baselinePath)
+    ? baselinePath
+    : path.resolve(cwd, baselinePath);
+  const generatedAt = payload.generatedAt ?? clock().toISOString();
+  const tolerancePct = Number.isFinite(payload.tolerancePct)
+    ? payload.tolerancePct
+    : DEFAULT_TOLERANCE_PCT;
+  if (
+    !payload ||
+    typeof payload.workspaces !== 'object' ||
+    payload.workspaces === null
+  ) {
+    throw new TypeError(
+      '[mutation/baseline-snapshot] writeBaseline: payload.workspaces must be an object',
+    );
+  }
+  const workspaces = canonicaliseWorkspaces(payload.workspaces);
+  const envelope = { generatedAt, tolerancePct, workspaces };
+  const bytes = `${JSON.stringify(envelope, null, 2)}\n`;
+  let prior = null;
+  if (fsImpl.existsSync(abs)) {
+    try {
+      prior = fsImpl.readFileSync(abs, 'utf8');
+    } catch {
+      prior = null;
+    }
+  }
+  if (prior === bytes) {
+    return { path: abs, bytes, didChange: false };
+  }
+  fsImpl.mkdirSync?.(path.dirname(abs), { recursive: true });
+  // Atomic write: write to a sibling temp file then rename. `renameSync`
+  // is atomic on POSIX and best-effort on Windows (which is good enough —
+  // the previous file is never half-overwritten).
+  const tmp = `${abs}.tmp-${process.pid}`;
+  fsImpl.writeFileSync(tmp, bytes);
+  try {
+    fsImpl.renameSync?.(tmp, abs);
+  } catch {
+    // `fs` shims in tests may not implement renameSync — fall back to a
+    // direct write + best-effort unlink so the in-memory store still
+    // converges to the right state.
+    fsImpl.writeFileSync(abs, bytes);
+    try {
+      fsImpl.unlinkSync?.(tmp);
+    } catch {
+      /* ignore */
+    }
+  }
+  return { path: abs, bytes, didChange: true };
+}
+
+/**
+ * Validate that `parsed` matches the baseline envelope contract. Returns
+ * the parsed object unchanged when it conforms; throws otherwise.
+ *
+ * Exposed for unit testing the validator independently of fs I/O.
+ *
+ * @param {unknown} parsed
+ * @param {string} sourceLabel
+ * @returns {{ generatedAt: string, tolerancePct: number, workspaces: Record<string, number> }}
+ */
+export function validateBaseline(parsed, sourceLabel = '<input>') {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(
+      `[mutation/baseline-snapshot] ${sourceLabel}: expected an object, got ${Array.isArray(parsed) ? 'array' : typeof parsed}`,
+    );
+  }
+  const { generatedAt, tolerancePct, workspaces } =
+    /** @type {Record<string, unknown>} */ (parsed);
+  if (typeof generatedAt !== 'string' || generatedAt.length === 0) {
+    throw new Error(
+      `[mutation/baseline-snapshot] ${sourceLabel}: 'generatedAt' must be a non-empty string`,
+    );
+  }
+  if (
+    !Number.isFinite(tolerancePct) ||
+    /** @type {number} */ (tolerancePct) < 0
+  ) {
+    throw new Error(
+      `[mutation/baseline-snapshot] ${sourceLabel}: 'tolerancePct' must be a non-negative number`,
+    );
+  }
+  if (
+    !workspaces ||
+    typeof workspaces !== 'object' ||
+    Array.isArray(workspaces)
+  ) {
+    throw new Error(
+      `[mutation/baseline-snapshot] ${sourceLabel}: 'workspaces' must be an object`,
+    );
+  }
+  for (const [name, score] of Object.entries(workspaces)) {
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new Error(
+        `[mutation/baseline-snapshot] ${sourceLabel}: workspace name must be a non-empty string`,
+      );
+    }
+    if (
+      !Number.isFinite(score) ||
+      /** @type {number} */ (score) < 0 ||
+      /** @type {number} */ (score) > 100
+    ) {
+      throw new Error(
+        `[mutation/baseline-snapshot] ${sourceLabel}: workspace "${name}" score must be a number in [0, 100], got ${JSON.stringify(score)}`,
+      );
+    }
+  }
+  return /** @type {{ generatedAt: string, tolerancePct: number, workspaces: Record<string, number> }} */ (
+    parsed
+  );
+}
+
+/**
+ * Sort `workspaces` keys deterministically so the on-disk serialisation
+ * is byte-stable. The `"*"` catch-all key is pinned to the first slot;
+ * the remaining keys sort alphabetically.
+ *
+ * @param {Record<string, number>} workspaces
+ * @returns {Record<string, number>}
+ */
+function canonicaliseWorkspaces(workspaces) {
+  const keys = Object.keys(workspaces);
+  const sorted = keys.slice().sort((a, b) => {
+    if (a === '*') return -1;
+    if (b === '*') return 1;
+    return a.localeCompare(b);
+  });
+  const out = /** @type {Record<string, number>} */ ({});
+  for (const k of sorted) {
+    out[k] = workspaces[k];
+  }
+  return out;
+}

package/.agents/scripts/lib/mutation/config-detector.js

@@ -0,0 +1,119 @@
+/**
+ * lib/mutation/config-detector.js — Detect a Stryker config in a repo
+ * (Story #1736, Task #1754).
+ *
+ * The mutation gate is on-by-default but self-skips when Stryker is not
+ * configured. The detector recognises the canonical Stryker config
+ * surfaces:
+ *
+ *   - `stryker.conf.js`
+ *   - `stryker.conf.cjs`
+ *   - `stryker.conf.mjs`
+ *   - `stryker.conf.json`
+ *   - `stryker.config.js` / `.cjs` / `.mjs` / `.json` (Stryker's alternate name)
+ *   - a `"stryker"` key in the repo-root `package.json`
+ *
+ * When an explicit `configPath` is supplied (from the gate's
+ * `strykerConfigPath` block), that path takes precedence — the file is
+ * checked for existence and returned without re-walking the canonical
+ * surfaces.
+ *
+ * Pure with respect to the injected fs surface; never invokes Stryker
+ * or any child process.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CANONICAL_FILES = Object.freeze([
+  'stryker.conf.js',
+  'stryker.conf.cjs',
+  'stryker.conf.mjs',
+  'stryker.conf.json',
+  'stryker.config.js',
+  'stryker.config.cjs',
+  'stryker.config.mjs',
+  'stryker.config.json',
+]);
+
+/**
+ * @typedef {Object} DetectionResult
+ * @property {boolean} found
+ * @property {'config-file' | 'package-json' | 'explicit' | null} via
+ * @property {string | null} path  Absolute path to the config artifact (or
+ *   the package.json that carries the `stryker` key).
+ * @property {string} [reason]     Populated when `found` is false.
+ */
+
+/**
+ * Detect a Stryker configuration in `cwd`.
+ *
+ * @param {{
+ *   cwd?: string,
+ *   configPath?: string | null,
+ *   fsImpl?: { existsSync: typeof fs.existsSync, readFileSync: typeof fs.readFileSync },
+ * }} [opts]
+ * @returns {DetectionResult}
+ */
+export function detectStrykerConfig(opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const fsImpl = opts.fsImpl ?? fs;
+  const explicit = opts.configPath;
+
+  if (typeof explicit === 'string' && explicit.length > 0) {
+    const abs = path.isAbsolute(explicit)
+      ? explicit
+      : path.resolve(cwd, explicit);
+    if (fsImpl.existsSync(abs)) {
+      return { found: true, via: 'explicit', path: abs };
+    }
+    return {
+      found: false,
+      via: null,
+      path: null,
+      reason: `explicit strykerConfigPath '${explicit}' does not exist`,
+    };
+  }
+
+  for (const filename of CANONICAL_FILES) {
+    const abs = path.resolve(cwd, filename);
+    if (fsImpl.existsSync(abs)) {
+      return { found: true, via: 'config-file', path: abs };
+    }
+  }
+
+  const pkgPath = path.resolve(cwd, 'package.json');
+  if (fsImpl.existsSync(pkgPath)) {
+    try {
+      const raw = fsImpl.readFileSync(pkgPath, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (
+        parsed &&
+        typeof parsed === 'object' &&
+        parsed.stryker &&
+        typeof parsed.stryker === 'object'
+      ) {
+        return { found: true, via: 'package-json', path: pkgPath };
+      }
+    } catch {
+      // Malformed package.json — fall through to "not found". The repo
+      // is already broken in other ways; the mutation gate skip is a
+      // benign symptom, not the cause.
+    }
+  }
+
+  return {
+    found: false,
+    via: null,
+    path: null,
+    reason: 'no Stryker config found',
+  };
+}
+
+/**
+ * Exposed for testing — the canonical filename list, frozen.
+ * @returns {readonly string[]}
+ */
+export function getCanonicalConfigFilenames() {
+  return CANONICAL_FILES;
+}

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

@@ -0,0 +1,306 @@
+/**
+ * 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;
+}