@fairfox/polly 0.91.0 → 0.92.0

package/dist/tools/mutate/src/engine/stray-writes.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Stray-write detection. Mutant runs share the project's working tree (no
+ * sandbox copy), so a mutant that redirects a write — a storage path, a temp
+ * dir — leaves a file in the repo. Polly's own storage-adapter.ts did exactly
+ * this (`st/orage-adapter-id` in the repo root after every full run).
+ *
+ * The engine snapshots `git status` before the run, after the baselines and
+ * after the mutants, and reports each new entry. It never deletes: a path that
+ * is new to git may still be the user's own work in progress.
+ *
+ * Untracked files are listed one by one (`--untracked-files=all`), so a new
+ * file inside an already-untracked directory still shows. Ignored paths are
+ * listed as their matching pattern (`--ignored=matching`): a write to a new
+ * `*.log` shows, a write inside an existing `node_modules/` does not.
+ */
+export interface WorktreeSnapshot {
+    /** Absolute repo root; entry paths are relative to it. */
+    root: string;
+    /** `XY path` lines, so a clean → modified change counts as new. */
+    entries: Set<string>;
+}
+/** Null when `cwd` is not inside a git worktree (or git is not installed). */
+export declare function snapshotWorktree(cwd: string): WorktreeSnapshot | null;
+/** Paths (relative to the repo root) whose `git status` entry is in `after` but not `before`. */
+export declare function newPaths(before: WorktreeSnapshot | null, after: WorktreeSnapshot | null): string[];

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

@@ -0,0 +1,37 @@
+import type { Mutant } from "./types.ts";
+/** Relaxed in the virtual config: mutants make code unreachable and bindings unused by design. */
+export declare const TYPECHECK_OVERRIDES: {
+    allowUnreachableCode: boolean;
+    noUnusedLocals: boolean;
+    noUnusedParameters: boolean;
+};
+export declare const TYPECHECK_CONFIG_NAME = "tsconfig.polly-mutate.json";
+export interface TypecheckTarget {
+    /** Absolute, symlink-resolved. */
+    file: string;
+    mutants: readonly Mutant[];
+}
+export interface TypecheckOutcome {
+    /** Mutant id → `TS<code>: <text>` of the first error the unmutated file does not have. */
+    invalid: Map<string, string>;
+    /** Targets the filter could not check, each with why. Their mutants run as usual. */
+    skipped: {
+        file: string;
+        reason: string;
+    }[];
+    /** Mutants that were checked (skipped targets excluded). */
+    checked: number;
+    wallMs: number;
+}
+export interface TypecheckOptions {
+    /** For log lines: paths print relative to it. */
+    cwd: string;
+    log?: (line: string) => void;
+}
+/** `tsconfig.json` paths from the file's directory upward, nearest first. */
+export declare function tsconfigCandidates(file: string): string[];
+/**
+ * Type-check every mutant of every target. Null when `typescript-7` is not
+ * installed (logged; the engine then runs every mutant).
+ */
+export declare function typecheckMutants(targets: readonly TypecheckTarget[], opts: TypecheckOptions): Promise<TypecheckOutcome | null>;

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

