@mutineerjs/mutineer 0.6.0 → 0.7.0

package/dist/bin/mutineer.d.ts

@@ -1,3 +1,3 @@
 #!/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\n  --help, -h                Show this help\n  --version, -V             Show version\n";
 export declare function getVersion(): string;

package/dist/bin/mutineer.js

@@ -28,6 +28,8 @@ 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)
 
   --help, -h                Show this help
   --version, -V             Show version
@@ -76,7 +78,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/mutators/__tests__/operator.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { relaxLE, relaxGE, tightenLT, tightenGT, andToOr, orToAnd, nullishToOr, flipEQ, flipNEQ, flipStrictEQ, flipStrictNEQ, addToSub, subToAdd, mulToDiv, divToMul, modToMul, powerToMul, } from '../operator.js';
+import { relaxLE, relaxGE, tightenLT, tightenGT, andToOr, orToAnd, nullishToOr, flipEQ, flipNEQ, flipStrictEQ, flipStrictNEQ, addToSub, subToAdd, mulToDiv, divToMul, modToMul, powerToMul, preInc, preDec, postInc, postDec, addAssignToSub, subAssignToAdd, mulAssignToDiv, divAssignToMul, } from '../operator.js';
 import { buildParseContext } from '../utils.js';
 // ---------------------------------------------------------------------------
 // Shared behaviour (tested once; all mutators use the same factory)
@@ -183,3 +183,99 @@ describe('powerToMul', () => {
         expect(result.code).toBe(`const n = a * b`);
     });
 });
+// ---------------------------------------------------------------------------
+// Increment/decrement mutators
+// ---------------------------------------------------------------------------
+describe('preInc', () => {
+    it("replaces '++x' to '--x'", () => {
+        const src = `const n = ++i`;
+        const [result] = preInc.apply(src);
+        expect(result.code).toBe(`const n = --i`);
+    });
+    it('does not match postfix x++', () => {
+        const src = `i++`;
+        expect(preInc.apply(src)).toHaveLength(0);
+    });
+    it('applyWithContext matches apply', () => {
+        const src = `const n = ++i`;
+        const ctx = buildParseContext(src);
+        expect(preInc.applyWithContext(src, ctx)).toEqual(preInc.apply(src));
+    });
+});
+describe('preDec', () => {
+    it("replaces '--x' to '++x'", () => {
+        const src = `const n = --i`;
+        const [result] = preDec.apply(src);
+        expect(result.code).toBe(`const n = ++i`);
+    });
+    it('does not match postfix x--', () => {
+        const src = `i--`;
+        expect(preDec.apply(src)).toHaveLength(0);
+    });
+});
+describe('postInc', () => {
+    it("replaces 'x++' to 'x--'", () => {
+        const src = `i++`;
+        const [result] = postInc.apply(src);
+        expect(result.code).toBe(`i--`);
+    });
+    it('does not match prefix ++x', () => {
+        const src = `const n = ++i`;
+        expect(postInc.apply(src)).toHaveLength(0);
+    });
+    it('applyWithContext matches apply', () => {
+        const src = `i++`;
+        const ctx = buildParseContext(src);
+        expect(postInc.applyWithContext(src, ctx)).toEqual(postInc.apply(src));
+    });
+});
+describe('postDec', () => {
+    it("replaces 'x--' to 'x++'", () => {
+        const src = `i--`;
+        const [result] = postDec.apply(src);
+        expect(result.code).toBe(`i++`);
+    });
+    it('does not match prefix --x', () => {
+        const src = `const n = --i`;
+        expect(postDec.apply(src)).toHaveLength(0);
+    });
+});
+// ---------------------------------------------------------------------------
+// Compound assignment mutators
+// ---------------------------------------------------------------------------
+describe('addAssignToSub', () => {
+    it("replaces '+=' with '-='", () => {
+        const src = `x += 1`;
+        const [result] = addAssignToSub.apply(src);
+        expect(result.code).toBe(`x -= 1`);
+    });
+    it('returns no results when operator absent', () => {
+        expect(addAssignToSub.apply(`x -= 1`)).toHaveLength(0);
+    });
+    it('applyWithContext matches apply', () => {
+        const src = `x += 1`;
+        const ctx = buildParseContext(src);
+        expect(addAssignToSub.applyWithContext(src, ctx)).toEqual(addAssignToSub.apply(src));
+    });
+});
+describe('subAssignToAdd', () => {
+    it("replaces '-=' with '+='", () => {
+        const src = `x -= 1`;
+        const [result] = subAssignToAdd.apply(src);
+        expect(result.code).toBe(`x += 1`);
+    });
+});
+describe('mulAssignToDiv', () => {
+    it("replaces '*=' with '/='", () => {
+        const src = `x *= 2`;
+        const [result] = mulAssignToDiv.apply(src);
+        expect(result.code).toBe(`x /= 2`);
+    });
+});
+describe('divAssignToMul', () => {
+    it("replaces '/=' with '*='", () => {
+        const src = `x /= 2`;
+        const [result] = divAssignToMul.apply(src);
+        expect(result.code).toBe(`x *= 2`);
+    });
+});

