131 lines
5.8 KiB
Python
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"
|