@fairfox/polly 0.91.0 → 0.92.1

package/dist/tools/mutate/src/config.d.ts

@@ -1,8 +1,19 @@
 import type { MutateArgs } from "./args.ts";
+import { type MutationConfig } from "./define.ts";
+export interface LoadedMutationConfig {
+    path: string;
+    /** "stryker": read from a Stryker JSON through the migration mapping (deprecated). */
+    format: "polly" | "stryker";
+    config: MutationConfig;
+    /** Migration notes (stryker format only). */
+    notes: string[];
+}
 export interface MutateConfig {
     cwd: string;
-    /** The Stryker config to use — explicit `--config`, else the first discovered. Null if none found. */
-    strykerConfigPath: string | null;
+    /** The config the bun engine runs from. Null if none was found or it failed to load. */
+    mutation: LoadedMutationConfig | null;
+    /** Why a Stryker config found as the fallback could not be mapped (fatal only when the engine runs). */
+    mutationError: string | null;
     /** mutation-testing-report-schema JSON the analysis reads. */
     reportPath: string;
     /** Intermediate SQLite db (":memory:" by default; a path persists it). */

package/dist/tools/mutate/src/define.d.ts

@@ -0,0 +1,76 @@
+import type { ContractsMode, CoverageMode, EngineMode, MutatorName } from "./engine/types.ts";
+export declare const MUTATION_CONFIG_FILE = "polly.mutate.ts";
+export interface MutationTests {
+    /** Test-file globs. The engine runs only the files whose imports reach a target. */
+    include: string[];
+    /** Project preloads, passed to `bun test` before the injection preload. */
+    preload?: string[];
+}
+export interface CommandRunner {
+    kind: "command";
+    /**
+     * The command, run once per mutant in the config dir; non-zero exit kills
+     * the mutant. Every Bun process it starts gets the injection preload via
+     * BUN_OPTIONS. No test selection, fast mode only.
+     */
+    argv: string[];
+}
+interface MutationCommon {
+    /** Files to mutate: globs, `!` exclusions, and `file.ts:10-20` line ranges. */
+    targets: string[];
+    /** fast stops at the first failing test; matrix records every killer. Default fast. */
+    mode?: EngineMode;
+    /**
+     * dynamic: one probed pass over every test file finds the tests that run
+     * each mutant; a mutant no test runs is NoCoverage. static: the test files
+     * that import the target. Default dynamic; the command runner is always static.
+     */
+    coverage?: CoverageMode;
+    /** Parallel test processes. Default: cores − 1. */
+    concurrency?: number;
+    /** Per-mutant timeout = baseline × factor + extraMs. Default 2 / 3000. */
+    timeout?: {
+        factor: number;
+        extraMs: number;
+    };
+    mutators?: {
+        exclude?: MutatorName[];
+    };
+    /**
+     * Report mutants the project's TypeScript config rejects as CompileError,
+     * never run (TypeScript 7 through the `typescript-7` dependency). Default true.
+     */
+    typecheck?: boolean;
+    /** Report mutants inside requires/ensures/… as Ignored (polly#143). Default true. */
+    ignoreVerifyCallsites?: boolean;
+    /**
+     * POLLY_CONTRACTS for every test process: a false requires/ensures throws,
+     * so each contract kills the mutants that falsify it. off keeps them
+     * no-ops; ensures enforces postconditions only. Default all.
+     */
+    contracts?: ContractsMode;
+    /** `polly mutate run` exits 1 when the score is below `break`. */
+    thresholds?: {
+        break?: number;
+    };
+    /** Report path. Default reports/mutation/mutation.json. */
+    report?: string;
+    /** Verdict log. Default .polly/test-debt/decisions.jsonl. */
+    decisions?: string;
+}
+export type MutationConfig = MutationCommon & ({
+    runner?: {
+        kind: "bun-test";
+    };
+    tests: MutationTests;
+} | {
+    runner: CommandRunner;
+    tests?: undefined;
+});
+export declare function defineMutation(config: MutationConfig): MutationConfig;
+export declare function isContractsMode(v: unknown): v is ContractsMode;
+/** Validate a loaded config's default export. `where` names the file in errors. */
+export declare function parseMutationConfig(raw: unknown, where: string): MutationConfig;
+/** Import a `polly.mutate.ts` (or `.js`) and validate its default export. */
+export declare function loadMutationConfig(path: string): Promise<MutationConfig>;
+export {};

package/dist/tools/mutate/src/engine/ast.d.ts

@@ -0,0 +1,13 @@
+export interface AstNode {
+    type: string;
+    start: number;
+    end: number;
+    [key: string]: unknown;
+}
+export declare function isAstNode(value: unknown): value is AstNode;
+/** The child node under `key`, or undefined when absent or not a node. */
+export declare function child(node: AstNode, key: string): AstNode | undefined;
+export declare function children(node: AstNode, key: string): AstNode[];
+export declare function stringField(node: AstNode, key: string): string | undefined;
+/** `foo(...)` → "foo"; `verify.foo(...)` → "foo"; computed access is not resolved. */
+export declare function calleeName(call: AstNode): string | undefined;

package/dist/tools/mutate/src/engine/baseline.d.ts

@@ -0,0 +1,20 @@
+import { type ContractKill } from "./junit.ts";
+import type { EngineConfig, TestRef } from "./types.ts";
+import { type Workdirs } from "./workdir.ts";
+export interface Baseline {
+    ok: boolean;
+    ms: number;
+    reason?: string;
+    /** The target's tests need the project cwd, so its mutants run there. */
+    inTree: boolean;
+    /** Matrix mode: the tests that ran. */
+    tests: TestRef[];
+    /** Matrix mode: test files that reported at least one case. */
+    reportedFiles: Set<string>;
+    /** Contracts on: the tests (or the command) that fail through a contract. */
+    contractViolations?: ContractKill[];
+}
+export declare function measureBaseline(cfg: EngineConfig, workdirs: Workdirs | null, preloads: string[], target: {
+    file: string;
+    covering: string[];
+}, log: (line: string) => void): Promise<Baseline>;

package/dist/tools/mutate/src/engine/cache.d.ts

@@ -0,0 +1,32 @@
+import type { Coverage } from "./coverage.ts";
+import type { Mutant, MutantResult, MutantStatus, TestRef } from "./types.ts";
+/** Bump when the runner's semantics change in a way the key does not capture. */
+export declare const CACHE_VERSION = 2;
+export interface CachedResult {
+    sig: string;
+    status: MutantStatus;
+    statusReason?: string;
+    durationMs?: number;
+    killedBy?: string[];
+    coveredBy?: string[];
+    killedByContract?: string[];
+    contractOnly?: boolean;
+}
+export interface CacheEntry {
+    baselineMs: number;
+    inTree: boolean;
+    tests: TestRef[];
+    results: CachedResult[];
+}
+export declare function mutantSig(m: Pick<Mutant, "start" | "end" | "replacement" | "mutatorName">): string;
+export declare function cacheKey(input: {
+    mutants: readonly Mutant[];
+    closure: readonly string[];
+    projectFiles: readonly string[];
+    settings: unknown;
+}): Promise<string>;
+export declare function readCache(dir: string, key: string): Promise<CacheEntry | null>;
+export declare function writeCache(dir: string, key: string, entry: CacheEntry): void;
+export declare function writeCoverageCache(dir: string, key: string, coverage: Coverage): void;
+export declare function readCoverageCache(dir: string, key: string): Promise<Coverage | null>;
+export declare function cachedResult(r: MutantResult): CachedResult;

package/dist/tools/mutate/src/engine/coverage.d.ts

@@ -0,0 +1,60 @@
+import type { ContractsMode, Mutant, TestRef } from "./types.ts";
+import { type Workdirs } from "./workdir.ts";
+/** Bump when attribution changes; part of the coverage cache key. */
+export declare const COVERAGE_VERSION = 1;
+export interface MutantCoverage {
+    /** Test ids that ran the mutant's code inside the test body or its hooks. */
+    tests: string[];
+    /** Test files to run whole: hits between tests, unordered files, static mutants. */
+    files: string[];
+}
+export type TargetCoverage = {
+    kind: "dynamic";
+    mutants: Record<string, MutantCoverage>;
+} | {
+    kind: "static";
+    reason: string;
+};
+export interface CoverageTest extends TestRef {
+    /** The full name `bun test -t` matches. */
+    filterName: string;
+}
+export interface Coverage {
+    targets: TargetCoverage[];
+    /** Every test the pass ran (not skipped), by id. */
+    tests: Record<string, CoverageTest>;
+    /** Test file → ids of its tests. */
+    byFile: Record<string, string[]>;
+}
+export interface CoverageTarget {
+    file: string;
+    /** Mutants to probe (ignored ones are left out). */
+    mutants: readonly Mutant[];
+    /** Static selection: test files whose import closure reaches the target. */
+    covering: readonly string[];
+}
+export interface CoverageRun {
+    cwd: string;
+    testFiles: readonly string[];
+    targets: readonly CoverageTarget[];
+    /** Project preloads, then the engine preload. */
+    preloads: string[];
+    concurrency: number;
+    /** Scratch cwds (workdir.ts); null runs in `cwd`. */
+    workdirs: Workdirs | null;
+    /** POLLY_CONTRACTS for the pass, as for every other run. */
+    contracts: ContractsMode;
+    log: (line: string) => void;
+}
+/** Contiguous slices, so neighbouring files still share a process as in a full run. */
+export declare function chunk<T>(items: readonly T[], n: number): T[][];
+/** Run the pass. Null when a process wrote no data: every target then keeps static selection. */
+export declare function collectCoverage(run: CoverageRun): Promise<Coverage | null>;
+export interface Selection {
+    /** Test files to pass to `bun test`; empty means NoCoverage. */
+    files: string[];
+    /** `bun test -t`, when every selected test is named. */
+    namePattern?: string;
+    coveredBy: string[];
+}
+export declare function selectionFor(cov: MutantCoverage, coverage: Coverage): Selection;

package/dist/tools/mutate/src/engine/generate.d.ts

@@ -0,0 +1,23 @@
+import type { ContractSite, Mutant, MutatorName, Position } from "./types.ts";
+export interface GenerateOptions {
+    ignoreVerifyCallsites?: boolean;
+    /** Keep only mutants that start inside this 1-based inclusive line range. */
+    lines?: {
+        from: number;
+        to: number;
+    };
+    /** Prefix for mutant ids, so ids stay unique across files in one report. */
+    idPrefix?: string;
+    /** Mutators whose edits are dropped (polly.mutate.ts `mutators.exclude`). */
+    exclude?: readonly MutatorName[];
+}
+export interface GenerateResult {
+    mutants: Mutant[];
+    /** Mutants whose mutated text no longer parses. Reported, never run. */
+    compileErrors: Mutant[];
+    /** Every requires/ensures call, whole file, whatever `lines` and the ignore flag say. */
+    contracts: ContractSite[];
+}
+export declare function lineIndex(src: string): (offset: number) => Position;
+export declare function applyMutant(src: string, m: Pick<Mutant, "start" | "end" | "replacement">): string;
+export declare function generateMutants(file: string, src: string, opts?: GenerateOptions): GenerateResult;

package/dist/tools/mutate/src/engine/graph.d.ts

@@ -0,0 +1,11 @@
+export interface ImportGraph {
+    testFiles: string[];
+    /** file → files it imports (absolute, symlink-resolved). */
+    imports: Map<string, string[]>;
+}
+export declare function findTestFiles(cwd: string, include: string[]): Promise<string[]>;
+export declare function buildImportGraph(testFiles: string[]): Promise<ImportGraph>;
+/** Test files whose import closure contains `target`, sorted. */
+export declare function coveringTests(graph: ImportGraph, target: string): string[];
+/** Every project file `files` load, themselves included, sorted. */
+export declare function closureOf(graph: ImportGraph, files: readonly string[]): string[];

package/dist/tools/mutate/src/engine/index.d.ts

@@ -0,0 +1,16 @@
+import type { EngineConfig, EngineResult, MutantResult } from "./types.ts";
+export { collectCoverage, selectionFor } from "./coverage.ts";
+export { applyMutant, generateMutants } from "./generate.ts";
+export { buildImportGraph, coveringTests, findTestFiles } from "./graph.ts";
+export { toMutationReport, writeReport } from "./report-writer.ts";
+export { newPaths, snapshotWorktree } from "./stray-writes.ts";
+export { typecheckMutants } from "./typecheck.ts";
+export type * from "./types.ts";
+export { VERIFY_PRIMITIVES } from "./verify-callsites.ts";
+export interface EngineHooks {
+    log?: (line: string) => void;
+    progress?: (done: number, total: number) => void;
+}
+export declare function runEngine(cfg: EngineConfig, hooks?: EngineHooks): Promise<EngineResult>;
+/** Stryker's score: detected / (detected + undetected); ignored and invalid mutants do not count. */
+export declare function mutationScore(results: readonly MutantResult[]): number | null;

package/dist/tools/mutate/src/engine/junit.d.ts

@@ -0,0 +1,38 @@
+export interface JunitCase {
+    /** Absolute path of the test file. */
+    file: string;
+    /** describe path and test name, outermost first, joined with " > ". */
+    name: string;
+    /** The same path joined with spaces: the full name `bun test -t` matches. */
+    filterName: string;
+    line: number;
+    status: "passed" | "failed" | "skipped";
+    /** A failed case: the `<failure>` message attribute and body, decoded. */
+    failureMessage?: string;
+}
+/** `cwd` is the directory `bun test` ran in: Bun writes `file` relative to it when it can. */
+export declare function parseJunit(xml: string, cwd: string): JunitCase[];
+/** `<file relative to the project>#<full name>@<line>`. */
+export declare function testId(projectCwd: string, file: string, name: string, line: number): string;
+/**
+ * The marker a ContractViolation's message starts with (verify primitives):
+ * `[polly-contract ensures /abs/handlers.ts:50] the author's message`.
+ */
+export declare const CONTRACT_MARKER: RegExp;
+/** Contract ids (`<file relative to the project>:<line>`) named in a failure text, sorted unique. */
+export declare function contractsIn(text: string, projectCwd: string): string[];
+export interface ContractKill {
+    /** junit.ts `testId` of the failed case. */
+    test: string;
+    contracts: string[];
+}
+/** Each failed case whose failure names a contract, with the contracts it names. */
+export declare function contractKills(cases: readonly JunitCase[], projectCwd: string): ContractKill[];
+export declare const LOAD_FAILURE_NAME = "(file produced no results)";
+export declare function loadFailureId(projectCwd: string, file: string): string;
+/**
+ * The tests that detected a mutant: every failed case, plus a stand-in for
+ * each file the baseline reported that this run did not (it threw while
+ * loading, or the process died first). Empty when the process failed for a reason no test file explains.
+ */
+export declare function killers(cases: readonly JunitCase[], baselineFiles: ReadonlySet<string>, projectCwd: string): string[];

package/dist/tools/mutate/src/engine/operators.d.ts

@@ -0,0 +1,14 @@
+import { type AstNode } from "./ast.ts";
+import type { MutatorName } from "./types.ts";
+export interface OperatorContext {
+    src: string;
+    parent: AstNode | undefined;
+    /** The key under which `node` hangs off `parent` (e.g. "test", "key"). */
+    key: string;
+    /** Every ancestor, outermost first; the last entry is `parent`. */
+    ancestors: readonly AstNode[];
+    emit(start: number, end: number, replacement: string, mutator: MutatorName): void;
+}
+type Operator = (node: AstNode, ctx: OperatorContext) => void;
+export declare const OPERATORS: readonly Operator[];
+export {};

package/dist/tools/mutate/src/engine/preload.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The mutated text, with the line count kept: a replacement that drops lines
+ * (an emptied block, object or arrow body) is followed by a comment holding
+ * them, so a contract after it still reports its own `file:line`.
+ */
+export declare function mutatedText(src: string, span: {
+    start: number;
+    end: number;
+    replacement: string;
+}): string;

package/dist/tools/mutate/src/engine/preload.js

@@ -0,0 +1,180 @@
+// tools/mutate/src/engine/preload.ts
+import { readFileSync, writeFileSync } from "node:fs";
+import { plugin } from "bun";
+var target = process.env["POLLY_MUTATE_FILE"];
+var rawSpan = process.env["POLLY_MUTATE_SPAN"];
+var coveragePlan = process.env["POLLY_MUTATE_COVERAGE"];
+var coverageOut = process.env["POLLY_MUTATE_COVERAGE_OUT"];
+function loaderFor(file) {
+  if (file.endsWith(".tsx"))
+    return "tsx";
+  if (file.endsWith(".jsx"))
+    return "jsx";
+  return /\.[cm]?ts$/.test(file) ? "ts" : "js";
+}
+function exactly(paths) {
+  const escaped = paths.map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  return new RegExp(`^(?:${escaped.join("|")})$`);
+}
+function parseSpan(raw) {
+  const value = JSON.parse(raw);
+  if (typeof value === "object" && value !== null && "start" in value && "end" in value && "replacement" in value && typeof value.start === "number" && typeof value.end === "number" && typeof value.replacement === "string") {
+    return { start: value.start, end: value.end, replacement: value.replacement };
+  }
+  throw new Error(`polly mutate preload: malformed POLLY_MUTATE_SPAN: ${raw}`);
+}
+function newlines(s) {
+  let n = 0;
+  for (let i = 0;i < s.length; i++)
+    if (s.charCodeAt(i) === 10)
+      n++;
+  return n;
+}
+function mutatedText(src, span) {
+  const lost = newlines(src.slice(span.start, span.end)) - newlines(span.replacement);
+  const pad = lost > 0 ? `/*${`
+`.repeat(lost)}*/` : "";
+  return src.slice(0, span.start) + span.replacement + pad + src.slice(span.end);
+}
+if (target && rawSpan) {
+  const span = parseSpan(rawSpan);
+  const src = await Bun.file(target).text();
+  const contents = mutatedText(src, span);
+  const loader = loaderFor(target);
+  plugin({
+    name: "polly-mutate",
+    setup(build) {
+      build.onLoad({ filter: exactly([target]) }, () => ({ contents, loader }));
+    }
+  });
+}
+var CONTRACT_VIOLATIONS_KEY = "__pollyContractViolations";
+function violationMessages() {
+  const list = globalThis[CONTRACT_VIOLATIONS_KEY];
+  if (!Array.isArray(list))
+    return [];
+  const messages = list.map((v) => v instanceof Error ? v.message : String(v));
+  list.length = 0;
+  return messages;
+}
+var contracts = process.env["POLLY_CONTRACTS"];
+if (contracts === "ensures" || contracts === "all") {
+  try {
+    const { afterEach, beforeEach } = await import("bun:test");
+    beforeEach(() => {
+      for (const m of violationMessages()) {
+        process.stderr.write(`polly mutate: contract violated outside any test: ${m}
+`);
+      }
+    });
+    afterEach(() => {
+      const messages = violationMessages();
+      if (messages.length > 0)
+        throw new Error(messages.join(`
+`));
+    });
+  } catch {}
+}
+function isStringList(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+function parsePlan(raw) {
+  const value = JSON.parse(raw);
+  if (typeof value === "object" && value !== null && "targets" in value && "tests" in value && Array.isArray(value.targets) && isStringList(value.tests)) {
+    const targets = [];
+    for (const t of value.targets) {
+      if (typeof t === "object" && t !== null && "file" in t && "code" in t && typeof t.file === "string" && typeof t.code === "string") {
+        targets.push({ file: t.file, code: t.code });
+      } else
+        throw new Error("polly mutate preload: malformed coverage plan target");
+    }
+    return { targets, tests: value.tests };
+  }
+  throw new Error("polly mutate preload: malformed coverage plan");
+}
+if (coveragePlan && coverageOut) {
+  const plan = parsePlan(readFileSync(coveragePlan, "utf8"));
+  const { afterAll, afterEach, beforeEach } = await import("bun:test");
+  const files = plan.tests.map(() => ({
+    load: new Set,
+    between: new Set,
+    tests: [],
+    overlapped: false
+  }));
+  const outside = new Set;
+  const served = new Set;
+  let current = outside;
+  let file;
+  let running = 0;
+  Object.assign(globalThis, {
+    __pollyMutateHit(probe) {
+      current.add(probe);
+    },
+    __pollyMutateFile(index) {
+      file = files[index];
+      running = 0;
+      current = file?.load ?? outside;
+    }
+  });
+  beforeEach(() => {
+    if (!file)
+      return;
+    running++;
+    if (running > 1)
+      file.overlapped = true;
+    const hits = new Set;
+    file.tests.push(hits);
+    current = hits;
+  });
+  afterEach(() => {
+    if (!file)
+      return;
+    running--;
+    current = file.between;
+  });
+  afterAll(() => {
+    const list = (s) => [...s];
+    writeFileSync(coverageOut, JSON.stringify({
+      served: list(served),
+      outside: list(outside),
+      files: files.map((f) => ({
+        load: list(f.load),
+        between: list(f.between),
+        tests: f.tests.map(list),
+        overlapped: f.overlapped
+      }))
+    }));
+  });
+  const targetIndex = new Map(plan.targets.map((t, i) => [t.file, i]));
+  const testIndex = new Map(plan.tests.map((t, i) => [t, i]));
+  plugin({
+    name: "polly-mutate-coverage",
+    setup(build) {
+      for (const i of testIndex.values()) {
+        build.module(`polly-mutate-mark:${i}`, () => ({
+          contents: `globalThis.__pollyMutateFile?.(${i});`,
+          loader: "js"
+        }));
+      }
+      build.onLoad({ filter: exactly([...targetIndex.keys(), ...testIndex.keys()]) }, (args) => {
+        const loader = loaderFor(args.path);
+        const t = targetIndex.get(args.path);
+        const planned = t === undefined ? undefined : plan.targets[t];
+        if (t !== undefined && planned) {
+          served.add(t);
+          return { contents: planned.code, loader };
+        }
+        const src = readFileSync(args.path, "utf8");
+        const mark = `import "polly-mutate-mark:${testIndex.get(args.path)}";`;
+        const cut = src.startsWith("#!") ? src.indexOf(`
+`) + 1 : 0;
+        return { contents: src.slice(0, cut) + mark + src.slice(cut), loader };
+      });
+    }
+  });
+}
+export {
+  mutatedText
+};
+
+//# debugId=679EED02066D37BE64756E2164756E21

package/dist/tools/mutate/src/engine/preload.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../tools/mutate/src/engine/preload.ts"],
+  "sourcesContent": [
+    "/**\n * The engine's preload, passed to `bun test --preload` by the runner. Two modes.\n *\n * Mutant (POLLY_MUTATE_FILE + POLLY_MUTATE_SPAN): a Bun plugin whose onLoad\n * answers for exactly that file with the mutated text. Nothing is copied and\n * no other file is touched. With neither variable set it does nothing, which\n * is how the runner measures each target's baseline.\n *\n * Coverage (POLLY_MUTATE_COVERAGE, a plan written by coverage.ts): every\n * target loads with its probes (probes.ts), every test file loads behind a\n * marker import that names it, and global beforeEach/afterEach hooks split\n * the hits into buckets — while a file loads, inside each test (by ordinal),\n * and between tests. A global afterAll writes the buckets to\n * POLLY_MUTATE_COVERAGE_OUT; coverage.ts matches the ordinals to the junit\n * report. The marker is an import, not a statement, because a test file's\n * imports run before its first statement.\n *\n * A separate build entrypoint: the runner spawns it by path, so it must exist\n * as its own file in dist (see build-lib.ts). It imports only built-ins.\n *\n * CLI `--preload` adds to a bunfig `[test].preload`, so the project's own\n * preloads still run. One limit: a file that a project preload imports is\n * already loaded before this plugin registers, so it cannot be mutated.\n *\n * Contracts (POLLY_CONTRACTS, set by the runner): the verify primitives\n * record each violation on globalThis before throwing, because the message\n * bus turns a handler's throw into `{ success: false }` and the test may\n * never see it. A global afterEach fails the test that left a violation\n * behind; a beforeEach clears what module load or beforeAll left, since that\n * belongs to no test. Under the command runner `bun:test` is absent and the\n * BDD runner drains the list itself.\n */\nimport { readFileSync, writeFileSync } from \"node:fs\";\nimport { plugin } from \"bun\";\n\nconst target = process.env[\"POLLY_MUTATE_FILE\"];\nconst rawSpan = process.env[\"POLLY_MUTATE_SPAN\"];\nconst coveragePlan = process.env[\"POLLY_MUTATE_COVERAGE\"];\nconst coverageOut = process.env[\"POLLY_MUTATE_COVERAGE_OUT\"];\n\nfunction loaderFor(file: string): \"tsx\" | \"jsx\" | \"ts\" | \"js\" {\n  if (file.endsWith(\".tsx\")) return \"tsx\";\n  if (file.endsWith(\".jsx\")) return \"jsx\";\n  return /\\.[cm]?ts$/.test(file) ? \"ts\" : \"js\";\n}\n\nfunction exactly(paths: readonly string[]): RegExp {\n  const escaped = paths.map((p) => p.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\"));\n  return new RegExp(`^(?:${escaped.join(\"|\")})$`);\n}\n\nfunction parseSpan(raw: string): { start: number; end: number; replacement: string } {\n  const value: unknown = JSON.parse(raw);\n  if (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"start\" in value &&\n    \"end\" in value &&\n    \"replacement\" in value &&\n    typeof value.start === \"number\" &&\n    typeof value.end === \"number\" &&\n    typeof value.replacement === \"string\"\n  ) {\n    return { start: value.start, end: value.end, replacement: value.replacement };\n  }\n  throw new Error(`polly mutate preload: malformed POLLY_MUTATE_SPAN: ${raw}`);\n}\n\nfunction newlines(s: string): number {\n  let n = 0;\n  for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) === 10) n++;\n  return n;\n}\n\n/**\n * The mutated text, with the line count kept: a replacement that drops lines\n * (an emptied block, object or arrow body) is followed by a comment holding\n * them, so a contract after it still reports its own `file:line`.\n */\nexport function mutatedText(\n  src: string,\n  span: { start: number; end: number; replacement: string }\n): string {\n  const lost = newlines(src.slice(span.start, span.end)) - newlines(span.replacement);\n  const pad = lost > 0 ? `/*${\"\\n\".repeat(lost)}*/` : \"\";\n  return src.slice(0, span.start) + span.replacement + pad + src.slice(span.end);\n}\n\nif (target && rawSpan) {\n  const span = parseSpan(rawSpan);\n  const src = await Bun.file(target).text();\n  const contents = mutatedText(src, span);\n  const loader = loaderFor(target);\n  plugin({\n    name: \"polly-mutate\",\n    setup(build) {\n      build.onLoad({ filter: exactly([target]) }, () => ({ contents, loader }));\n    },\n  });\n}\n\nconst CONTRACT_VIOLATIONS_KEY = \"__pollyContractViolations\";\n\nfunction violationMessages(): string[] {\n  const list = (globalThis as Record<string, unknown>)[CONTRACT_VIOLATIONS_KEY];\n  if (!Array.isArray(list)) return [];\n  const messages = list.map((v) => (v instanceof Error ? v.message : String(v)));\n  list.length = 0;\n  return messages;\n}\n\nconst contracts = process.env[\"POLLY_CONTRACTS\"];\nif (contracts === \"ensures\" || contracts === \"all\") {\n  try {\n    const { afterEach, beforeEach } = await import(\"bun:test\");\n    beforeEach(() => {\n      for (const m of violationMessages()) {\n        process.stderr.write(`polly mutate: contract violated outside any test: ${m}\\n`);\n      }\n    });\n    afterEach(() => {\n      const messages = violationMessages();\n      if (messages.length > 0) throw new Error(messages.join(\"\\n\"));\n    });\n  } catch {\n    // Not under `bun test` (the command runner): the BDD runner drains the list.\n  }\n}\n\ninterface CoveragePlan {\n  targets: { file: string; code: string }[];\n  tests: string[];\n}\n\nfunction isStringList(v: unknown): v is string[] {\n  return Array.isArray(v) && v.every((x) => typeof x === \"string\");\n}\n\nfunction parsePlan(raw: string): CoveragePlan {\n  const value: unknown = JSON.parse(raw);\n  if (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"targets\" in value &&\n    \"tests\" in value &&\n    Array.isArray(value.targets) &&\n    isStringList(value.tests)\n  ) {\n    const targets: CoveragePlan[\"targets\"] = [];\n    for (const t of value.targets) {\n      if (\n        typeof t === \"object\" &&\n        t !== null &&\n        \"file\" in t &&\n        \"code\" in t &&\n        typeof t.file === \"string\" &&\n        typeof t.code === \"string\"\n      ) {\n        targets.push({ file: t.file, code: t.code });\n      } else throw new Error(\"polly mutate preload: malformed coverage plan target\");\n    }\n    return { targets, tests: value.tests };\n  }\n  throw new Error(\"polly mutate preload: malformed coverage plan\");\n}\n\ninterface FileHits {\n  load: Set<number>;\n  between: Set<number>;\n  tests: Set<number>[];\n  /** A test began while another was running (concurrent tests): ordinals mean nothing. */\n  overlapped: boolean;\n}\n\nif (coveragePlan && coverageOut) {\n  const plan = parsePlan(readFileSync(coveragePlan, \"utf8\"));\n  const { afterAll, afterEach, beforeEach } = await import(\"bun:test\");\n  const files: FileHits[] = plan.tests.map(() => ({\n    load: new Set(),\n    between: new Set(),\n    tests: [],\n    overlapped: false,\n  }));\n  const outside = new Set<number>();\n  const served = new Set<number>();\n  let current = outside;\n  let file: FileHits | undefined;\n  let running = 0;\n\n  Object.assign(globalThis, {\n    __pollyMutateHit(probe: number) {\n      current.add(probe);\n    },\n    __pollyMutateFile(index: number) {\n      file = files[index];\n      running = 0;\n      current = file?.load ?? outside;\n    },\n  });\n  beforeEach(() => {\n    if (!file) return;\n    running++;\n    if (running > 1) file.overlapped = true;\n    const hits = new Set<number>();\n    file.tests.push(hits);\n    current = hits;\n  });\n  afterEach(() => {\n    if (!file) return;\n    running--;\n    current = file.between;\n  });\n  afterAll(() => {\n    const list = (s: Set<number>) => [...s];\n    writeFileSync(\n      coverageOut,\n      JSON.stringify({\n        served: list(served),\n        outside: list(outside),\n        files: files.map((f) => ({\n          load: list(f.load),\n          between: list(f.between),\n          tests: f.tests.map(list),\n          overlapped: f.overlapped,\n        })),\n      })\n    );\n  });\n\n  const targetIndex = new Map(plan.targets.map((t, i) => [t.file, i]));\n  const testIndex = new Map(plan.tests.map((t, i) => [t, i]));\n  plugin({\n    name: \"polly-mutate-coverage\",\n    setup(build) {\n      for (const i of testIndex.values()) {\n        build.module(`polly-mutate-mark:${i}`, () => ({\n          contents: `globalThis.__pollyMutateFile?.(${i});`,\n          loader: \"js\",\n        }));\n      }\n      // Synchronous on purpose: an async onLoad makes the module async, and\n      // `require()` of an async module throws (mock.module factories use require).\n      build.onLoad({ filter: exactly([...targetIndex.keys(), ...testIndex.keys()]) }, (args) => {\n        const loader = loaderFor(args.path);\n        const t = targetIndex.get(args.path);\n        const planned = t === undefined ? undefined : plan.targets[t];\n        if (t !== undefined && planned) {\n          served.add(t);\n          return { contents: planned.code, loader };\n        }\n        const src = readFileSync(args.path, \"utf8\");\n        const mark = `import \"polly-mutate-mark:${testIndex.get(args.path)}\";`;\n        // After a shebang line, and on the same line as the code: no line moves.\n        const cut = src.startsWith(\"#!\") ? src.indexOf(\"\\n\") + 1 : 0;\n        return { contents: src.slice(0, cut) + mark + src.slice(cut), loader };\n      });\n    },\n  });\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "679EED02066D37BE64756E2164756E21",
+  "names": []
+}

package/dist/tools/mutate/src/engine/probes.d.ts

@@ -0,0 +1,12 @@
+import type { Mutant } from "./types.ts";
+export declare const HIT = "globalThis.__pollyMutateHit?.";
+export interface Instrumented {
+    code: string;
+    /** Mutant ids per probe, indexed by `probe - firstProbe`. */
+    probes: string[][];
+}
+/**
+ * Probe calls numbered from `firstProbe`. Null when the result does not
+ * parse (the target then keeps static selection).
+ */
+export declare function instrument(file: string, src: string, mutants: readonly Mutant[], firstProbe: number): Instrumented | null;

package/dist/tools/mutate/src/engine/report-writer.d.ts

@@ -0,0 +1,44 @@
+import type { MutationReport, ReportContracts } from "../ingest.ts";
+import type { ContractsMode, EngineResult } from "./types.ts";
+export declare const ENGINE_NAME = "polly mutate (bun engine)";
+export interface WrittenReport extends MutationReport {
+    thresholds: {
+        high: number;
+        low: number;
+    };
+    framework: {
+        name: string;
+    };
+    files: Record<string, {
+        language: string;
+        source: string;
+        mutants: {
+            id: string;
+            mutatorName: string;
+            replacement: string;
+            status: string;
+            statusReason?: string;
+            location: {
+                start: {
+                    line: number;
+                    column: number;
+                };
+                end: {
+                    line: number;
+                    column: number;
+                };
+            };
+            killedBy: string[];
+            coveredBy: string[];
+            killedByContract: string[];
+            contractOnly?: boolean;
+        }[];
+    }>;
+    contracts: ReportContracts;
+}
+export interface ReportMeta {
+    contracts: ContractsMode;
+    runner: "bun-test" | "command";
+}
+export declare function toMutationReport(result: EngineResult, cwd: string, meta: ReportMeta): Promise<WrittenReport>;
+export declare function writeReport(report: WrittenReport, path: string): Promise<void>;

package/dist/tools/mutate/src/engine/runner.d.ts

@@ -0,0 +1,31 @@
+import type { ContractsMode, EngineRunner } from "./types.ts";
+export interface BunTestRun {
+    cwd: string;
+    files: string[];
+    /** Every `--preload`, in order; the mutant preload goes last. */
+    preloads: string[];
+    env?: Record<string, string>;
+    /** POLLY_CONTRACTS for the process (both runner kinds). Unset: off. */
+    contracts?: ContractsMode;
+    bail: boolean;
+    timeoutMs: number;
+    /** Capture the tail of stderr (baselines only; mutant runs discard output). */
+    captureStderr?: boolean;
+    /** Ask for Bun's junit report and return its XML (matrix mode). */
+    junit?: boolean;
+    /** `bun test -t`: run only the tests whose full name matches. */
+    namePattern?: string;
+}
+export interface BunTestOutcome {
+    exitCode: number;
+    timedOut: boolean;
+    ms: number;
+    stderrTail?: string;
+    /** The junit XML; undefined when not asked for or not written (a crash). */
+    junitXml?: string;
+}
+/** The preload as built (dist) or as source (monorepo / bun-run-from-source). */
+export declare function preloadPath(): string;
+export declare function runBunTest(run: BunTestRun, runner?: EngineRunner): Promise<BunTestOutcome>;
+/** Run `fn` over `items` with at most `concurrency` in flight; results keep input order. */
+export declare function pool<T, R>(items: readonly T[], concurrency: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;