@@ -0,0 +1,191 @@
+/**
+ * Shared types for the Bun-native mutation engine (`polly mutate --engine bun`).
+ *
+ * Mutator names are Stryker's, on purpose: the report keeps the
+ * mutation-testing-report-schema shape, so ingest/report/decisions and any
+ * existing decisions.jsonl read the engine's output exactly as they read
+ * Stryker's.
+ */
+export type MutatorName = "ArithmeticOperator" | "ArrayDeclaration" | "ArrowFunction" | "AssignmentOperator" | "BlockStatement" | "BooleanLiteral" | "ConditionalExpression" | "EqualityOperator" | "LogicalOperator" | "MethodExpression" | "ObjectLiteral" | "OptionalChaining" | "Regex" | "StringLiteral" | "UnaryOperator" | "UpdateOperator";
+/** One source edit: replace `[start, end)` of the target file's text with `replacement`. */
+export interface Mutant {
+    id: string;
+    /** Absolute, symlink-resolved path of the mutated file. */
+    file: string;
+    mutatorName: MutatorName;
+    start: number;
+    end: number;
+    replacement: string;
+    /** 1-based, as mutation-testing-report-schema expects. */
+    location: {
+        start: Position;
+        end: Position;
+    };
+    /** Set when the mutant sits inside a polly verify primitive (polly#143). */
+    ignoredReason?: string;
+}
+export interface Position {
+    line: number;
+    column: number;
+}
+export type MutantStatus = "Killed" | "Survived" | "Timeout" | "NoCoverage" | "CompileError" | "RuntimeError" | "Ignored";
+export interface MutantResult {
+    mutant: Mutant;
+    status: MutantStatus;
+    statusReason?: string;
+    durationMs?: number;
+    /** Matrix mode: ids (see junit.ts `testId`) of every test that failed under the mutant. */
+    killedBy?: string[];
+    /** Dynamic coverage: ids of every test that ran the mutant's code (coverage.ts). */
+    coveredBy?: string[];
+    /**
+     * Matrix mode with contracts on: ids (`<file relative to cwd>:<line>`) of
+     * every requires/ensures whose violation a killing test reported.
+     */
+    killedByContract?: string[];
+    /** Every killing test failed through a contract violation: no assertion caught it. */
+    contractOnly?: boolean;
+}
+/**
+ * POLLY_CONTRACTS for every test process the engine starts: off keeps
+ * requires/ensures as no-ops; ensures makes a false postcondition throw;
+ * all makes a false precondition throw too.
+ */
+export type ContractsMode = "off" | "ensures" | "all";
+/** A `requires` / `ensures` call in a target (generate.ts). */
+export interface ContractSite {
+    /** Absolute, symlink-resolved path, as `Mutant.file`. */
+    file: string;
+    /** 1-based line of the call. */
+    line: number;
+    primitive: "requires" | "ensures";
+    /** The author's message, when it is a string literal. */
+    message?: string;
+    /** Lines of the enclosing `bus.on(...)` call, else the enclosing function. */
+    handler?: {
+        from: number;
+        to: number;
+    };
+}
+/** A baseline test (or the command) that fails only because a contract is false. */
+export interface ContractViolationRecord {
+    /** Absolute path of the target whose baseline reported it. */
+    target: string;
+    /** Test id (junit.ts `testId`), or "(command)" for the command runner. */
+    test: string;
+    /** Contract ids, `<file relative to cwd>:<line>`; empty for the command runner. */
+    contracts: string[];
+}
+/** One test the baseline ran (matrix mode). */
+export interface TestRef {
+    id: string;
+    /** Absolute path of the test file. */
+    file: string;
+    name: string;
+    line: number;
+}
+/**
+ * fast    `--bail`: stop at the first failing test; status only.
+ * matrix  no bail, junit per run: every killing test, for the redundancy analysis.
+ */
+export type EngineMode = "fast" | "matrix";
+/** A target file, optionally narrowed to a line range (Stryker's `file.ts:10-20`). */
+export interface MutateTarget {
+    file: string;
+    lines?: {
+        from: number;
+        to: number;
+    };
+}
+export type EngineRunner = {
+    kind: "bun-test";
+} | {
+    kind: "command";
+    argv: string[];
+};
+/**
+ * dynamic  one probed pass over every test file decides, per mutant, which
+ *          tests run it (coverage.ts); a mutant no test runs is NoCoverage
+ * static   every test file whose import closure reaches the target (graph.ts)
+ */
+export type CoverageMode = "dynamic" | "static";
+export interface EngineConfig {
+    /** Directory `bun test` runs from; test globs and report paths are relative to it. */
+    cwd: string;
+    targets: MutateTarget[];
+    /**
+     * bun-test  `bun test` on the test files that reach each target.
+     * command   the argv, whole, for every mutant (polly.mutate.ts `runner`).
+     */
+    runner: EngineRunner;
+    /** Test-file globs (relative to cwd) the import graph starts from. */
+    testInclude: string[];
+    /**
+     * The project's own test preloads (absolute), passed before the mutant
+     * preload. Needed because a subset of test files can depend on a preload
+     * the full suite happens to load some other way (polly's CSS-module shim).
+     */
+    testPreload: string[];
+    mode: EngineMode;
+    /**
+     * Report mutants the project's TypeScript config rejects as CompileError
+     * without running them (typecheck.ts). Needs `typescript-7`.
+     */
+    typecheck: boolean;
+    /** Test selection. The command runner selects nothing, so it is always static. */
+    coverage: CoverageMode;
+    concurrency: number;
+    timeout: {
+        factor: number;
+        extraMs: number;
+    };
+    /** Mutators that generate nothing. */
+    excludeMutators: MutatorName[];
+    /** Mark mutants inside requires/ensures/… as Ignored instead of running them. */
+    ignoreVerifyCallsites: boolean;
+    /** POLLY_CONTRACTS for every test process (baseline, coverage pass, mutant runs). */
+    contracts: ContractsMode;
+    /**
+     * Run each test process in a fresh scratch cwd (workdir.ts), so a mutant's
+     * relative writes miss the repo. False runs everything in `cwd`.
+     */
+    scratchCwd: boolean;
+    /** Result cache directory (cache.ts); null runs everything. */
+    cacheDir: string | null;
+    reportPath: string;
+}
+export interface TargetSummary {
+    file: string;
+    coveringTests: string[];
+    baselineMs: number | null;
+    /** Its mutants ran in the project cwd (scratch off, or its tests need the cwd). */
+    inTree: boolean;
+    /** Results came from the cache; nothing ran. */
+    cached: boolean;
+    /** Matrix mode: every test the baseline ran, plus any load-failure stand-in a mutant named. */
+    tests: TestRef[];
+    results: MutantResult[];
+    /** Every requires/ensures call in the target, whatever the contracts mode. */
+    contracts: ContractSite[];
+}
+export interface EngineResult {
+    targets: TargetSummary[];
+    wallMs: number;
+    /**
+     * Paths new to `git status` (relative to `root`), split by phase: written by
+     * the unmutated baselines (the tests' own side effects) or by mutant runs
+     * (a mutant redirected a write into the tree). Null outside a git worktree.
+     * The report is written after the last snapshot, so it never appears here.
+     */
+    strayWrites: {
+        root: string;
+        baseline: string[];
+        mutants: string[];
+    } | null;
+    /**
+     * Baselines that failed through a contract: a test drives a handler outside
+     * its declared precondition, or a handler breaks its own postcondition.
+     * Those targets' mutants are RuntimeError; `run` exits 1 and names them.
+     */
+    contractViolations: ContractViolationRecord[];
+}

