@mutineerjs/mutineer 0.5.0 → 0.6.0

package/README.md

@@ -19,10 +19,10 @@ Built for **Vitest** with first-class **Jest** support. Other test runners can b
 
 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 a fast file-swap mechanism
+3. **Test** -- re-runs only the tests that import the mutated file, using temp files in `__mutineer__` dirs loaded via Vite plugin / Jest resolver
 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 injected at runtime via Vite plugins (Vitest) or custom resolvers (Jest) -- no files on disk are modified.
+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).
 
 ## Supported Mutations (WIP)
 
@@ -164,6 +164,46 @@ export default defineMutineerConfig({
 | `testPatterns`      | `string[]`           | Globs for test file discovery                    |
 | `extensions`        | `string[]`           | File extensions to consider                      |
 
+## Recommended Workflow
+
+Large repos can generate thousands of mutations. These strategies keep runs fast and incremental.
+
+### 1. PR-scoped runs (CI) — `--changed-with-deps`
+
+Run only on files changed in the branch plus their direct dependents:
+
+```bash
+mutineer run --changed-with-deps
+```
+
+- Tune the dependency graph depth with `dependencyDepth` in config (default: `1`)
+- Add `--per-test-coverage` to only run tests that cover the mutated line
+- Recommended `package.json` script:
+
+```json
+"mutineer:ci": "mutineer run --changed-with-deps --per-test-coverage"
+```
+
+### 2. Split configs by domain
+
+Create a `mutineer.config.ts` per domain and run selectively:
+
+```bash
+mutineer run -c src/api/mutineer.config.ts
+```
+
+Each config sets its own `source` glob and `minKillPercent`. Good for monorepos or large modular projects — domains can also be parallelized in CI.
+
+### 3. Combine filters to reduce scope
+
+- `--only-covered-lines` — skips lines not covered by any test (requires a coverage file)
+- `maxMutantsPerFile` — caps mutations per file as a safety valve
+- Combine for maximum focus:
+
+```bash
+mutineer run --changed-with-deps --only-covered-lines --per-test-coverage
+```
+
 ## File Support
 
 - TypeScript and JavaScript modules (`.ts`, `.js`, `.tsx`, `.jsx`)

package/dist/bin/__tests__/mutineer.spec.d.ts

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

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

@@ -0,0 +1,43 @@
+import { createRequire } from 'node:module';
+import { describe, it, expect } from 'vitest';
+import { HELP_TEXT, getVersion } from '../mutineer.js';
+describe('HELP_TEXT', () => {
+    const flags = [
+        '--config',
+        '-c',
+        '--concurrency',
+        '--runner',
+        '--progress',
+        '--changed',
+        '--changed-with-deps',
+        '--only-covered-lines',
+        '--per-test-coverage',
+        '--coverage-file',
+        '--min-kill-percent',
+        '--help',
+        '-h',
+        '--version',
+        '-V',
+    ];
+    it.each(flags)('includes %s', (flag) => {
+        expect(HELP_TEXT).toContain(flag);
+    });
+    it('includes all three commands', () => {
+        expect(HELP_TEXT).toContain('init');
+        expect(HELP_TEXT).toContain('run');
+        expect(HELP_TEXT).toContain('clean');
+    });
+    it('--changed-with-deps description mentions local dependencies', () => {
+        expect(HELP_TEXT).toContain('local dependencies');
+    });
+});
+describe('getVersion()', () => {
+    it('returns a semver string', () => {
+        expect(getVersion()).toMatch(/^\d+\.\d+\.\d+/);
+    });
+    it('matches package.json version', () => {
+        const require = createRequire(import.meta.url);
+        const pkg = require('../../../package.json');
+        expect(getVersion()).toBe(pkg.version);
+    });
+});

package/dist/bin/mutineer.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export {};
+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 function getVersion(): string;

package/dist/bin/mutineer.js

@@ -1,12 +1,41 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { runOrchestrator } from '../runner/orchestrator.js';
 import { cleanupMutineerDirs } from '../runner/cleanup.js';
 // Constants
 const RUN_COMMAND = 'run';
 const CLEAN_COMMAND = 'clean';
 const INIT_COMMAND = 'init';
+export const HELP_TEXT = `\
+Usage: mutineer <command> [options]
+
+Commands:
+  init       Create a mutineer.config.ts template
+  run        Run mutation testing
+  clean      Remove __mutineer__ temp directories
+
+Options (run):
+  --config, -c <path>       Config file path
+  --concurrency <n>         Worker count (default: CPU count - 1)
+  --runner <vitest|jest>    Test runner (default: vitest)
+  --progress <bar|list|quiet>  Progress display (default: bar)
+  --changed                 Mutate only git-changed files
+  --changed-with-deps       Mutate changed files + their local dependencies
+  --only-covered-lines      Mutate only lines covered by tests
+  --per-test-coverage       Collect per-test coverage data
+  --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)
+
+  --help, -h                Show this help
+  --version, -V             Show version
+`;
+export function getVersion() {
+    const require = createRequire(import.meta.url);
+    return require('../../package.json').version;
+}
 const CONFIG_TEMPLATE = `\
 import { defineMutineerConfig } from 'mutineer'
 
@@ -19,7 +48,19 @@ export default defineMutineerConfig({
  */
 async function main() {
     const args = process.argv.slice(2);
+    if (args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(HELP_TEXT);
+        process.exit(0);
+    }
+    if (args[0] === '--version' || args[0] === '-V') {
+        console.log(getVersion());
+        process.exit(0);
+    }
     if (args[0] === RUN_COMMAND) {
+        if (args.includes('--help') || args.includes('-h')) {
+            process.stdout.write(HELP_TEXT);
+            process.exit(0);
+        }
         await runOrchestrator(args.slice(1), process.cwd());
     }
     else if (args[0] === INIT_COMMAND) {

package/dist/core/__tests__/variant-utils.spec.js

@@ -1,5 +1,5 @@
-import { describe, it, expect } from 'vitest';
-import { generateMutationVariants, getFilteredRegistry } from '../variant-utils.js';
+import { describe, it, expect, vi } from 'vitest';
+import { generateMutationVariants, getFilteredRegistry, } from '../variant-utils.js';
 function makeMutator(name, mutations) {
     return {
         name,
@@ -72,6 +72,28 @@ describe('generateMutationVariants', () => {
         const result = generateMutationVariants([mutator], 'code', {});
         expect(result).toHaveLength(2);
     });
+    it('calls applyWithContext instead of apply when available', () => {
+        const applyWithContext = vi
+            .fn()
+            .mockReturnValue([{ code: 'ctx_result', line: 1, col: 0 }]);
+        const mutator = {
+            name: 'm',
+            description: 'm',
+            apply: () => [{ code: 'apply_result', line: 1, col: 0 }],
+            applyWithContext,
+        };
+        const result = generateMutationVariants([mutator], 'const x = 1');
+        expect(applyWithContext).toHaveBeenCalledOnce();
+        expect(result[0].code).toBe('ctx_result');
+    });
+    it('falls back to apply when applyWithContext is absent', () => {
+        const apply = vi
+            .fn()
+            .mockReturnValue([{ code: 'apply_result', line: 1, col: 0 }]);
+        const mutator = { name: 'm', description: 'm', apply };
+        generateMutationVariants([mutator], 'const x = 1');
+        expect(apply).toHaveBeenCalledOnce();
+    });
 });
 describe('getFilteredRegistry', () => {
     it('returns the full registry when no filters', () => {

package/dist/core/sfc.js

@@ -1,5 +1,6 @@
 import MagicString from 'magic-string';
 import { getFilteredRegistry } from './variant-utils.js';
+import { buildParseContext } from '../mutators/utils.js';
 /**
  * Generate all possible mutations for a Vue SFC `<script setup>` block.
  * @param filename - The path to the Vue file (used by the parser for error reporting)
@@ -26,12 +27,16 @@ export async function mutateVueSfcScriptSetup(filename, code, include, exclude,
     const registry = getFilteredRegistry(include, exclude);
     const variants = [];
     const seenOutputs = new Set();
+    const ctx = buildParseContext(originalBlock);
     for (const mutator of registry) {
         // Early termination if limit reached
         if (max !== undefined && variants.length >= max) {
             break;
         }
-        for (const mutation of mutator.apply(originalBlock)) {
+        const blockMutations = mutator.applyWithContext
+            ? mutator.applyWithContext(originalBlock, ctx)
+            : mutator.apply(originalBlock);
+        for (const mutation of blockMutations) {
             const ms = new MagicString(code);
             ms.overwrite(startOffset, endOffset, mutation.code);
             const mutatedOutput = ms.toString();

package/dist/core/variant-utils.js

@@ -1,4 +1,5 @@
 import { getRegistry } from '../mutators/registry.js';
+import { buildParseContext } from '../mutators/utils.js';
 /**
  * Generate mutations from a registry of mutators, deduplicating the output.
  * Supports early termination when max limit is reached.
@@ -17,12 +18,16 @@ export function generateMutationVariants(registry, code, opts = {}) {
     }
     const variants = [];
     const seen = new Set();
+    const ctx = buildParseContext(code);
     for (const mutator of registry) {
         // Early termination if limit reached
         if (max !== undefined && variants.length >= max) {
             break;
         }
-        for (const mutation of mutator.apply(code)) {
+        const mutations = mutator.applyWithContext
+            ? mutator.applyWithContext(code, ctx)
+            : mutator.apply(code);
+        for (const mutation of mutations) {
             // Skip unchanged code and duplicates in a single check
             if (!seen.has(mutation.code)) {
                 seen.add(mutation.code);

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

@@ -1,5 +1,6 @@
 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 { buildParseContext } from '../utils.js';
 // ---------------------------------------------------------------------------
 // Shared behaviour (tested once; all mutators use the same factory)
 // ---------------------------------------------------------------------------
@@ -37,6 +38,21 @@ describe('operator mutator shared behaviour', () => {
     });
 });
 // ---------------------------------------------------------------------------
+// applyWithContext (shared behaviour)
+// ---------------------------------------------------------------------------
+describe('operator mutator applyWithContext', () => {
+    it('produces same results as apply', () => {
+        const src = `const ok = a && b && c`;
+        const ctx = buildParseContext(src);
+        expect(andToOr.applyWithContext(src, ctx)).toEqual(andToOr.apply(src));
+    });
+    it('respects disable comments via pre-built context', () => {
+        const src = `// mutineer-disable-next-line\nconst ok = a && b`;
+        const ctx = buildParseContext(src);
+        expect(andToOr.applyWithContext(src, ctx)).toHaveLength(0);
+    });
+});
+// ---------------------------------------------------------------------------
 // Boundary mutators
 // ---------------------------------------------------------------------------
 describe('relaxLE', () => {

package/dist/mutators/__tests__/return-value.spec.js

@@ -1,5 +1,6 @@
 import { describe, it, expect } from 'vitest';
 import { returnToNull, returnToUndefined, returnFlipBool, returnZero, returnEmptyStr, returnEmptyArr, } from '../return-value.js';
+import { buildParseContext } from '../utils.js';
 // ---------------------------------------------------------------------------
 // returnToNull
 // ---------------------------------------------------------------------------
@@ -237,3 +238,39 @@ describe('returnEmptyArr', () => {
         expect(results).toHaveLength(0);
     });
 });
