mutgate 0.1.0__tar.gz

mutgate-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+
+# packaging
+build/
+dist/
+*.egg-info/
+
+# coverage
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/

mutgate-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## Unreleased
+
+Planned: a `control=` field naming an invariance's firing sibling, with a warning on an
+unpaired invariance, once a real declaration carries more than a handful of them.
+
+## 0.1.0 — 2026-09-07
+
+First release. `Mutation` with `fires` / `may_fire` / `invisible` / `count`; the sandbox
+copy via `git ls-files`; verdicts OK, DECORATION, OVERREACH, VISIBLE, NOT_APPLIED, ERROR;
+a red baseline aborts; `mutgate run` and `mutgate list`, with `--markdown` for build
+records. Extracted from three hand-rolled mutation harnesses written in one week across
+the Morphospace and abiogenesis repositories, after the third one found a duplicated
+convention by firing on the wrong kind of assertion.
+
+### Fixed before release, on a second session's review of the first commit
+
+- **A symlinked TMPDIR crashed every mutation** ("escapes the sandbox"): the sandbox
+  directory is now resolved before the containment check. macOS keeps `/var` behind a
+  symlink, so this was every macOS user.
+- **A suppressed pytest summary was a silent false pass.** `pytest` exit 1 with no
+  failure readable is now `ERROR`, never `OK`; the same at baseline.
+- **`fires="Name"` (a bare string) was a silent false pass**: it became one-letter
+  fragments matching every node id. Strings and empty fragments are refused.
+- **A typo in `--only`, or an emptied `MUTATIONS`, exited 0.** Both are usage errors (2).
+- **A project whose config stops at the first failure (`-x`, `--maxfail=N`) truncated the
+  fired set with a consistent-looking exit**, so an OVERREACH read OK. mutgate now owns
+  `--maxfail=0` after every user argument, and pytest's own "stopping after N failures"
+  line (a conftest can still force it) makes the run `ERROR`. Second review round.
+- **An interrupted run with a partial fired set read as a verdict** (a conftest setting
+  `session.shouldstop` after the first failure: exit 2, one failure parsed). Only exit codes
+  0 and 1 now count as a completed run; anything else is `ERROR` whatever parsed. Third
+  review round.
+- Node ids containing " - " inside a parametrisation are no longer truncated; `--timeout`
+  makes a hanging suite an `ERROR`; a missing `--python` is a usage error; `ROOT` is
+  relative to the declaration file; the `git ls-files` sandbox and real PYTHONPATH
+  shadowing are now tested; the `Framework :: Pytest` classifier (for plugins) is dropped.

mutgate-0.1.0/CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+title: "mutgate: named mutations as contracts on a test suite"
+message: "If you use this software, please cite it using these metadata."
+type: software
+authors:
+  - given-names: James P.
+    family-names: Galasyn
+  - given-names: Claude
+    family-names: Théodore
+repository-code: "https://github.com/JimGalasyn/mutgate"
+url: "https://github.com/JimGalasyn/mutgate"
+abstract: >-
+  A dependency-free tool that turns "break the code on purpose and see whether the
+  test notices" into a checked artefact. Each mutation is a named, exact-string change
+  to one file of the project under test, applied in a sandbox copy, with a contract
+  naming the tests it must turn red or the statement that it must turn nothing red.
+  Verdicts distinguish a guard that does not fire (a decoration) from a mutation that
+  fires beyond its contract (the tell for a convention duplicated in two places) and
+  from an invariance that breaks; a mutation whose text is not found exactly once is
+  reported rather than silently skipped.
+keywords:
+  - mutation-testing
+  - pytest
+  - test-quality
+  - scientific-software
+  - reproducibility
+license: MIT
+version: 0.1.0
+date-released: "2026-09-07"

mutgate-0.1.0/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.

mutgate-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,128 @@
+# 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/docs/RELEASING.md

@@ -0,0 +1,36 @@
+# Releasing
+
+The version is static in three files and they must agree:
+
+- `pyproject.toml` → `[project] version`
+- `src/mutgate/__init__.py` → `__version__`
+- `CITATION.cff` → `version` (and `date-released`)
+
+## Cutting a release
+
+1. Bump those three, and move the `CHANGELOG.md` `Unreleased` section under the new
+   version heading.
+2. Commit, then tag and push:
+
+   ```bash
+   git tag vX.Y.Z && git push origin vX.Y.Z
+   ```
+
+3. Publish a GitHub Release for the tag. That triggers `.github/workflows/publish-pypi.yml`,
+   which refuses to build unless the tag matches the `pyproject.toml` version, runs
+   `twine check`, and uploads to PyPI by trusted publishing.
+
+```bash
+gh release create vX.Y.Z --title "vX.Y.Z" --notes-file <(sed -n '/^## X.Y.Z/,/^## /p' CHANGELOG.md)
+```
+
+## Before the first publish (one-time, web console)
+
+- pypi.org → Publishing → add a **pending** trusted publisher: project `mutgate`, owner
+  `JimGalasyn`, repository `mutgate`, workflow `publish-pypi.yml`, environment `pypi`.
+- GitHub → Settings → Environments → create `pypi`.
+- Zenodo → GitHub integration → enable `JimGalasyn/mutgate` before the first release, so
+  the first release mints the concept DOI; then record it in `CITATION.cff`.
+
+The `publish-release` skill in the Claude Code setup walks these steps for the sibling
+repositories (rafkit, run-farm, jax-morpho, jax-solitons, proc-warden); this one is the same.

mutgate-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mutgate"
+version = "0.1.0"
+description = "Named mutations as contracts on a test suite: each mutation must turn exactly the tests it names red, or nothing at all."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+  { name = "James P. Galasyn" },
+  { name = "Claude Théodore" },
+]
+keywords = [
+  "mutation-testing", "pytest", "testing", "test-quality", "contracts",
+  "reproducibility", "scientific-software",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Testing",
+]
+# No runtime dependencies, deliberately: pytest is invoked as a subprocess of whichever
+# interpreter owns the project under test, so mutgate never has to agree with it on versions.
+dependencies = []
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8",
+  "pytest-cov>=4",
+]
+
+[project.urls]
+Homepage = "https://github.com/JimGalasyn/mutgate"
+Issues = "https://github.com/JimGalasyn/mutgate/issues"
+Changelog = "https://github.com/JimGalasyn/mutgate/blob/main/CHANGELOG.md"
+
+[project.scripts]
+mutgate = "mutgate.cli:run_cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mutgate"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/", "tests/", "docs/",
+  "README.md", "CHANGELOG.md", "LICENSE", "CITATION.cff",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["mutgate"]
+
+[tool.coverage.report]
+exclude_also = [
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]

mutgate-0.1.0/src/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-0.1.0/src/mutgate/__main__.py

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

mutgate-0.1.0/src/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()