package/dist/mutators/__tests__/registry.spec.js

@@ -18,6 +18,14 @@ const ALL_NAMES = [
     'divToMul',
     'modToMul',
     'powerToMul',
+    'preInc',
+    'preDec',
+    'postInc',
+    'postDec',
+    'addAssignToSub',
+    'subAssignToAdd',
+    'mulAssignToDiv',
+    'divAssignToMul',
     'returnToNull',
     'returnToUndefined',
     'returnFlipBool',

package/dist/mutators/operator.d.ts

@@ -23,3 +23,11 @@ export declare const mulToDiv: ASTMutator;
 export declare const divToMul: ASTMutator;
 export declare const modToMul: ASTMutator;
 export declare const powerToMul: ASTMutator;
+export declare const preInc: ASTMutator;
+export declare const preDec: ASTMutator;
+export declare const postInc: ASTMutator;
+export declare const postDec: ASTMutator;
+export declare const addAssignToSub: ASTMutator;
+export declare const subAssignToAdd: ASTMutator;
+export declare const mulAssignToDiv: ASTMutator;
+export declare const divAssignToMul: ASTMutator;

package/dist/mutators/operator.js

@@ -5,7 +5,7 @@
  * using AST traversal and produces a mutated source string with that operator
  * replaced by its counterpart.
  */
-import { collectOperatorTargets } from './utils.js';
+import { collectOperatorTargets, buildParseContext } from './utils.js';
 /**
  * Factory to build an operator mutator using AST traversal and token analysis.
  *
@@ -33,6 +33,53 @@ function makeOperatorMutator(name, description, fromOp, toOp) {
         },
     };
 }
+/**
+ * Factory for UpdateExpression mutators (++/--).
+ * mapKey distinguishes prefix vs postfix: 'pre++', 'post++', 'pre--', 'post--'
+ */
+function makeUpdateMutator(name, description, mapKey, toOp) {
+    function targetsToOutputs(src, targets) {
+        return targets.map((target) => ({
+            line: target.line,
+            col: target.col1,
+            code: src.slice(0, target.start) + toOp + src.slice(target.end),
+        }));
+    }
+    return {
+        name,
+        description,
+        apply(src) {
+            const ctx = buildParseContext(src);
+            return targetsToOutputs(src, ctx.preCollected.updateTargets.get(mapKey) ?? []);
+        },
+        applyWithContext(src, ctx) {
+            return targetsToOutputs(src, ctx.preCollected.updateTargets.get(mapKey) ?? []);
+        },
+    };
+}
+/**
+ * Factory for AssignmentExpression mutators (+=, -=, *=, /=).
+ */
+function makeAssignmentMutator(name, description, fromOp, toOp) {
+    function targetsToOutputs(src, targets) {
+        return targets.map((target) => ({
+            line: target.line,
+            col: target.col1,
+            code: src.slice(0, target.start) + toOp + src.slice(target.end),
+        }));
+    }
+    return {
+        name,
+        description,
+        apply(src) {
+            const ctx = buildParseContext(src);
+            return targetsToOutputs(src, ctx.preCollected.assignmentTargets.get(fromOp) ?? []);
+        },
+        applyWithContext(src, ctx) {
+            return targetsToOutputs(src, ctx.preCollected.assignmentTargets.get(fromOp) ?? []);
+        },
+    };
+}
 /* === Boundary mutators === */
 export const relaxLE = makeOperatorMutator('relaxLE', "Change '<=' to '<' (relax boundary)", '<=', '<');
 export const relaxGE = makeOperatorMutator('relaxGE', "Change '>=' to '>' (relax boundary)", '>=', '>');
@@ -54,3 +101,13 @@ export const mulToDiv = makeOperatorMutator('mulToDiv', "Change '*' to '/'", '*'
 export const divToMul = makeOperatorMutator('divToMul', "Change '/' to '*'", '/', '*');
 export const modToMul = makeOperatorMutator('modToMul', "Change '%' to '*'", '%', '*');
 export const powerToMul = makeOperatorMutator('powerToMul', "Change '**' to '*'", '**', '*');
+/* === Increment/decrement mutators === */
+export const preInc = makeUpdateMutator('preInc', "Change '++x' to '--x'", 'pre++', '--');
+export const preDec = makeUpdateMutator('preDec', "Change '--x' to '++x'", 'pre--', '++');
+export const postInc = makeUpdateMutator('postInc', "Change 'x++' to 'x--'", 'post++', '--');
+export const postDec = makeUpdateMutator('postDec', "Change 'x--' to 'x++'", 'post--', '++');
+/* === Compound assignment mutators === */
+export const addAssignToSub = makeAssignmentMutator('addAssignToSub', "Change '+=' to '-='", '+=', '-=');
+export const subAssignToAdd = makeAssignmentMutator('subAssignToAdd', "Change '-=' to '+='", '-=', '+=');
+export const mulAssignToDiv = makeAssignmentMutator('mulAssignToDiv', "Change '*=' to '/='", '*=', '/=');
+export const divAssignToMul = makeAssignmentMutator('divAssignToMul', "Change '/=' to '*='", '/=', '*=');

package/dist/mutators/registry.js

@@ -3,7 +3,7 @@
  *
  * Aggregates all mutators and exposes `getRegistry` for filtered access.
  */
-import { relaxLE, relaxGE, tightenLT, tightenGT, andToOr, orToAnd, nullishToOr, flipEQ, flipNEQ, flipStrictEQ, flipStrictNEQ, addToSub, subToAdd, mulToDiv, divToMul, modToMul, powerToMul, } from './operator.js';
+import { relaxLE, relaxGE, tightenLT, tightenGT, andToOr, orToAnd, nullishToOr, flipEQ, flipNEQ, flipStrictEQ, flipStrictNEQ, addToSub, subToAdd, mulToDiv, divToMul, modToMul, powerToMul, preInc, preDec, postInc, postDec, addAssignToSub, subAssignToAdd, mulAssignToDiv, divAssignToMul, } from './operator.js';
 import { returnToNull, returnToUndefined, returnFlipBool, returnZero, returnEmptyStr, returnEmptyArr, } from './return-value.js';
 const ALL = [
     relaxLE,
@@ -23,6 +23,14 @@ const ALL = [
     divToMul,
     modToMul,
     powerToMul,
+    preInc,
+    preDec,
+    postInc,
+    postDec,
+    addAssignToSub,
+    subAssignToAdd,
+    mulAssignToDiv,
+    divAssignToMul,
     returnToNull,
     returnToUndefined,
     returnFlipBool,

package/dist/mutators/utils.d.ts

@@ -81,6 +81,8 @@ export interface ReturnStatementInfo {
 export interface PreCollected {
     readonly operatorTargets: Map<string, OperatorTarget[]>;
     readonly returnStatements: ReturnStatementInfo[];
+    readonly updateTargets: Map<string, OperatorTarget[]>;
+    readonly assignmentTargets: Map<string, OperatorTarget[]>;
 }
 /**
  * Pre-parsed context for a source file.

package/dist/mutators/utils.js

@@ -128,6 +128,8 @@ export function isBinaryOrLogical(node) {
 export function collectAllTargets(src, ast, tokens, ignoreLines) {
     const operatorTargets = new Map();
     const returnStatements = [];
+    const updateTargets = new Map();
+    const assignmentTargets = new Map();
     function handleBinaryOrLogical(n) {
         const nodeStart = n.start ?? 0;
         const nodeEnd = n.end ?? 0;
@@ -152,6 +154,55 @@ export function collectAllTargets(src, ast, tokens, ignoreLines) {
             });
         }
     }
+    function handleUpdate(n) {
+        const nodeStart = n.start ?? 0;
+        const nodeEnd = n.end ?? 0;
+        const opValue = n.operator;
+        const tok = tokens.find((tk) => tk.start >= nodeStart && tk.end <= nodeEnd && tk.value === opValue);
+        if (tok) {
+            const line = tok.loc.start.line;
+            if (ignoreLines.has(line))
+                return;
+            const visualCol = getVisualColumn(src, tok.start);
+            const mapKey = (n.prefix ? 'pre' : 'post') + opValue;
+            let arr = updateTargets.get(mapKey);
+            if (!arr) {
+                arr = [];
+                updateTargets.set(mapKey, arr);
+            }
+            arr.push({
+                start: tok.start,
+                end: tok.end,
+                line,
+                col1: visualCol,
+                op: opValue,
+            });
+        }
+    }
+    function handleAssignment(n) {
+        const nodeStart = n.start ?? 0;
+        const nodeEnd = n.end ?? 0;
+        const opValue = n.operator;
+        const tok = tokens.find((tk) => tk.start >= nodeStart && tk.end <= nodeEnd && tk.value === opValue);
+        if (tok) {
+            const line = tok.loc.start.line;
+            if (ignoreLines.has(line))
+                return;
+            const visualCol = getVisualColumn(src, tok.start);
+            let arr = assignmentTargets.get(opValue);
+            if (!arr) {
+                arr = [];
+                assignmentTargets.set(opValue, arr);
+            }
+            arr.push({
+                start: tok.start,
+                end: tok.end,
+                line,
+                col1: visualCol,
+                op: opValue,
+            });
+        }
+    }
     traverse(ast, {
         BinaryExpression(p) {
             handleBinaryOrLogical(p.node);
@@ -159,6 +210,12 @@ export function collectAllTargets(src, ast, tokens, ignoreLines) {
         LogicalExpression(p) {
             handleBinaryOrLogical(p.node);
         },
+        UpdateExpression(p) {
+            handleUpdate(p.node);
+        },
+        AssignmentExpression(p) {
+            handleAssignment(p.node);
+        },
         ReturnStatement(p) {
             const node = p.node;
             if (!node.argument)
@@ -182,7 +239,7 @@ export function collectAllTargets(src, ast, tokens, ignoreLines) {
             });
         },
     });
-    return { operatorTargets, returnStatements };
+    return { operatorTargets, returnStatements, updateTargets, assignmentTargets };
 }
 /**
  * Parse a source file once and build a reusable ParseContext.

package/dist/runner/__tests__/args.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseFlagNumber, readNumberFlag, readStringFlag, validatePercent, validatePositiveMs, parseConcurrency, parseProgressMode, parseCliOptions, extractConfigPath, } from '../args.js';
+import { parseFlagNumber, readNumberFlag, readStringFlag, validatePercent, validatePositiveMs, parseConcurrency, parseProgressMode, parseCliOptions, extractConfigPath, parseShardOption, } from '../args.js';
 describe('parseFlagNumber', () => {
     it('parses valid integers', () => {
         expect(parseFlagNumber('42', '--flag')).toBe(42);
@@ -227,6 +227,24 @@ describe('parseCliOptions', () => {
     it('rejects --timeout abc', () => {
         expect(() => parseCliOptions(['--timeout', 'abc'], emptyCfg)).toThrow('Invalid value for --timeout: abc');
     });
+    it('defaults reportFormat to text', () => {
+        const opts = parseCliOptions([], emptyCfg);
+        expect(opts.reportFormat).toBe('text');
+    });
+    it('parses --report json', () => {
+        const opts = parseCliOptions(['--report', 'json'], emptyCfg);
+        expect(opts.reportFormat).toBe('json');
+    });
+    it('reads report from config', () => {
+        const opts = parseCliOptions([], { report: 'json' });
+        expect(opts.reportFormat).toBe('json');
+    });
+    it('CLI --report takes precedence over config', () => {
+        const opts = parseCliOptions(['--report', 'json'], {
+            report: 'text',
+        });
+        expect(opts.reportFormat).toBe('json');
+    });
 });
 describe('validatePositiveMs', () => {
     it('returns undefined for undefined', () => {
@@ -247,6 +265,44 @@ describe('validatePositiveMs', () => {
         expect(() => validatePositiveMs(NaN, '--timeout')).toThrow('Invalid --timeout: expected a positive number');
     });
 });
+describe('parseShardOption', () => {
+    it('returns undefined when --shard is absent', () => {
+        expect(parseShardOption([])).toBeUndefined();
+        expect(parseShardOption(['--runner', 'vitest'])).toBeUndefined();
+    });
+    it('parses valid shard with space syntax', () => {
+        expect(parseShardOption(['--shard', '1/2'])).toEqual({ index: 1, total: 2 });
+        expect(parseShardOption(['--shard', '2/2'])).toEqual({ index: 2, total: 2 });
+        expect(parseShardOption(['--shard', '3/4'])).toEqual({ index: 3, total: 4 });
+    });
+    it('parses valid shard with = syntax', () => {
+        expect(parseShardOption(['--shard=1/2'])).toEqual({ index: 1, total: 2 });
+    });
+    it('throws on 5/4 (index > total)', () => {
+        expect(() => parseShardOption(['--shard', '5/4'])).toThrow('Invalid --shard');
+    });
+    it('throws on 0/4 (index < 1)', () => {
+        expect(() => parseShardOption(['--shard', '0/4'])).toThrow('Invalid --shard');
+    });
+    it('throws on 1/0 (total < 1)', () => {
+        expect(() => parseShardOption(['--shard', '1/0'])).toThrow('Invalid --shard');
+    });
+    it('throws on bad format', () => {
+        expect(() => parseShardOption(['--shard', 'bad'])).toThrow('Invalid --shard format');
+        expect(() => parseShardOption(['--shard', '1-2'])).toThrow('Invalid --shard format');
+    });
+});
+describe('parseCliOptions shard', () => {
+    const emptyCfg = {};
+    it('parses --shard into opts.shard', () => {
+        const opts = parseCliOptions(['--shard', '2/4'], emptyCfg);
+        expect(opts.shard).toEqual({ index: 2, total: 4 });
+    });
+    it('opts.shard is undefined when flag absent', () => {
+        const opts = parseCliOptions([], emptyCfg);
+        expect(opts.shard).toBeUndefined();
+    });
+});
 describe('extractConfigPath', () => {
     it('extracts --config with separate value', () => {
         expect(extractConfigPath(['--config', 'my.config.ts'])).toBe('my.config.ts');

package/dist/runner/__tests__/cache.spec.js

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import { clearCacheOnStart, saveCacheAtomic, decodeCacheKey, keyForTests, hash, readMutantCache, } from '../cache.js';
+import { clearCacheOnStart, saveCacheAtomic, decodeCacheKey, keyForTests, hash, readMutantCache, getCacheFilename, } from '../cache.js';
 let tmpDir;
 beforeEach(async () => {
     tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mutineer-cache-'));
@@ -10,9 +10,19 @@ beforeEach(async () => {
 afterEach(async () => {
     await fs.rm(tmpDir, { recursive: true, force: true });
 });
+describe('getCacheFilename', () => {
+    it('returns default filename when no shard', () => {
+        expect(getCacheFilename()).toBe('.mutineer-cache.json');
+        expect(getCacheFilename(undefined)).toBe('.mutineer-cache.json');
+    });
+    it('returns shard-namespaced filename when shard provided', () => {
+        expect(getCacheFilename({ index: 1, total: 2 })).toBe('.mutineer-cache-shard-1-of-2.json');
+        expect(getCacheFilename({ index: 3, total: 4 })).toBe('.mutineer-cache-shard-3-of-4.json');
+    });
+});
 describe('clearCacheOnStart', () => {
     it('removes the cache file if it exists', async () => {
-        const cacheFile = path.join(tmpDir, '.mutate-cache.json');
+        const cacheFile = path.join(tmpDir, '.mutineer-cache.json');
         await fs.writeFile(cacheFile, '{}');
         await clearCacheOnStart(tmpDir);
         await expect(fs.access(cacheFile)).rejects.toThrow();
@@ -20,6 +30,19 @@ describe('clearCacheOnStart', () => {
     it('does not throw if cache file does not exist', async () => {
         await expect(clearCacheOnStart(tmpDir)).resolves.toBeUndefined();
     });
+    it('removes shard-specific cache file', async () => {
+        const shardFile = path.join(tmpDir, '.mutineer-cache-shard-1-of-2.json');
+        await fs.writeFile(shardFile, '{}');
+        await clearCacheOnStart(tmpDir, { index: 1, total: 2 });
+        await expect(fs.access(shardFile)).rejects.toThrow();
+    });
+    it('does not remove default cache when shard is specified', async () => {
+        const defaultFile = path.join(tmpDir, '.mutineer-cache.json');
+        await fs.writeFile(defaultFile, '{}');
+        await clearCacheOnStart(tmpDir, { index: 1, total: 2 });
+        // default file should still exist
+        await expect(fs.access(defaultFile)).resolves.toBeUndefined();
+    });
 });
 describe('saveCacheAtomic', () => {
     it('writes cache data to the file', async () => {
@@ -33,7 +56,7 @@ describe('saveCacheAtomic', () => {
             },
         };
         await saveCacheAtomic(tmpDir, cache);
-        const content = await fs.readFile(path.join(tmpDir, '.mutate-cache.json'), 'utf8');
+        const content = await fs.readFile(path.join(tmpDir, '.mutineer-cache.json'), 'utf8');
         expect(JSON.parse(content)).toEqual(cache);
     });
     it('overwrites existing cache', async () => {
@@ -48,9 +71,25 @@ describe('saveCacheAtomic', () => {
             },
         };
         await saveCacheAtomic(tmpDir, newCache);
-        const content = await fs.readFile(path.join(tmpDir, '.mutate-cache.json'), 'utf8');
+        const content = await fs.readFile(path.join(tmpDir, '.mutineer-cache.json'), 'utf8');
         expect(JSON.parse(content)).toEqual(newCache);
     });
+    it('writes to shard-named file when shard is provided', async () => {
+        const cache = {
+            k: {
+                status: 'killed',
+                file: 'x.ts',
+                line: 1,
+                col: 0,
+                mutator: 'm',
+            },
+        };
+        await saveCacheAtomic(tmpDir, cache, { index: 2, total: 3 });
+        const content = await fs.readFile(path.join(tmpDir, '.mutineer-cache-shard-2-of-3.json'), 'utf8');
+        expect(JSON.parse(content)).toEqual(cache);
+        // default file should NOT exist
+        await expect(fs.access(path.join(tmpDir, '.mutineer-cache.json'))).rejects.toThrow();
+    });
 });
 describe('decodeCacheKey', () => {
     it('decodes a full cache key', () => {
@@ -128,6 +167,24 @@ describe('readMutantCache', () => {
         const result = await readMutantCache(tmpDir);
         expect(result).toEqual({});
     });
+    it('reads from shard-named file when shard is provided', async () => {
+        const cache = {
+            'k:v:f.ts:1,0:m': {
+                status: 'killed',
+                file: 'f.ts',
+                line: 1,
+                col: 0,
+                mutator: 'm',
+            },
+        };
+        await fs.writeFile(path.join(tmpDir, '.mutineer-cache-shard-1-of-2.json'), JSON.stringify(cache));
+        const result = await readMutantCache(tmpDir, { index: 1, total: 2 });
+        expect(result['k:v:f.ts:1,0:m'].status).toBe('killed');
+    });
+    it('returns empty object when shard file does not exist', async () => {
+        const result = await readMutantCache(tmpDir, { index: 2, total: 4 });
+        expect(result).toEqual({});
+    });
     it('reads and normalizes object-format cache entries', async () => {
         const cache = {
             'testsig:codesig:file.ts:1,0:flip': {
@@ -138,7 +195,7 @@ describe('readMutantCache', () => {
                 mutator: 'flip',
             },
         };
-        await fs.writeFile(path.join(tmpDir, '.mutate-cache.json'), JSON.stringify(cache));
+        await fs.writeFile(path.join(tmpDir, '.mutineer-cache.json'), JSON.stringify(cache));
         const result = await readMutantCache(tmpDir);
         expect(result['testsig:codesig:file.ts:1,0:flip']).toEqual({
             status: 'killed',
@@ -152,14 +209,14 @@ describe('readMutantCache', () => {
         const cache = {
             'testsig:codesig:file.ts:1,0:flip': 'killed',
         };
-        await fs.writeFile(path.join(tmpDir, '.mutate-cache.json'), JSON.stringify(cache));
+        await fs.writeFile(path.join(tmpDir, '.mutineer-cache.json'), JSON.stringify(cache));
         const result = await readMutantCache(tmpDir);
         const entry = result['testsig:codesig:file.ts:1,0:flip'];
         expect(entry.status).toBe('killed');
         expect(entry.mutator).toBe('flip');
     });
     it('returns empty object for invalid JSON', async () => {
-        await fs.writeFile(path.join(tmpDir, '.mutate-cache.json'), 'not json');
+        await fs.writeFile(path.join(tmpDir, '.mutineer-cache.json'), 'not json');
         const result = await readMutantCache(tmpDir);
         expect(result).toEqual({});
     });
@@ -169,7 +226,7 @@ describe('readMutantCache', () => {
                 status: 'escaped',
             },
         };
-        await fs.writeFile(path.join(tmpDir, '.mutate-cache.json'), JSON.stringify(cache));
+        await fs.writeFile(path.join(tmpDir, '.mutineer-cache.json'), JSON.stringify(cache));
         const result = await readMutantCache(tmpDir);
         const entry = result['testsig:codesig:file.ts:5,3:mut'];
         expect(entry.status).toBe('escaped');

package/dist/runner/__tests__/cleanup.spec.js

@@ -38,4 +38,34 @@ describe('cleanupMutineerDirs', () => {
         const stat = await fs.stat(srcDir);
         expect(stat.isDirectory()).toBe(true);
     });
+    it('does not remove cache files by default', async () => {
+        const cacheFile = path.join(tmpDir, '.mutineer-cache.json');
+        await fs.writeFile(cacheFile, '{}');
+        await cleanupMutineerDirs(tmpDir);
+        await expect(fs.access(cacheFile)).resolves.toBeUndefined();
+    });
+    it('removes .mutineer-cache*.json files when includeCacheFiles is true', async () => {
+        const cacheFile = path.join(tmpDir, '.mutineer-cache.json');
+        const shardFile = path.join(tmpDir, '.mutineer-cache-shard-1-of-2.json');
+        await fs.writeFile(cacheFile, '{}');
+        await fs.writeFile(shardFile, '{}');
+        await cleanupMutineerDirs(tmpDir, { includeCacheFiles: true });
+        await expect(fs.access(cacheFile)).rejects.toThrow();
+        await expect(fs.access(shardFile)).rejects.toThrow();
+    });
+    it('removes legacy .mutate-cache*.json files for migration when includeCacheFiles is true', async () => {
+        const legacyCache = path.join(tmpDir, '.mutate-cache.json');
+        const legacyShard = path.join(tmpDir, '.mutate-cache-shard-2-of-4.json');
+        await fs.writeFile(legacyCache, '{}');
+        await fs.writeFile(legacyShard, '{}');
+        await cleanupMutineerDirs(tmpDir, { includeCacheFiles: true });
+        await expect(fs.access(legacyCache)).rejects.toThrow();
+        await expect(fs.access(legacyShard)).rejects.toThrow();
+    });
+    it('removes .mutineer-cache*.json.tmp temp files when includeCacheFiles is true', async () => {
+        const tmpFile = path.join(tmpDir, '.mutineer-cache.json.tmp');
+        await fs.writeFile(tmpFile, '{}');
+        await cleanupMutineerDirs(tmpDir, { includeCacheFiles: true });
+        await expect(fs.access(tmpFile)).rejects.toThrow();
+    });
 });

package/dist/runner/__tests__/coverage-resolver.spec.js

@@ -16,6 +16,8 @@ function makeOpts(overrides = {}) {
         minKillPercent: undefined,
         runner: 'vitest',
         timeout: undefined,
+        reportFormat: 'text',
+        shard: undefined,
         ...overrides,
     };
 }