+// ---------------------------------------------------------------------------
+// applyWithContext (shared behaviour)
+// ---------------------------------------------------------------------------
+describe('return-value mutator applyWithContext', () => {
+    it('produces same results as apply', () => {
+        const src = `function f() { return x }`;
+        const ctx = buildParseContext(src);
+        expect(returnToNull.applyWithContext(src, ctx)).toEqual(returnToNull.apply(src));
+    });
+    it('respects disable comments via pre-built context', () => {
+        const src = `function f() {\n  // mutineer-disable-next-line\n  return x\n}`;
+        const ctx = buildParseContext(src);
+        expect(returnToNull.applyWithContext(src, ctx)).toHaveLength(0);
+    });
+    it('all return mutators produce same results via applyWithContext as apply', () => {
+        const src = `
+function f(x) {
+  if (x) return true
+  if (x > 0) return 42
+  if (x < 0) return 'hello'
+  return [1, 2]
+}
+`;
+        const ctx = buildParseContext(src);
+        for (const mutator of [
+            returnToNull,
+            returnToUndefined,
+            returnFlipBool,
+            returnZero,
+            returnEmptyStr,
+            returnEmptyArr,
+        ]) {
+            expect(mutator.applyWithContext(src, ctx)).toEqual(mutator.apply(src));
+        }
+    });
+});

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { collectOperatorTargets, buildIgnoreLines, parseSource, } from '../utils.js';
+import { collectOperatorTargets, collectOperatorTargetsFromContext, collectAllTargets, buildIgnoreLines, buildParseContext, parseSource, } from '../utils.js';
 // ---------------------------------------------------------------------------
 // buildIgnoreLines
 // ---------------------------------------------------------------------------
