@fairfox/polly 0.79.0 → 0.80.0

package/dist/tools/test/src/coverage-policy/enforce.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fairfox/polly/test/coverage — the coverage-policy engine.
+ *
+ * Parses a `bun test --coverage` table and applies a {@link CoverageConfig}.
+ * It fails on four conditions, not just low numbers: a non-exempt file below
+ * the floor, an exempt key whose source no longer exists, an exemption whose
+ * `claimedBy` test no longer exists, and an exempt file that has climbed back
+ * over the floor (promote it). It also reports orphans — source files no unit
+ * test imports, the blind spot a coverage table can't show.
+ *
+ * Everything here is parameterised by the project root, so the same engine
+ * backs Polly's own gate and the consumer-facing `polly coverage` command.
+ */
+import type { CoverageConfig } from "./types";
+export interface CoverageRow {
+    /** Project-relative, e.g. `src/shared/lib/state.ts`. */
+    file: string;
+    funcs: number;
+    lines: number;
+}
+export interface Violation {
+    file: string;
+    metric: "lines" | "funcs";
+    observed: number;
+    required: number;
+}
+export interface CoverageFindings {
+    rowCount: number;
+    violations: Violation[];
+    staleExempts: string[];
+    missingExemptFiles: string[];
+    missingClaimedBy: Array<{
+        file: string;
+        claimedBy: string;
+    }>;
+    orphans: string[];
+    /** True when a floor was configured; false means report-only. */
+    enforced: boolean;
+}
+/**
+ * Parse the `bun test --coverage` table. Only rows under `srcDir` are
+ * policy-bearing; the `All files` summary and test-infra rows are skipped.
+ * Column order is `File | % Funcs | % Lines | Uncovered`.
+ */
+export declare function parseCoverageTable(text: string, srcDir: string): CoverageRow[];
+/** Run `bun test --coverage` in the configured cwd and return combined output. */
+export declare function runCoverage(root: string, testCwd: string): Promise<string>;
+/** Apply the policy to a parsed table. Pure — no spawning. */
+export declare function evaluateCoverage(root: string, rows: CoverageRow[], config: CoverageConfig): Promise<CoverageFindings>;
+/** Run the suite under coverage and apply the policy. */
+export declare function enforceCoverage(root: string, config: CoverageConfig, coverageText?: string): Promise<CoverageFindings>;
+/** True when the findings represent a policy failure (orphans are advisory
+ *  unless `strictOrphans`). */
+export declare function hasFailure(findings: CoverageFindings, strictOrphans: boolean): boolean;

package/dist/tools/test/src/coverage-policy/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fairfox/polly/test/coverage — programmatic API behind `polly coverage`.
+ *
+ * Use the CLI (`polly coverage`) for the common case; import these to script
+ * the policy yourself or to add a coverage tier to a custom runner.
+ */
+export { type LoadedConfig, loadCoverageConfig } from "./discover";
+export { type CoverageFindings, type CoverageRow, enforceCoverage, evaluateCoverage, hasFailure, parseCoverageTable, runCoverage, type Violation, } from "./enforce";
+export { findStrykerConfigs, type MutateTargetIssue, type MutateTargetReport, validateMutateTargets, } from "./mutate-targets";
+export type { CoverageConfig, ExemptEntry, FileThreshold } from "./types";

package/dist/tools/test/src/coverage-policy/index.js

