pi-dev-team 0.2.0

package/hooks/mutation_adapters/lib.py

@@ -0,0 +1,478 @@
+"""Shared library for mutation-gate hook and adapters — Python port of lib.sh.
+
+Adapter contract (mirrors the bash lib.sh header):
+
+Inputs (env vars set by mutation-gate orchestrator):
+  ADAPTER_COMMAND       — the original test command (used for pitest class extraction)
+  ADAPTER_SOURCE_FILE   — path to the source file under test (JS/TS adapters)
+  ADAPTER_TIMEOUT       — seconds (from MUTATION_GATE_TIMEOUT, default 60)
+  ADAPTER_RUNNER_STDOUT — captured test runner stdout (for pitest test-list derivation)
+
+Output: adapter writes normalized zero-kill list to $TMPDIR/mutation-gate/zero-kills.json
+  Format: [{"name":"TestName","file":"path.ts","line":12,"covered":4}]
+  "line" is null when unknown.
+
+Exit codes: 0 = success or advisory (orchestrator reads zero-kills.json), 1 = internal error.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# _timeout — portable wrapper: `timeout` > `gtimeout` > unbounded fallback
+# ---------------------------------------------------------------------------
+
+
+def run_with_timeout(
+    seconds: int,
+    argv: Sequence[str],
+    **kwargs: Any,
+) -> subprocess.CompletedProcess[bytes]:
+    """Run `argv` with the given `seconds` wall-clock cap, mirroring bash `_timeout`.
+
+    Prefers `timeout`/`gtimeout` on PATH (so the runner keeps its bash-native
+    kill semantics on hosts that have coreutils); falls back to
+    `subprocess.run(..., timeout=...)` when neither is available. On timeout,
+    return code is 124 to match `timeout(1)`'s convention.
+
+    All extra kwargs pass through to `subprocess.run`. Callers pass `check=False`
+    when they want to inspect the exit code themselves.
+    """
+    kwargs.setdefault("check", False)
+    timeout_bin = shutil.which("timeout") or shutil.which("gtimeout")
+    if timeout_bin is not None:
+        # `check` is already guaranteed present via the `setdefault` above;
+        # ruff can't see through `**kwargs` to confirm it statically.
+        return subprocess.run([timeout_bin, str(seconds), *argv], **kwargs)  # noqa: PLW1510
+    # No coreutils timeout available — emit the same advisory as bash lib
+    # to stderr so the JSON stdout channel stays clean.
+    sys.stderr.write(
+        "mutation-gate: timeout unavailable (install coreutils for gtimeout); "
+        "run is unbounded\n"
+    )
+    try:
+        # `check` is already guaranteed present via the `setdefault` above;
+        # ruff can't see through `**kwargs` to confirm it statically.
+        return subprocess.run(list(argv), timeout=seconds, **kwargs)  # noqa: PLW1510
+    except subprocess.TimeoutExpired as exc:
+        # Synthesize a CompletedProcess with the timeout-native exit code so
+        # callers keep their `exit == 124` branch.
+        return subprocess.CompletedProcess(
+            args=list(argv),
+            returncode=124,
+            stdout=exc.stdout or b"",
+            stderr=exc.stderr or b"",
+        )
+
+
+# ---------------------------------------------------------------------------
+# JSON output helpers
+#
+# The bash lib pipes through `jq -n` to build objects; here we compose with
+# `json.dumps` and preserve the same key order + no trailing newline so the
+# hook's JSON decision channel stays byte-parity with the bash implementation.
+# ---------------------------------------------------------------------------
+
+
+def emit_block(reason: str) -> str:
+    """Return `{"decision":"block","reason":"..."}` as compact JSON (no trailing \\n)."""
+    return json.dumps({"decision": "block", "reason": reason})
+
+
+# Canonical coverage-capture-failure signal (see #1156). Verbatim from
+# Stryker.NET's own log: src/Stryker.Core/Stryker.Core/CoverageAnalysis/
+# CoverageAnalyser.cs emits "It looks like the test coverage capture failed.
+# Disable coverage based optimisation." when the initial per-test coverage pass
+# yields zero covered mutations, then calls AssumeAllTestsAreNeeded() —
+# silently falling back to whole-suite-per-mutant. The British "optimisation"
+# spelling matches the source. Kept byte-identical with the copy in the status
+# loop (csharp_stryker_net_status_loop.py); the two live in different import
+# roots (hooks/ vs skills/) so they cannot share a constant — the equivalence
+# is armored by test_coverage_capture_regex_matches_status_loop.
+_COVERAGE_CAPTURE_FAILURE_RE = re.compile(
+    r"test coverage capture failed|disable coverage based optimisation",
+    re.IGNORECASE,
+)
+
+
+def detect_coverage_capture_failure(text: str) -> bool:
+    """True when `text` (Stryker's captured stdout/stderr) shows per-test
+    coverage capture failed and Stryker fell back to whole-suite-per-mutant.
+
+    A pure predicate later slices (#1158's feasibility gate) branch on to
+    decide loop-vs-degrade. Matches either half of 'It looks like the test
+    coverage capture failed. Disable coverage based optimisation.'
+    """
+    if not text:
+        return False
+    return bool(_COVERAGE_CAPTURE_FAILURE_RE.search(text))
+
+
+def emit_advisory(message: str) -> str:
+    """Return the PostToolUse additionalContext envelope for an advisory message."""
+    return json.dumps(
+        {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": message,
+            }
+        }
+    )
+
+
+# ---------------------------------------------------------------------------
+# State file management — mirrors bash lib
+#
+# Location: $TMPDIR/mutation-gate/session-<12-char sha256 of cwd>
+# TTL: 4 hours (14400 seconds)
+# ---------------------------------------------------------------------------
+
+
+_STATE_TTL_SECONDS = 14400
+
+
+def _state_dir() -> Path:
+    return Path(os.environ.get("TMPDIR", "/tmp")) / "mutation-gate"
+
+
+def state_file_path(cwd: Path | None = None) -> Path:
+    """Return the per-project state file path (`session-<hash>`)."""
+    base = str(cwd if cwd is not None else Path.cwd())
+    digest = hashlib.sha256(base.encode("utf-8")).hexdigest()[:12]
+    return _state_dir() / f"session-{digest}"
+
+
+def _purge_stale_states(state_dir: Path) -> None:
+    """Delete session-* files older than TTL. Best-effort; errors ignored."""
+    if not state_dir.is_dir():
+        return
+    now = time.time()
+    for path in state_dir.glob("session-*"):
+        try:
+            if now - path.stat().st_mtime > _STATE_TTL_SECONDS:
+                path.unlink()
+        except OSError:
+            pass
+
+
+def write_state(result: str, event_json: str, cwd: Path | None = None) -> None:
+    """Write the state file from a PostToolUse event body.
+
+    `result` is "pass" or "fail"; `event_json` is the raw stdin JSON string —
+    we extract `tool_response.output` and truncate it to 64 KiB, matching the
+    bash `head -c 65536` behaviour.
+    """
+    state_dir = _state_dir()
+    state_dir.mkdir(parents=True, exist_ok=True)
+    _purge_stale_states(state_dir)
+    try:
+        event = json.loads(event_json) if event_json else {}
+    except (TypeError, ValueError):
+        event = {}
+    tool_response = event.get("tool_response") or {}
+    runner_stdout = tool_response.get("output") or ""
+    if len(runner_stdout) > 65536:
+        runner_stdout = runner_stdout[:65536]
+    payload = {
+        "result": result,
+        "timestamp": int(time.time()),
+        "runner_stdout": runner_stdout,
+    }
+    target = state_file_path(cwd)
+    target.write_text(json.dumps(payload))
+
+
+def read_state(cwd: Path | None = None) -> str:
+    """Return the state JSON as a string, or `""` if absent / stale.
+
+    Stale files (> TTL) are deleted lazily on read so subsequent calls don't
+    keep re-reading them.
+    """
+    path = state_file_path(cwd)
+    if not path.is_file():
+        return ""
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, ValueError):
+        return ""
+    ts = data.get("timestamp") or 0
+    if int(time.time()) - int(ts) > _STATE_TTL_SECONDS:
+        try:
+            path.unlink()
+        except OSError:
+            pass
+        return ""
+    return path.read_text()
+
+
+# ---------------------------------------------------------------------------
+# Result detection
+# ---------------------------------------------------------------------------
+
+
+_PASS_PATTERNS = re.compile(
+    r"passing|tests run.*failures: 0|all tests passed|✓|ok [0-9]",
+    re.IGNORECASE,
+)
+_FAIL_PATTERNS = re.compile(
+    r"failing|failures: [1-9]|error:|FAILED",
+    re.IGNORECASE,
+)
+
+
+def detect_result(event_json: str) -> str:
+    """Return "pass" or "fail" for a PostToolUse event.
+
+    Primary signal: `tool_response.exit_code`. Secondary: stdout patterns —
+    used for runners that always exit 0. Default: "fail" when uncertain (the
+    bash lib does the same).
+    """
+    try:
+        event = json.loads(event_json) if event_json else {}
+    except (TypeError, ValueError):
+        event = {}
+    tool_response = event.get("tool_response") or {}
+    exit_code = tool_response.get("exit_code")
+    if exit_code == 0:
+        return "pass"
+    if exit_code is not None and exit_code != -1:
+        return "fail"
+    output = tool_response.get("output") or ""
+    if _PASS_PATTERNS.search(output):
+        return "pass"
+    if _FAIL_PATTERNS.search(output):
+        return "fail"
+    return "fail"
+
+
+def is_red_to_green(prev_result: str, cur_result: str) -> bool:
+    """Return True if `prev_result` = fail and `cur_result` = pass."""
+    return prev_result == "fail" and cur_result == "pass"
+
+
+# ---------------------------------------------------------------------------
+# Test command detection
+# ---------------------------------------------------------------------------
+
+
+def _tokens(command: str) -> list[str]:
+    return command.strip().split()
+
+
+def is_test_command(command: str) -> bool:
+    """Return True when `command` looks like a supported test runner invocation."""
+    tokens = _tokens(command)
+    if not tokens:
+        return False
+    head = tokens[0]
+    if head == "npm":
+        if len(tokens) >= 2 and tokens[1] == "test":
+            return True
+        return len(tokens) >= 3 and tokens[1] == "run" and tokens[2] == "test"
+    if head == "npx" and len(tokens) >= 2 and tokens[1] in {"vitest", "jest"}:
+        return True
+    if (
+        head in {"mvn", "./mvnw", "mvnw"}
+        and len(tokens) >= 2
+        and tokens[1]
+        in {
+            "test",
+            "verify",
+        }
+    ):
+        return True
+    if (
+        head in {"gradle", "./gradlew", "gradlew"}
+        and len(tokens) >= 2
+        and tokens[1] == "test"
+    ):
+        return True
+    if head == "dotnet" and len(tokens) >= 2 and tokens[1] == "test":
+        return True
+    if head == "pytest":
+        return True
+    if head in {"python", "python3"} and any("pytest" in t for t in tokens[1:]):
+        return True
+    if head == "go" and len(tokens) >= 2 and tokens[1] == "test":
+        return True
+    return head == "cargo" and len(tokens) >= 2 and tokens[1] == "test"
+
+
+# ---------------------------------------------------------------------------
+# Adapter dispatch
+# ---------------------------------------------------------------------------
+
+
+def detect_adapter(command: str) -> str:
+    """Return one of stryker | pitest | stryker-net | mutmut | none."""
+    tokens = _tokens(command)
+    if not tokens:
+        return "none"
+    head = tokens[0]
+    if head == "npm" and (
+        (len(tokens) >= 2 and tokens[1] == "test")
+        or (len(tokens) >= 3 and tokens[1] == "run" and tokens[2] == "test")
+    ):
+        return "stryker"
+    if head == "npx" and len(tokens) >= 2 and tokens[1] in {"vitest", "jest"}:
+        return "stryker"
+    if (
+        head in {"mvn", "./mvnw", "mvnw"}
+        and len(tokens) >= 2
+        and tokens[1]
+        in {
+            "test",
+            "verify",
+        }
+    ):
+        return "pitest"
+    if (
+        head in {"gradle", "./gradlew", "gradlew"}
+        and len(tokens) >= 2
+        and tokens[1] == "test"
+    ):
+        return "pitest"
+    if head == "dotnet" and len(tokens) >= 2 and tokens[1] == "test":
+        return "stryker-net"
+    if head == "pytest":
+        return "mutmut"
+    if head in {"python", "python3"}:
+        # python -m pytest, python3 -m pytest, python somefile-pytest, python -m unittest
+        for t in tokens[1:]:
+            if "pytest" in t or "unittest" in t:
+                return "mutmut"
+        return "none"
+    return "none"
+
+
+# ---------------------------------------------------------------------------
+# First changed source file — shared by pitest / stryker-net / mutmut adapters
+#
+# Each adapter needs "the first non-test source file touched by this change"
+# to scope its mutation run (target class, --mutate pattern, --paths-to-mutate).
+# The traversal (git diff --name-only HEAD, falling back to --cached) is
+# identical across adapters; only the extension set and test-name exclusion
+# differ, so those are supplied as a single predicate.
+# ---------------------------------------------------------------------------
+
+
+def first_changed_file(is_source_predicate: Callable[[str], bool]) -> str:
+    """Return the first changed file for which `is_source_predicate` is True.
+
+    Checks `git diff --name-only HEAD` first, then falls back to
+    `git diff --cached --name-only` (mirrors the bash adapters' behaviour of
+    preferring unstaged/working-tree changes over already-staged ones).
+    Returns "" when git is unavailable or no line satisfies the predicate.
+    """
+    for cmd in (
+        ["git", "diff", "--name-only", "HEAD"],
+        ["git", "diff", "--cached", "--name-only"],
+    ):
+        try:
+            proc = subprocess.run(cmd, capture_output=True, text=True, check=False)
+        except (FileNotFoundError, OSError):
+            return ""
+        for line in proc.stdout.splitlines():
+            if is_source_predicate(line):
+                return line
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# Zero-kill parsing (Stryker JSON schema, shared by stryker + stryker-net)
+# ---------------------------------------------------------------------------
+
+
+def parse_stryker_kills(report_file: Path, output_file: Path) -> str | None:
+    """Parse Stryker JSON, write zero-kills to `output_file`.
+
+    Returns None on success; returns the advisory JSON string when the report
+    is missing (mirrors bash: bash emits the advisory to stdout, callers
+    forward it). Caller writes `[]` to `output_file` in that path already so
+    the return value is only consumed for the advisory.
+    """
+    report_file = Path(report_file)
+    output_file = Path(output_file)
+    if not report_file.is_file():
+        advisory = emit_advisory(
+            f"MUTATION GATE ADVISORY: Stryker report not found at {report_file}. "
+            "Run completed without mutation gate."
+        )
+        try:
+            output_file.write_text("[]")
+        except OSError:
+            pass
+        return advisory
+
+    data = json.loads(report_file.read_text())
+    mutants = data.get("mutants", [])
+
+    killing_set = set()
+    coverage: dict[str, int] = {}
+    for mutant in mutants:
+        for t in mutant.get("killedBy", []):
+            killing_set.add(t)
+        for t in mutant.get("coveredBy", []):
+            coverage[t] = coverage.get(t, 0) + 1
+
+    zero_kills: list[dict[str, Any]] = []
+    for test in sorted(set(coverage.keys()) - killing_set):
+        zero_kills.append(
+            {
+                "name": test,
+                "file": None,
+                "line": None,
+                "covered": coverage[test],
+            }
+        )
+
+    output_file.write_text(json.dumps(zero_kills))
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Blocking-reason formatter — same output as the bash inline Python heredoc.
+# ---------------------------------------------------------------------------
+
+
+def format_blocking_reason(zero_kills_file: Path, command: str) -> str:
+    """Return the multi-line human-readable reason string for a blocked gate.
+
+    `command` is unused (kept for signature parity with bash) — the message
+    catalogs the zero-kill tests read from `zero_kills_file`.
+    """
+    with open(zero_kills_file) as f:
+        zero_kills = json.load(f)
+
+    lines = [
+        "MUTATION GATE BLOCKED: zero-kill tests detected after RED-GREEN transition",
+        "",
+        "These tests covered mutants but killed none — they provide no regression safety.",
+        "A useful assertion changes the expected value when the implementation changes",
+        "(e.g., assert result === 5, not assert result !== undefined).",
+        "Rewrite each to assert the precise return value or side effect, or remove it:",
+        "",
+    ]
+    for zk in zero_kills:
+        name = zk.get("name", "<unknown>")
+        file_ = zk.get("file") or "<unknown>"
+        line = zk.get("line")
+        loc = f"({file_}:{line})" if line else f"({file_}:<unknown>)"
+        covered = zk.get("covered", 0)
+        lines.append(f"  - {name}  {loc}")
+        lines.append(f"    Covered {covered} mutants, killed 0")
+        lines.append("")
+
+    lines.append("Fix these tests before continuing.")
+    return "\n".join(lines)

package/hooks/mutation_adapters/mutmut.py

@@ -0,0 +1,188 @@
+"""mutmut (Python) mutation-testing adapter — Python port of mutmut.sh.
+
+mutmut scopes to a single file via `--paths-to-mutate` and completes in
+seconds-to-minutes for typical Python unit test suites. mutmut has no
+`--json` results output; survivors are read from `mutmut junitxml`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from . import lib
+
+
+def mutmut_detect() -> bool:
+    """Return True when mutmut is available in this project."""
+    if shutil.which("mutmut") is not None:
+        return True
+    try:
+        # `mutmut` is a `version` subcommand, not a `--version` flag — the
+        # flag form exits nonzero on the real CLI and always reads as absent.
+        proc = subprocess.run(
+            ["python3", "-m", "mutmut", "version"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+        )
+        if proc.returncode == 0:
+            return True
+    except (FileNotFoundError, OSError):
+        pass
+    print(
+        lib.emit_advisory(
+            "MUTATION GATE ADVISORY: mutmut not installed. Run /setup to "
+            "install it, or: pip install mutmut"
+        )
+    )
+    return False
+
+
+def _derive_python_source(test_file: str) -> str:
+    """Strip test_ prefix / _test suffix from `test_file` to find the source."""
+    base = Path(test_file).stem
+    base = base.removeprefix("test_")
+    base = base.removesuffix("_test")
+    for dir_ in ("src", "", "lib"):
+        candidate = f"{dir_}/{base}.py" if dir_ else f"{base}.py"
+        if Path(candidate).is_file():
+            return candidate
+    return test_file
+
+
+def _is_python_source(line: str) -> bool:
+    """True for a non-test Python source path."""
+    if not line.endswith(".py"):
+        return False
+    return not (line.startswith("test_") or "_test.py" in line or "/test_" in line)
+
+
+def _changed_python_source() -> str:
+    return lib.first_changed_file(_is_python_source)
+
+
+def _mutmut_argv() -> list[str]:
+    """Return the argv prefix for invoking mutmut — either `mutmut` or `python3 -m mutmut`."""
+    if shutil.which("mutmut") is not None:
+        return ["mutmut"]
+    return ["python3", "-m", "mutmut"]
+
+
+def mutmut_run(output_file: Path) -> int:
+    """Run mutmut scoped to the changed Python file; write zero-kills."""
+    output_file = Path(output_file)
+    timeout_seconds = int(os.environ.get("ADAPTER_TIMEOUT", "120"))
+
+    src_file = _changed_python_source()
+
+    mutmut_prefix = _mutmut_argv()
+    mutmut_args = ["run"]
+    if src_file:
+        mutmut_args.append(f"--paths-to-mutate={src_file}")
+
+    argv = [*mutmut_prefix, *mutmut_args]
+    completed = lib.run_with_timeout(
+        timeout_seconds,
+        argv,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    exit_code = completed.returncode
+
+    if exit_code == 124:
+        hint = (
+            ""
+            if src_file
+            else " No source file detected — scope with --paths-to-mutate."
+        )
+        print(
+            lib.emit_advisory(
+                f"MUTATION GATE SKIPPED: mutmut timed out after {timeout_seconds}s.{hint}"
+                " Or: MUTATION_GATE_TIMEOUT=<seconds> to extend the limit."
+            )
+        )
+        output_file.write_text("[]")
+        return 0
+
+    # mutmut's exit code is a bitmask: 1=fatal error, 2=survived, 4=timeout,
+    # 8=slow (any combination ORs together; 0 means every mutant was
+    # killed). Bit 1 (fatal error — e.g. the baseline test run itself
+    # failed) is the only outcome that invalidates the run; survivors
+    # (bit 2) are the expected, common case and must still be parsed.
+    if exit_code & 1:
+        stderr = completed.stderr or ""
+        if "cannot pickle" in stderr and "itertools.count" in stderr:
+            hint = (
+                " Known cause: mutmut<3 crashes on Python 3.13+ "
+                "('TypeError: cannot pickle itertools.count object', a "
+                "parso/pony-ORM deepcopy incompatibility) — install mutmut "
+                "into a venv running Python <=3.12; the --runner test "
+                "command can stay on the project's real interpreter."
+            )
+        else:
+            hint = ""
+        print(
+            lib.emit_advisory(
+                f"MUTATION GATE ADVISORY: mutmut exited with code {exit_code}. "
+                f"Skipping mutation gate.{hint}"
+            )
+        )
+        output_file.write_text("[]")
+        return 0
+
+    # Read survivors from `mutmut junitxml` — mutmut's `results` subcommand
+    # has no `--json` output; junitxml is the only structured report it
+    # ships. A <testcase> with a <failure> child is a survived mutant under
+    # the default suspicious/untested policies (both "ignore").
+    try:
+        junit = subprocess.run(
+            [*mutmut_prefix, "junitxml"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        raw = junit.stdout or ""
+    except (FileNotFoundError, OSError):
+        raw = ""
+
+    try:
+        root = ET.fromstring(raw) if raw.strip() else None
+    except ET.ParseError:
+        root = None
+
+    zero_kills = []
+    if root is not None:
+        for testcase in root.iter("testcase"):
+            if testcase.find("failure") is None:
+                continue
+            line = testcase.get("line")
+            zero_kills.append(
+                {
+                    "name": f"mutant_{testcase.get('name', '?')}",
+                    "file": testcase.get("file"),
+                    "line": int(line) if line and line.isdigit() else None,
+                    "covered": 0,
+                }
+            )
+
+    output_file.write_text(json.dumps(zero_kills))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args:
+        print("mutmut.py: OUTPUT_FILE argument required", file=sys.stderr)
+        return 2
+    return mutmut_run(Path(args[0]))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())