@@ -65,7 +65,86 @@ describe('parseSource', () => {
     });
 });
 // ---------------------------------------------------------------------------
-// collectOperatorTargets
+// buildParseContext
+// ---------------------------------------------------------------------------
+describe('buildParseContext', () => {
+    it('returns an object with ast, tokens, ignoreLines, and preCollected', () => {
+        const ctx = buildParseContext(`const x = a && b`);
+        expect(ctx.ast.type).toBe('File');
+        expect(Array.isArray(ctx.tokens)).toBe(true);
+        expect(ctx.ignoreLines).toBeInstanceOf(Set);
+        expect(ctx.preCollected).toBeDefined();
+        expect(ctx.preCollected.operatorTargets).toBeInstanceOf(Map);
+        expect(Array.isArray(ctx.preCollected.returnStatements)).toBe(true);
+    });
+    it('populates ignoreLines from disable comments', () => {
+        const src = `// mutineer-disable-next-line\nconst x = a && b`;
+        const ctx = buildParseContext(src);
+        expect(ctx.ignoreLines.has(2)).toBe(true);
+    });
+    it('preCollected.operatorTargets groups targets by operator', () => {
+        const src = `const x = a && b || c && d`;
+        const ctx = buildParseContext(src);
+        expect(ctx.preCollected.operatorTargets.get('&&')).toHaveLength(2);
+        expect(ctx.preCollected.operatorTargets.get('||')).toHaveLength(1);
+    });
+    it('preCollected.returnStatements captures return arguments', () => {
+        const src = `function f() { return x }\nfunction g() { return y }`;
+        const ctx = buildParseContext(src);
+        expect(ctx.preCollected.returnStatements).toHaveLength(2);
+    });
+});
+// ---------------------------------------------------------------------------
+// collectAllTargets
+// ---------------------------------------------------------------------------
+describe('collectAllTargets', () => {
+    it('collects operator targets grouped by operator', () => {
+        const src = `const x = a && b || c`;
+        const ctx = buildParseContext(src);
+        const result = collectAllTargets(src, ctx.ast, ctx.tokens, ctx.ignoreLines);
+        expect(result.operatorTargets.get('&&')).toHaveLength(1);
+        expect(result.operatorTargets.get('||')).toHaveLength(1);
+    });
+    it('collects return statement info', () => {
+        const src = `function f() { return 42 }`;
+        const ctx = buildParseContext(src);
+        const result = collectAllTargets(src, ctx.ast, ctx.tokens, ctx.ignoreLines);
+        expect(result.returnStatements).toHaveLength(1);
+        const info = result.returnStatements[0];
+        expect(info.line).toBe(1);
+        expect(typeof info.col).toBe('number');
+        expect(typeof info.argStart).toBe('number');
+        expect(typeof info.argEnd).toBe('number');
+        expect(info.argNode).toBeDefined();
+    });
+    it('skips operators on ignored lines', () => {
+        const src = `// mutineer-disable-next-line\nconst x = a && b`;
+        const ctx = buildParseContext(src);
+        const result = collectAllTargets(src, ctx.ast, ctx.tokens, ctx.ignoreLines);
+        expect(result.operatorTargets.get('&&') ?? []).toHaveLength(0);
+    });
+    it('skips return statements on ignored lines', () => {
+        const src = `function f() {\n  // mutineer-disable-next-line\n  return x\n}`;
+        const ctx = buildParseContext(src);
+        const result = collectAllTargets(src, ctx.ast, ctx.tokens, ctx.ignoreLines);
+        expect(result.returnStatements).toHaveLength(0);
+    });
+    it('skips bare return with no argument', () => {
+        const src = `function f() { return }`;
+        const ctx = buildParseContext(src);
+        const result = collectAllTargets(src, ctx.ast, ctx.tokens, ctx.ignoreLines);
+        expect(result.returnStatements).toHaveLength(0);
+    });
+    it('matches collectOperatorTargetsFromContext for &&', () => {
+        const src = `const x = a && b && c`;
+        const ctx = buildParseContext(src);
+        const result = collectAllTargets(src, ctx.ast, ctx.tokens, ctx.ignoreLines);
+        const fromCtx = collectOperatorTargetsFromContext(src, ctx, '&&');
+        expect(result.operatorTargets.get('&&')).toEqual(fromCtx);
+    });
+});
+// ---------------------------------------------------------------------------
+// collectOperatorTargets / collectOperatorTargetsFromContext
 // ---------------------------------------------------------------------------
 describe('collectOperatorTargets', () => {
     it('honors mutineer disable comments', () => {
@@ -80,3 +159,18 @@ const d = e && f
         expect(lines).toEqual([5]);
     });
 });
