@mutineerjs/mutineer 0.6.0 → 0.8.0

package/dist/core/schemata.js

@@ -0,0 +1,236 @@
+import MagicString from 'magic-string';
+import { parse } from '@babel/parser';
+import * as t from '@babel/types';
+import { parserOptsTs } from '../mutators/utils.js';
+const isWordChar = (s, i) => i >= 0 && i < s.length && /[a-zA-Z0-9_]/.test(s[i]);
+function findSingleDiff(original, mutated) {
+    let start = 0;
+    const minLen = Math.min(original.length, mutated.length);
+    while (start < minLen && original[start] === mutated[start]) {
+        start++;
+    }
+    let origEnd = original.length;
+    let mutEnd = mutated.length;
+    while (origEnd > start &&
+        mutEnd > start &&
+        original[origEnd - 1] === mutated[mutEnd - 1]) {
+        origEnd--;
+        mutEnd--;
+    }
+    // Extend to word boundaries so we never produce partial-token ternary branches.
+    // e.g. 'true'→'false' has minimal diff 'tru'→'fals' (shared 'e' suffix), but
+    // 'tru' alone is not a valid expression — extend forward to include the 'e'.
+    while (start > 0 &&
+        isWordChar(original, start - 1) &&
+        isWordChar(original, start)) {
+        start--;
+    }
+    while (isWordChar(original, origEnd - 1) && isWordChar(original, origEnd)) {
+        origEnd++;
+        mutEnd++;
+    }
+    return { origStart: start, origEnd, mutEnd };
+}
+function escapeId(id) {
+    return id.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+/**
+ * Returns true if the string is usable as a standalone JS expression fragment.
+ * Operator-only strings (e.g. '+', '!', '===') are not valid standalone expressions
+ * and cannot appear as ternary branches in generated schema code.
+ */
+function isExpressionFragment(s) {
+    return /[a-zA-Z0-9_]/.test(s);
+}
+/**
+ * Parse source code for AST-based span detection.
+ * Returns null if parsing fails (e.g. syntax errors in the file).
+ */
+function parseForSchema(code) {
+    try {
+        return parse(code, { ...parserOptsTs, tokens: false });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find the smallest AST Expression node whose span contains `offset`.
+ * Used to expand operator-only char diffs (e.g. '+') to the full enclosing
+ * expression (e.g. 'x + y') so the ternary branch is a valid JS expression.
+ */
+function findSmallestEnclosingExpression(root, offset) {
+    let best = null;
+    function walk(node) {
+        if (!node ||
+            typeof node.start !== 'number' ||
+            typeof node.end !== 'number') {
+            return;
+        }
+        if (offset < node.start || offset >= node.end)
+            return;
+        if (t.isExpression(node)) {
+            const span = node.end - node.start;
+            if (!best || span < best.end - best.start) {
+                best = { start: node.start, end: node.end };
+            }
+        }
+        for (const key of Object.keys(node)) {
+            if (key === 'type' ||
+                key === 'start' ||
+                key === 'end' ||
+                key === 'loc' ||
+                key === 'range' ||
+                key === 'errors' ||
+                key === 'operator') {
+                continue;
+            }
+            const child = node[key];
+            if (!child || typeof child !== 'object')
+                continue;
+            if (Array.isArray(child)) {
+                for (const item of child) {
+                    if (item &&
+                        typeof item === 'object' &&
+                        typeof item.start === 'number') {
+                        walk(item);
+                    }
+                }
+            }
+            else if (typeof child.start === 'number') {
+                walk(child);
+            }
+        }
+    }
+    walk(root);
+    return best;
+}
+/**
+ * Generate a schema file that embeds all mutation variants as a ternary chain.
+ *
+ * The schema uses `globalThis.__mutineer_active_id__` at call time to select
+ * which mutant is active, avoiding per-mutant module reloads.
+ *
+ * For value mutations (true→false, null→undefined), a character-level diff with
+ * word-boundary extension finds the span. For operator mutations (+→-, ===→!==),
+ * the Babel AST is used to find the enclosing expression (x + y, x === y) so
+ * the ternary branch is a valid JS expression.
+ *
+ * @param originalCode - The original source file contents
+ * @param variants - All variants to embed (must all be from the same source file)
+ * @returns schemaCode (the embedded schema) and fallbackIds (variants that
+ *   couldn't be embedded due to overlapping diff ranges or parse errors)
+ */
+export function generateSchema(originalCode, variants) {
+    const fallbackIds = new Set();
+    const siteMap = new Map();
+    // Lazily parsed AST — only needed for operator mutations
+    let ast = undefined;
+    function getAst() {
+        if (ast === undefined)
+            ast = parseForSchema(originalCode);
+        return ast;
+    }
+    for (const variant of variants) {
+        const { origStart, origEnd, mutEnd } = findSingleDiff(originalCode, variant.code);
+        // Skip variants with empty diffs (identical to original)
+        if (origStart >= origEnd && origStart >= mutEnd) {
+            fallbackIds.add(variant.id);
+            continue;
+        }
+        const origSpan = originalCode.slice(origStart, origEnd);
+        const repSpan = variant.code.slice(origStart, mutEnd);
+        let siteStart;
+        let siteEnd;
+        let replacement;
+        if (isExpressionFragment(origSpan) && isExpressionFragment(repSpan)) {
+            // Value mutation (true→false, null→undefined, 0→1 etc.): char diff is usable
+            siteStart = origStart;
+            siteEnd = origEnd;
+            replacement = repSpan;
+        }
+        else {
+            // Operator mutation (+→-, ===→!==, &&→|| etc.): char diff produces an
+            // operator-only span that isn't a valid standalone expression.
+            // Use the Babel AST to find the smallest enclosing Expression node
+            // (e.g. the BinaryExpression x + y) so the ternary branches are valid JS.
+            const parsedAst = getAst();
+            if (!parsedAst) {
+                fallbackIds.add(variant.id);
+                continue;
+            }
+            const enclosing = findSmallestEnclosingExpression(parsedAst, origStart);
+            if (!enclosing) {
+                fallbackIds.add(variant.id);
+                continue;
+            }
+            siteStart = enclosing.start;
+            siteEnd = enclosing.end;
+            // The enclosing node end is from the original AST. For variable-length
+            // operators (e.g. '>' → '>=', '+=' → '-='), the variant code is longer or
+            // shorter by delta = mutEnd - origEnd. Adjust the slice end accordingly.
+            const delta = mutEnd - origEnd;
+            replacement = variant.code.slice(siteStart, siteEnd + delta);
+            // Sanity: if replacement equals original span, the mutation had no effect
+            if (replacement === originalCode.slice(siteStart, siteEnd)) {
+                fallbackIds.add(variant.id);
+                continue;
+            }
+        }
+        const key = `${siteStart}:${siteEnd}`;
+        if (!siteMap.has(key)) {
+            siteMap.set(key, { origStart: siteStart, origEnd: siteEnd, variants: [] });
+        }
+        siteMap.get(key).variants.push({ id: variant.id, replacement });
+    }
+    const sites = Array.from(siteMap.values()).sort((a, b) => a.origStart - b.origStart);
+    // Detect overlapping sites.
+    // When one site is fully contained within another (nested expressions), keep
+    // the inner (smaller) site and mark the outer one as fallback. For partial
+    // overlaps, mark both as fallback.
+    const overlappingSiteKeys = new Set();
+    for (let i = 0; i < sites.length; i++) {
+        for (let j = i + 1; j < sites.length; j++) {
+            const a = sites[i];
+            const b = sites[j];
+            if (b.origStart >= a.origEnd)
+                break; // sorted by start, no further overlap
+            const keyA = `${a.origStart}:${a.origEnd}`;
+            const keyB = `${b.origStart}:${b.origEnd}`;
+            if (b.origEnd <= a.origEnd) {
+                // b fully contained within a → keep b (inner), mark a (outer) as fallback
+                overlappingSiteKeys.add(keyA);
+            }
+            else if (a.origStart === b.origStart) {
+                // Same start, b is larger → b contains a → mark b (outer) as fallback
+                overlappingSiteKeys.add(keyB);
+            }
+            else {
+                // Partial overlap → mark both as fallback
+                overlappingSiteKeys.add(keyA);
+                overlappingSiteKeys.add(keyB);
+            }
+        }
+    }
+    const s = new MagicString(originalCode);
+    // Apply sites in descending order to preserve character positions
+    const sortedDesc = [...sites].sort((a, b) => b.origStart - a.origStart);
+    for (const site of sortedDesc) {
+        const key = `${site.origStart}:${site.origEnd}`;
+        if (overlappingSiteKeys.has(key)) {
+            for (const v of site.variants)
+                fallbackIds.add(v.id);
+            continue;
+        }
+        const originalSpan = originalCode.slice(site.origStart, site.origEnd);
+        // Build ternary chain: iterate from last variant inward, wrapping originalSpan
+        let chain = originalSpan;
+        for (let i = site.variants.length - 1; i >= 0; i--) {
+            const v = site.variants[i];
+            chain = `(globalThis.__mutineer_active_id__ === '${escapeId(v.id)}' ? (${v.replacement}) : ${chain})`;
+        }
+        s.overwrite(site.origStart, site.origEnd, chain);
+    }
+    const schemaCode = `// @ts-nocheck\n` + s.toString();
+    return { schemaCode, fallbackIds };
+}

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,56 @@ 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');
+    });
+    it('parses --typescript flag', () => {
+        const opts = parseCliOptions(['--typescript'], emptyCfg);
+        expect(opts.typescriptCheck).toBe(true);
+    });
+    it('parses --no-typescript flag', () => {
+        const opts = parseCliOptions(['--no-typescript'], emptyCfg);
+        expect(opts.typescriptCheck).toBe(false);
+    });
+    it('defaults typescriptCheck to undefined', () => {
+        const opts = parseCliOptions([], emptyCfg);
+        expect(opts.typescriptCheck).toBeUndefined();
+    });
+    it('--typescript takes precedence over --no-typescript (first one wins)', () => {
+        const opts = parseCliOptions(['--typescript', '--no-typescript'], emptyCfg);
+        expect(opts.typescriptCheck).toBe(true);
+    });
+    it('parses --vitest-project flag', () => {
+        const opts = parseCliOptions(['--vitest-project', 'my-pkg'], emptyCfg);
+        expect(opts.vitestProject).toBe('my-pkg');
+    });
+    it('defaults vitestProject to undefined', () => {
+        const opts = parseCliOptions([], emptyCfg);
+        expect(opts.vitestProject).toBeUndefined();
+    });
+    it('parses --skip-baseline flag', () => {
+        const opts = parseCliOptions(['--skip-baseline'], emptyCfg);
+        expect(opts.skipBaseline).toBe(true);
+    });
+    it('defaults skipBaseline to false', () => {
+        const opts = parseCliOptions([], emptyCfg);
+        expect(opts.skipBaseline).toBe(false);
+    });
 });
 describe('validatePositiveMs', () => {
     it('returns undefined for undefined', () => {
@@ -247,6 +297,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');