qa-agent-kit 0.6.0__py3-none-any.whl

qakit/tools/mutate.py

@@ -0,0 +1,684 @@
+#!/usr/bin/env python3
+"""Mutation testing for any repo: break the code on purpose, one small change at a time, and see whether the tests notice.
+
+A mutant the tests catch is *killed*. One they miss *survived*: no test pins that behaviour. Every survivor gets a test, or a
+`mutation-ok: <reason>` comment on its line when the change cannot alter behaviour (an equivalent mutant).
+
+  python3 mutate.py --config apps/pawday/release/testing/mutation.json
+  python3 mutate.py --config <json> --changed-since 'latest-tag:pawday/*'   # release gate: lines changed since the last release
+  python3 mutate.py --root agent --source 'core/**/*.py' --test '{orig}/.venv/bin/python -m pytest -x -q'
+  python3 mutate.py --config <json> --list                            # print the mutants, run nothing
+
+Config (JSON, paths relative to the git top level that holds the config): root, sources, exclude, setup, build, test,
+env, copy_exclude, jobs, timeout_factor, operators, sweep_sample (seeded sample size for a full sweep only), coverage
+(writes lcov to {lcov}; mutants on lines it never ran are reported uncovered without a run), test_timeout (seconds,
+when the per-mutant test command differs from the baseline one, e.g. it picks tests by {stem}). `build` failing means the mutant does not compile (invalid, not counted);
+`test` failing or timing out means killed. Commands run with a shell inside a throwaway copy of root, never in the checkout;
+{orig} is the real root, {file} and {stem} the mutated file. Languages: Python (tokenize and ast) and C-family syntax
+(Swift, JS/TS, Kotlin, Go, Java, C#), where a binary operator must have spaces on both sides; that keeps generics
+(`Array<Int>`), arrows and prefix/postfix operators out. Exit 0 no survivors, 1 survivors, 2 setup or baseline failure.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import concurrent.futures as futures
+import datetime as dt
+import fnmatch
+import io
+import json
+import os
+import queue
+import random
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import tokenize
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+C_FAMILY = {".swift", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".kt", ".go", ".java", ".cs"}
+OPERATORS = ("boundary", "equality", "logical", "arithmetic", "boolean", "negation", "drop-call")
+COPY_EXCLUDE = {".git", ".build", "DerivedData", ".dd", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache",
+                ".venv", "venv", "xcuserdata", ".swiftpm"}
+SKIP_MARK = "mutation-ok"
+# Calls whose removal says nothing about behaviour a test should pin: logging, debug output, assertions that crash.
+QUIET_CALLS = re.compile(r"(^|\.)(print|debugPrint|dump|NSLog|os_log|log|logger|Logger|console|assert\w*|precondition\w*|"
+                         r"fatalError|super|warn|warning|info|debug|error|exception|critical)\b")
+SWAP = {"<": "<=", "<=": "<", ">": ">=", ">=": ">", "==": "!=", "!=": "==", "===": "!==", "!==": "===",
+        "&&": "||", "||": "&&", "+": "-", "-": "+", "+=": "-=", "-=": "+=", "*": "/", "/": "*",
+        "true": "false", "false": "true", "and": "or", "or": "and", "True": "False", "False": "True"}
+FAMILY = {"<": "boundary", "<=": "boundary", ">": "boundary", ">=": "boundary", "==": "equality", "!=": "equality",
+          "===": "equality", "!==": "equality", "&&": "logical", "||": "logical", "and": "logical", "or": "logical",
+          "+": "arithmetic", "-": "arithmetic", "+=": "arithmetic", "-=": "arithmetic", "*": "arithmetic",
+          "/": "arithmetic", "true": "boolean", "false": "boolean", "True": "boolean", "False": "boolean"}
+C_BINARY = re.compile(r"(?<=\s)(===|!==|==|!=|<=|>=|&&|\|\||\+=|-=|<|>|\+|-|\*|/)(?=\s)")
+C_BOOL = re.compile(r"\b(true|false)\b")
+C_NOT = re.compile(r"(?:(?<=[\s(\[,{=&|:?])|^)!(?=[A-Za-z_($.])", re.MULTILINE)
+C_DIRECTIVE = re.compile(r"^\s*(#(if|else|elseif|endif|warning|error|sourceLocation)\b|import\b|@testable\b)")
+C_CONTINUATION = ("=", "(", ",", ".", "?", ":", "&&", "||", "+", "-", "*", "/", "return", "->", "{")   # the previous line is unfinished
+C_CALL_LINE = re.compile(r"^(\s*)((?:try[!?]?\s+|await\s+)*([A-Za-z_$][\w$]*(?:\??\.[A-Za-z_$][\w$]*)*)\s*\(.*\)(?:\s*;)?)\s*$")
+C_KEYWORDS = {"return", "if", "guard", "while", "for", "switch", "case", "let", "var", "throw", "defer", "func", "init",
+              "else", "repeat", "catch", "yield", "await", "try", "new", "typeof", "delete", "const"}
+PY_VALUE_END = {tokenize.NAME, tokenize.NUMBER, tokenize.STRING}
+PY_KEYWORDS = {"and", "or", "not", "in", "is", "if", "else", "elif", "return", "yield", "lambda", "await", "assert", "del",
+               "import", "from", "as", "with", "for", "while", "def", "class", "raise", "pass", "global", "nonlocal"}
+
+
+@dataclass(frozen=True)
+class Mutant:
+    file: str     # relative to root
+    line: int     # 1-based
+    start: int    # character offsets into the file text
+    end: int
+    before: str
+    after: str
+    op: str
+
+    def apply(self, text: str) -> str:
+        return text[:self.start] + self.after + text[self.end:]
+
+    def label(self) -> str:
+        return f"{self.file}:{self.line} {self.op} `{self.before.strip()}` -> `{self.after.strip() or '(removed)'}`"
+
+
+def line_starts(text: str) -> list[int]:
+    starts = [0]
+    for index, char in enumerate(text):
+        if char == "\n":
+            starts.append(index + 1)
+    return starts
+
+
+def line_of(starts: list[int], offset: int) -> int:
+    low, high = 0, len(starts) - 1
+    while low < high:
+        mid = (low + high + 1) // 2
+        if starts[mid] <= offset:
+            low = mid
+        else:
+            high = mid - 1
+    return low + 1
+
+
+def mask_c_family(text: str) -> str:
+    """Same length as text; comments and string/char literals become spaces (newlines kept), so offsets map 1:1."""
+    out = list(text)
+    i, n = 0, len(text)
+
+    def blank(a: int, b: int) -> None:
+        for k in range(a, min(b, n)):
+            if out[k] != "\n":
+                out[k] = " "
+
+    while i < n:
+        if text.startswith("//", i):
+            j = text.find("\n", i)
+            j = n if j < 0 else j
+            blank(i, j)
+            i = j
+        elif text.startswith("/*", i):
+            depth, j = 1, i + 2
+            while j < n and depth:
+                if text.startswith("/*", j):
+                    depth, j = depth + 1, j + 2
+                elif text.startswith("*/", j):
+                    depth, j = depth - 1, j + 2
+                else:
+                    j += 1
+            blank(i, j)
+            i = j
+        elif text[i] == "#" and re.match(r"#+\"", text[i:]):   # Swift raw string #"..."#
+            hashes = len(re.match(r"#+", text[i:]).group(0))
+            multi = text.startswith('"""', i + hashes)
+            close = ('"""' if multi else '"') + "#" * hashes
+            j = text.find(close, i + hashes + (3 if multi else 1))
+            j = n if j < 0 else j + len(close)
+            blank(i, j)
+            i = j
+        elif text.startswith('"""', i):
+            j = i + 3
+            while j < n and not text.startswith('"""', j):
+                j += 2 if text[j] == "\\" else 1
+            j = min(n, j + 3)
+            blank(i, j)
+            i = j
+        elif text[i] in "\"'`":
+            quote, j = text[i], i + 1
+            while j < n and text[j] != quote and not (quote != "`" and text[j] == "\n"):
+                j += 2 if text[j] == "\\" else 1
+            j = min(n, j + 1)
+            blank(i, j)
+            i = j
+        else:
+            i += 1
+    return "".join(out)
+
+
+def c_family_mutants(rel: str, text: str) -> list[Mutant]:
+    masked = mask_c_family(text)
+    starts = line_starts(text)
+    lines = text.split("\n")
+    masked_lines = masked.split("\n")
+    skip = {number for number, line in enumerate(lines, 1) if SKIP_MARK in line or C_DIRECTIVE.match(masked_lines[number - 1])}
+    found: list[Mutant] = []
+
+    def add(start: int, end: int, after: str, op: str) -> None:
+        number = line_of(starts, start)
+        if number not in skip:
+            found.append(Mutant(rel, number, start, end, text[start:end], after, op))
+
+    for match in C_BINARY.finditer(masked):
+        token = match.group(1)
+        add(match.start(1), match.end(1), SWAP[token], FAMILY[token])
+    for match in C_BOOL.finditer(masked):
+        add(match.start(), match.end(), SWAP[match.group(0)], "boolean")
+    for match in C_NOT.finditer(masked):
+        add(match.start(), match.end(), "", "negation")
+    for number, line in enumerate(masked_lines, 1):
+        call = C_CALL_LINE.match(line)
+        if not call or number in skip:
+            continue
+        # A call that continues the previous line (`let x =` / an open `(` / a trailing `,` or `.`) is an expression, not a
+        # statement: dropping it leaves a dangling `=` (every invalid Swift mutant in docs/case-studies.md was this).
+        previous = next((masked_lines[k].rstrip() for k in range(number - 2, -1, -1) if masked_lines[k].strip()), "")
+        if previous.endswith(C_CONTINUATION):
+            continue
+        callee = call.group(3)
+        head = callee.split(".")[0].rstrip("?")
+        if head in C_KEYWORDS or QUIET_CALLS.search(callee) or line.count("(") != line.count(")"):
+            continue
+        if "." not in callee and callee[0].isupper():   # `Text("a")`, `Spacer()`: a result-builder element, not a side effect
+            continue
+        offset = starts[number - 1] + len(call.group(1))
+        add(offset, offset + len(call.group(2)), "", "drop-call")
+    return found
+
+
+def typing_only_lines(tree: ast.AST) -> set[int]:
+    """Lines whose mutants can never change behaviour at runtime: `TYPE_CHECKING = False`, the body of `if TYPE_CHECKING:`,
+    `@overload` stubs, and the test of `if sys.version_info ...` (the interpreter running the tests takes one branch only).
+    The case studies (docs/case-studies.md) found 11% of the Python survivors here, every one equivalent."""
+    skip: set[int] = set()
+
+    def dotted(node: ast.AST) -> str:
+        return ast.unparse(node) if isinstance(node, (ast.Name, ast.Attribute)) else ""
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.If):
+            test = node.test
+            if dotted(test).endswith("TYPE_CHECKING"):
+                skip.update(range(node.lineno, node.end_lineno + 1))
+            elif isinstance(test, ast.Compare) and "version_info" in dotted(test.left):
+                skip.update(range(test.lineno, test.end_lineno + 1))
+        elif isinstance(node, ast.Assign) and any(dotted(t) == "TYPE_CHECKING" for t in node.targets):
+            skip.update(range(node.lineno, node.end_lineno + 1))
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and any(dotted(d).endswith("overload") for d in node.decorator_list):
+            skip.update(range(node.lineno, node.end_lineno + 1))
+    return skip
+
+
+def python_mutants(rel: str, text: str) -> list[Mutant]:
+    starts = line_starts(text)
+    lines = text.split("\n")
+    skip = {number for number, line in enumerate(lines, 1) if SKIP_MARK in line or "__name__" in line}
+    try:
+        skip |= typing_only_lines(ast.parse(text))
+    except SyntaxError:
+        pass
+    found: list[Mutant] = []
+
+    def offset(position: tuple[int, int]) -> int:
+        return starts[position[0] - 1] + position[1]
+
+    def add(start: int, end: int, after: str, op: str) -> None:
+        number = line_of(starts, start)
+        if number not in skip:
+            found.append(Mutant(rel, number, start, end, text[start:end], after, op))
+
+    try:
+        tokens = list(tokenize.generate_tokens(io.StringIO(text).readline))
+    except (tokenize.TokenError, SyntaxError):
+        return []
+    significant = [t for t in tokens if t.type not in (tokenize.NL, tokenize.NEWLINE, tokenize.COMMENT, tokenize.INDENT,
+                                                        tokenize.DEDENT, tokenize.ENCODING)]
+    for index, token in enumerate(significant):
+        previous = significant[index - 1] if index else None
+        value_before = previous is not None and (
+            (previous.type in PY_VALUE_END and previous.string not in PY_KEYWORDS) or previous.string in (")", "]", "}"))
+        start, end = offset(token.start), offset(token.end)
+        if token.type == tokenize.OP and token.string in ("<", "<=", ">", ">=", "==", "!="):
+            add(start, end, SWAP[token.string], FAMILY[token.string])
+        elif token.type == tokenize.OP and token.string in ("+", "-", "*", "/") and value_before:
+            add(start, end, SWAP[token.string], "arithmetic")
+        elif token.type == tokenize.OP and token.string in ("+=", "-="):
+            add(start, end, SWAP[token.string], "arithmetic")
+        elif token.type == tokenize.NAME and token.string in ("and", "or", "True", "False"):
+            add(start, end, SWAP[token.string], FAMILY[token.string])
+        elif token.type == tokenize.NAME and token.string == "not":
+            following = significant[index + 1] if index + 1 < len(significant) else None
+            if following is not None:
+                add(start, offset(following.start), "", "negation")
+    try:
+        tree = ast.parse(text)
+    except SyntaxError:
+        return found
+    for node in ast.walk(tree):
+        call = node.value.value if isinstance(node, ast.Expr) and isinstance(node.value, ast.Await) else getattr(node, "value", None)
+        if not isinstance(node, ast.Expr) or not isinstance(call, ast.Call) or node.lineno != node.end_lineno:
+            continue
+        if QUIET_CALLS.search(ast.unparse(call.func)):
+            continue
+        start = starts[node.lineno - 1] + utf8_col(lines[node.lineno - 1], node.col_offset)
+        end = starts[node.lineno - 1] + utf8_col(lines[node.lineno - 1], node.end_col_offset)
+        add(start, end, "pass", "drop-call")
+    return found
+
+
+def utf8_col(line: str, byte_col: int) -> int:
+    """ast columns count UTF-8 bytes; text offsets count characters."""
+    return len(line.encode("utf-8")[:byte_col].decode("utf-8", errors="ignore"))
+
+
+def mutants_for(rel: str, text: str) -> list[Mutant]:
+    suffix = Path(rel).suffix
+    if suffix == ".py":
+        return python_mutants(rel, text)
+    if suffix in C_FAMILY:
+        return c_family_mutants(rel, text)
+    return []
+
+
+def changed_lines(repo: Path, ref: str, paths: list[Path]) -> dict[Path, set[int] | None]:
+    """Lines added or changed since ref (working tree included). None means the whole file (untracked, so all new)."""
+    untracked = set(run_git(repo, ["ls-files", "--others", "--exclude-standard", "--full-name"]).split("\n"))
+    result: dict[Path, set[int] | None] = {}
+    for path in paths:
+        rel = path.resolve().relative_to(repo).as_posix()
+        if rel in untracked:
+            result[path] = None
+            continue
+        lines: set[int] = set()
+        for match in re.finditer(r"^@@ -\S+ \+(\d+)(?:,(\d+))? @@", run_git(repo, ["diff", "-U0", ref, "--", rel]), re.MULTILINE):
+            first, count = int(match.group(1)), int(match.group(2) or "1")
+            lines.update(range(first, first + count))
+        result[path] = lines
+    return result
+
+
+def run_git(repo: Path, args: list[str]) -> str:
+    done = subprocess.run(["git", "-C", str(repo), *args], capture_output=True, text=True, check=False)
+    if done.returncode:
+        raise SystemExit(f"git {' '.join(args)}: {done.stderr.strip()}")
+    return done.stdout
+
+
+def resolve_ref(repo: Path, ref: str) -> str | None:
+    """`latest-tag:<glob>` is the newest tag matching glob (the last release); anything else is a git ref as given."""
+    if not ref.startswith("latest-tag:"):
+        return ref
+    tags = run_git(repo, ["tag", "-l", ref.split(":", 1)[1], "--sort=-creatordate"]).split()
+    return tags[0] if tags else None   # never released: every line is new
+
+
+def git_top(path: Path) -> Path | None:
+    done = subprocess.run(["git", "-C", str(path), "rev-parse", "--show-toplevel"], capture_output=True, text=True, check=False)
+    return Path(done.stdout.strip()).resolve() if done.returncode == 0 else None
+
+
+def matches(rel: str, patterns: list[str]) -> bool:
+    return any(fnmatch.fnmatchcase(rel, pattern) or fnmatch.fnmatchcase(rel, pattern.replace("**/", "")) for pattern in patterns)
+
+
+def source_files(root: Path, sources: list[str], exclude: list[str]) -> list[Path]:
+    files: set[Path] = set()
+    for pattern in sources:
+        files.update(p for p in root.glob(pattern) if p.is_file())
+    return sorted(p for p in files if not matches(p.relative_to(root).as_posix(), exclude)
+                  and not any(part in COPY_EXCLUDE for part in p.relative_to(root).parts))
+
+
+def load_config(args: argparse.Namespace) -> dict:
+    config: dict = {}
+    base = Path.cwd()
+    if args.config:
+        path = Path(args.config).resolve()
+        config = json.loads(path.read_text())
+        base = git_top(path.parent) or path.parent
+    for key in ("root", "build", "test"):
+        if getattr(args, key):
+            config[key] = getattr(args, key)
+    if args.source:
+        config["sources"] = args.source
+    if not config.get("root") or not config.get("sources") or not config.get("test"):
+        raise SystemExit("need root, sources and test (from --config or flags)")
+    config["root"] = str((base / config["root"]).resolve())
+    config["name"] = config.get("name") or Path(config["root"]).name
+    return config
+
+
+def shell(command: str, cwd: Path, env: dict[str, str], timeout: float) -> tuple[str, float, str]:
+    """('ok'|'fail'|'timeout', seconds, output tail). The whole process group dies on timeout."""
+    began = time.monotonic()
+    # nice: a sweep is background work and must not starve the machine's interactive sessions and services
+    process = subprocess.Popen(["nice", "-n", "10", "/bin/sh", "-c", command], cwd=cwd, env=env, stdout=subprocess.PIPE,
+                               stderr=subprocess.STDOUT, text=True, errors="replace", start_new_session=True)
+    try:
+        output, _ = process.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        kill_tree(process.pid, cwd)
+        output, _ = process.communicate()
+        return "timeout", time.monotonic() - began, digest(output or "")
+    return ("ok" if process.returncode == 0 else "fail"), time.monotonic() - began, digest(output or "")
+
+
+def kill_tree(pid: int, copy: Path) -> None:
+    """Every process the command started, not just its process group: `swift test` runs xctest in a group of its own, and
+    an infinite-loop mutant then spun at 90% CPU for 4 h 40 min after its timeout (2026-10-28). Descendants first, then
+    anything still running from inside this copy (it may already have been reparented to launchd)."""
+    table = subprocess.run(["ps", "-A", "-o", "pid=,ppid="], capture_output=True, text=True).stdout.split()
+    children: dict[int, list[int]] = {}
+    for child, parent in zip(table[::2], table[1::2]):
+        children.setdefault(int(parent), []).append(int(child))
+    victims, stack = [], [pid]
+    while stack:
+        current = stack.pop()
+        victims.append(current)
+        stack.extend(children.get(current, []))
+    for victim in [pid] + victims:
+        try:
+            os.killpg(victim, 9) if victim == pid else os.kill(victim, 9)
+        except (ProcessLookupError, PermissionError):
+            pass
+    subprocess.run(["pkill", "-9", "-f", f"{Path(copy).resolve()}/"], capture_output=True)
+    subprocess.run(["pkill", "-9", "-f", f"{Path(copy)}/"], capture_output=True)
+
+
+FAILURE_LINE = re.compile(r"error:|' failed|failed \(|FAIL|Traceback|AssertionError|✘|not ok ")
+
+
+def digest(output: str) -> str:
+    """The lines that name what failed (anywhere in the output), then the tail. A plain tail cut the failing test's name."""
+    named = [line for line in output.splitlines() if FAILURE_LINE.search(line)][:20]
+    return ("\n".join(named) + "\n...\n" if named else "") + output[-1500:]
+
+
+def touch(path: Path) -> None:
+    """Move mtime forward so mtime-based build caches always see the edit, even two edits within one tick."""
+    stamp = max(time.time_ns(), path.stat().st_mtime_ns + 1_000_000_000)
+    os.utime(path, ns=(stamp, stamp))
+
+
+def uncovered_lines(lcov: str, copy: Path) -> dict[str, set[int]]:
+    """Lines an lcov report saw as executable and never ran, keyed by path relative to the copy. Relative SF paths are
+    relative to the copy (node writes them so); a file can appear in several records (one per test process), and a line
+    any record ran counts as run."""
+    base = copy.resolve()
+    zero: dict[str, set[int]] = {}
+    ran: dict[str, set[int]] = {}
+    rel: str | None = None
+    for line in lcov.splitlines():
+        if line.startswith("SF:"):
+            source = Path(line[3:])
+            try:
+                rel = (source if source.is_absolute() else base / source).resolve().relative_to(base).as_posix()
+            except ValueError:
+                rel = None
+        elif line.startswith("DA:") and rel is not None:
+            number, count = line[3:].split(",")[:2]
+            (zero if int(float(count)) == 0 else ran).setdefault(rel, set()).add(int(number))
+    return {path: lines - ran.get(path, set()) for path, lines in zero.items()}
+
+
+def fill(command: str, orig: Path, rel: str = "", lcov: str = "") -> str:
+    return (command.replace("{orig}", str(orig)).replace("{file}", rel).replace("{stem}", Path(rel).stem if rel else "")
+            .replace("{lcov}", lcov))
+
+
+def copy_tree(source: Path, target: Path, excluded: set[str]) -> None:
+    """APFS clone when the OS has one (a 1 GB repo copies in seconds and costs no disk), plain copy otherwise."""
+    if sys.platform == "darwin" and subprocess.run(["cp", "-cR", str(source), str(target)], capture_output=True).returncode == 0:
+        for folder, dirs, _files in os.walk(target):
+            for name in [d for d in dirs if d in excluded]:
+                dirs.remove(name)
+                victim = Path(folder) / name
+                victim.unlink() if victim.is_symlink() else shutil.rmtree(victim, ignore_errors=True)
+        return
+    shutil.rmtree(target, ignore_errors=True)
+    shutil.copytree(source, target, symlinks=True, ignore=lambda _d, names: [n for n in names if n in excluded])
+
+
+class Worker:
+    def __init__(self, index: int, config: dict, scratch: Path, env: dict[str, str]):
+        self.orig = Path(config["root"])
+        self.copy = scratch / f"w{index}"
+        self.config, self.env = config, env
+        copy_tree(self.orig, self.copy, COPY_EXCLUDE | set(config.get("copy_exclude", [])))
+        self.build_seconds = self.test_seconds = 0.0
+
+    def baseline(self) -> str | None:
+        if self.config.get("setup"):   # once per copy: `pod install`, `npm ci`, a dedicated simulator
+            status, _, tail = shell(fill(self.config["setup"], self.orig), self.copy, self.env, 3600)
+            if status != "ok":
+                return f"setup {status}:\n{tail}"
+        if self.config.get("build"):
+            status, self.build_seconds, tail = shell(fill(self.config["build"], self.orig), self.copy, self.env, 3600)
+            if status != "ok":
+                return f"baseline build {status}:\n{tail}"
+        status, self.test_seconds, tail = shell(fill(self.config["test"], self.orig), self.copy, self.env, 3600)
+        return None if status == "ok" else f"baseline tests {status} (they must pass before mutants mean anything):\n{tail}"
+
+    def coverage(self) -> dict[str, set[int]] | None:
+        """Optional `coverage` command writes lcov to {lcov}; mutants on never-run lines need no test run to judge."""
+        if not self.config.get("coverage"):
+            return None
+        lcov = self.copy.parent / f"{self.copy.name}.lcov"
+        status, _, tail = shell(fill(self.config["coverage"], self.orig, lcov=str(lcov)), self.copy, self.env, 3600)
+        if status != "ok" or not lcov.exists():
+            print(f"coverage {status}; every mutant runs:\n{tail[-600:]}", file=sys.stderr)
+            return None
+        return uncovered_lines(lcov.read_text(errors="replace"), self.copy)
+
+    def run(self, mutant: Mutant, build_limit: float, test_limit: float) -> tuple[str, float, str]:
+        target = self.copy / mutant.file
+        original = target.read_text()
+        began = time.monotonic()
+        try:
+            target.write_text(mutant.apply(original))
+            touch(target)
+            if self.config.get("build"):
+                status, _, tail = shell(fill(self.config["build"], self.orig, mutant.file), self.copy, self.env, build_limit)
+                if status != "ok":
+                    return ("invalid" if status == "fail" else "timeout"), time.monotonic() - began, tail
+            status, _, tail = shell(fill(self.config["test"], self.orig, mutant.file), self.copy, self.env, test_limit)
+            verdict = {"ok": "survived", "fail": "killed", "timeout": "timeout"}[status]
+            return verdict, time.monotonic() - began, tail
+        finally:
+            target.write_text(original)
+            touch(target)
+
+
+def collect(config: dict, changed_since: str | None, operators: set[str]) -> tuple[list[Mutant], str | None]:
+    """The mutants in scope, and the ref the scope was cut at (None: whole source set)."""
+    root = Path(config["root"])
+    files = source_files(root, config["sources"], config.get("exclude", []))
+    scope: dict[Path, set[int] | None] = {}
+    if changed_since:
+        repo = git_top(root)
+        if repo is None:
+            raise SystemExit("--changed-since needs a git checkout")
+        ref = resolve_ref(repo, changed_since)
+        if ref is None:
+            print(f"{changed_since}: no such tag yet, so this is a full sweep (sampled if the config says so); "
+                  "tag the last release to gate on changed lines", flush=True)
+            changed_since = None
+        else:
+            scope = changed_lines(repo, ref, files)
+            changed_since = ref
+    found: list[Mutant] = []
+    for path in files:
+        lines = scope.get(path, None) if changed_since else None
+        if changed_since and lines is not None and not lines:
+            continue
+        for mutant in mutants_for(path.relative_to(root).as_posix(), path.read_text(errors="replace")):
+            if mutant.op in operators and (lines is None or mutant.line in lines):
+                found.append(mutant)
+    return found, changed_since
+
+
+def report(config: dict, results: list[dict], out: Path, args: argparse.Namespace, seconds: float,
+           coverage: bool = False) -> dict:
+    counts = {k: sum(1 for r in results if r["verdict"] == k) for k in ("killed", "timeout", "survived", "uncovered", "invalid")}
+    caught = counts["killed"] + counts["timeout"]
+    measured = caught + counts["survived"] + counts["uncovered"]
+    summary = {"name": config["name"], "root": config["root"], "changed_since": args.changed_since, "mutants": len(results),
+               **counts, "score": round(caught / measured, 4) if measured else None, "seconds": round(seconds),
+               "finished": dt.datetime.now().isoformat(timespec="seconds")}
+    survivors = sorted((r for r in results if r["verdict"] in ("survived", "uncovered")), key=lambda r: (r["file"], r["line"]))
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "mutation.json").write_text(json.dumps({"summary": summary, "results": results}, ensure_ascii=False, indent=1))
+    lived = "tests run it, nothing checks it" if coverage else "no test failed (coverage not measured)"
+    rows = [f"| `{r['file']}:{r['line']}` | {r['op']} | `{r['before'].strip()}` → `{r['after'].strip() or '(removed)'}` | "
+            f"{'no test runs this line' if r['verdict'] == 'uncovered' else lived} |" for r in survivors]
+    score = f"{summary['score']:.0%}" if summary["score"] is not None else "n/a"
+    lines = [f"# Mutation report: {config['name']}", "",
+             f"Scope: {'lines changed since ' + args.changed_since if args.changed_since else 'all sources'}. "
+             f"Score {score} ({caught} caught of {measured}); {counts['invalid']} did not compile; {summary['seconds']} s.", "",
+             "Each survivor needs a test that fails on it, or `mutation-ok: <reason>` on its line if it cannot change behaviour.", ""]
+    if rows:
+        lines += ["| Where | Operator | Change | Why it lived |", "|---|---|---|---|", *rows]
+    (out / "mutation.md").write_text("\n".join(lines) + "\n")
+    return summary
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--config")
+    parser.add_argument("--root")
+    parser.add_argument("--source", action="append", help="glob relative to root; repeatable")
+    parser.add_argument("--build")
+    parser.add_argument("--test")
+    parser.add_argument("--changed-since", help="git ref; mutate only lines added or changed since it")
+    parser.add_argument("--file", action="append", help="limit to these files, or file:line (relative to root); repeatable")
+    parser.add_argument("--operator", action="append", choices=OPERATORS)
+    parser.add_argument("--max-mutants", type=int, help="seeded sample when there are more")
+    parser.add_argument("--seed", type=int, default=1)
+    parser.add_argument("--jobs", type=int)
+    parser.add_argument("--max-survivors", type=int, default=0, help="exit 0 up to this many survivors")
+    parser.add_argument("--out", help="report directory (default: $TMPDIR/mutation-reports/<name>-<time>)")
+    parser.add_argument("--list", action="store_true", help="print the mutants and stop")
+    parser.add_argument("--keep", action="store_true", help="keep the scratch copies")
+    parser.add_argument("--resume", action="store_true", help="reuse verdicts already in --out/results.jsonl (a long run cut short)")
+    args = parser.parse_args(argv)
+
+    config = load_config(args)
+    operators = set(args.operator or config.get("operators") or OPERATORS)
+    mutants, scoped_at = collect(config, args.changed_since, operators)
+    if args.file:   # `path` or `path:line`
+        wanted = [f.rsplit(":", 1) if re.fullmatch(r".+:\d+", f) else [f, None] for f in args.file]
+        mutants = [m for m in mutants if any(m.file == f and (line is None or m.line == int(line)) for f, line in wanted)]
+    cap = args.max_mutants or (None if scoped_at else config.get("sweep_sample"))
+    args.changed_since = scoped_at
+    if cap and len(mutants) > cap:
+        mutants = sorted(random.Random(args.seed).sample(mutants, cap), key=lambda m: (m.file, m.start))
+    if args.list:
+        for mutant in mutants:
+            print(mutant.label())
+        print(f"{len(mutants)} mutants")
+        return 0
+    stamp = dt.datetime.now().strftime("%Y%m%d-%H%M%S")
+    out = Path(args.out) if args.out else Path(tempfile.gettempdir()) / "mutation-reports" / f"{config['name']}-{stamp}"
+    if not mutants:
+        report(config, [], out, args, 0)
+        print(f"{config['name']}: no mutants in scope; report {out / 'mutation.md'}")
+        return 0
+
+    env = os.environ.copy()
+    env["PYTHONDONTWRITEBYTECODE"] = "1"   # a .pyc keyed on mtime seconds and size hides a same-size mutant written in the same second
+    if Path("/Applications/Xcode.app/Contents/Developer").is_dir():
+        env.setdefault("DEVELOPER_DIR", "/Applications/Xcode.app/Contents/Developer")   # xcode-select may point at CommandLineTools
+    env.update({k: str(v) for k, v in config.get("env", {}).items()})
+    jobs = max(1, min(args.jobs or config.get("jobs") or max(1, (os.cpu_count() or 4) // 6), len(mutants)))
+    scratch = Path(tempfile.mkdtemp(prefix=f"mutate-{config['name']}-"))
+    began = time.monotonic()
+    measured_coverage = False
+    print(f"{config['name']}: {len(mutants)} mutants, {jobs} workers, scratch {scratch}", flush=True)
+    try:
+        workers = [Worker(i, config, scratch, env) for i in range(jobs)]
+        with futures.ThreadPoolExecutor(jobs) as pool:
+            failures = [f for f in pool.map(Worker.baseline, workers) if f]
+        if failures:
+            print(failures[0], file=sys.stderr)
+            return 2
+        factor = float(config.get("timeout_factor", 3))
+        build_limit = max(120.0, max(w.build_seconds for w in workers) * factor)
+        test_limit = float(config.get("test_timeout") or max(30.0, max(w.test_seconds for w in workers) * factor))
+        print(f"baseline ok: build {workers[0].build_seconds:.0f} s, tests {workers[0].test_seconds:.0f} s", flush=True)
+        results: list[dict] = []
+        lock = threading.Lock()
+        out.mkdir(parents=True, exist_ok=True)
+        journal = out / "results.jsonl"
+        done = {}
+        if args.resume and journal.exists():
+            for raw in journal.read_text().splitlines():
+                row = json.loads(raw)
+                done[(row["file"], row["start"], row["op"], row["after"])] = row
+        elif journal.exists():
+            journal.unlink()
+        coverage_map = workers[0].coverage()
+        measured_coverage = coverage_map is not None
+        never_run = coverage_map or {}
+        pending: queue.Queue[Mutant] = queue.Queue()
+        for mutant in mutants:
+            previous = done.get((mutant.file, mutant.start, mutant.op, mutant.after))
+            if previous:
+                results.append(previous)
+            elif mutant.line in never_run.get(mutant.file, ()):
+                results.append({**asdict(mutant), "verdict": "uncovered", "seconds": 0})
+            else:
+                pending.put(mutant)
+        if done:
+            print(f"resume: {len(results)} verdicts reused from {journal}", flush=True)
+        if never_run:
+            print(f"coverage: {len(results)} mutants sit on lines no test runs (uncovered, not run)", flush=True)
+
+        def drain(worker: Worker) -> None:
+            while True:
+                try:
+                    mutant = pending.get_nowait()
+                except queue.Empty:
+                    return
+                verdict, seconds, tail = worker.run(mutant, build_limit, test_limit)
+                row = {**asdict(mutant), "verdict": verdict, "seconds": round(seconds, 1)}
+                if verdict == "survived":
+                    row["tail"] = tail[-400:]
+                with lock:
+                    results.append(row)
+                    with journal.open("a") as handle:
+                        handle.write(json.dumps(row, ensure_ascii=False) + "\n")
+                    print(f"[{len(results)}/{len(mutants)}] {verdict:8} {mutant.label()}", flush=True)
+
+        with futures.ThreadPoolExecutor(jobs) as pool:
+            list(pool.map(drain, workers))
+    finally:
+        for workdir in (scratch, scratch.resolve()):   # nothing may outlive the run from inside its copies
+            subprocess.run(["pkill", "-9", "-f", f"{workdir}/"], capture_output=True)
+        if not args.keep:
+            shutil.rmtree(scratch, ignore_errors=True)
+            for litter in scratch.parent.glob(f"*{scratch.name}*"):   # SwiftPM drops <mangled path>.build.lock files in TMPDIR
+                if litter.is_file():
+                    litter.unlink(missing_ok=True)
+    summary = report(config, results, out, args, time.monotonic() - began, coverage=measured_coverage)
+    score = f"{summary['score']:.0%}" if summary["score"] is not None else "n/a"
+    print(f"{config['name']}: score {score}, killed {summary['killed']}, timeout {summary['timeout']}, "
+          f"survived {summary['survived']}, uncovered {summary['uncovered']}, invalid {summary['invalid']}; "
+          f"report {out / 'mutation.md'}")
+    return 1 if summary["survived"] + summary["uncovered"] > args.max_survivors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())