+describe('collectOperatorTargetsFromContext', () => {
+    it('returns same results as collectOperatorTargets', () => {
+        const src = `const ok = a && b && c`;
+        const ctx = buildParseContext(src);
+        const fromCtx = collectOperatorTargetsFromContext(src, ctx, '&&');
+        const fromSrc = collectOperatorTargets(src, '&&');
+        expect(fromCtx).toEqual(fromSrc);
+    });
+    it('honors disable comments via pre-built context', () => {
+        const src = `// mutineer-disable-next-line\nconst x = a && b`;
+        const ctx = buildParseContext(src);
+        const targets = collectOperatorTargetsFromContext(src, ctx, '&&');
+        expect(targets).toHaveLength(0);
+    });
+});

package/dist/mutators/operator.js

@@ -15,15 +15,21 @@ import { collectOperatorTargets } from './utils.js';
  * @param toOp - The operator to replace it with (e.g., '||')
  */
 function makeOperatorMutator(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) {
-            return collectOperatorTargets(src, fromOp).map((target) => ({
-                line: target.line,
-                col: target.col1,
-                code: src.slice(0, target.start) + toOp + src.slice(target.end),
-            }));
+            return targetsToOutputs(src, collectOperatorTargets(src, fromOp));
+        },
+        applyWithContext(src, ctx) {
+            return targetsToOutputs(src, ctx.preCollected.operatorTargets.get(fromOp) ?? []);
         },
     };
 }

