mutgate 0.1.0__py3-none-any.whl

mutgate/__init__.py

@@ -0,0 +1,22 @@
+"""mutgate — named mutations as contracts on a test suite.
+
+    from mutgate import Mutation
+    MUTATIONS = [
+        Mutation("keep-larger", file="pkg/engine.py",
+                 old="if birth[a] >= birth[b]:", new="if size[a] >= size[b]:",
+                 fires=("TestElderRule",)),
+        Mutation("tie-to-higher-index", file="pkg/engine.py",
+                 old="(birth[a], -a) >= (birth[b], -b)", new="(birth[a], a) >= (birth[b], b)",
+                 invisible=True),          # an invariance: must fire nothing
+    ]
+
+Then `mutgate run tests/mutations.py`. Each mutation is applied in a sandbox copy, the
+tests run, and the contract judged: OK, DECORATION (a named guard did not fire),
+OVERREACH (something outside the contract fired — two copies of one convention?),
+VISIBLE (an invariance was broken), NOT_APPLIED (the text was not found), ERROR.
+"""
+
+from .core import Mutation, Report, Verdict, load, run
+
+__version__ = "0.1.0"
+__all__ = ["Mutation", "Report", "Verdict", "load", "run", "__version__"]

mutgate/__main__.py

@@ -0,0 +1,3 @@
+from .cli import run_cli
+
+run_cli()

mutgate/cli.py

