@mutineerjs/mutineer 0.2.3 → 0.3.2

package/dist/mutators/return-value.js

@@ -0,0 +1,104 @@
+/**
+ * Return value mutators.
+ *
+ * These mutators target `return` statements and replace the returned expression
+ * with a simpler or opposite value. They catch a different class of test gap
+ * from operator mutators: they reveal when callers never check what a function
+ * returns (e.g. no null-check, no assertion on the return value).
+ */
+import * as t from '@babel/types';
+import { traverse, getVisualColumn, parseSource, buildIgnoreLines, } from './utils.js';
+/**
+ * Factory for return-value mutators.
+ *
+ * Traverses all `ReturnStatement` nodes in the source. For each node that has
+ * an argument (i.e. not a bare `return;`), calls `replacer` with the argument
+ * AST node. If `replacer` returns a non-null string, emits a mutation that
+ * splices that string in place of the original argument.
+ *
+ * @param name - Mutator name used in the registry and config include/exclude
+ * @param description - Human-readable description shown in reports
+ * @param replacer - Returns the replacement source text, or null to skip
+ */
+function makeReturnMutator(name, description, replacer) {
+    return {
+        name,
+        description,
+        apply(src) {
+            const ast = parseSource(src);
+            const fileAst = ast;
+            const ignoreLines = buildIgnoreLines(fileAst.comments ?? []);
+            const outputs = [];
+            traverse(ast, {
+                ReturnStatement(path) {
+                    const node = path.node;
+                    if (!node.argument)
+                        return; // bare return; — nothing to replace
+                    const line = node.loc?.start.line;
+                    if (line === undefined)
+                        return;
+                    if (ignoreLines.has(line))
+                        return;
+                    const replacement = replacer(node.argument);
+                    if (replacement === null)
+                        return;
+                    const argStart = node.argument.start;
+                    const argEnd = node.argument.end;
+                    if (argStart == null || argEnd == null)
+                        return;
+                    const col = getVisualColumn(src, node.start ?? 0);
+                    const code = src.slice(0, argStart) + replacement + src.slice(argEnd);
+                    outputs.push({ line, col, code });
+                },
+            });
+            return outputs;
+        },
+    };
+}
+/* === Concrete return-value mutators === */
+/**
+ * Replace any non-null return value with `null`.
+ * Reveals callers that never check for null returns.
+ */
+export const returnToNull = makeReturnMutator('returnToNull', 'Replace return value with null', (node) => (t.isNullLiteral(node) ? null : 'null'));
+/**
+ * Replace any non-undefined return value with `undefined`.
+ * Reveals callers that never guard against undefined returns.
+ */
+export const returnToUndefined = makeReturnMutator('returnToUndefined', 'Replace return value with undefined', (node) => (t.isIdentifier(node, { name: 'undefined' }) ? null : 'undefined'));
+/**
+ * Flip `return true` ↔ `return false`.
+ * Catches missing assertions on boolean-returning functions.
+ */
+export const returnFlipBool = makeReturnMutator('returnFlipBool', 'Flip boolean return value (true ↔ false)', (node) => {
+    if (!t.isBooleanLiteral(node))
+        return null;
+    return node.value ? 'false' : 'true';
+});
+/**
+ * Replace a non-zero numeric return with `0`.
+ * Catches callers that never check the numeric return value.
+ */
+export const returnZero = makeReturnMutator('returnZero', 'Replace numeric return value with 0', (node) => {
+    if (!t.isNumericLiteral(node))
+        return null;
+    return node.value === 0 ? null : '0';
+});
+/**
+ * Replace a non-empty string return with `''`.
+ * Catches callers that never check the string return value.
+ */
+export const returnEmptyStr = makeReturnMutator('returnEmptyStr', "Replace string return value with ''", (node) => {
+    if (!t.isStringLiteral(node))
+        return null;
+    return node.value === '' ? null : "''";
+});
+/**
+ * Replace an array expression return with `[]`.
+ * Catches callers that never check for an empty array.
+ */
+export const returnEmptyArr = makeReturnMutator('returnEmptyArr', 'Replace array return value with []', (node) => {
+    if (!t.isArrayExpression(node))
+        return null;
+    return node.elements.length === 0 ? null : '[]';
+});