package/dist/mutators/return-value.js

@@ -20,6 +20,32 @@ import { traverse, getVisualColumn, parseSource, buildIgnoreLines, } from './uti
  * @param description - Human-readable description shown in reports
  * @param replacer - Returns the replacement source text, or null to skip
  */
+function collectReturnMutations(src, ast, ignoreLines, replacer) {
+    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;
+}
 function makeReturnMutator(name, description, replacer) {
     return {
         name,
@@ -28,29 +54,17 @@ function makeReturnMutator(name, description, replacer) {
             const ast = parseSource(src);
             const fileAst = ast;
             const ignoreLines = buildIgnoreLines(fileAst.comments ?? []);
+            return collectReturnMutations(src, ast, ignoreLines, replacer);
+        },
+        applyWithContext(src, ctx) {
             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 });
-                },
-            });
+            for (const info of ctx.preCollected.returnStatements) {
+                const replacement = replacer(info.argNode);
+                if (replacement === null)
+                    continue;
+                const code = src.slice(0, info.argStart) + replacement + src.slice(info.argEnd);
+                outputs.push({ line: info.line, col: info.col, code });
+            }
             return outputs;
         },
     };

package/dist/mutators/types.d.ts

@@ -4,6 +4,7 @@
  * Defines the interface that all mutators must implement and the output format
  * for mutations. This allows for different mutator implementations to be plugged in.
  */
