@mutineerjs/mutineer 0.5.1 → 0.7.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  --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

@@ -1,12 +1,43 @@
 #!/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)
+  --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
+`;
+export function getVersion() {
+    const require = createRequire(import.meta.url);
+    return require('../../package.json').version;
+}
 const CONFIG_TEMPLATE = `\
 import { defineMutineerConfig } from 'mutineer'
 
@@ -19,7 +50,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) {
@@ -35,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, 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);
@@ -202,6 +202,106 @@ describe('parseCliOptions', () => {
     it('rejects invalid --min-kill-percent', () => {
         expect(() => parseCliOptions(['--min-kill-percent', '150'], emptyCfg)).toThrow('expected value between 0 and 100');
     });
+    it('parses --timeout flag', () => {
+        const opts = parseCliOptions(['--timeout', '5000'], emptyCfg);
+        expect(opts.timeout).toBe(5000);
+    });
+    it('parses --timeout with = syntax', () => {
+        const opts = parseCliOptions(['--timeout=5000'], emptyCfg);
+        expect(opts.timeout).toBe(5000);
+    });
+    it('returns undefined timeout when flag absent', () => {
+        const opts = parseCliOptions([], emptyCfg);
+        expect(opts.timeout).toBeUndefined();
+    });
+    it('config timeout does not affect opts.timeout (resolved in orchestrator)', () => {
+        const opts = parseCliOptions([], { timeout: 10000 });
+        expect(opts.timeout).toBeUndefined();
+    });
+    it('rejects --timeout 0', () => {
+        expect(() => parseCliOptions(['--timeout', '0'], emptyCfg)).toThrow('expected a positive number');
+    });
+    it('rejects --timeout -1', () => {
+        expect(() => parseCliOptions(['--timeout', '-1'], emptyCfg)).toThrow('expected a positive number');
+    });
+    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', () => {
+        expect(validatePositiveMs(undefined, 'test')).toBeUndefined();
+    });
+    it('returns the value for a positive number', () => {
+        expect(validatePositiveMs(5000, '--timeout')).toBe(5000);
+        expect(validatePositiveMs(1, '--timeout')).toBe(1);
+    });
+    it('throws for zero', () => {
+        expect(() => validatePositiveMs(0, '--timeout')).toThrow('Invalid --timeout: expected a positive number (received 0)');
+    });
+    it('throws for negative values', () => {
+        expect(() => validatePositiveMs(-1, '--timeout')).toThrow('Invalid --timeout: expected a positive number (received -1)');
+    });
+    it('throws for non-finite values', () => {
+        expect(() => validatePositiveMs(Infinity, '--timeout')).toThrow('Invalid --timeout: expected a positive number');
+        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', () => {