package/dist/mutators/utils.d.ts

@@ -4,9 +4,16 @@
  * Provides functions for parsing, traversing, and analyzing code ASTs.
  * These utilities are used by operator mutators to locate and replace operators.
  */
+import { type ParserOptions } from '@babel/parser';
 import * as t from '@babel/types';
 import type { OperatorTarget } from './types.js';
 export declare const traverse: typeof import('@babel/traverse').default;
+/**
+ * Parser configuration for Babel.
+ * Enables support for TypeScript, JSX, decorators, and modern JavaScript features.
+ */
+export declare const parserOptsTs: ParserOptions;
+export declare const parserOptsFlow: ParserOptions;
 /**
  * Tab width used for converting character columns to visual columns.
  * This helps report correct column positions for terminals that render tabs.
@@ -21,6 +28,20 @@ export declare const TAB_WIDTH = 4;
  * @returns The visual column (1-based)
  */
 export declare function getVisualColumn(src: string, charOffset: number): number;
+/**
+ * Build a set of line numbers that should be ignored for mutation based on
+ * disable comments (`mutineer-disable`, `mutineer-disable-line`,
+ * `mutineer-disable-next-line`).
+ *
+ * @param comments - The comment nodes from the parsed AST
+ * @returns Set of 1-based line numbers that should not be mutated
+ */
+export declare function buildIgnoreLines(comments: readonly t.Comment[]): Set<number>;
+/**
+ * Parse source with the TypeScript Babel plugin, falling back to the Flow
+ * plugin for Flow-typed React files that fail TS parsing.
+ */
+export declare function parseSource(src: string): import("@babel/parser").ParseResult<t.File>;
 /**
  * Type guard to check if a node is a BinaryExpression or LogicalExpression.
  */

package/dist/mutators/utils.js

@@ -13,7 +13,7 @@ export const traverse = traverseModuleNormalized.default ?? traverseModuleNormal
  * Parser configuration for Babel.
  * Enables support for TypeScript, JSX, decorators, and modern JavaScript features.
  */