package/dist/tools/mutate/src/engine/verify-callsites.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The polly verify primitives whose argument expressions are runtime no-ops.
+ * A mutation anywhere inside a call to one of these cannot be killed by a test,
+ * so its mutants are excluded from scoring (polly#143).
+ *
+ * The single source: generate.ts marks mutants inside these calls Ignored.
+ */
+export declare const VERIFY_PRIMITIVES: ReadonlySet<string>;
+export declare function verifyCallsiteReason(name: string): string;

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

@@ -0,0 +1,16 @@
+export interface Workdirs {
+    root: string;
+    /** A fresh cwd holding the project's tsconfig and bunfig. */
+    create(): string;
+    /** Remove one directory from `create()`. */
+    release(dir: string): void;
+    /** Remove every scratch directory. */
+    remove(): void;
+}
+/** Resolve top-level `preload` and `[test].preload` (a string or a list) against the project. */
+export declare function absolutiseBunfig(config: Record<string, unknown>, projectCwd: string): Record<string, unknown>;
+/** TOML for the plain shapes a bunfig holds: scalars, arrays and nested tables. */
+export declare function renderToml(config: Record<string, unknown>, prefix?: string[]): string;
+export declare function createWorkdirs(projectCwd: string): Workdirs;
+/** Run `fn` in a fresh scratch cwd, or in `projectCwd` when `workdirs` is null. */
+export declare function inCwd<R>(workdirs: Workdirs | null, projectCwd: string, fn: (cwd: string) => Promise<R>): Promise<R>;

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

@@ -0,0 +1,7 @@
+import type { MutateArgs } from "./args.ts";
+import type { MutateConfig } from "./config.ts";
+import type { EngineConfig, MutateTarget } from "./engine/types.ts";
+/** Expand Stryker `mutate` entries: globs, `!` exclusions, and `file.ts:10-20` ranges. */
+export declare function expandMutateEntries(cwd: string, entries: string[]): Promise<MutateTarget[]>;
+/** The engine's config from the loaded mutation config plus CLI flags (flags win). */
+export declare function engineConfigFor(cfg: MutateConfig, args: MutateArgs): Promise<EngineConfig>;

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

@@ -1,13 +1,17 @@
 /**
  * @fairfox/polly/mutate — programmatic surface for mutation-testing analysis.
  *
- * The CLI (`polly mutate`) is the primary entry point; this barrel exposes the
- * reusable pieces for consumers who want to drive the analysis themselves:
+ * The CLI (`polly mutate`) is the primary entry point; `defineMutation` types a
+ * project's `polly.mutate.ts`. The rest is for consumers who want to drive the
+ * engine or the analysis themselves:
  * ingest a mutation report into the kill matrix, derive the useless-test signals,
  * and assert the matrix contract.
  */
 export { decide, type FileSignal, fileSignals, status } from "./decisions.ts";
-export { buildDb, type MutationReport } from "./ingest.ts";
+export { type CommandRunner, defineMutation, loadMutationConfig, MUTATION_CONFIG_FILE, type MutationConfig, type MutationTests, parseMutationConfig, } from "./define.ts";
+export { applyMutant, buildImportGraph, type ContractSite, type ContractsMode, type ContractViolationRecord, coveringTests, type EngineConfig, type EngineHooks, type EngineResult, findTestFiles, generateMutants, type Mutant, type MutantResult, type MutantStatus, type MutateTarget, type MutatorName, mutationScore, runEngine, VERIFY_PRIMITIVES, } from "./engine/index.ts";
+export { buildDb, type MutationReport, type ReportContracts } from "./ingest.ts";
 export { type InitResult, initConfig } from "./init.ts";
+export { type Migration, migrateConfig, strykerToMutation } from "./migrate.ts";
 export { report } from "./report.ts";
 export { isMatrixComplete, type MatrixCheck, verifyMatrix } from "./verify-matrix.ts";