Files
claude-config/bin/mutate_changes/main.py
T

131 lines
5.8 KiB
Python

"""Mutation-test the lines a branch adds or changes, and print each mutant its tests don't kill.
usage: mutate-changes [--base <ref>] [--prefix <shell text>] [--jobs <n>]
Run it in a checkout, under ~/.claude/bin/run-heavy. It diffs the working tree's tracked files against the merge base of HEAD and
--base, by default the default branch: origin's as last fetched, else main or master. It picks the tool by each changed file's
extension, and leaves out test files: test_*.py, *_test.py, conftest.py, *.test.* and *.spec.*, and any file under a tests/, test/
or __tests__/ folder.
- .py: mutmut 3, in a scratch copy of the nearest folder above the file that holds a setup.cfg or a pyproject.toml, else of the
checkout's top. It mutates each function or method a changed line falls in, and counts the mutants on changed lines. The
folder's setup.cfg settings stay, but source_paths and also_copy are set, and pytest leaves out each test that fails without a
mutant; the report names their files. A pyproject.toml with a [tool.mutmut] section fails the run.
- .rs: cargo-mutants, with --in-diff.
- .cjs, .cts, .js, .jsx, .mjs, .mts, .ts, .tsx: Stryker, with --mutate on the changed lines.
- .php: Infection, with --git-diff-lines.
--prefix is shell text put before each tool's command, such as 'uvx --from "mutmut>=3,<4"' or 'docker compose run --rm app'.
Without it, each tool must be on PATH. mutmut runs in its scratch copy, a folder in the checkout's top, and every other tool in
the checkout's top; in the prefix, $PWD names that folder. --jobs sets how many tests each tool runs at once, 4 by default: one
heavy slot's CPUs.
For mutmut and cargo-mutants, it prints a line with the mutant count, then a line per mutant on a changed line that is not
killed: `<path>:<line>: <status>: <the line as mutated>`. Stryker and Infection print their own report, after their exit code.
The last line gives the wall time.
Exit 1, saying why, on unknown arguments, or when git fails, a tool cannot start, or mutmut or cargo-mutants fails before it reports.
"""
import sys
import time
from mutate_changes.changed_lines import added_lines, tool_for
from machine_load.slots import CPUS_PER_SLOT
from git_cli.git_repo import default_ref, git, top
from failure import Failure
from mutate_changes.in_diff_tools import run_cargo_mutants, run_infection, run_stryker
from mutate_changes.mutmut_tool import run_mutmut
USAGE = "usage: mutate-changes [--base <ref>] [--prefix <shell text>] [--jobs <n>]"
# A panel of three readers, seated as the README's audience, picked the command's name and these options on 2026-11-11.
OPTIONS = ("--base", "--jobs", "--prefix")
def main(argv: list[str]) -> int:
if argv in (["-h"], ["--help"]):
print(__doc__.strip())
return 0
given = options(argv)
if isinstance(given, Failure):
print(f"{given.reason}; {USAGE}", file=sys.stderr)
return 1
started = time.monotonic()
report = mutate(given)
if isinstance(report, Failure):
print(report.reason, file=sys.stderr)
return 1
if not report:
print("No line the branch changes is in a language mutate-changes mutates.")
return 0
print("\n".join(report))
print(f"mutate-changes took {took(time.monotonic() - started)}.")
return 0
def options(argv: list[str]) -> dict[str, str] | Failure:
given: dict[str, str] = {}
rest = list(argv)
while rest:
name, equals, value = rest.pop(0).partition("=")
if name not in OPTIONS or name in given:
return Failure(f"unknown or repeated argument {name}")
if not equals and not rest:
return Failure(f"{name} needs a value")
given[name] = value if equals else rest.pop(0)
if not given.get("--jobs", "1").isdigit() or int(given.get("--jobs", "1")) < 1:
return Failure(f"--jobs takes a whole number from 1, not {given['--jobs']}")
return given
def mutate(given: dict[str, str]) -> list[str] | Failure:
"""Each tool's report on the branch's changed lines; empty where none of them is in a language a tool covers."""
checkout = top()
if isinstance(checkout, Failure):
return checkout
base = given.get("--base") or default_ref(cwd=checkout)
if isinstance(base, Failure):
return base
merge_base = git("merge-base", base, "HEAD", cwd=checkout)
if isinstance(merge_base, Failure):
return merge_base
changed = changed_by_tool(checkout, merge_base.strip())
if isinstance(changed, Failure):
return changed
prefix, jobs = given.get("--prefix"), int(given.get("--jobs", CPUS_PER_SLOT))
report: list[str] = []
for tool, files in sorted(changed.items()):
if tool == "cargo-mutants":
lines = run_cargo_mutants(checkout, merge_base.strip(), sorted(files), prefix, jobs)
elif tool == "infection":
lines = run_infection(checkout, merge_base.strip(), prefix, jobs)
elif tool == "stryker":
lines = run_stryker(checkout, files, prefix, jobs)
else:
lines = run_mutmut(checkout, files, prefix, jobs)
if isinstance(lines, Failure):
return lines
report.extend(lines)
return report
def changed_by_tool(checkout: str, merge_base: str) -> dict[str, dict[str, frozenset[int]]] | Failure:
"""Each tool's files that the working tree changes since merge_base, by path from the checkout's top, with their changed lines."""
names = git("diff", "--name-only", "-z", "--diff-filter=d", "--no-renames", merge_base, cwd=checkout)
if isinstance(names, Failure):
return names
changed: dict[str, dict[str, frozenset[int]]] = {}
for path in filter(None, names.split("\0")):
if (tool := tool_for(path)) is None:
continue
diff = git("diff", "-U0", "--no-color", "--no-ext-diff", "--no-textconv", "--no-renames", merge_base, "--", path, cwd=checkout, errors="replace")
if isinstance(diff, Failure):
return diff
if lines := added_lines(diff):
changed.setdefault(tool, {})[path] = lines
return changed
def took(seconds: float) -> str:
whole = round(seconds)
return f"{whole // 60} min {whole % 60} s" if whole >= 60 else f"{whole} s"