@@ -0,0 +1,242 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// tools/test/src/coverage-policy/enforce.ts
+var exports_enforce = {};
+__export(exports_enforce, {
+  runCoverage: () => runCoverage,
+  parseCoverageTable: () => parseCoverageTable,
+  hasFailure: () => hasFailure,
+  evaluateCoverage: () => evaluateCoverage,
+  enforceCoverage: () => enforceCoverage
+});
+import { existsSync as existsSync2 } from "node:fs";
+import { join as join2, resolve as resolve2 } from "node:path";
+import { Glob } from "bun";
+function normalizePath(raw) {
+  return raw.replace(/^(?:\.\.\/)+/, "");
+}
+function parseCoverageTable(text, srcDir) {
+  const prefix = `${srcDir}/`;
+  const rows = [];
+  for (const line of text.split(`
+`)) {
+    if (!line.includes("|"))
+      continue;
+    if (line.includes("All files") || line.includes("% Funcs"))
+      continue;
+    if (line.trim().startsWith("---"))
+      continue;
+    const cells = line.split("|").map((c) => c.trim());
+    if (cells.length < 3)
+      continue;
+    const file = normalizePath(cells[0] ?? "");
+    const funcs = Number(cells[1]);
+    const lines = Number(cells[2]);
+    if (!file.startsWith(prefix) || Number.isNaN(funcs) || Number.isNaN(lines))
+      continue;
+    rows.push({ file, funcs, lines });
+  }
+  return rows;
+}
+async function runCoverage(root, testCwd) {
+  const proc = Bun.spawn(["bun", "test", "--coverage"], {
+    cwd: join2(root, testCwd),
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  const [out, err] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text()
+  ]);
+  await proc.exited;
+  if (proc.exitCode !== 0) {
+    throw new Error(`bun test --coverage exited ${proc.exitCode}
+${err}`);
+  }
+  return `${out}
+${err}`;
+}
+function evaluateRows(rows, config) {
+  const t = config.defaultThreshold;
+  const exempt = config.exempt ?? {};
+  const violations = [];
+  const staleExempts = [];
+  if (!t)
+    return { violations, staleExempts };
+  for (const row of rows) {
+    if (exempt[row.file]) {
+      if (row.lines >= t.lines && row.funcs >= t.funcs)
+        staleExempts.push(row.file);
+      continue;
+    }
+    if (row.lines < t.lines) {
+      violations.push({ file: row.file, metric: "lines", observed: row.lines, required: t.lines });
+    }
+    if (row.funcs < t.funcs) {
+      violations.push({ file: row.file, metric: "funcs", observed: row.funcs, required: t.funcs });
+    }
+  }
+  return { violations, staleExempts };
+}
+function validateExemptions(root, config) {
+  const missingExemptFiles = [];
+  const missingClaimedBy = [];
+  for (const [file, entry] of Object.entries(config.exempt ?? {})) {
+    if (!existsSync2(resolve2(root, file)))
+      missingExemptFiles.push(file);
+    const claimedBy = entry.claimedBy.trim();
+    if (!claimedBy.startsWith("n/a") && !existsSync2(resolve2(root, claimedBy))) {
+      missingClaimedBy.push({ file, claimedBy });
+    }
+  }
+  return { missingExemptFiles, missingClaimedBy };
+}
+async function findOrphans(root, srcDir, covered, config) {
+  const exempt = config.exempt ?? {};
+  const orphans = [];
+  const glob = new Glob(`${srcDir}/**/*.{ts,tsx}`);
+  for await (const file of glob.scan({ cwd: root, onlyFiles: true })) {
+    if (file.endsWith(".d.ts") || /\.test\.tsx?$/.test(file) || file.includes("/__tests__/")) {
+      continue;
+    }
+    if (covered.has(file) || exempt[file])
+      continue;
+    orphans.push(file);
+  }
+  return orphans.sort();
+}
+async function evaluateCoverage(root, rows, config) {
+  const srcDir = config.srcDir ?? DEFAULT_SRC;
+  const { violations, staleExempts } = evaluateRows(rows, config);
+  const { missingExemptFiles, missingClaimedBy } = validateExemptions(root, config);
+  const orphans = await findOrphans(root, srcDir, new Set(rows.map((r) => r.file)), config);
+  return {
+    rowCount: rows.length,
+    violations,
+    staleExempts,
+    missingExemptFiles,
+    missingClaimedBy,
+    orphans,
+    enforced: config.defaultThreshold !== undefined
+  };
+}
+async function enforceCoverage(root, config, coverageText) {
+  const srcDir = config.srcDir ?? DEFAULT_SRC;
+  const text = coverageText ?? await runCoverage(root, config.testCwd ?? ".");
+  const rows = parseCoverageTable(text, srcDir);
+  return evaluateCoverage(root, rows, config);
+}
+function hasFailure(findings, strictOrphans) {
+  return findings.violations.length > 0 || findings.staleExempts.length > 0 || findings.missingExemptFiles.length > 0 || findings.missingClaimedBy.length > 0 || strictOrphans && findings.orphans.length > 0;
+}
+var DEFAULT_SRC = "src";
+var init_enforce = () => {};
+
+// tools/test/src/coverage-policy/discover.ts
+import { existsSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+function isCoverageConfig(value) {
+  return typeof value === "object" && value !== null;
+}
+async function importConfig(path) {
+  const mod = await import(path);
+  const candidate = mod["config"] ?? mod["default"];
+  if (!isCoverageConfig(candidate)) {
+    throw new Error(`${path} must export \`config\` (a CoverageConfig object)`);
+  }
+  return candidate;
+}
+async function loadCoverageConfig(root, explicitPath) {
+  if (explicitPath) {
+    const abs = isAbsolute(explicitPath) ? explicitPath : resolve(root, explicitPath);
+    if (!existsSync(abs))
+      throw new Error(`coverage config not found: ${abs}`);
+    return { config: await importConfig(abs), source: abs };
+  }
+  for (const name of ["coverage.config.ts", "coverage.config.js"]) {
+    const abs = join(root, name);
+    if (existsSync(abs))
+      return { config: await importConfig(abs), source: abs };
+  }
+  return { config: {}, source: null };
+}
+
+// tools/test/src/coverage-policy/index.ts
+init_enforce();
+
+// tools/test/src/coverage-policy/mutate-targets.ts
+import { existsSync as existsSync3, readFileSync } from "node:fs";
+import { join as join3, resolve as resolve3 } from "node:path";
+import { Glob as Glob2 } from "bun";
+async function findStrykerConfigs(root) {
+  const found = [];
+  const single = join3(root, "stryker.conf.json");
+  if (existsSync3(single))
+    found.push(single);
+  const glob = new Glob2("stryker/*.{json,conf.json}");
+  for await (const rel of glob.scan({ cwd: root, onlyFiles: true })) {
+    found.push(join3(root, rel));
+  }
+  return found.sort();
+}
+function isGlob(pattern) {
+  return pattern.includes("*") || pattern.includes("?") || pattern.includes("[");
+}
+async function resolvesToFile(pattern, cwd) {
+  if (pattern.startsWith("!"))
+    return true;
+  if (!isGlob(pattern))
+    return existsSync3(resolve3(cwd, pattern));
+  const glob = new Glob2(pattern);
+  for await (const _ of glob.scan({ cwd, onlyFiles: true }))
+    return true;
+  return false;
+}
+async function checkField(configPath, field, patterns, cwd) {
+  const issues = [];
+  for (const pattern of patterns ?? []) {
+    if (!await resolvesToFile(pattern, cwd)) {
+      issues.push({ config: configPath, field, pattern });
+    }
+  }
+  return issues;
+}
+async function validateMutateTargets(root) {
+  const configs = await findStrykerConfigs(root);
+  const issues = [];
+  for (const configPath of configs) {
+    const config = JSON.parse(readFileSync(configPath, "utf8"));
+    const testFiles = config.testFiles ?? config.bun?.testFiles;
+    issues.push(...await checkField(configPath, "mutate", config.mutate, root));
+    issues.push(...await checkField(configPath, "testFiles", testFiles, root));
+  }
+  return { configs, issues };
+}
+export {
+  validateMutateTargets,
+  runCoverage,
+  parseCoverageTable,
+  loadCoverageConfig,
+  hasFailure,
+  findStrykerConfigs,
+  evaluateCoverage,
+  enforceCoverage
+};
+
+//# debugId=046D33457FD03F6D64756E2164756E21

package/dist/tools/test/src/coverage-policy/index.js.map

@@ -0,0 +1,13 @@
+{
+  "version": 3,
+  "sources": ["../tools/test/src/coverage-policy/enforce.ts", "../tools/test/src/coverage-policy/discover.ts", "../tools/test/src/coverage-policy/index.ts", "../tools/test/src/coverage-policy/mutate-targets.ts"],
+  "sourcesContent": [
+    "/**\n * @fairfox/polly/test/coverage — the coverage-policy engine.\n *\n * Parses a `bun test --coverage` table and applies a {@link CoverageConfig}.\n * It fails on four conditions, not just low numbers: a non-exempt file below\n * the floor, an exempt key whose source no longer exists, an exemption whose\n * `claimedBy` test no longer exists, and an exempt file that has climbed back\n * over the floor (promote it). It also reports orphans — source files no unit\n * test imports, the blind spot a coverage table can't show.\n *\n * Everything here is parameterised by the project root, so the same engine\n * backs Polly's own gate and the consumer-facing `polly coverage` command.\n */\n\nimport { existsSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { Glob } from \"bun\";\nimport type { CoverageConfig } from \"./types\";\n\nexport interface CoverageRow {\n  /** Project-relative, e.g. `src/shared/lib/state.ts`. */\n  file: string;\n  funcs: number;\n  lines: number;\n}\n\nexport interface Violation {\n  file: string;\n  metric: \"lines\" | \"funcs\";\n  observed: number;\n  required: number;\n}\n\nexport interface CoverageFindings {\n  rowCount: number;\n  violations: Violation[];\n  staleExempts: string[];\n  missingExemptFiles: string[];\n  missingClaimedBy: Array<{ file: string; claimedBy: string }>;\n  orphans: string[];\n  /** True when a floor was configured; false means report-only. */\n  enforced: boolean;\n}\n\nconst DEFAULT_SRC = \"src\";\n\n/** `../src/foo.ts` (run from a subdir) → `src/foo.ts` (project-relative). */\nfunction normalizePath(raw: string): string {\n  return raw.replace(/^(?:\\.\\.\\/)+/, \"\");\n}\n\n/**\n * Parse the `bun test --coverage` table. Only rows under `srcDir` are\n * policy-bearing; the `All files` summary and test-infra rows are skipped.\n * Column order is `File | % Funcs | % Lines | Uncovered`.\n */\nexport function parseCoverageTable(text: string, srcDir: string): CoverageRow[] {\n  const prefix = `${srcDir}/`;\n  const rows: CoverageRow[] = [];\n  for (const line of text.split(\"\\n\")) {\n    if (!line.includes(\"|\")) continue;\n    if (line.includes(\"All files\") || line.includes(\"% Funcs\")) continue;\n    if (line.trim().startsWith(\"---\")) continue;\n\n    const cells = line.split(\"|\").map((c) => c.trim());\n    if (cells.length < 3) continue;\n\n    const file = normalizePath(cells[0] ?? \"\");\n    const funcs = Number(cells[1]);\n    const lines = Number(cells[2]);\n    if (!file.startsWith(prefix) || Number.isNaN(funcs) || Number.isNaN(lines)) continue;\n\n    rows.push({ file, funcs, lines });\n  }\n  return rows;\n}\n\n/** Run `bun test --coverage` in the configured cwd and return combined output. */\nexport async function runCoverage(root: string, testCwd: string): Promise<string> {\n  const proc = Bun.spawn([\"bun\", \"test\", \"--coverage\"], {\n    cwd: join(root, testCwd),\n    stdout: \"pipe\",\n    stderr: \"pipe\",\n  });\n  const [out, err] = await Promise.all([\n    new Response(proc.stdout).text(),\n    new Response(proc.stderr).text(),\n  ]);\n  await proc.exited;\n  if (proc.exitCode !== 0) {\n    throw new Error(`bun test --coverage exited ${proc.exitCode}\\n${err}`);\n  }\n  return `${out}\\n${err}`;\n}\n\nfunction evaluateRows(\n  rows: CoverageRow[],\n  config: CoverageConfig\n): { violations: Violation[]; staleExempts: string[] } {\n  const t = config.defaultThreshold;\n  const exempt = config.exempt ?? {};\n  const violations: Violation[] = [];\n  const staleExempts: string[] = [];\n  if (!t) return { violations, staleExempts };\n\n  for (const row of rows) {\n    if (exempt[row.file]) {\n      if (row.lines >= t.lines && row.funcs >= t.funcs) staleExempts.push(row.file);\n      continue;\n    }\n    if (row.lines < t.lines) {\n      violations.push({ file: row.file, metric: \"lines\", observed: row.lines, required: t.lines });\n    }\n    if (row.funcs < t.funcs) {\n      violations.push({ file: row.file, metric: \"funcs\", observed: row.funcs, required: t.funcs });\n    }\n  }\n  return { violations, staleExempts };\n}\n\nfunction validateExemptions(\n  root: string,\n  config: CoverageConfig\n): { missingExemptFiles: string[]; missingClaimedBy: Array<{ file: string; claimedBy: string }> } {\n  const missingExemptFiles: string[] = [];\n  const missingClaimedBy: Array<{ file: string; claimedBy: string }> = [];\n  for (const [file, entry] of Object.entries(config.exempt ?? {})) {\n    if (!existsSync(resolve(root, file))) missingExemptFiles.push(file);\n    const claimedBy = entry.claimedBy.trim();\n    if (!claimedBy.startsWith(\"n/a\") && !existsSync(resolve(root, claimedBy))) {\n      missingClaimedBy.push({ file, claimedBy });\n    }\n  }\n  return { missingExemptFiles, missingClaimedBy };\n}\n\n/** Source files no row covers and no exemption names — the coverage blind spot. */\nasync function findOrphans(\n  root: string,\n  srcDir: string,\n  covered: Set<string>,\n  config: CoverageConfig\n): Promise<string[]> {\n  const exempt = config.exempt ?? {};\n  const orphans: string[] = [];\n  const glob = new Glob(`${srcDir}/**/*.{ts,tsx}`);\n  for await (const file of glob.scan({ cwd: root, onlyFiles: true })) {\n    if (file.endsWith(\".d.ts\") || /\\.test\\.tsx?$/.test(file) || file.includes(\"/__tests__/\")) {\n      continue;\n    }\n    if (covered.has(file) || exempt[file]) continue;\n    orphans.push(file);\n  }\n  return orphans.sort();\n}\n\n/** Apply the policy to a parsed table. Pure — no spawning. */\nexport async function evaluateCoverage(\n  root: string,\n  rows: CoverageRow[],\n  config: CoverageConfig\n): Promise<CoverageFindings> {\n  const srcDir = config.srcDir ?? DEFAULT_SRC;\n  const { violations, staleExempts } = evaluateRows(rows, config);\n  const { missingExemptFiles, missingClaimedBy } = validateExemptions(root, config);\n  const orphans = await findOrphans(root, srcDir, new Set(rows.map((r) => r.file)), config);\n  return {\n    rowCount: rows.length,\n    violations,\n    staleExempts,\n    missingExemptFiles,\n    missingClaimedBy,\n    orphans,\n    enforced: config.defaultThreshold !== undefined,\n  };\n}\n\n/** Run the suite under coverage and apply the policy. */\nexport async function enforceCoverage(\n  root: string,\n  config: CoverageConfig,\n  coverageText?: string\n): Promise<CoverageFindings> {\n  const srcDir = config.srcDir ?? DEFAULT_SRC;\n  const text = coverageText ?? (await runCoverage(root, config.testCwd ?? \".\"));\n  const rows = parseCoverageTable(text, srcDir);\n  return evaluateCoverage(root, rows, config);\n}\n\n/** True when the findings represent a policy failure (orphans are advisory\n *  unless `strictOrphans`). */\nexport function hasFailure(findings: CoverageFindings, strictOrphans: boolean): boolean {\n  return (\n    findings.violations.length > 0 ||\n    findings.staleExempts.length > 0 ||\n    findings.missingExemptFiles.length > 0 ||\n    findings.missingClaimedBy.length > 0 ||\n    (strictOrphans && findings.orphans.length > 0)\n  );\n}\n",
+    "/**\n * @fairfox/polly/test/coverage — zero-config loading.\n *\n * `polly coverage` runs without any config: it looks for a `coverage.config.ts`\n * (or `.js`) at the project root, and if there is none it returns an empty\n * config, which the engine treats as report-only — it prints the numbers and\n * the orphan count but never fails the build. A consumer opts into enforcement\n * by adding a `defaultThreshold`, and into legible tiering by adding `exempt`\n * entries. This mirrors how `polly test --tier` discovers tiers by convention.\n */\n\nimport { existsSync } from \"node:fs\";\nimport { isAbsolute, join, resolve } from \"node:path\";\nimport type { CoverageConfig } from \"./types\";\n\nexport interface LoadedConfig {\n  config: CoverageConfig;\n  /** Absolute path the config was loaded from, or null for the zero-config default. */\n  source: string | null;\n}\n\nfunction isCoverageConfig(value: unknown): value is CoverageConfig {\n  return typeof value === \"object\" && value !== null;\n}\n\nasync function importConfig(path: string): Promise<CoverageConfig> {\n  const mod: Record<string, unknown> = await import(path);\n  const candidate = mod[\"config\"] ?? mod[\"default\"];\n  if (!isCoverageConfig(candidate)) {\n    throw new Error(`${path} must export \\`config\\` (a CoverageConfig object)`);\n  }\n  return candidate;\n}\n\n/**\n * Resolve the coverage config. With `explicitPath` (Polly's own front-end\n * passes scripts/coverage.config.ts) that file must exist. Otherwise look for\n * coverage.config.{ts,js} at the root; absent → the zero-config report-only\n * default.\n */\nexport async function loadCoverageConfig(\n  root: string,\n  explicitPath?: string\n): Promise<LoadedConfig> {\n  if (explicitPath) {\n    const abs = isAbsolute(explicitPath) ? explicitPath : resolve(root, explicitPath);\n    if (!existsSync(abs)) throw new Error(`coverage config not found: ${abs}`);\n    return { config: await importConfig(abs), source: abs };\n  }\n\n  for (const name of [\"coverage.config.ts\", \"coverage.config.js\"]) {\n    const abs = join(root, name);\n    if (existsSync(abs)) return { config: await importConfig(abs), source: abs };\n  }\n  return { config: {}, source: null };\n}\n",
+    "/**\n * @fairfox/polly/test/coverage — programmatic API behind `polly coverage`.\n *\n * Use the CLI (`polly coverage`) for the common case; import these to script\n * the policy yourself or to add a coverage tier to a custom runner.\n */\n\nexport { type LoadedConfig, loadCoverageConfig } from \"./discover\";\nexport {\n  type CoverageFindings,\n  type CoverageRow,\n  enforceCoverage,\n  evaluateCoverage,\n  hasFailure,\n  parseCoverageTable,\n  runCoverage,\n  type Violation,\n} from \"./enforce\";\nexport {\n  findStrykerConfigs,\n  type MutateTargetIssue,\n  type MutateTargetReport,\n  validateMutateTargets,\n} from \"./mutate-targets\";\nexport type { CoverageConfig, ExemptEntry, FileThreshold } from \"./types\";\n",
+    "/**\n * @fairfox/polly/test/coverage — Stryker mutate-/test-target validation.\n *\n * A Stryker config's `mutate` and `testFiles` lists are hand-curated. A path\n * that is renamed, or a glob whose directory moves, silently resolves to\n * nothing — Stryker mutates fewer files (or none) and the only signal is a\n * long mutation run whose score quietly drops. This asserts, in milliseconds,\n * that every entry still resolves to at least one file.\n *\n * Discovers configs two ways, covering both layouts in the wild: a single\n * `stryker.conf.json` at the root, and a `stryker/` directory of per-package\n * shards.\n */\n\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { Glob } from \"bun\";\n\ninterface StrykerConfig {\n  mutate?: string[];\n  testFiles?: string[];\n  bun?: { testFiles?: string[] };\n}\n\nexport interface MutateTargetIssue {\n  config: string;\n  field: \"mutate\" | \"testFiles\";\n  pattern: string;\n}\n\nexport interface MutateTargetReport {\n  configs: string[];\n  issues: MutateTargetIssue[];\n}\n\n/** Locate every Stryker config under the project root. */\nexport async function findStrykerConfigs(root: string): Promise<string[]> {\n  const found: string[] = [];\n  const single = join(root, \"stryker.conf.json\");\n  if (existsSync(single)) found.push(single);\n\n  const glob = new Glob(\"stryker/*.{json,conf.json}\");\n  for await (const rel of glob.scan({ cwd: root, onlyFiles: true })) {\n    found.push(join(root, rel));\n  }\n  return found.sort();\n}\n\nfunction isGlob(pattern: string): boolean {\n  return pattern.includes(\"*\") || pattern.includes(\"?\") || pattern.includes(\"[\");\n}\n\nasync function resolvesToFile(pattern: string, cwd: string): Promise<boolean> {\n  if (pattern.startsWith(\"!\")) return true; // negations are filters, not targets\n  if (!isGlob(pattern)) return existsSync(resolve(cwd, pattern));\n  const glob = new Glob(pattern);\n  for await (const _ of glob.scan({ cwd, onlyFiles: true })) return true;\n  return false;\n}\n\nasync function checkField(\n  configPath: string,\n  field: \"mutate\" | \"testFiles\",\n  patterns: string[] | undefined,\n  cwd: string\n): Promise<MutateTargetIssue[]> {\n  const issues: MutateTargetIssue[] = [];\n  for (const pattern of patterns ?? []) {\n    if (!(await resolvesToFile(pattern, cwd))) {\n      issues.push({ config: configPath, field, pattern });\n    }\n  }\n  return issues;\n}\n\n/**\n * Validate every Stryker config under `root`. Paths in a Stryker config are\n * relative to that config's directory; for the monorepo-root configs that is\n * the root, so we resolve globs against `root`.\n */\nexport async function validateMutateTargets(root: string): Promise<MutateTargetReport> {\n  const configs = await findStrykerConfigs(root);\n  const issues: MutateTargetIssue[] = [];\n  for (const configPath of configs) {\n    const config = JSON.parse(readFileSync(configPath, \"utf8\")) as unknown as StrykerConfig;\n    const testFiles = config.testFiles ?? config.bun?.testFiles;\n    issues.push(...(await checkField(configPath, \"mutate\", config.mutate, root)));\n    issues.push(...(await checkField(configPath, \"testFiles\", testFiles, root)));\n  }\n  return { configs, issues };\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "046D33457FD03F6D64756E2164756E21",
+  "names": []
+}

package/dist/tools/test/src/coverage-policy/mutate-targets.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @fairfox/polly/test/coverage — Stryker mutate-/test-target validation.
+ *
+ * A Stryker config's `mutate` and `testFiles` lists are hand-curated. A path
+ * that is renamed, or a glob whose directory moves, silently resolves to
+ * nothing — Stryker mutates fewer files (or none) and the only signal is a
+ * long mutation run whose score quietly drops. This asserts, in milliseconds,
+ * that every entry still resolves to at least one file.
+ *
+ * Discovers configs two ways, covering both layouts in the wild: a single
+ * `stryker.conf.json` at the root, and a `stryker/` directory of per-package
+ * shards.
+ */
+export interface MutateTargetIssue {
+    config: string;
+    field: "mutate" | "testFiles";
+    pattern: string;
+}
+export interface MutateTargetReport {
+    configs: string[];
+    issues: MutateTargetIssue[];
+}
+/** Locate every Stryker config under the project root. */
+export declare function findStrykerConfigs(root: string): Promise<string[]>;
+/**
+ * Validate every Stryker config under `root`. Paths in a Stryker config are
+ * relative to that config's directory; for the monorepo-root configs that is
+ * the root, so we resolve globs against `root`.
+ */
+export declare function validateMutateTargets(root: string): Promise<MutateTargetReport>;

package/dist/tools/test/src/coverage-policy/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fairfox/polly/test/coverage — the per-file coverage policy a consumer can
+ * declare. Every field is optional so the tool runs zero-config: with no
+ * `coverage.config.ts` the enforcer reports numbers and orphans without
+ * failing; add a `defaultThreshold` to start enforcing, and `exempt` entries
+ * to record which higher-tier test covers a unit-thin file.
+ */
+export interface FileThreshold {
+    /** Minimum `% Lines` from the `bun test --coverage` table. */
+    lines: number;
+    /** Minimum `% Funcs` from the `bun test --coverage` table. */
+    funcs: number;
+}
+export interface ExemptEntry {
+    /** Why this file is thin at the unit tier. */
+    reason: string;
+    /**
+     * Package-relative path to the test or script that exercises this file at a
+     * higher tier. Verified to exist by the enforcer. Use the `'n/a — <reason>'`
+     * form for genuine waivers (extension-only shims, browser-only geometry).
+     */
+    claimedBy: string;
+}
+export interface CoverageConfig {
+    /** Per-file floor. Omit to run report-only (numbers + orphans, never fails). */
+    defaultThreshold?: FileThreshold;
+    /** Files below the floor that are covered at a higher tier, keyed by
+     *  source path relative to the project root (e.g. `src/shared/lib/x.ts`). */
+    exempt?: Record<string, ExemptEntry>;
+    /** Source directory to police, relative to the project root. Default `src`. */
+    srcDir?: string;
+    /** Directory to run `bun test --coverage` in, relative to the project root.
+     *  Default `.` (the root). Polly itself runs its suite from `tests`. */
+    testCwd?: string;
+}

package/dist/tools/test/src/e2e-mesh/index.js

@@ -1010,6 +1010,21 @@ ${logs}`);
     }
   };
 }
+// tools/test/src/e2e-shared/timeout-context.ts
+async function resolveContext(context) {
+  if (!context)
+    return "";
+  try {
+    return `
+
+transport: ${await context()}`;
+  } catch (err) {
+    return `
+
+transport: <context threw: ${err instanceof Error ? err.message : String(err)}>`;
+  }
+}
+
 // tools/test/src/e2e-mesh/wait-for-convergence.ts
 async function readPeerSnapshot(peer) {
   return peer.page.evaluate(() => {
@@ -1033,8 +1048,9 @@ async function waitForConvergence(peers, predicate, options = {}) {
   }
   const summary = lastSnapshots.map((s) => `  ${s.peerId}: status="${s.status}" peerCount=${s.peerCount} items=${JSON.stringify(s.items)}`).join(`
 `);
+  const transport = await resolveContext(options.context);
   throw new Error(`waitForConvergence: predicate did not hold for every peer within ${timeoutMs}ms.
-${summary}`);
+${summary}${transport}`);
 }
 async function waitForMeshConnected(peers, options = {}) {
   const minPeers = peers.length - 1;
@@ -1209,4 +1225,4 @@ export {
   MESH_CONSOLE_ALLOWLIST
 };
 
-//# debugId=DBF39E19E602FCC464756E2164756E21
+//# debugId=3188CA6C80D67D2E64756E2164756E21