-const parserOptsTs = {
+export const parserOptsTs = {
     sourceType: 'unambiguous',
     plugins: [
         'typescript',
@@ -28,7 +28,7 @@ const parserOptsTs = {
     ],
     tokens: true,
 };
-const parserOptsFlow = {
+export const parserOptsFlow = {
     sourceType: 'unambiguous',
     plugins: [
         'flow',
@@ -74,33 +74,14 @@ export function getVisualColumn(src, charOffset) {
     return visualCol;
 }
 /**
- * Type guard to check if a node is a BinaryExpression or LogicalExpression.
- */
-export function isBinaryOrLogical(node) {
-    return node.type === 'BinaryExpression' || node.type === 'LogicalExpression';
-}
-/**
- * Collect the operator tokens for a given operator and return their exact locations.
- * Uses AST traversal to find BinaryExpression/LogicalExpression nodes, then maps them
- * to token positions for accurate column reporting.
+ * Build a set of line numbers that should be ignored for mutation based on
+ * disable comments (`mutineer-disable`, `mutineer-disable-line`,
+ * `mutineer-disable-next-line`).
  *
- * @param src - The source code
- * @param opValue - The operator to search for (e.g., '&&', '<=')
- * @returns Array of target locations for the operator
+ * @param comments - The comment nodes from the parsed AST
+ * @returns Set of 1-based line numbers that should not be mutated
  */
-export function collectOperatorTargets(src, opValue) {
-    let ast;
-    try {
-        ast = parse(src, parserOptsTs);
-    }
-    catch {
-        // Flow-typed React sources fail under TS parsing; fall back to Flow plugins.
-        ast = parse(src, parserOptsFlow);
-    }
-    const fileAst = ast;
-    const tokens = fileAst.tokens ?? [];
-    const comments = fileAst.comments ?? [];
-    const out = [];
+export function buildIgnoreLines(comments) {
     const ignoreLines = new Set();
     for (const comment of comments) {
         const text = comment.value.trim();
@@ -120,6 +101,42 @@ export function collectOperatorTargets(src, opValue) {
             }
         }
     }
+    return ignoreLines;
+}
+/**
+ * Parse source with the TypeScript Babel plugin, falling back to the Flow
+ * plugin for Flow-typed React files that fail TS parsing.
+ */
+export function parseSource(src) {
+    try {
+        return parse(src, parserOptsTs);
+    }
+    catch {
+        return parse(src, parserOptsFlow);
+    }
+}
+/**
+ * Type guard to check if a node is a BinaryExpression or LogicalExpression.
+ */
+export function isBinaryOrLogical(node) {
+    return node.type === 'BinaryExpression' || node.type === 'LogicalExpression';
+}
+/**
+ * Collect the operator tokens for a given operator and return their exact locations.
+ * Uses AST traversal to find BinaryExpression/LogicalExpression nodes, then maps them
+ * to token positions for accurate column reporting.
+ *
+ * @param src - The source code
+ * @param opValue - The operator to search for (e.g., '&&', '<=')
+ * @returns Array of target locations for the operator
+ */
+export function collectOperatorTargets(src, opValue) {
+    const ast = parseSource(src);
+    const fileAst = ast;
+    const tokens = fileAst.tokens ?? [];
+    const comments = fileAst.comments ?? [];
+    const out = [];
+    const ignoreLines = buildIgnoreLines(comments);
     traverse(ast, {
         enter(p) {
             if (!isBinaryOrLogical(p.node))

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

@@ -0,0 +1,225 @@
+import { describe, it, expect } from 'vitest';
+import { parseFlagNumber, readNumberFlag, readStringFlag, validatePercent, parseConcurrency, parseProgressMode, parseCliOptions, extractConfigPath, } from '../args.js';
+describe('parseFlagNumber', () => {
+    it('parses valid integers', () => {
+        expect(parseFlagNumber('42', '--flag')).toBe(42);
+    });
+    it('parses valid floats', () => {
+        expect(parseFlagNumber('3.14', '--flag')).toBe(3.14);
+    });
+    it('parses zero', () => {
+        expect(parseFlagNumber('0', '--flag')).toBe(0);
+    });
+    it('parses negative numbers', () => {
+        expect(parseFlagNumber('-5', '--flag')).toBe(-5);
+    });
+    it('throws on non-numeric strings', () => {
+        expect(() => parseFlagNumber('abc', '--flag')).toThrow('Invalid value for --flag: abc');
+    });
+    it('parses empty string as 0', () => {
+        // Number('') === 0, which is finite
+        expect(parseFlagNumber('', '--flag')).toBe(0);
+    });
+    it('throws on NaN-producing values', () => {
+        expect(() => parseFlagNumber('not-a-number', '--flag')).toThrow('Invalid value for --flag: not-a-number');
+    });
+    it('throws on Infinity', () => {
+        expect(() => parseFlagNumber('Infinity', '--flag')).toThrow('Invalid value for --flag: Infinity');
+    });
+});
+describe('readNumberFlag', () => {
+    it('reads flag with separate value', () => {
+        expect(readNumberFlag(['--count', '5'], '--count')).toBe(5);
+    });
+    it('reads flag with = syntax', () => {
+        expect(readNumberFlag(['--count=10'], '--count')).toBe(10);
+    });
+    it('returns undefined when flag is not present', () => {
+        expect(readNumberFlag(['--other', '5'], '--count')).toBeUndefined();
+    });
+    it('throws when no value follows flag', () => {
+        expect(() => readNumberFlag(['--count'], '--count')).toThrow('Expected a numeric value after --count');
+    });
+    it('throws when value is not a number', () => {
+        expect(() => readNumberFlag(['--count', 'abc'], '--count')).toThrow('Invalid value for --count: abc');
+    });
+});
+describe('readStringFlag', () => {
+    it('reads flag with separate value', () => {
+        expect(readStringFlag(['--config', 'path.ts'], '--config')).toBe('path.ts');
+    });
+    it('reads flag with = syntax', () => {
+        expect(readStringFlag(['--config=path.ts'], '--config')).toBe('path.ts');
+    });
+    it('reads alias', () => {
+        expect(readStringFlag(['-c', 'path.ts'], '--config', '-c')).toBe('path.ts');
+    });
+    it('reads alias with = syntax', () => {
+        expect(readStringFlag(['-c=path.ts'], '--config', '-c')).toBe('path.ts');
+    });
+    it('returns undefined when flag is not present', () => {
+        expect(readStringFlag(['--other', 'val'], '--config')).toBeUndefined();
+    });
+    it('throws when no value follows flag', () => {
+        expect(() => readStringFlag(['--config'], '--config')).toThrow('Expected a value after --config');
+    });
+    it('throws when no value follows alias', () => {
+        expect(() => readStringFlag(['-c'], '--config', '-c')).toThrow('Expected a value after -c');
+    });
+});
+describe('validatePercent', () => {
+    it('returns undefined for undefined', () => {
+        expect(validatePercent(undefined, 'test')).toBeUndefined();
+    });
+    it('returns the value for valid percentages', () => {
+        expect(validatePercent(0, 'test')).toBe(0);
+        expect(validatePercent(50, 'test')).toBe(50);
+        expect(validatePercent(100, 'test')).toBe(100);
+    });
+    it('throws for negative values', () => {
+        expect(() => validatePercent(-1, 'test')).toThrow('Invalid test: expected value between 0 and 100 (received -1)');
+    });
+    it('throws for values over 100', () => {
+        expect(() => validatePercent(101, 'test')).toThrow('Invalid test: expected value between 0 and 100 (received 101)');
+    });
+    it('throws for non-finite values', () => {
+        expect(() => validatePercent(NaN, 'test')).toThrow('Invalid test: expected a number between 0 and 100');
+        expect(() => validatePercent(Infinity, 'test')).toThrow('Invalid test: expected a number between 0 and 100');
+    });
+});
+describe('parseConcurrency', () => {
+    it('returns default when flag not present', () => {
+        const result = parseConcurrency([]);
+        expect(result).toBeGreaterThanOrEqual(1);
+    });
+    it('parses explicit concurrency', () => {
+        expect(parseConcurrency(['--concurrency', '4'])).toBe(4);
+    });
+    it('clamps to minimum of 1', () => {
+        expect(parseConcurrency(['--concurrency', '0'])).toBeGreaterThanOrEqual(1);
+    });
+    it('handles invalid concurrency value gracefully', () => {
+        const result = parseConcurrency(['--concurrency', 'abc']);
+        expect(result).toBeGreaterThanOrEqual(1);
+    });
+});
+describe('parseProgressMode', () => {
+    it('returns bar by default', () => {
+        expect(parseProgressMode([])).toBe('bar');
+    });
+    it('returns list when specified', () => {
+        expect(parseProgressMode(['--progress', 'list'])).toBe('list');
+    });
+    it('returns quiet when specified', () => {
+        expect(parseProgressMode(['--progress', 'quiet'])).toBe('quiet');
+    });
+    it('returns bar for unknown values', () => {
+        expect(parseProgressMode(['--progress', 'unknown'])).toBe('bar');
+    });
+    it('defaults to bar when --progress has no following value', () => {
+        expect(parseProgressMode(['--progress'])).toBe('bar');
+    });
+});
+describe('parseCliOptions', () => {
+    const emptyCfg = {};
+    it('parses --changed flag', () => {
+        const opts = parseCliOptions(['--changed'], emptyCfg);
+        expect(opts.wantsChanged).toBe(true);
+        expect(opts.wantsChangedWithDeps).toBe(false);
+    });
+    it('parses --changed-with-deps flag', () => {
+        const opts = parseCliOptions(['--changed-with-deps'], emptyCfg);
+        expect(opts.wantsChangedWithDeps).toBe(true);
+    });
+    it('parses --only-covered-lines flag', () => {
+        const opts = parseCliOptions(['--only-covered-lines'], emptyCfg);
+        expect(opts.wantsOnlyCoveredLines).toBe(true);
+    });
+    it('reads onlyCoveredLines from config', () => {
+        const opts = parseCliOptions([], { onlyCoveredLines: true });
+        expect(opts.wantsOnlyCoveredLines).toBe(true);
+    });
+    it('parses --per-test-coverage flag', () => {
+        const opts = parseCliOptions(['--per-test-coverage'], emptyCfg);
+        expect(opts.wantsPerTestCoverage).toBe(true);
+    });
+    it('reads perTestCoverage from config', () => {
+        const opts = parseCliOptions([], { perTestCoverage: true });
+        expect(opts.wantsPerTestCoverage).toBe(true);
+    });
+    it('parses --coverage-file flag', () => {
+        const opts = parseCliOptions(['--coverage-file', 'coverage.json'], emptyCfg);
+        expect(opts.coverageFilePath).toBe('coverage.json');
+    });
+    it('reads coverageFile from config', () => {
+        const opts = parseCliOptions([], { coverageFile: 'cov.json' });
+        expect(opts.coverageFilePath).toBe('cov.json');
+    });
+    it('CLI coverage-file takes precedence over config', () => {
+        const opts = parseCliOptions(['--coverage-file', 'cli.json'], {
+            coverageFile: 'config.json',
+        });
+        expect(opts.coverageFilePath).toBe('cli.json');
+    });
+    it('parses --runner vitest', () => {
+        const opts = parseCliOptions(['--runner', 'vitest'], emptyCfg);
+        expect(opts.runner).toBe('vitest');
+    });
+    it('parses --runner jest', () => {
+        const opts = parseCliOptions(['--runner', 'jest'], emptyCfg);
+        expect(opts.runner).toBe('jest');
+    });
+    it('falls back to config runner', () => {
+        const opts = parseCliOptions([], { runner: 'jest' });
+        expect(opts.runner).toBe('jest');
+    });
+    it('defaults to vitest', () => {
+        const opts = parseCliOptions([], emptyCfg);
+        expect(opts.runner).toBe('vitest');
+    });
+    it('parses --config flag', () => {
+        const opts = parseCliOptions(['--config', 'my.config.ts'], emptyCfg);
+        expect(opts.configPath).toBe('my.config.ts');
+    });
+    it('parses -c alias', () => {
+        const opts = parseCliOptions(['-c', 'my.config.ts'], emptyCfg);
+        expect(opts.configPath).toBe('my.config.ts');
+    });
+    it('parses --min-kill-percent from CLI', () => {
+        const opts = parseCliOptions(['--min-kill-percent', '80'], emptyCfg);
+        expect(opts.minKillPercent).toBe(80);
+    });
+    it('reads minKillPercent from config', () => {
+        const opts = parseCliOptions([], { minKillPercent: 75 });
+        expect(opts.minKillPercent).toBe(75);
+    });
+    it('CLI min-kill-percent takes precedence over config', () => {
+        const opts = parseCliOptions(['--min-kill-percent', '90'], {
+            minKillPercent: 75,
+        });
+        expect(opts.minKillPercent).toBe(90);
+    });
+    it('rejects invalid --min-kill-percent', () => {
+        expect(() => parseCliOptions(['--min-kill-percent', '150'], emptyCfg)).toThrow('expected value between 0 and 100');
+    });
+});
+describe('extractConfigPath', () => {
+    it('extracts --config with separate value', () => {
+        expect(extractConfigPath(['--config', 'my.config.ts'])).toBe('my.config.ts');
+    });
+    it('extracts --config with = syntax', () => {
+        expect(extractConfigPath(['--config=my.config.ts'])).toBe('my.config.ts');
+    });
+    it('extracts -c alias with separate value', () => {
+        expect(extractConfigPath(['-c', 'my.config.ts'])).toBe('my.config.ts');
+    });
+    it('extracts -c alias with = syntax', () => {
+        expect(extractConfigPath(['-c=my.config.ts'])).toBe('my.config.ts');
+    });
+    it('returns undefined when no config flag is present', () => {
+        expect(extractConfigPath(['--changed', '--runner', 'vitest'])).toBeUndefined();
+    });
+    it('returns undefined for empty args', () => {
+        expect(extractConfigPath([])).toBeUndefined();
+    });
+});

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

@@ -0,0 +1,180 @@
+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';
+let tmpDir;
+beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'mutineer-cache-'));
+});
+afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+});
+describe('clearCacheOnStart', () => {
+    it('removes the cache file if it exists', async () => {
+        const cacheFile = path.join(tmpDir, '.mutate-cache.json');
+        await fs.writeFile(cacheFile, '{}');
+        await clearCacheOnStart(tmpDir);
+        await expect(fs.access(cacheFile)).rejects.toThrow();
+    });
+    it('does not throw if cache file does not exist', async () => {
+        await expect(clearCacheOnStart(tmpDir)).resolves.toBeUndefined();
+    });
+});
+describe('saveCacheAtomic', () => {
+    it('writes cache data to the file', async () => {
+        const cache = {
+            key1: {
+                status: 'killed',
+                file: 'foo.ts',
+                line: 1,
+                col: 0,
+                mutator: 'flipEQ',
+            },
+        };
+        await saveCacheAtomic(tmpDir, cache);
+        const content = await fs.readFile(path.join(tmpDir, '.mutate-cache.json'), 'utf8');
+        expect(JSON.parse(content)).toEqual(cache);
+    });
+    it('overwrites existing cache', async () => {
+        await saveCacheAtomic(tmpDir, { old: {} });
+        const newCache = {
+            new: {
+                status: 'escaped',
+                file: 'bar.ts',
+                line: 2,
+                col: 3,
+                mutator: 'andToOr',
+            },
+        };
+        await saveCacheAtomic(tmpDir, newCache);
+        const content = await fs.readFile(path.join(tmpDir, '.mutate-cache.json'), 'utf8');
+        expect(JSON.parse(content)).toEqual(newCache);
+    });
+});
+describe('decodeCacheKey', () => {
+    it('decodes a full cache key', () => {
+        const key = 'testsig:codesig:src/foo.ts:10,5:flipEQ';
+        const decoded = decodeCacheKey(key);
+        expect(decoded.file).toBe('src/foo.ts');
+        expect(decoded.line).toBe(10);
+        expect(decoded.col).toBe(5);
+        expect(decoded.mutator).toBe('flipEQ');
+    });
+    it('handles key with no colons', () => {
+        const decoded = decodeCacheKey('nodelimiters');
+        expect(decoded.mutator).toBe('unknown');
+    });
+    it('handles key with only one colon', () => {
+        const decoded = decodeCacheKey('only:one');
+        expect(decoded.mutator).toBe('one');
+    });
+    it('handles malformed position', () => {
+        const key = 'a:b:file:badpos:mutator';
+        const decoded = decodeCacheKey(key);
+        expect(decoded.mutator).toBe('mutator');
+    });
+    it('handles key with exactly two colons (no firstColon in rest)', () => {
+        // Key: "pos:mutator" after splitting last colon → rest = "pos", no colon in rest
+        // Full key: "10,5:mutator" → lastColon splits mutator, positionColon splits pos
+        // rest becomes empty string before positionColon
+        const decoded = decodeCacheKey('10,5:mutator');
+        expect(decoded.mutator).toBe('mutator');
+        expect(decoded.line).toBe(0); // positionColon = -1, returns early
+    });
+    it('handles key with exactly three colons (firstColon but no secondColon)', () => {
+        // "sig:10,5:mutator" → mutator='mutator', posRaw='10,5', rest='sig'
+        // firstColon in 'sig' = -1, returns early at line 70
+        const decoded = decodeCacheKey('sig:10,5:mutator');
+        expect(decoded.mutator).toBe('mutator');
+        expect(decoded.line).toBe(10);
+        expect(decoded.col).toBe(5);
+    });
+    it('handles key with four colons (firstColon but no secondColon in restAfterFirst)', () => {
+        // "tsig:csig:10,5:mutator" → mutator='mutator', posRaw='10,5', rest='tsig:csig'
+        // firstColon=4, restAfterFirst='csig', secondColon in 'csig' = -1, returns at line 73
+        const decoded = decodeCacheKey('tsig:csig:10,5:mutator');
+        expect(decoded.mutator).toBe('mutator');
+        expect(decoded.line).toBe(10);
+        expect(decoded.col).toBe(5);
+    });
+});
+describe('keyForTests', () => {
+    it('produces deterministic keys regardless of input order', () => {
+        const key1 = keyForTests(['b.test.ts', 'a.test.ts']);
+        const key2 = keyForTests(['a.test.ts', 'b.test.ts']);
+        expect(key1).toBe(key2);
+    });
+    it('produces different keys for different test sets', () => {
+        const key1 = keyForTests(['a.test.ts']);
+        const key2 = keyForTests(['b.test.ts']);
+        expect(key1).not.toBe(key2);
+    });
+});
+describe('hash', () => {
+    it('returns a 12 character hex string', () => {
+        const h = hash('test');
+        expect(h).toMatch(/^[0-9a-f]{12}$/);
+    });
+    it('returns the same hash for the same input', () => {
+        expect(hash('hello')).toBe(hash('hello'));
+    });
+    it('returns different hashes for different inputs', () => {
+        expect(hash('a')).not.toBe(hash('b'));
+    });
+});
+describe('readMutantCache', () => {
+    it('returns empty object when no cache file exists', async () => {
+        const result = await readMutantCache(tmpDir);
+        expect(result).toEqual({});
+    });
+    it('reads and normalizes object-format cache entries', async () => {
+        const cache = {
+            'testsig:codesig:file.ts:1,0:flip': {
+                status: 'killed',
+                file: 'file.ts',
+                line: 1,
+                col: 0,
+                mutator: 'flip',
+            },
+        };
+        await fs.writeFile(path.join(tmpDir, '.mutate-cache.json'), JSON.stringify(cache));
+        const result = await readMutantCache(tmpDir);
+        expect(result['testsig:codesig:file.ts:1,0:flip']).toEqual({
+            status: 'killed',
+            file: 'file.ts',
+            line: 1,
+            col: 0,
+            mutator: 'flip',
+        });
+    });
+    it('reads and normalizes old string-format cache entries', async () => {
+        const cache = {
+            'testsig:codesig:file.ts:1,0:flip': 'killed',
+        };
+        await fs.writeFile(path.join(tmpDir, '.mutate-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');
+        const result = await readMutantCache(tmpDir);
+        expect(result).toEqual({});
+    });
+    it('normalizes partial object entries with decoded fallbacks', async () => {
+        const cache = {
+            'testsig:codesig:file.ts:5,3:mut': {
+                status: 'escaped',
+            },
+        };
+        await fs.writeFile(path.join(tmpDir, '.mutate-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');
+        expect(entry.line).toBe(5);
+        expect(entry.col).toBe(3);
+        expect(entry.mutator).toBe('mut');
+    });
+});