@@ -0,0 +1,82 @@
+"""`mutgate run tests/mutations.py` — check every named mutation's contract.
+
+Exit codes: 0 every contract holds; 1 a verdict is not OK; 2 the baseline is red or the
+declaration cannot be loaded.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+from . import __version__
+from .core import load, run
+
+
+def _parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="mutgate",
+                                 description="Named mutations as contracts on a test suite.")
+    ap.add_argument("--version", action="version", version=f"mutgate {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    r = sub.add_parser("run", help="apply each mutation in a sandbox and judge its contract")
+    r.add_argument("file", help="the mutations file (defines MUTATIONS, optionally TESTS/PATHS/ROOT/PYTHON)")
+    r.add_argument("--tests", nargs="+", help="pytest targets (override the file's TESTS)")
+    r.add_argument("--only", nargs="+", metavar="NAME", help="run only these mutations")
+    r.add_argument("--python", help="interpreter to run pytest with (default: this one)")
+    r.add_argument("--timeout", type=float, default=None, metavar="SECONDS",
+                   help="abort a pytest run that takes longer (verdict ERROR)")
+    r.add_argument("--pytest-arg", action="append", default=[], metavar="ARG",
+                   help="extra argument passed to pytest (repeatable)")
+    r.add_argument("--markdown", action="store_true", help="print the build-record table instead of the plain one")
+    r.add_argument("--keep", action="store_true", help="keep the sandbox directory")
+    r.add_argument("-x", "--stop", action="store_true", help="stop at the first verdict that is not OK")
+    r.add_argument("-v", "--verbose", action="store_true")
+
+    ls = sub.add_parser("list", help="list the mutations a file declares")
+    ls.add_argument("file")
+    return ap
+
+
+def main(argv=None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        decl = load(Path(args.file))
+    except Exception as exc:  # noqa: BLE001 — every load failure is a usage error here
+        print(f"mutgate: cannot load {args.file}: {exc}", file=sys.stderr)
+        return 2
+    if args.cmd == "list":
+        w = max(len(m.name) for m in decl.mutations) if decl.mutations else 8
+        for m in decl.mutations:
+            exp = "invisible" if m.invisible else ", ".join(m.fires)
+            print(f"{m.name:<{w}}  {m.file}  ->  {exp}")
+        print(f"\nroot {decl.root}\ntests {' '.join(decl.tests)}\npaths {' '.join(decl.paths)}")
+        return 0
+    log = (lambda s: print(f"mutgate: {s}", file=sys.stderr, flush=True)) if args.verbose else None
+    python = args.python or decl.python or sys.executable
+    if not (Path(python).is_file() or shutil.which(python)):
+        print(f"mutgate: interpreter not found: {python}", file=sys.stderr)
+        return 2
+    try:
+        report = run(decl.mutations, decl.root, args.tests or decl.tests,
+                     python=python, paths=decl.paths, only=args.only, keep=args.keep,
+                     stop_early=args.stop, extra_pytest_args=args.pytest_arg, log=log,
+                     timeout=args.timeout)
+    except ValueError as exc:
+        print(f"mutgate: {exc}", file=sys.stderr)
+        return 2
+    if report.baseline_failed or report.baseline_error:
+        print(report.table())
+        return 2
+    print(report.markdown() if args.markdown else report.table())
+    return 0 if report.ok else 1
+
+
+def run_cli() -> None:
+    sys.exit(main())
+
+
+if __name__ == "__main__":
+    run_cli()

mutgate/core.py

@@ -0,0 +1,453 @@
+"""Named mutations as contracts on a test suite.
+
+A *mutation* is an exact-string replacement in one source file of the project under test,
+applied in a sandbox copy (the working tree is never touched), together with a *contract*:
+the set of tests it must turn red, or the statement that it must turn nothing red.
+
+Four verdicts do the work:
+
+  OK           the mutation fired exactly the tests the contract names (plus any it may fire)
+  DECORATION   a test the contract says must fire did not — the guard is a decoration
+  OVERREACH    a test outside the contract fired — the mutation reaches further than its
+               author believed, which is the tell for two copies of one convention
+  VISIBLE      an `invisible` mutation (an invariance: swap a convention the measurement
+               must not depend on) fired something
+
+and two failure modes that are not verdicts about the suite:
+
+  NOT_APPLIED  the `old` text was not found exactly `count` times, so nothing was mutated —
+               a mutation that silently does not land looks identical to a working guard
+  ERROR        the suite could not run (a mutation that does not compile, a collection
+               error, a usage error)
+
+A red baseline aborts the whole run: mutations are meaningless on a suite that already fails.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable, Optional, Sequence
+
+__all__ = ["Mutation", "Verdict", "Report", "Sandbox", "run", "load", "run_pytest"]
+
+_IGNORE_DIRS = {".git", ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache",
+                ".ruff_cache", "node_modules", ".tox", ".nox", "dist", "build"}
+_STATUSES = ("OK", "DECORATION", "OVERREACH", "VISIBLE", "NOT_APPLIED", "ERROR")
+
+
+@dataclass(frozen=True)
+class Mutation:
+    """One named mutation and its contract.
+
+    file      path of the source file, relative to the project root
+    old/new   exact text to replace; `old` must occur exactly `count` times in the file
+    fires     test-id fragments (any substring of a pytest node id, e.g. "TestK2ElderRule"
+              or "test_x.py::TestK2::test_ratio") that MUST fail under the mutation
+    may_fire  fragments that are allowed to fail as well, without being required
+    invisible True for an invariance: the mutation must fail NOTHING
+    count     how many occurrences of `old` the file must contain (all are replaced)
+    note      free text, carried into reports
+    """
+    name: str
+    file: str
+    old: str
+    new: str
+    fires: tuple[str, ...] = ()
+    may_fire: tuple[str, ...] = ()
+    invisible: bool = False
+    count: int = 1
+    note: str = ""
+
+    def __post_init__(self):
+        for attr in ("fires", "may_fire"):
+            val = getattr(self, attr)
+            if isinstance(val, str):
+                # a bare string would become its own letters, each matching every node id,
+                # and every contract would read OK (review 2026-09-07, item 3)
+                raise ValueError(f"{self.name}: {attr} must be a tuple of fragments, not a string; "
+                                 f"write ({val!r},)")
+            val = tuple(val)
+            if any(not isinstance(f, str) or not f.strip() for f in val):
+                raise ValueError(f"{self.name}: every {attr} entry must be a non-empty string")
+            object.__setattr__(self, attr, val)
+        if not self.name:
+            raise ValueError("a mutation needs a name")
+        if self.old == self.new:
+            raise ValueError(f"{self.name}: old and new are identical; nothing would change")
+        if not self.old:
+            raise ValueError(f"{self.name}: old must be non-empty")
+        if self.count < 1:
+            raise ValueError(f"{self.name}: count must be >= 1")
+        if self.invisible and (self.fires or self.may_fire):
+            raise ValueError(f"{self.name}: an invisible mutation fires nothing; drop fires/may_fire")
+        if not self.invisible and not self.fires:
+            raise ValueError(f"{self.name}: name the tests it must fire, or mark it invisible")
+
+
+@dataclass(frozen=True)
+class Verdict:
+    mutation: Mutation
+    status: str
+    fired: tuple[str, ...] = ()        # failing test node ids under the mutation
+    missing: tuple[str, ...] = ()      # contract entries that matched no failing test
+    unexpected: tuple[str, ...] = ()   # failing tests matching neither fires nor may_fire
+    detail: str = ""
+
+    def __post_init__(self):
+        if self.status not in _STATUSES:
+            raise ValueError(self.status)
+
+    @property
+    def ok(self) -> bool:
+        return self.status == "OK"
+
+
+@dataclass
+class Report:
+    root: Path
+    tests: tuple[str, ...]
+    baseline_failed: tuple[str, ...] = ()
+    baseline_error: str = ""
+    verdicts: list[Verdict] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.baseline_failed and not self.baseline_error and all(v.ok for v in self.verdicts)
+
+    def summary(self) -> str:
+        counts = {s: sum(v.status == s for v in self.verdicts) for s in _STATUSES}
+        parts = [f"{n} {s}" for s, n in counts.items() if n]
+        return ", ".join(parts) if parts else "no mutations"
+
+    def table(self) -> str:
+        lines = []
+        if self.baseline_error:
+            lines.append(f"BASELINE ERROR: {self.baseline_error}")
+            return "\n".join(lines)
+        if self.baseline_failed:
+            lines.append("BASELINE RED — nothing mutated. Failing before any mutation:")
+            lines.extend(f"    {t}" for t in self.baseline_failed)
+            return "\n".join(lines)
+        w = max((len(v.mutation.name) for v in self.verdicts), default=8)
+        lines.append(f"{'mutation':<{w}}  {'verdict':<11}  fired  expected")
+        for v in self.verdicts:
+            exp = "nothing" if v.mutation.invisible else ", ".join(v.mutation.fires)
+            lines.append(f"{v.mutation.name:<{w}}  {v.status:<11}  {len(v.fired):>5}  {exp}")
+            if v.status == "DECORATION":
+                lines.extend(f"{'':<{w}}    did not fire: {m}" for m in v.missing)
+            if v.status in ("OVERREACH", "DECORATION"):
+                lines.extend(f"{'':<{w}}    unexpected:   {u}" for u in v.unexpected)
+            if v.status == "VISIBLE":
+                lines.extend(f"{'':<{w}}    fired:        {f}" for f in v.fired)
+            if v.status in ("NOT_APPLIED", "ERROR"):
+                lines.append(f"{'':<{w}}    {v.detail}")
+        lines.append(f"\n{self.summary()}")
+        return "\n".join(lines)
+
+    def markdown(self) -> str:
+        """A table for a design note's build record: what each mutation fires."""
+        rows = ["| mutation | must fire | fired | verdict |", "|---|---|---|---|"]
+        for v in self.verdicts:
+            exp = "*nothing (invariance)*" if v.mutation.invisible else ", ".join(f"`{f}`" for f in v.mutation.fires)
+            fired = _collapse(v.fired)
+            rows.append(f"| {v.mutation.name} | {exp} | {fired} | {v.status} |")
+        return "\n".join(rows)
+
+
+def _collapse(ids: Sequence[str]) -> str:
+    """Failing node ids collapsed to their class or module level, for a readable cell."""
+    seen = []
+    for nid in ids:
+        parts = nid.split("::")
+        key = "::".join(parts[:2]) if len(parts) >= 3 else nid
+        if key not in seen:
+            seen.append(key)
+    return ", ".join(f"`{k}`" for k in seen) if seen else "—"
+
+
+# ---------------------------------------------------------------------------------------
+# the sandbox: a copy of the project the mutations are applied to
+# ---------------------------------------------------------------------------------------
+
+def project_files(root: Path) -> list[Path]:
+    """Files to copy: `git ls-files` (tracked plus untracked-but-not-ignored, so uncommitted
+    work is included and the venv is not) when `root` is in a git repo; otherwise a walk
+    that skips the usual build and cache directories."""
+    root = Path(root)
+    try:
+        out = subprocess.run(["git", "-C", str(root), "ls-files", "-z", "--cached", "--others",
+                              "--exclude-standard"], capture_output=True, check=True)
+        rels = [r for r in out.stdout.decode("utf-8", "surrogateescape").split("\0") if r]
+        files = [root / r for r in rels]
+        return [f for f in files if f.is_file()]
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pass
+    files = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in _IGNORE_DIRS and not d.endswith(".egg-info")]
+        files.extend(Path(dirpath) / f for f in filenames)
+    return files
+
+
+class Sandbox:
+    """A temporary copy of the project. Mutations are applied and restored here, one at a
+    time; the working tree is never written."""
+
+    def __init__(self, root: Path, keep: bool = False):
+        self.root = Path(root).resolve()
+        self.keep = keep
+        # resolved: on a symlinked TMPDIR (macOS /var -> /private/var) an unresolved dir
+        # fails its own containment check in `path` (review 2026-09-07, item 1)
+        self.dir = Path(tempfile.mkdtemp(prefix="mutgate-")).resolve()
+        for src in project_files(self.root):
+            rel = src.relative_to(self.root)
+            dst = self.dir / rel
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src, dst)
+
+    def path(self, rel: str) -> Path:
+        p = (self.dir / rel).resolve()
+        if self.dir not in p.parents and p != self.dir:
+            raise ValueError(f"{rel} escapes the sandbox")
+        return p
+
+    def apply(self, m: Mutation) -> tuple[bool, str, str]:
+        """(applied, original_text, detail). Applied only if `old` occurs exactly `count`
+        times; otherwise nothing is written and `detail` says what was found."""
+        p = self.path(m.file)
+        if not p.is_file():
+            return False, "", f"{m.file}: no such file in the project"
+        text = p.read_text(encoding="utf-8")
+        found = text.count(m.old)
+        if found != m.count:
+            return False, text, f"{m.file}: `old` found {found} time(s), contract says {m.count}"
+        p.write_text(text.replace(m.old, m.new), encoding="utf-8")
+        return True, text, ""
+
+    def restore(self, m: Mutation, original: str) -> None:
+        self.path(m.file).write_text(original, encoding="utf-8")
+
+    def close(self) -> None:
+        if not self.keep:
+            shutil.rmtree(self.dir, ignore_errors=True)
+
+
+# ---------------------------------------------------------------------------------------
+# running pytest and reading which tests failed
+# ---------------------------------------------------------------------------------------
+
+def _node_id(rest: str) -> str:
+    """The node id at the start of a summary line's remainder: everything up to the first
+    " - " that is not inside a parametrisation bracket (ids like `test_x[a - b]` keep it)."""
+    depth = 0
+    i = 0
+    while i < len(rest):
+        ch = rest[i]
+        if ch == "[":
+            depth += 1
+        elif ch == "]" and depth:
+            depth -= 1
+        elif depth == 0 and rest.startswith(" - ", i):
+            return rest[:i].strip()
+        i += 1
+    return rest.strip()
+
+
+_CUT_SHORT_LINE = re.compile(r"^!{3,} stopping after \d+ failures? !{3,}\s*$", re.MULTILINE)
+TIMEOUT = -9999     # return code standing for "pytest did not finish in time"
+CUT_SHORT = -9998   # pytest stopped early (maxfail), so the fired set is incomplete
+
+
+def run_pytest(cwd: Path, tests: Sequence[str], python: str = sys.executable,
+               paths: Sequence[str] = ("src", "."), extra_args: Sequence[str] = (),
+               env: Optional[dict] = None, timeout: Optional[float] = None) -> tuple[int, list[str], str]:
+    """Run pytest in `cwd`; return (returncode, failing node ids, tail of the output).
+
+    Failures are read from pytest's own short summary (`-rfE`), so node ids are exactly the
+    ones a contract names. `paths` are prepended to PYTHONPATH relative to `cwd`, so an
+    editable install elsewhere cannot shadow the sandbox copy. A run that exceeds `timeout`
+    seconds returns `TIMEOUT` as the code."""
+    e = dict(os.environ if env is None else env)
+    pp = [str(Path(cwd) / p) for p in paths]
+    if e.get("PYTHONPATH"):
+        pp.append(e["PYTHONPATH"])
+    e["PYTHONPATH"] = os.pathsep.join(pp)
+    e.setdefault("PYTHONDONTWRITEBYTECODE", "1")
+    # mutgate OWNS three flags: -rfE (the summary it reads), no:cacheprovider (a clean
+    # sandbox) and --maxfail=0 AFTER every user argument, because a contract needs the whole
+    # failure set and a project's addopts "-x" / "--maxfail=N" would truncate it to a
+    # consistent-looking single failure (review 2026-09-07, second round)
+    cmd = [python, "-m", "pytest", "-q", "-rfE", "-p", "no:cacheprovider", "--no-header",
+           *extra_args, "--maxfail=0", *tests]
+    try:
+        proc = subprocess.run(cmd, cwd=str(cwd), env=e, capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired as exc:
+        out = (exc.stdout or b"")
+        out = out.decode("utf-8", "replace") if isinstance(out, bytes) else out
+        return TIMEOUT, [], f"pytest exceeded {timeout} s\n" + "\n".join(out.strip().splitlines()[-25:])
+    failed = []
+    for line in proc.stdout.splitlines():
+        if line.startswith("FAILED ") or line.startswith("ERROR "):
+            nid = _node_id(line.split(" ", 1)[1])
+            # "ERROR tests/x.py" with no "::" is a COLLECTION error (the file did not
+            # import), not a red test; it is reported through the return code instead
+            if line.startswith("ERROR ") and "::" not in nid:
+                continue
+            if nid and nid not in failed:
+                failed.append(nid)
+    tail = (proc.stdout + proc.stderr).strip().splitlines()[-25:]
+    if _CUT_SHORT_LINE.search(proc.stdout):
+        # the belt: pytest announces a truncated run ("!!! stopping after N failures !!!");
+        # a conftest setting config.option.maxfail can get past the flag above. Anchored to
+        # a whole line at column 0: a target's own captured output can quote the phrase
+        # (mutgate's suite does), and that must not read as a truncated run
+        return CUT_SHORT, failed, "the run was cut short (maxfail); the fired set is incomplete\n" + "\n".join(tail)
+    return proc.returncode, failed, "\n".join(tail)
+
+
+# ---------------------------------------------------------------------------------------
+# the contract check
+# ---------------------------------------------------------------------------------------
+
+_NO_SUMMARY = ("pytest reported failures but none could be read from its short summary; is "
+               "the summary suppressed (addopts --no-summary / -p no:terminal)? mutgate needs -rfE")
+
+
+def _classify(m: Mutation, rc: int, fired: list[str], tail: str) -> Verdict:
+    fired_t = tuple(fired)
+    if rc in (TIMEOUT, CUT_SHORT):
+        return Verdict(m, "ERROR", fired_t, detail=tail)
+    if rc == 1 and not fired:
+        # the gate that cannot fail, in the classifier itself: an invisible mutation that
+        # broke the suite would read OK, a firing one DECORATION (review 2026-09-07, item 2)
+        return Verdict(m, "ERROR", fired_t, detail=f"{_NO_SUMMARY}\n{tail}")
+    if rc not in (0, 1):
+        # only 0 and 1 mean the test loop ran to completion. An interrupted run (exit 2)
+        # can carry a PARTIAL fired set -- a conftest setting session.shouldstop after the
+        # first failure gives one failure in the summary and "!!! Interrupted !!!", not the
+        # maxfail line -- and a partial set is never a verdict (review, third round)
+        why = {2: "interrupted, or collection failed (does the mutated file still compile?); "
+                  "any fired set is partial",
+               3: "pytest internal error", 4: "pytest usage error", 5: "no tests collected"}.get(rc, f"pytest exit {rc}")
+        return Verdict(m, "ERROR", fired_t, detail=f"{why}\n{tail}")
+    if m.invisible:
+        return Verdict(m, "VISIBLE" if fired else "OK", fired_t)
+    missing = tuple(e for e in m.fires if not any(e in f for f in fired))
+    allowed = m.fires + m.may_fire
+    unexpected = tuple(f for f in fired if not any(e in f for e in allowed))
+    if missing:
+        return Verdict(m, "DECORATION", fired_t, missing, unexpected)
+    if unexpected:
+        return Verdict(m, "OVERREACH", fired_t, missing, unexpected)
+    return Verdict(m, "OK", fired_t)
+
+
+def run(mutations: Iterable[Mutation], root: Path, tests: Sequence[str],
+        python: str = sys.executable, paths: Sequence[str] = ("src", "."),
+        only: Optional[Sequence[str]] = None, keep: bool = False, stop_early: bool = False,
+        extra_pytest_args: Sequence[str] = (), log=None, timeout: Optional[float] = None) -> Report:
+    """Apply each mutation in a sandbox copy of `root`, run `tests`, and judge the contract.
+
+    The baseline (no mutation) runs first; if it is red the report says so and nothing is
+    mutated. Each mutation is applied, run, and restored before the next."""
+    root = Path(root).resolve()
+    tests = tuple(tests)
+    report = Report(root=root, tests=tests)
+    mutations = list(mutations)
+    if only is not None:
+        known = {m.name for m in mutations}
+        unknown = [n for n in only if n not in known]
+        if unknown:
+            raise ValueError(f"--only names no declared mutation: {unknown}")
+        mutations = [m for m in mutations if m.name in only]
+    if not mutations:
+        raise ValueError("no mutations to run: an emptied declaration must not pass green")
+    log = log or (lambda s: None)
+    sb = Sandbox(root, keep=keep)
+    try:
+        log(f"sandbox {sb.dir}")
+        rc, failed, tail = run_pytest(sb.dir, tests, python, paths, extra_pytest_args, timeout=timeout)
+        if rc not in (0, 1) or (rc == 1 and not failed):
+            note = _NO_SUMMARY if rc == 1 else ""
+            report.baseline_error = f"baseline could not run (pytest exit {rc}) {note}\n{tail}"
+            return report
+        if failed:
+            report.baseline_failed = tuple(failed)
+            return report
+        log("baseline green")
+        for m in mutations:
+            applied, original, detail = sb.apply(m)
+            if not applied:
+                v = Verdict(m, "NOT_APPLIED", detail=detail)
+            else:
+                try:
+                    rc, failed, tail = run_pytest(sb.dir, tests, python, paths, extra_pytest_args,
+                                                  timeout=timeout)
+                finally:
+                    sb.restore(m, original)
+                v = _classify(m, rc, failed, tail)
+            report.verdicts.append(v)
+            log(f"{m.name}: {v.status} ({len(v.fired)} fired)")
+            if stop_early and not v.ok:
+                break
+    finally:
+        sb.close()
+    return report
+
+
+# ---------------------------------------------------------------------------------------
+# the declaration file
+# ---------------------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class Declaration:
+    mutations: tuple[Mutation, ...]
+    root: Path
+    tests: tuple[str, ...]
+    paths: tuple[str, ...]
+    python: Optional[str] = None
+
+
+def _find_root(start: Path) -> Path:
+    for p in [start, *start.parents]:
+        if (p / "pyproject.toml").is_file() or (p / ".git").exists():
+            return p
+    return start
+
+
+def load(path: Path) -> Declaration:
+    """Import a mutations file. It must define `MUTATIONS` (a sequence of `Mutation`);
+    optionally `TESTS` (pytest targets, default the file's own directory), `PATHS`
+    (PYTHONPATH entries relative to the root, default ("src", ".")), `ROOT` (relative to the
+    declaration file; default: the nearest ancestor holding pyproject.toml or .git) and
+    `PYTHON` (interpreter)."""
+    path = Path(path).resolve()
+    spec = importlib.util.spec_from_file_location(f"_mutgate_decl_{path.stem}", path)
+    if spec is None or spec.loader is None:
+        raise ValueError(f"cannot import {path}")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    if not hasattr(mod, "MUTATIONS"):
+        raise ValueError(f"{path} defines no MUTATIONS")
+    muts = tuple(mod.MUTATIONS)
+    for m in muts:
+        if not isinstance(m, Mutation):
+            raise ValueError(f"{path}: MUTATIONS holds a {type(m).__name__}, not a Mutation")
+    names = [m.name for m in muts]
+    dupes = sorted({n for n in names if names.count(n) > 1})
+    if dupes:
+        raise ValueError(f"{path}: duplicate mutation names {dupes}")
+    root_decl = getattr(mod, "ROOT", None)
+    root = (_find_root(path.parent) if root_decl is None else (path.parent / root_decl)).resolve()
+    tests_default = str(path.parent.relative_to(root)) if root in path.parent.parents or root == path.parent else "tests"
+    tests = tuple(getattr(mod, "TESTS", (tests_default,)))
+    paths = tuple(getattr(mod, "PATHS", ("src", ".")))
+    return Declaration(muts, root, tests, paths, getattr(mod, "PYTHON", None))

mutgate-0.1.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: mutgate
+Version: 0.1.0
+Summary: Named mutations as contracts on a test suite: each mutation must turn exactly the tests it names red, or nothing at all.
+Project-URL: Homepage, https://github.com/JimGalasyn/mutgate
+Project-URL: Issues, https://github.com/JimGalasyn/mutgate/issues
+Project-URL: Changelog, https://github.com/JimGalasyn/mutgate/blob/main/CHANGELOG.md
+Author: James P. Galasyn, Claude Théodore
+License: MIT
+License-File: LICENSE
+Keywords: contracts,mutation-testing,pytest,reproducibility,scientific-software,test-quality,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mutgate
+
+**Named mutations as contracts on a test suite.** Each mutation is a deliberate, named
+change to the code under test, together with the list of tests it must turn red — or the
+statement that it must turn nothing red. `mutgate` applies each one in a sandbox copy, runs
+the suite, and judges the contract.
+
+```python
+# tests/mutations.py
+from mutgate import Mutation
+
+MUTATIONS = [
+    Mutation("keep-larger", file="pkg/engine.py",
+             old="if (birth[a], -a) >= (birth[b], -b):",
+             new="if size[a] >= size[b]:",
+             fires=("TestElderRule",)),
+    Mutation("skip-absolute-floor", file="pkg/engine.py",
+             old="if u.birth < abs_floor:", new="if False:",
+             fires=("TestAbsoluteFloor",)),
+    Mutation("tie-to-higher-index", file="pkg/engine.py",
+             old="(birth[a], -a) >= (birth[b], -b)",
+             new="(birth[a], a) >= (birth[b], b)",
+             invisible=True),   # an invariance: the measurement must not depend on it
+]
+```
+
+```
+$ mutgate run tests/mutations.py
+mutation             verdict      fired  expected
+keep-larger          OK               3  TestElderRule
+skip-absolute-floor  DECORATION       0  TestAbsoluteFloor
+                       did not fire: TestAbsoluteFloor
+tie-to-higher-index  OK               0  nothing
+
+2 OK, 1 DECORATION
+```
+
+## Why
+
+A green test suite guards only the defects that shaped it. The usual way to find out
+whether a test is load-bearing is to break the code on purpose and see whether the test
+notices — and in practice that is done by hand, in a scratch copy, with `sed`, once, and then
+the result is written into a design note as prose. `mutgate` makes that a checked artefact:
+
+- **the mutation is named and exact.** `old` must occur exactly `count` times in the file,
+  or the verdict is `NOT_APPLIED`. A mutation that silently does not land looks identical
+  to a working guard; this is the trap that motivated the tool.
+- **the contract says which tests must fire.** A named test that does not fire is a
+  `DECORATION` — a guard that would not go red.
+- **a test outside the contract firing is a finding, not noise.** `OVERREACH` means the
+  mutation reaches further than its author believed. When a convention (a tie-breaking rule,
+  a sign, an ordering) is changed and tests that should only *relabel* things fail on
+  *values*, the convention exists in two places that have drifted apart.
+- **an invariance is a mutation that must fire nothing.** `invisible=True` pins that the
+  suite passes unchanged under the alternative convention; if it does not, the verdict is
+  `VISIBLE`. ⚠ An `OK` on an invariance is a *negative* result, and it is only as strong as
+  the evidence that the mutated line ran: a dead function, a site the named `TESTS` never
+  reach, or a suite that imports an installed copy instead of the sandbox all read `OK`
+  honestly. **Pair every invariance with a firing mutation at the same site in the same
+  declaration** — the known-positive control — so the file itself proves the site is
+  exercised by these tests. An unpaired `OK` on an invariance is unevidenced.
+- **the working tree is never touched.** Each mutation is applied and restored in a
+  temporary copy (`git ls-files`, so uncommitted work is included and the venv is not), and
+  the copy is put first on `PYTHONPATH` so an editable install elsewhere cannot shadow it.
+- **a red baseline aborts.** Mutations mean nothing on a suite that already fails.
+- **a run whose failures cannot be read is an error, never a verdict.** If the project's
+  pytest configuration suppresses the short summary (`--no-summary`), pytest's exit code
+  says "failed" while nothing parses; that is reported as `ERROR`, not silently as `OK`.
+  And a run cut short is never a verdict either: `mutgate` owns `--maxfail=0` after every
+  user argument (a project's `-x` would truncate the fired set to one test), and a
+  `conftest` that forces `maxfail` anyway trips pytest's own "stopping after N failures"
+  line, which reads as `ERROR`.
+
+The sandbox holds the project's files but not its `.git`; a suite that shells out to git
+(a `setuptools_scm`-style version check, say) goes red at baseline and says so.
+
+## What it is not
+
+It is not automatic mutation testing. Tools like `mutmut` and `cosmic-ray` generate operator
+mutations at random and report a kill rate; that answers "how thorough is this suite?".
+`mutgate` answers a narrower question that random mutation cannot: *does this specific guard
+fire under the specific defect it was written for, and only that?* The two are complementary.
+
+## Declaration file
+
+A Python file (conventionally `tests/mutations.py`) defining:
+
+| name | required | meaning |
+|---|---|---|
+| `MUTATIONS` | yes | a sequence of `Mutation` |
+| `TESTS` | no | pytest targets; default: the declaration file's own directory |
+| `PATHS` | no | `PYTHONPATH` entries relative to the root; default `("src", ".")` |
+| `ROOT` | no | project root, relative to the declaration file; default: the nearest ancestor with `pyproject.toml` or `.git` |
+| `PYTHON` | no | interpreter to run pytest with; default: the one running `mutgate` |
+
+`Mutation(name, file, old, new, fires=(), may_fire=(), invisible=False, count=1, note="")`.
+Entries in `fires` and `may_fire` are substrings of pytest node ids, so `"TestElderRule"`,
+`"test_engine.py::TestElderRule"` and `"test_tie_goes_to_lower_index"` all work.
+
+## CLI
+
+```
+mutgate run tests/mutations.py [--tests T ...] [--only NAME ...] [--python PY]
+                               [--pytest-arg ARG] [--markdown] [--keep] [-x] [-v]
+mutgate list tests/mutations.py
+```
+
+`--markdown` prints a table meant to be pasted into a design note's build record. Exit code
+0 when every contract holds, 1 when a verdict is not `OK`, 2 when the baseline is red or the
+file cannot be loaded.
+
+## In CI
+
+```yaml
+- run: pip install mutgate
+- run: mutgate run tests/mutations.py
+```
+
+Each mutation runs the named tests once, so the cost is the suite's cost times the number of
+mutations; point `TESTS` at the module the mutations concern.
+
+## Install
+
+```
+pip install mutgate
+```
+
+No runtime dependencies. Python 3.10+. MIT.

mutgate-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+mutgate/__init__.py,sha256=owlSDq3ktIA-dvpIMBbJ51hI2gPBAkgB9QszrrgvUSQ,1022
+mutgate/__main__.py,sha256=bV6F-JJz7HFmmQqzfQ-_u__AOs-LNYme3uFK7e9FtWE,36
+mutgate/cli.py,sha256=DdZdLlPhGrf1dQmcSRIxzNycqJIA8_oTuAhYCErpT8E,3627
+mutgate/core.py,sha256=dajh1vYNsR02VwHxI0HLJdYw2bdG7Cb2zsvr4PwR1-s,21284
+mutgate-0.1.0.dist-info/METADATA,sha256=d3e9Zf_SiUQJ8dr5-eTBQCPdTBLjSA0_FrsMXaTnW0o,7491
+mutgate-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mutgate-0.1.0.dist-info/entry_points.txt,sha256=dPl0jY2PgdRhTNUdDCM_m3su4fFwBQfRVxzLPag8Br8,48
+mutgate-0.1.0.dist-info/licenses/LICENSE,sha256=pXi-REGP6qna7DadI_rzujveoXI4u3PxyD-Af-G_XPc,1073
+mutgate-0.1.0.dist-info/RECORD,,

mutgate-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mutgate-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mutgate = mutgate.cli:run_cli

mutgate-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James P. Galasyn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.