pi-dev-team 0.2.0

package/skills/mutation-testing/scripts/mutation_baseline_reuse.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""Baseline mutation-report reuse for the mutant-kill loop's Round 1 (#1545).
+
+The mutant-kill loop's per-file Round 1 always triggers a fresh scoped
+mutation run, even when a fresh baseline report (captured once, before the
+per-file loop starts) already covers that file. This module owns the
+eligibility decision and the consumption bookkeeping so a file's Round 1 can
+be safely seeded from the baseline via ``--report`` instead of paying for a
+redundant run — as real, unit-tested code, not agent-followed prose.
+
+Eligibility is a two-part test:
+  1. an **ancestor check** — is the file's last commit an ancestor of the
+     baseline's capture commit? (git itself treats a commit as its own
+     ancestor, so a file last committed exactly at the capture commit is
+     eligible too — the "self-ancestor boundary".) A file with no
+     discoverable last-commit SHA (untracked/never committed), or a
+     non-ancestor relationship, is never eligible.
+  2. a **consumption check** — has this file already consumed *this exact*
+     baseline capture commit? If so it is not eligible again until a
+     different (not-yet-consumed) baseline capture commit comes along.
+
+Concurrency (#1920): ``mark_consumed`` is the sole writer of the tracking
+file, and its read-modify-write span is serialized by
+``atomic_state.locked_state(strict=True)`` so two concurrent callers can
+never lose one another's update to the tracking FILE. ``resolve``/
+``read_tracking`` are deliberately lock-free — a stale read there can only
+under-count eligibility (miss a consumption recorded moments ago and report
+a file eligible when it is about to be marked consumed elsewhere).
+
+That serialization, on its own, does NOT guarantee a file is never
+double-consumed: two concurrent ``resolve`` calls for the SAME file would
+both observe pre-consumption state and both seed Round 1, regardless of how
+serialized ``mark_consumed``'s writes are — serialization protects the
+tracking file's integrity across *different* files' writes, not the
+ordering between one file's ``resolve`` calls and its own eventual
+``mark_consumed``. The "never double-consume" property this module relies
+on instead comes from an explicit assumption held by its callers: each file
+is resolved and consumed by at most one worker per run (the ``--all``
+fan-out assigns files disjointly across workers, so two workers never race
+on the same file to begin with).
+
+Stdlib-only. (ADR 0014/0015).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from collections.abc import Sequence
+from datetime import datetime, timezone
+from pathlib import Path
+
+import mutation_report
+
+# skills/mutation-testing/scripts -> skills/mutation-testing -> skills
+# -> plugin root -> hooks/lib
+_HOOKS_LIB_DIR = Path(__file__).resolve().parents[3] / "hooks" / "lib"
+if str(_HOOKS_LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_LIB_DIR))
+
+try:
+    import atomic_state  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover - degraded fallback, hooks/lib unreachable
+    atomic_state = None
+
+
+class _AtomicStateUnavailableError(RuntimeError):
+    """Raised by ``mark_consumed`` when ``hooks/lib``'s ``atomic_state``
+    module could not be imported — refusing to run the read-modify-write
+    cycle unlocked rather than silently proceeding without it."""
+
+
+# The exception type ``mark_consumed``'s ``except`` clause narrows to
+# (#1920 correctness review): ``atomic_state.LockAcquisitionError`` when the
+# module imported successfully, or the local fallback above when it didn't.
+# Computed once here, at import time, so the ``except`` clause itself never
+# has to attribute-access a possibly-``None`` ``atomic_state`` — evaluating
+# ``atomic_state.LockAcquisitionError`` directly inside the ``except`` tuple
+# would raise ``AttributeError`` instead of matching the real error whenever
+# ``atomic_state is None``.
+_LOCK_FAILURE_ERROR: type[Exception] = (
+    atomic_state.LockAcquisitionError
+    if atomic_state is not None
+    else _AtomicStateUnavailableError
+)
+
+
+# =============================================================================
+# Tracking file — read / decide / write
+# =============================================================================
+def read_tracking(tracking_path) -> dict:
+    """Return the parsed consumption-tracking JSON, or ``{}`` for an
+    absent, malformed, or non-dict-shaped file.
+
+    Delegates to ``mutation_report.load_report`` — this module used to
+    reimplement that function's absent/empty/malformed-JSON handling itself;
+    it now genuinely calls it, so the two stay behaviorally identical by
+    construction rather than by convention.
+    """
+    return mutation_report.load_report(tracking_path)
+
+
+def is_eligible_for_reuse(
+    tracking: dict, file_path: str, capture_commit: str, is_ancestor: bool
+) -> bool:
+    """Pure eligibility decision.
+
+    ``False`` when the file's last commit is not an ancestor of the
+    baseline's capture commit (``is_ancestor`` is the caller's already-
+    resolved git ancestor check — this function does no git work itself).
+    Otherwise ``False`` only when ``tracking`` already records ``file_path``
+    as consumed at this exact ``capture_commit``; ``True`` in every other
+    case, including a file consumed at some *other*, older baseline capture
+    commit it hasn't yet consumed.
+    """
+    if not is_ancestor:
+        return False
+    entry = tracking.get(file_path)
+    return entry is None or entry.get("capture_commit") != capture_commit
+
+
+def mark_consumed(tracking_path, file_path: str, capture_commit: str) -> dict:
+    """Atomically record ``file_path``'s consumption of ``capture_commit``.
+
+    The full read-tracking -> mutate-dict -> atomic-write sequence runs
+    inside ``atomic_state.locked_state(tracking_path, strict=True)`` (#1920),
+    so a second concurrent caller's read can never observe a state older than
+    the first caller's completed write — closing the lost-update race two
+    processes racing on the same tracking file could otherwise hit. Within
+    that lock, the write itself delegates to ``atomic_state.atomic_write(...,
+    fail_open=False)`` (#1920 review) rather than hand-rolling a second
+    ``tempfile.mkstemp``/``os.fdopen``/``os.replace`` sequence here — one
+    shared, unique-per-call-tmp-file implementation instead of two forks that
+    could drift apart, and it closes an fd-leak-on-fdopen-failure gap this
+    module's own former hand-rolled version had (``atomic_write`` guards that
+    internally now). ``fail_open=False`` makes a write failure raise instead
+    of silently no-op'ing, so it still reaches this function's own ``except``
+    below and is reported exactly as it always was.
+
+    Never raises: a write failure (permission denied, unwritable directory,
+    a monkeypatched ``os.replace`` failure, ...) *or* a failed lock
+    acquisition (``strict=True`` raises ``atomic_state.LockAcquisitionError``
+    instead of running unlocked — or the local ``_AtomicStateUnavailableError``
+    when ``atomic_state`` itself could not be imported) is caught and
+    reported as ``{"success": False, "error": str(exc)}``, leaving the
+    on-disk file (if any) untouched — the file stays recorded as
+    not-yet-consumed. ``atomic_write``'s own best-effort tmp-file cleanup
+    (unique-per-call via ``tempfile.mkstemp``, so a failed call can never
+    delete a different, still-in-flight caller's temp file) runs before the
+    OSError re-raises, so no cleanup logic is duplicated here.
+
+    ``resolve``/``read_tracking`` stay lock-free by design — see the module
+    docstring's ``Concurrency`` note for why a stale read there is safe, and
+    for the explicit assumption behind "never double-consume" (single
+    worker per file per run, not serialization alone).
+    """
+    tracking_path = Path(tracking_path)
+    try:
+        if atomic_state is None:
+            raise _AtomicStateUnavailableError(
+                "atomic_state unavailable (hooks/lib unreachable); refusing "
+                "to run mark_consumed's read-modify-write unlocked"
+            )
+        with atomic_state.locked_state(tracking_path, strict=True):
+            tracking = read_tracking(tracking_path)
+            tracking[file_path] = {
+                "capture_commit": capture_commit,
+                "recorded_at": datetime.now(timezone.utc)
+                .isoformat()
+                .replace("+00:00", "Z"),
+            }
+            atomic_state.atomic_write(
+                tracking_path, json.dumps(tracking, indent=2), fail_open=False
+            )
+    except (OSError, _LOCK_FAILURE_ERROR) as exc:
+        return {"success": False, "error": str(exc)}
+    return {"success": True}
+
+
+# =============================================================================
+# Git-backed ancestor check
+# =============================================================================
+def _run_git(args: list[str], *, cwd=None) -> subprocess.CompletedProcess | None:
+    """Run a git subcommand, returning ``None`` on a missing git binary, a
+    non-repo ``cwd``, or a 30s timeout — never raises."""
+    try:
+        return subprocess.run(
+            args,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=30,
+        )
+    except (OSError, FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+
+
+def _git_last_commit_sha(file_path, *, cwd=None) -> str | None:
+    """Return ``file_path``'s last-commit SHA, or ``None`` when git is
+    unavailable (missing binary, not a repo, timeout) or the file has no
+    commit history at all (empty ``git log`` result — untracked/never
+    committed). Never raises."""
+    result = _run_git(
+        ["git", "log", "-1", "--format=%H", "--", str(file_path)], cwd=cwd
+    )
+    if result is None:
+        return None
+    sha = result.stdout.strip()
+    return sha or None
+
+
+def _git_is_ancestor(commit_a: str, commit_b: str, *, cwd=None) -> bool:
+    """True when ``commit_a`` is an ancestor of (or equal to) ``commit_b``
+    (``git merge-base --is-ancestor``). ``False`` when git is unavailable
+    (missing binary, not a repo, timeout) rather than letting the exception
+    propagate. Never raises."""
+    result = _run_git(
+        ["git", "merge-base", "--is-ancestor", "--", commit_a, commit_b], cwd=cwd
+    )
+    if result is None:
+        return False
+    return result.returncode == 0
+
+
+# =============================================================================
+# CLI — resolve / mark-consumed
+# =============================================================================
+def _resolve(args) -> dict:
+    tracking = read_tracking(args.tracking)
+    last_commit = _git_last_commit_sha(args.file, cwd=args.cwd)
+    is_ancestor = (
+        _git_is_ancestor(last_commit, args.capture_commit, cwd=args.cwd)
+        if last_commit is not None
+        else False
+    )
+    eligible = is_eligible_for_reuse(
+        tracking, args.file, args.capture_commit, is_ancestor
+    )
+    return {
+        "eligible": eligible,
+        "file": args.file,
+        "capture_commit": args.capture_commit,
+    }
+
+
+def _mark_consumed(args) -> dict:
+    return mark_consumed(args.tracking, args.file, args.capture_commit)
+
+
+def _cli(argv: Sequence[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Resolve baseline-reuse eligibility, or mark a file's "
+        "consumption of a baseline capture commit."
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    parent_parser = argparse.ArgumentParser(add_help=False)
+    parent_parser.add_argument("--file", required=True)
+    parent_parser.add_argument("--capture-commit", required=True)
+    parent_parser.add_argument("--tracking", required=True)
+
+    resolve_parser = sub.add_parser(
+        "resolve",
+        help="resolve whether a file may reuse the baseline report",
+        parents=[parent_parser],
+    )
+    resolve_parser.add_argument("--cwd", default=None)
+
+    sub.add_parser(
+        "mark-consumed",
+        help="record a file's consumption of a baseline",
+        parents=[parent_parser],
+    )
+
+    args = parser.parse_args(list(argv))
+
+    if args.command == "resolve":
+        payload = _resolve(args)
+    else:
+        payload = _mark_consumed(args)
+
+    print(json.dumps(payload))
+    # Exit 0 either way — advisory/informational, matching
+    # mutation_feasibility_gate.py's "advisory arbiter, not a gate" convention.
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(_cli(sys.argv[1:]))

package/skills/mutation-testing/scripts/mutation_exclude_policy.py

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""mutation_exclude_policy.py — committed, human-approved mutation
+exclude-policy bootstrap (#1757).
+
+`mutation-kill`'s "Infrastructure exclusion detection"
+(agents/mutation-kill.md) already flags likely-infrastructure files at run
+time — DI wiring, exception handlers, middleware, generated code — but its
+decision persists only to a typically-gitignored build-output path
+(`StrykerOutput/mutation-kill-convergence.json`), so it's lost across a
+fresh clone or a new CI runner. This module drafts the SAME two-signal
+judgment as a standalone, committed, source-controlled policy file instead —
+durable across machines.
+
+**Never writes the committed policy file without human approval.** This is
+the one hard constraint the whole module exists to satisfy: an unattended
+night-watch run can *draft* a proposal (``draft_policy`` + a plain
+``write_json`` to any path the caller chooses), but the ONLY code path that
+writes ``mutation-exclude-policy.json`` at the repo root is :func:`approve`,
+invoked deliberately via ``--approve`` — never called from
+``mutation_nightwatch.py``'s unattended loop.
+
+Two-signal rule, ported verbatim from `mutation-kill`'s own "Infrastructure
+exclusion detection" section — BOTH must hold before a file is even
+considered; neither alone is sufficient:
+
+- ``honest score < 15%``
+- ``NoCoverage > 50%`` of effective mutants (killed + survived + no_coverage)
+
+A filename match against a known DI/wiring/generated-code naming convention
+is a **hint that strengthens the tier**, never a requirement: it promotes a
+flagged file from ``propose_and_ask`` to ``always``, but its absence never
+blocks the numeric signals from flagging a file in the first place — mirrors
+`mutation-kill.md`'s "named convention vs. signal-only" framing exactly.
+
+Stdlib-only. See ADR 0014.
+"""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import json
+import sys
+from enum import Enum
+from pathlib import Path
+
+import mutation_report
+
+POLICY_FILENAME = "mutation-exclude-policy.json"
+
+
+class ExclusionTier(str, Enum):
+    """The two mutation exclude-policy tiers a flagged file can land in
+    (issue #1904 item 4) — a closed vocabulary previously carried as bare
+    string literals (`"always"`/`"propose_and_ask"`) compared with `==`, so
+    a typo silently read as "not the always tier" rather than failing
+    loudly. `str, Enum` — deliberately NOT `coverage_config.TestClassification`'s
+    convention, which is a plain `Enum` chosen so an accidental attempt to
+    JSON-serialize it fails loudly instead of silently succeeding. This
+    enum diverges on purpose: its values ARE meant to serialize to JSON
+    (`write_json`/`draft_policy`'s output) and to keep matching existing
+    bare-string `== "always"`-style call sites, so the `str` mixin is the
+    correct choice here, not a mirrored one."""
+
+    ALWAYS = "always"
+    PROPOSE_AND_ASK = "propose_and_ask"
+
+# Ported verbatim from agents/mutation-kill.md's "Infrastructure exclusion
+# detection" section — the single source of truth for these two numbers.
+SCORE_THRESHOLD_PCT = 15.0
+NO_COVERAGE_THRESHOLD_PCT = 50.0
+
+# Filename hints per stack. The C# list is copied verbatim from
+# mutation-kill.md; the javascript list is a parallel, analogous set for a
+# second stack mutation_report.py can already score — see SUPPORTED_STACKS
+# in mutation_nightwatch_stacks.py.
+#
+# Coverage is intentionally partial. ``"csharp"`` and ``"javascript"`` have
+# curated filename hints today; ``"python"``, ``"java"``, and ``"go"`` — all
+# recognized by mutation_nightwatch_stacks.py's STACK_DETECTORS/MEASURERS —
+# do not yet. That is not an oversight: a file flagged for one of those
+# stacks by the two-signal rule alone still lands in the ``propose_and_ask``
+# tier (never dropped), it just never gets promoted to ``always`` until
+# someone writes its filename-hint list. See KNOWN_STACKS_WITHOUT_HINTS
+# below, which makes that gap explicit rather than indistinguishable from a
+# typo'd/unrecognized stack name (#1854).
+FILENAME_HINTS: dict[str, list[str]] = {
+    "csharp": [
+        "Startup.cs",
+        "Program.cs",
+        "*Filter.cs",
+        "*Middleware.cs",
+        "*Logger*.cs",
+        "*HealthCheck*.cs",
+        "*.Designer.cs",
+        "*Module.cs",
+        "*Container.cs",
+        "*Registration.cs",
+        "*Bootstrap*.cs",
+        "*DependencyInjection*.cs",
+    ],
+    "javascript": [
+        "main.ts",
+        "main.js",
+        "*.module.ts",
+        "*.config.js",
+        "*.config.ts",
+        "*Middleware.ts",
+        "*Logger*.ts",
+        "*Container.ts",
+    ],
+}
+
+# Stacks recognized by mutation_nightwatch_stacks.py that deliberately have
+# no curated FILENAME_HINTS entry yet (not written, not a typo). A stack in
+# neither this set nor FILENAME_HINTS is genuinely unknown — see
+# _matching_hint below.
+KNOWN_STACKS_WITHOUT_HINTS: frozenset[str] = frozenset({"python", "java", "go"})
+
+
+def _matching_hint(filename: str, stack: str) -> str | None:
+    """Return the first filename-hint pattern that matches, or ``None``.
+
+    Raises ``ValueError`` when ``stack`` is neither in ``FILENAME_HINTS`` nor
+    ``KNOWN_STACKS_WITHOUT_HINTS`` — a genuinely unrecognized/typo'd stack
+    name must surface loudly rather than silently returning no hints (#1854).
+    """
+    if stack not in FILENAME_HINTS and stack not in KNOWN_STACKS_WITHOUT_HINTS:
+        raise ValueError(
+            f"unknown stack: {stack!r} (known: "
+            f"{sorted(set(FILENAME_HINTS) | KNOWN_STACKS_WITHOUT_HINTS)})"
+        )
+    for pattern in FILENAME_HINTS.get(stack, ()):
+        if fnmatch.fnmatch(filename, pattern):
+            return pattern
+    return None
+
+
+def draft_entries(report_path: Path, stack: str) -> list[dict]:
+    """Apply the two-signal rule to every file in `report_path`'s native
+    report, returning one ``{file, stack, tier, reason}`` entry per flagged
+    file. A file with zero effective mutants (killed+survived+no_coverage)
+    yields no scoring signal and is never flagged."""
+    data = mutation_report.load_report(report_path)
+    entries = []
+    for file_key in sorted(data.get("files", {})):
+        summary = mutation_report.score_report_for_file(report_path, file_key)
+        effective = summary.killed + summary.survived + summary.no_coverage
+        if effective == 0:
+            continue
+        no_coverage_pct = (summary.no_coverage / effective) * 100
+        # Both signals must hold — failing either alone must never flag.
+        if summary.honest_score >= SCORE_THRESHOLD_PCT:
+            continue
+        if no_coverage_pct <= NO_COVERAGE_THRESHOLD_PCT:
+            continue
+
+        hint = _matching_hint(Path(file_key).name, stack)
+        if hint:
+            tier = ExclusionTier.ALWAYS
+            reason = (
+                f"named convention: {hint} (score {summary.honest_score:.1f}%, "
+                f"NoCoverage {no_coverage_pct:.1f}%)"
+            )
+        else:
+            tier = ExclusionTier.PROPOSE_AND_ASK
+            reason = (
+                f"signal-only: score {summary.honest_score:.1f}%, NoCoverage "
+                f"{no_coverage_pct:.1f}% (no filename match)"
+            )
+        entries.append({"file": file_key, "stack": stack, "tier": tier, "reason": reason})
+    return entries
+
+
+def draft_policy(report_paths: dict[str, Path]) -> dict:
+    """Draft a two-tier exclude policy from one native report per stack.
+
+    ``report_paths`` maps stack name -> native report path. A stack with no
+    on-disk native report path (mutmut/python — see
+    ``mutation_nightwatch_stacks.StackResult.report_path``'s docstring) is
+    simply absent from the mapping; it is never guessed at.
+    """
+    always: list[dict] = []
+    propose_and_ask: list[dict] = []
+    for stack, report_path in sorted(report_paths.items()):
+        for entry in draft_entries(report_path, stack):
+            (always if entry["tier"] == ExclusionTier.ALWAYS else propose_and_ask).append(entry)
+    return {
+        "schema_version": 1,
+        ExclusionTier.ALWAYS.value: always,
+        ExclusionTier.PROPOSE_AND_ASK.value: propose_and_ask,
+    }
+
+
+def write_json(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def approve(draft_path: Path, repo_root: Path) -> Path:
+    """Write the approved draft as the committed policy file at
+    `repo_root`. The ONLY code path that writes `POLICY_FILENAME` at the
+    repo root — see the module docstring's approval-gate constraint."""
+    draft = json.loads(draft_path.read_text(encoding="utf-8"))
+    policy_path = repo_root / POLICY_FILENAME
+    write_json(policy_path, draft)
+    return policy_path
+
+
+def parse_args(argv) -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="mutation_exclude_policy.py",
+        description=(
+            "Draft (never auto-write) a two-tier mutation exclude policy from "
+            "native mutation reports; write the committed policy file only "
+            "on --approve."
+        ),
+    )
+    p.add_argument(
+        "--report",
+        action="append",
+        default=[],
+        metavar="STACK=PATH",
+        help="One native report path per stack, e.g. "
+        "javascript=reports/mutation/mutation.json. Repeatable.",
+    )
+    p.add_argument("--draft", action="store_true", help="Draft mode.")
+    p.add_argument("--out", help="Where to write the draft (--draft mode).")
+    p.add_argument(
+        "--approve", metavar="DRAFT_PATH", help="Approve a draft, writing the committed policy file."
+    )
+    p.add_argument(
+        "--repo-root", default=".", help="Repo root (--approve mode; default: cwd)"
+    )
+    return p.parse_args(list(argv))
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    args = parse_args(argv)
+
+    if args.approve:
+        policy_path = approve(Path(args.approve), Path(args.repo_root).resolve())
+        print(f"approved: wrote {policy_path}")
+        return 0
+
+    if args.draft:
+        if not args.out:
+            sys.stderr.write("error: --draft requires --out\n")
+            return 2
+        report_paths = {}
+        for item in args.report:
+            if "=" not in item:
+                sys.stderr.write(f"error: --report must be STACK=PATH, got {item!r}\n")
+                return 2
+            stack, _, path_str = item.partition("=")
+            report_paths[stack] = Path(path_str)
+        policy = draft_policy(report_paths)
+        write_json(Path(args.out), policy)
+        print(f"drafted: wrote {args.out}")
+        return 0
+
+    sys.stderr.write("error: pass --draft or --approve\n")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())