+export type { ParseContext } from './utils.js';
 /**
  * Output of a single mutation, including location info and mutated code.
  */
@@ -20,6 +21,7 @@ export interface ASTMutator {
     readonly name: string;
     readonly description: string;
     apply(src: string): readonly MutationOutput[];
+    applyWithContext?(src: string, ctx: import('./utils.js').ParseContext): readonly MutationOutput[];
 }
 /**
  * Union type for different mutator kinds.

package/dist/mutators/utils.d.ts

@@ -46,6 +46,73 @@ export declare function parseSource(src: string): import("@babel/parser").ParseR
  * Type guard to check if a node is a BinaryExpression or LogicalExpression.
  */
 export declare function isBinaryOrLogical(node: t.Node): node is t.BinaryExpression | t.LogicalExpression;
+/**
+ * Internal token-like interface for AST token analysis.
+ */
+export interface TokenLike {
+    readonly value?: string;
+    readonly start: number;
+    readonly end: number;
+    readonly loc: {
+        readonly start: {
+            readonly line: number;
+            readonly column: number;
+        };
+        readonly end: {
+            readonly line: number;
+            readonly column: number;
+        };
+    };
+}
+/**
+ * Location info for a single return statement argument, pre-collected
+ * during a single AST traversal so return-value mutators need no traversal.
+ */
+export interface ReturnStatementInfo {
+    readonly line: number;
+    readonly col: number;
+    readonly argStart: number;
+    readonly argEnd: number;
+    readonly argNode: t.Expression;
+}
+/**
+ * All mutation targets pre-collected in a single traversal.
+ */
+export interface PreCollected {
+    readonly operatorTargets: Map<string, OperatorTarget[]>;
+    readonly returnStatements: ReturnStatementInfo[];
+}
+/**
+ * Pre-parsed context for a source file.
+ * Allows sharing a single Babel parse across all mutators.
+ */
+export interface ParseContext {
+    readonly ast: t.File & {
+        tokens?: TokenLike[];
+        comments?: t.Comment[];
+    };
+    readonly tokens: readonly TokenLike[];
+    readonly ignoreLines: Set<number>;
+    readonly preCollected: PreCollected;
+}
+/**
+ * Single traversal that collects all operator targets and return statements.
+ * Eliminates per-mutator traversals when using ParseContext.
+ */
+export declare function collectAllTargets(src: string, ast: t.File & {
+    tokens?: TokenLike[];
+    comments?: t.Comment[];
+}, tokens: readonly TokenLike[], ignoreLines: Set<number>): PreCollected;
+/**
+ * Parse a source file once and build a reusable ParseContext.
+ * Pass this to mutators' applyWithContext to avoid redundant parses.
+ */
+export declare function buildParseContext(src: string): ParseContext;
+/**
+ * Collect operator targets from a pre-built ParseContext.
+ * Avoids re-parsing; use when processing multiple operators on the same source.
+ */
+export declare function collectOperatorTargetsFromContext(src: string, ctx: ParseContext, opValue: string): OperatorTarget[];
 /**
  * Collect the operator tokens for a given operator and return their exact locations.
  * Uses AST traversal to find BinaryExpression/LogicalExpression nodes, then maps them