Mutation Testing skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Mutation Testing"
  short_description: "Find the bugs your green test suite would ship"
  default_prompt: "$mutation-testing Our coverage is 90% but bugs still get through. Run mutation testing on the pricing module"

#!/usr/bin/env python3
"""List surviving mutants from a mutation testing report, grouped by file.

Supports:
  * mutation-testing-elements JSON (Stryker JS/.NET "json" reporter,
    default path reports/mutation/mutation.json, and other tools emitting that schema)
  * PIT mutations.xml (outputFormats XML)

Usage:
  python3 survivors.py <report> [--min-score N] [--limit N] [--include-no-coverage]

Exit codes: 0 = ok (score >= min-score), 1 = score below --min-score, 2 = bad input.
"""
from __future__ import annotations

import argparse
import json
import sys
import xml.etree.ElementTree as ET
from collections import defaultdict
from pathlib import Path

DETECTED = {"Killed", "Timeout"}
UNDETECTED = {"Survived", "NoCoverage"}
# Statuses excluded from the score: CompileError, RuntimeError, Ignored, Pending.


def load_mte(data: dict) -> list[dict]:
    mutants = []
    for path, f in (data.get("files") or {}).items():
        source_lines = (f.get("source") or "").splitlines()
        for m in f.get("mutants", []):
            line = m.get("location", {}).get("start", {}).get("line", 0)
            original = source_lines[line - 1].strip() if 0 < line <= len(source_lines) else ""
            mutants.append({
                "file": path,
                "line": line,
                "mutator": m.get("mutatorName", "?"),
                "detail": m.get("replacement") or m.get("description") or "",
                "original": original,
                "status": m.get("status", "?"),
            })
    return mutants


PIT_STATUS = {
    "KILLED": "Killed", "TIMED_OUT": "Timeout", "SURVIVED": "Survived",
    "NO_COVERAGE": "NoCoverage", "MEMORY_ERROR": "RuntimeError",
    "RUN_ERROR": "RuntimeError", "NON_VIABLE": "CompileError",
}


def load_pit(root: ET.Element) -> list[dict]:
    mutants = []
    for m in root.iter("mutation"):
        cls = m.findtext("mutatedClass", "")
        pkg_path = cls.rsplit(".", 1)[0].replace(".", "/") if "." in cls else ""
        src = m.findtext("sourceFile", "?")
        mutants.append({
            "file": f"{pkg_path}/{src}" if pkg_path else src,
            "line": int(m.findtext("lineNumber", "0") or 0),
            "mutator": (m.findtext("mutator", "?") or "?").rsplit(".", 1)[-1],
            "detail": m.findtext("description", "") or "",
            "original": f"in {m.findtext('mutatedMethod', '?')}()",
            "status": PIT_STATUS.get(m.get("status", ""), m.get("status", "?")),
        })
    return mutants


def load(path: Path) -> list[dict]:
    text = path.read_text(encoding="utf-8")
    stripped = text.lstrip()
    if stripped.startswith("{"):
        return load_mte(json.loads(text))
    if stripped.startswith("<"):
        return load_pit(ET.fromstring(text))
    raise ValueError("unrecognized report format (expected JSON or PIT XML)")


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    ap.add_argument("report", type=Path)
    ap.add_argument("--min-score", type=float, default=None,
                    help="fail (exit 1) if the mutation score is below this percentage")
    ap.add_argument("--limit", type=int, default=50, help="max survivors to print (default 50)")
    ap.add_argument("--include-no-coverage", action="store_true",
                    help="also list NoCoverage mutants (otherwise only counted)")
    args = ap.parse_args()

    try:
        mutants = load(args.report)
    except (OSError, ValueError, ET.ParseError) as exc:
        print(f"error: cannot read {args.report}: {exc}", file=sys.stderr)
        return 2

    counts: dict[str, int] = defaultdict(int)
    for m in mutants:
        counts[m["status"]] += 1
    detected = sum(counts[s] for s in DETECTED)
    undetected = sum(counts[s] for s in UNDETECTED)
    valid = detected + undetected
    score = 100.0 * detected / valid if valid else 100.0

    print(f"mutants: {len(mutants)}  " + "  ".join(f"{k}={v}" for k, v in sorted(counts.items()) if v))
    print(f"mutation score: {score:.1f}% ({detected}/{valid} detected)")

    wanted = {"Survived"} | ({"NoCoverage"} if args.include_no_coverage else set())
    by_file: dict[str, list[dict]] = defaultdict(list)
    for m in mutants:
        if m["status"] in wanted:
            by_file[m["file"]].append(m)

    shown = 0
    for file in sorted(by_file, key=lambda f: -len(by_file[f])):
        if shown >= args.limit:
            break
        items = sorted(by_file[file], key=lambda m: m["line"])
        print(f"\n{file}  ({len(items)} undetected)")
        for m in items:
            if shown >= args.limit:
                break
            tag = "" if m["status"] == "Survived" else " [no coverage]"
            detail = f" -> {m['detail']}" if m["detail"] else ""
            ctx = f"   | {m['original']}" if m["original"] else ""
            print(f"  L{m['line']:<5} {m['mutator']}{detail}{tag}{ctx}")
            shown += 1
    if shown >= args.limit:
        print(f"\n(output limited to {args.limit}; use --limit to see more)")

    if args.min_score is not None and score < args.min_score:
        print(f"\nFAIL: score {score:.1f}% is below --min-score {args.min_score}", file=sys.stderr)
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())