@mutineerjs/mutineer 0.6.0 → 0.8.0

package/README.md

@@ -13,13 +13,11 @@ Mutineer is a fast, targeted mutation testing framework for JavaScript and TypeS
 
 Built for **Vitest** with first-class **Jest** support. Other test runners can be added via the adapter interface.
 
-**Author**: [Billy Jones](https://www.linkedin.com/in/billyjonesy/)
-
 ## How It Works
 
 1. **Baseline** -- runs your test suite to make sure everything passes before mutating
 2. **Mutate** -- applies AST-safe operator replacements to your source files (not your tests)
-3. **Test** -- re-runs only the tests that import the mutated file, using temp files in `__mutineer__` dirs loaded via Vite plugin / Jest resolver
+3. **Test** -- re-runs only the tests that import the mutated file; compile errors are detected via parallel TypeScript workers and surfaced in an interactive UI
 4. **Report** -- prints a summary with kill rate, escaped mutants, and per-file breakdowns
 
 Mutations are applied using Babel AST analysis, so operators inside strings and comments are never touched. Mutated code is written to a temporary `__mutineer__` directory next to each source file, then loaded at runtime via Vite plugins (Vitest) or custom resolvers (Jest).
@@ -95,18 +93,22 @@ npm run mutineer
 
 ### CLI Options (for `mutineer run`)
 
-| Flag                     | Description                                | Default       |
-| ------------------------ | ------------------------------------------ | ------------- |
-| `--runner <type>`        | Test runner: `vitest` or `jest`            | `vitest`      |
-| `--config`, `-c`         | Path to config file                        | auto-detected |
-| `--concurrency <n>`      | Parallel workers (min 1)                   | CPUs - 1      |
-| `--changed`              | Only mutate files changed vs base branch   | --            |
-| `--changed-with-deps`    | Include dependents of changed files        | --            |
-| `--only-covered-lines`   | Skip mutations on uncovered lines          | --            |
-| `--per-test-coverage`    | Run only tests that cover the mutated line | --            |
-| `--coverage-file <path>` | Path to Istanbul coverage JSON             | auto-detected |
-| `--min-kill-percent <n>` | Fail if kill rate is below threshold       | --            |
-| `--progress <mode>`      | Display mode: `bar`, `list`, or `quiet`    | `bar`         |
+| Flag                     | Description                                                     | Default       |
+| ------------------------ | --------------------------------------------------------------- | ------------- |
+| `--runner <type>`        | Test runner: `vitest` or `jest`                                 | `vitest`      |
+| `--config`, `-c`         | Path to config file                                             | auto-detected |
+| `--concurrency <n>`      | Parallel workers (min 1)                                        | CPUs - 1      |
+| `--changed`              | Only mutate files changed vs base branch                        | --            |
+| `--changed-with-deps`    | Include dependents of changed files                             | --            |
+| `--only-covered-lines`   | Skip mutations on uncovered lines                               | --            |
+| `--per-test-coverage`    | Run only tests that cover the mutated line                      | --            |
+| `--coverage-file <path>` | Path to Istanbul coverage JSON                                  | auto-detected |
+| `--min-kill-percent <n>` | Fail if kill rate is below threshold                            | --            |
+| `--progress <mode>`      | Display mode: `bar`, `list`, or `quiet`                         | `bar`         |
+| `--timeout <ms>`         | Per-mutant test timeout                                         | `30000`       |
+| `--report <format>`      | Output format: `text` or `json` (writes `mutineer-report.json`) | `text`        |
+| `--shard <n>/<total>`    | Run a slice of mutants (e.g. `--shard 1/4`)                     | --            |
+| `--skip-baseline`        | Skip the baseline test run                                      | --            |
 
 ### Examples
 
@@ -168,6 +170,17 @@ export default defineMutineerConfig({
 
 Large repos can generate thousands of mutations. These strategies keep runs fast and incremental.
 
+When you run `mutineer run` without `--changed` or `--changed-with-deps` on an interactive terminal, mutineer warns you and lets you narrow scope before starting:
+
+```
+Warning: Running on the full codebase may take a while.
+
+  [1] Continue (full codebase)
+  [2] --changed          (git-changed files only)
+  [3] --changed-with-deps (changed + their local deps)
+  [4] Abort
+```
+
 ### 1. PR-scoped runs (CI) — `--changed-with-deps`
 
 Run only on files changed in the branch plus their direct dependents:
@@ -262,6 +275,10 @@ export function createMyRunnerAdapter(
 
 The key requirement is the **file-swap mechanism** -- the adapter needs a way to intercept module resolution so the mutated source code is loaded instead of the original file on disk. See the Vitest adapter (Vite plugin + ESM loader) and Jest adapter (custom resolver) for working reference implementations in `src/runner/vitest/` and `src/runner/jest/`.
 
+## Maintainers
+
+- [Billy Jones](https://www.linkedin.com/in/billyjonesy/)
+
 ## License
 
 MIT

package/dist/bin/__tests__/mutineer.spec.js

@@ -1,6 +1,7 @@
 import { createRequire } from 'node:module';
-import { describe, it, expect } from 'vitest';
-import { HELP_TEXT, getVersion } from '../mutineer.js';
+import readline from 'node:readline';
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { HELP_TEXT, getVersion, confirmFullRun } from '../mutineer.js';
 describe('HELP_TEXT', () => {
     const flags = [
         '--config',
@@ -31,6 +32,70 @@ describe('HELP_TEXT', () => {
         expect(HELP_TEXT).toContain('local dependencies');
     });
 });
+describe('confirmFullRun()', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    function mockTTY(isTTY) {
+        Object.defineProperty(process.stdin, 'isTTY', {
+            value: isTTY,
+            configurable: true,
+        });
+    }
+    function mockReadline(answers) {
+        let callIndex = 0;
+        vi.spyOn(readline, 'createInterface').mockReturnValue({
+            question(_prompt, cb) {
+                cb(answers[callIndex++] ?? '');
+            },
+            close: vi.fn(),
+        });
+    }
+    it('returns args unchanged when --changed is present', async () => {
+        mockTTY(true);
+        const args = ['--changed', '--concurrency', '4'];
+        expect(await confirmFullRun(args)).toBe(args);
+    });
+    it('returns args unchanged when --changed-with-deps is present', async () => {
+        mockTTY(true);
+        const args = ['--changed-with-deps'];
+        expect(await confirmFullRun(args)).toBe(args);
+    });
+    it('skips prompt and returns args unchanged when stdin is not a TTY', async () => {
+        mockTTY(false);
+        const createSpy = vi.spyOn(readline, 'createInterface');
+        const args = ['--concurrency', '2'];
+        expect(await confirmFullRun(args)).toBe(args);
+        expect(createSpy).not.toHaveBeenCalled();
+    });
+    it('choice 1 (default Enter) returns args unchanged', async () => {
+        mockTTY(true);
+        mockReadline(['']);
+        const args = ['--concurrency', '2'];
+        expect(await confirmFullRun(args)).toEqual(args);
+    });
+    it('choice 1 returns args unchanged', async () => {
+        mockTTY(true);
+        mockReadline(['1']);
+        const args = [];
+        expect(await confirmFullRun(args)).toEqual([]);
+    });
+    it('choice 2 appends --changed', async () => {
+        mockTTY(true);
+        mockReadline(['2']);
+        expect(await confirmFullRun([])).toEqual(['--changed']);
+    });
+    it('choice 3 appends --changed-with-deps', async () => {
+        mockTTY(true);
+        mockReadline(['3']);
+        expect(await confirmFullRun([])).toEqual(['--changed-with-deps']);
+    });
+    it('invalid input re-prompts, then accepts valid choice', async () => {
+        mockTTY(true);
+        mockReadline(['9', 'x', '2']);
+        expect(await confirmFullRun([])).toEqual(['--changed']);
+    });
+});
 describe('getVersion()', () => {
     it('returns a semver string', () => {
         expect(getVersion()).toMatch(/^\d+\.\d+\.\d+/);

package/dist/bin/mutineer.d.ts

@@ -1,3 +1,8 @@
 #!/usr/bin/env node
-export declare const HELP_TEXT = "Usage: mutineer <command> [options]\n\nCommands:\n  init       Create a mutineer.config.ts template\n  run        Run mutation testing\n  clean      Remove __mutineer__ temp directories\n\nOptions (run):\n  --config, -c <path>       Config file path\n  --concurrency <n>         Worker count (default: CPU count - 1)\n  --runner <vitest|jest>    Test runner (default: vitest)\n  --progress <bar|list|quiet>  Progress display (default: bar)\n  --changed                 Mutate only git-changed files\n  --changed-with-deps       Mutate changed files + their local dependencies\n  --only-covered-lines      Mutate only lines covered by tests\n  --per-test-coverage       Collect per-test coverage data\n  --coverage-file <path>    Path to coverage JSON\n  --min-kill-percent <n>    Minimum kill % threshold (0\u2013100)\n  --timeout <ms>            Per-mutant test timeout in ms (default: 30000)\n\n  --help, -h                Show this help\n  --version, -V             Show version\n";
+export declare const HELP_TEXT = "Usage: mutineer <command> [options]\n\nCommands:\n  init       Create a mutineer.config.ts template\n  run        Run mutation testing\n  clean      Remove __mutineer__ temp directories\n\nOptions (run):\n  --config, -c <path>       Config file path\n  --concurrency <n>         Worker count (default: CPU count - 1)\n  --runner <vitest|jest>    Test runner (default: vitest)\n  --progress <bar|list|quiet>  Progress display (default: bar)\n  --changed                 Mutate only git-changed files\n  --changed-with-deps       Mutate changed files + their local dependencies\n  --only-covered-lines      Mutate only lines covered by tests\n  --per-test-coverage       Collect per-test coverage data\n  --coverage-file <path>    Path to coverage JSON\n  --min-kill-percent <n>    Minimum kill % threshold (0\u2013100)\n  --timeout <ms>            Per-mutant test timeout in ms (default: 30000)\n  --report <text|json>      Output format: text (default) or json (writes mutineer-report.json)\n  --shard <n>/<total>       Run a shard of mutants (e.g. --shard 1/4)\n  --skip-baseline           Skip the baseline test run\n\n  --help, -h                Show this help\n  --version, -V             Show version\n";
 export declare function getVersion(): string;
+/**
+ * When running in full-codebase mode on an interactive TTY, warn the user and
+ * let them narrow scope or abort. Returns args (possibly with a flag appended).
+ */
+export declare function confirmFullRun(args: string[]): Promise<string[]>;

package/dist/bin/mutineer.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
 import path from 'node:path';
+import readline from 'node:readline';
 import { createRequire } from 'node:module';
 import { runOrchestrator } from '../runner/orchestrator.js';
 import { cleanupMutineerDirs } from '../runner/cleanup.js';
@@ -28,6 +29,9 @@ Options (run):
   --coverage-file <path>    Path to coverage JSON
   --min-kill-percent <n>    Minimum kill % threshold (0–100)
   --timeout <ms>            Per-mutant test timeout in ms (default: 30000)
+  --report <text|json>      Output format: text (default) or json (writes mutineer-report.json)
+  --shard <n>/<total>       Run a shard of mutants (e.g. --shard 1/4)
+  --skip-baseline           Skip the baseline test run
 
   --help, -h                Show this help
   --version, -V             Show version
@@ -43,6 +47,57 @@ export default defineMutineerConfig({
   source: 'src',
 })
 `;
+const FULL_RUN_WARNING = `
+Warning: Running on the full codebase may take a while.
+
+  [1] Continue (full codebase)
+  [2] --changed          (git-changed files only)
+  [3] --changed-with-deps (changed + their local deps)
+  [4] Abort
+
+`;
+/**
+ * When running in full-codebase mode on an interactive TTY, warn the user and
+ * let them narrow scope or abort. Returns args (possibly with a flag appended).
+ */
+export async function confirmFullRun(args) {
+    const isFullRun = !args.includes('--changed') && !args.includes('--changed-with-deps');
+    if (!isFullRun || !process.stdin.isTTY)
+        return args;
+    process.stdout.write(FULL_RUN_WARNING);
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        const ask = () => {
+            rl.question('Choice [1]: ', (answer) => {
+                const choice = answer.trim() || '1';
+                if (choice === '1') {
+                    rl.close();
+                    resolve(args);
+                }
+                else if (choice === '2') {
+                    rl.close();
+                    resolve([...args, '--changed']);
+                }
+                else if (choice === '3') {
+                    rl.close();
+                    resolve([...args, '--changed-with-deps']);
+                }
+                else if (choice === '4') {
+                    rl.close();
+                    process.exit(0);
+                }
+                else {
+                    process.stdout.write('Please enter 1, 2, 3, or 4.\n');
+                    ask();
+                }
+            });
+        };
+        ask();
+    });
+}
 /**
  * Main entry point - routes to orchestrator or clean
  */
@@ -61,7 +116,8 @@ async function main() {
             process.stdout.write(HELP_TEXT);
             process.exit(0);
         }
-        await runOrchestrator(args.slice(1), process.cwd());
+        const runArgs = await confirmFullRun(args.slice(1));
+        await runOrchestrator(runArgs, process.cwd());
     }
     else if (args[0] === INIT_COMMAND) {
         const configFile = path.join(process.cwd(), 'mutineer.config.ts');
@@ -76,7 +132,7 @@ async function main() {
     }
     else if (args[0] === CLEAN_COMMAND) {
         console.log('Cleaning up __mutineer__ directories...');
-        await cleanupMutineerDirs(process.cwd());
+        await cleanupMutineerDirs(process.cwd(), { includeCacheFiles: true });
         console.log('Done.');
     }
     else {

package/dist/core/__tests__/schemata.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/schemata.spec.js

@@ -0,0 +1,165 @@
+import { describe, it, expect } from 'vitest';
+import { generateSchema } from '../schemata.js';
+function makeVariant(id, code) {
+    return {
+        id,
+        name: 'test',
+        file: '/src/foo.ts',
+        code,
+        line: 1,
+        col: 1,
+        tests: [],
+    };
+}
+describe('generateSchema', () => {
+    it('returns original code with ts-nocheck header for empty variants', () => {
+        const original = 'const x = 1 + 2';
+        const { schemaCode, fallbackIds } = generateSchema(original, []);
+        expect(schemaCode).toBe('// @ts-nocheck\n' + original);
+        expect(fallbackIds.size).toBe(0);
+    });
+    it('embeds an operator mutation using the enclosing expression', () => {
+        // '+' is operator-only char diff — uses AST to find BinaryExpression 'x + y'
+        const original = 'x + y';
+        const { schemaCode, fallbackIds } = generateSchema(original, [
+            makeVariant('f#0', 'x - y'),
+        ]);
+        expect(fallbackIds.size).toBe(0);
+        expect(schemaCode).toContain("'f#0'");
+        expect(schemaCode).toContain('x - y');
+        expect(schemaCode).toContain('x + y');
+    });
+    it('embeds === to !== operator mutation using the enclosing BinaryExpression', () => {
+        const original = 'x === true';
+        const { schemaCode, fallbackIds } = generateSchema(original, [
+            makeVariant('f#0', 'x !== true'),
+        ]);
+        expect(fallbackIds.size).toBe(0);
+        expect(schemaCode).toContain("'f#0'");
+        expect(schemaCode).toContain('x !== true');
+        expect(schemaCode).toContain('x === true');
+    });
+    it('handles variable-length operator replacement (> → >=) without truncating operands', () => {
+        // '>' is 1 char, '>=' is 2 chars — the AST end from original must be shifted by +1
+        const original = 'hitCount > 0';
+        const { schemaCode, fallbackIds } = generateSchema(original, [
+            makeVariant('f#0', 'hitCount >= 0'),
+        ]);
+        expect(fallbackIds.size).toBe(0);
+        expect(schemaCode).toContain('hitCount >= 0');
+        expect(schemaCode).toContain('hitCount > 0');
+    });
+    it('handles variable-length operator replacement (>= → >) without truncating operands', () => {
+        // '>=' is 2 chars, '>' is 1 char — AST end shifts by -1
+        const original = 'hitCount >= 0';
+        const { schemaCode, fallbackIds } = generateSchema(original, [
+            makeVariant('f#0', 'hitCount > 0'),
+        ]);
+        expect(fallbackIds.size).toBe(0);
+        expect(schemaCode).toContain('hitCount > 0');
+        expect(schemaCode).toContain('hitCount >= 0');
+    });
+    it('chains multiple operator variants on the same expression site', () => {
+        const original = 'x + y';
+        const v0 = makeVariant('f#0', 'x - y');
+        const v1 = makeVariant('f#1', 'x * y');
+        const { schemaCode, fallbackIds } = generateSchema(original, [v0, v1]);
+        expect(fallbackIds.size).toBe(0);
+        expect(schemaCode).toContain("'f#0'");
+        expect(schemaCode).toContain("'f#1'");
+        expect(schemaCode).toContain('x - y');
+        expect(schemaCode).toContain('x * y');
+        expect(schemaCode).toContain('x + y');
+    });
+    it('wraps a value mutation site in a ternary', () => {
+        // 'true' → 'false': both valid identifiers, char diff path
+        const original = 'return true';
+        const { schemaCode, fallbackIds } = generateSchema(original, [
+            makeVariant('f#0', 'return false'),
+        ]);
+        expect(fallbackIds.size).toBe(0);
+        expect(schemaCode).toContain("'f#0'");
+        expect(schemaCode).toContain('false');
+        expect(schemaCode).toContain('true');
+    });
+    it('chains multiple value variants on the same site', () => {
+        const original = 'return true';
+        const v0 = makeVariant('f#0', 'return false');
+        const v1 = makeVariant('f#1', 'return null');
+        const { schemaCode, fallbackIds } = generateSchema(original, [v0, v1]);
+        expect(fallbackIds.size).toBe(0);
+        expect(schemaCode).toContain("'f#0'");
+        expect(schemaCode).toContain("'f#1'");
+        expect(schemaCode).toContain('false');
+        expect(schemaCode).toContain('null');
+        expect(schemaCode).toContain('true');
+    });
+    it('produces separate ternaries for non-overlapping sites', () => {
+        // 'return true || false': two value sites, non-overlapping
+        const original = 'return true || false';
+        const v0 = makeVariant('f#0', 'return false || false'); // first 'true' → 'false'
+        const v1 = makeVariant('f#1', 'return true || true'); // second 'false' → 'true'
+        const { schemaCode, fallbackIds } = generateSchema(original, [v0, v1]);
+        expect(fallbackIds.size).toBe(0);
+        expect(schemaCode).toContain("'f#0'");
+        expect(schemaCode).toContain("'f#1'");
+    });
+    it('marks outer expression as fallback when inner and outer sites overlap (nested binary)', () => {
+        // 'x + y - z': '+' → inner BinaryExpression 'x + y', '-' → outer 'x + y - z'
+        // Inner is kept in schema; outer (containing inner) is fallback.
+        const original = 'x + y - z';
+        const vInner = makeVariant('f#0', 'x - y - z'); // '+' → '-'
+        const vOuter = makeVariant('f#1', 'x + y + z'); // '-' → '+'
+        const { schemaCode, fallbackIds } = generateSchema(original, [
+            vInner,
+            vOuter,
+        ]);
+        // Inner (x + y site) kept in schema, outer (x + y - z site) fallback
+        expect(fallbackIds.has('f#1')).toBe(true);
+        expect(fallbackIds.has('f#0')).toBe(false);
+        expect(schemaCode).toContain("'f#0'");
+    });
+    it('embeds two value-mutation variants on the same site', () => {
+        const orig2 = 'return true';
+        const vX = makeVariant('g#0', 'return false');
+        const vY = makeVariant('g#1', 'return null');
+        const { schemaCode: sc2, fallbackIds: fb2 } = generateSchema(orig2, [
+            vX,
+            vY,
+        ]);
+        expect(fb2.size).toBe(0);
+        expect(sc2).toContain("'g#0'");
+        expect(sc2).toContain("'g#1'");
+    });
+    it('marks variant as fallback when diff produces empty range', () => {
+        // Variant identical to original → empty diff
+        const original = 'const x = 1';
+        const identical = makeVariant('f#0', 'const x = 1');
+        const { fallbackIds } = generateSchema(original, [identical]);
+        expect(fallbackIds.has('f#0')).toBe(true);
+    });
+    it('escapes single quotes in variant IDs', () => {
+        const original = 'return true';
+        const v = makeVariant("it's#0", 'return false');
+        const { schemaCode } = generateSchema(original, [v]);
+        expect(schemaCode).toContain("it\\'s#0");
+    });
+    it('handles multi-character replacements correctly', () => {
+        const original = 'return true';
+        const v = makeVariant('r#0', 'return false');
+        const { schemaCode, fallbackIds } = generateSchema(original, [v]);
+        expect(fallbackIds.size).toBe(0);
+        expect(schemaCode).toContain("'r#0'");
+        expect(schemaCode).toMatch(/globalThis\.__mutineer_active_id__/);
+    });
+    it('merges variants into same site when word-boundary extension unifies their spans', () => {
+        // 'abcde' (all word chars): both variants extend to the full 5-char span [0,5]
+        const original = 'abcde';
+        const v0 = makeVariant('f#0', 'xyzde');
+        const v1 = makeVariant('f#1', 'aUVWe');
+        const { schemaCode, fallbackIds } = generateSchema(original, [v0, v1]);
+        expect(fallbackIds.size).toBe(0);
+        expect(schemaCode).toContain("'f#0'");
+        expect(schemaCode).toContain("'f#1'");
+    });
+});

package/dist/core/schemata.d.ts

@@ -0,0 +1,22 @@
+import type { Variant } from '../types/mutant.js';
+export interface SchemaResult {
+    schemaCode: string;
+    fallbackIds: Set<string>;
+}
+/**
+ * Generate a schema file that embeds all mutation variants as a ternary chain.
+ *
+ * The schema uses `globalThis.__mutineer_active_id__` at call time to select
+ * which mutant is active, avoiding per-mutant module reloads.
+ *
+ * For value mutations (true→false, null→undefined), a character-level diff with
+ * word-boundary extension finds the span. For operator mutations (+→-, ===→!==),
+ * the Babel AST is used to find the enclosing expression (x + y, x === y) so
+ * the ternary branch is a valid JS expression.
+ *
+ * @param originalCode - The original source file contents
+ * @param variants - All variants to embed (must all be from the same source file)
+ * @returns schemaCode (the embedded schema) and fallbackIds (variants that
+ *   couldn't be embedded due to overlapping diff ranges or parse errors)
+ */
+export declare function generateSchema(originalCode: string, variants: readonly Variant[]): SchemaResult;