jitcatch 0.2.0__py3-none-any.whl

jitcatch/assessors/rules.py

@@ -0,0 +1,343 @@
+"""RubFake-style rule-based assessor.
+
+Implements the false-positive patterns (paper Table 2) and true-positive patterns (Table 3) as
+deterministic checks over three sources: the code change, the generated test, and the execution
+log of the test on the changed revision. Output is a score in [-1, 1].
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Callable
+
+from ..models import AssessorScore, GeneratedTest, Intent
+from . import failure_parse as fp
+
+FP_LIKELIHOOD = {"high": -1.0, "medium": -0.6, "low": -0.3}
+
+
+@dataclass
+class RuleInput:
+    test: GeneratedTest
+    output: str                 # execution log on the changed revision
+    patch: str                  # diff for the target file (falls back to the whole change)
+    intent: Intent | None
+    title: str
+    language: str
+
+    @property
+    def code(self) -> str:
+        return self.test.code
+
+    @property
+    def changed(self) -> list[str]:
+        return fp.changed_lines(self.patch)
+
+    @property
+    def changed_text(self) -> str:
+        return "\n".join(self.changed)
+
+
+@dataclass
+class Rule:
+    name: str
+    kind: str          # "fp" or "tp"
+    level: str         # fp: high/medium/low ; tp: score as string-able float
+    sources: str
+    check: Callable[[RuleInput], str | None]   # returns evidence string when the pattern applies
+
+
+def _search(rx: str, text: str, flags: int = 0) -> str | None:
+    m = re.search(rx, text, flags)
+    return m.group(0)[:200] if m else None
+
+
+# --------------------------------------------------------------------------------------
+# False-positive patterns (Table 2)
+# --------------------------------------------------------------------------------------
+
+def _broken_test_runner(r: RuleInput) -> str | None:
+    if r.test.head_run is not None and r.test.head_run.outcome.value == "infra":
+        return "test runner reported an infrastructure outcome"
+    return _search(r"INTERNALERROR|Test runner .* crashed|Could not find or load main class|"
+                   r"jest-worker|worker process has failed to exit|Error: spawn .* ENOENT|"
+                   r"Unable to start the daemon|OutOfMemoryError", r.output)
+
+
+def _reflection(r: RuleInput) -> str | None:
+    return _search(r"\bgetDeclared(Field|Method|Constructor)s?\(|setAccessible\(true\)|\breflect\.\w+|"
+                   r"\binspect\.(getsource|getmembers|signature)|\b__dict__\b|object\.__setattr__|"
+                   r"Reflect\.(get|set|ownKeys)|Object\.getOwnPropertyNames|_[A-Z]\w*__\w+", r.code)
+
+
+def _type_mismatch(r: RuleInput) -> str | None:
+    return _search(r"TypeError: .*(takes \d+ positional|missing \d+ required|unexpected keyword argument|"
+                   r"positional arguments? but)|error TS(2345|2322|2554|2339|2741|2353)|incompatible types|"
+                   r"cannot be applied to given types|method .* in class .* cannot be applied|"
+                   r"cannot use .* as .* (value|type)|(too many|not enough) arguments in call", r.output)
+
+
+def _bad_mock_smell(r: RuleInput) -> str | None:
+    if not re.search(r"\b(Mock|MagicMock|patch\(|monkeypatch|jest\.(fn|mock|spyOn)|vi\.(fn|mock|spyOn)|"
+                     r"Mockito|mock\(|gomock|testify/mock)", r.code):
+        return None
+    return _search(r"(Mock|mock)\w*.{0,80}(Error|Exception|not callable|has no attribute|undefined)|"
+                   r"(Error|Exception).{0,80}\b(Mock|mock)\w*", r.output)
+
+
+def _mock_broken(r: RuleInput) -> str | None:
+    return _search(r"UnnecessaryStubbing|WrongTypeOfReturnValue|InvalidUseOfMatchers|"
+                   r"MissingMethodInvocation|mockImplementation is not a function|"
+                   r"vi\.mock.*hoist|jest\.mock\(\) .* not allowed to reference|"
+                   r"AttributeError: Mock object has no attribute|missing call\(s\) to|"
+                   r"Unexpected call to \*mock|aborting test due to missing call", r.output)
+
+
+def _data_provider_broken(r: RuleInput) -> str | None:
+    return _search(r"ParameterResolutionException|PreconditionViolationException.*(MethodSource|ValueSource)|"
+                   r"In (test_\w+|\w+): function uses no argument|parametrize.*(wrong|got)|"
+                   r"each\(\) .* (must|expects)|\.each is not a function|Invalid parametrize", r.output)
+
+
+def _should_be_private(r: RuleInput) -> str | None:
+    if r.language == "python":
+        m = re.search(r"\.\_(?!_)[a-z]\w*", r.code)
+        if m and re.search(r"AttributeError|has no attribute", r.output):
+            return f"test touches private member {m.group(0)}"
+        return None
+    return _search(r"error TS2341|has private access|is private and only accessible|"
+                   r"cannot refer to unexported", r.output)
+
+
+def _must_be_protected(r: RuleInput) -> str | None:
+    return _search(r"error TS2445|has protected access|is protected and only accessible", r.output)
+
+
+def _not_implemented(r: RuleInput) -> str | None:
+    hit = _search(r"NotImplementedError|UnsupportedOperationException|[Nn]ot implemented|TODO: implement|"
+                  r"panic: (not implemented|unimplemented)", r.output)
+    if hit and re.search(r"NotImplemented|UnsupportedOperation|not implemented|unimplemented", r.changed_text, re.I):
+        return hit
+    return None
+
+
+def _key_value_pair_change(r: RuleInput) -> str | None:
+    for c in fp.comparisons(r.output):
+        if fp.same_elements_different_order(c.actual, c.expected):
+            return f"same elements, different order: {c.actual[:80]} vs {c.expected[:80]}"
+    return _search(r"Compared values (have no visual difference|serialize to the same structure)|"
+                   r"Received: serializes to the same string", r.output)
+
+
+def _undefined_variable(r: RuleInput) -> str | None:
+    return _search(r"NameError: name '\w+' is not defined|ReferenceError: \w+ is not defined|"
+                   r"error: cannot find symbol|undefined: \w+|error TS2304|"
+                   r"ImportError: cannot import name|has no exported member|is not exported by|"
+                   r"SyntaxError: The requested module .* does not provide an export", r.output)
+
+
+def _expecting_calls(r: RuleInput) -> str | None:
+    code_hit = re.search(r"assert_called(_once)?(_with)?|assert_not_called|call_count|call_args|"
+                         r"toHaveBeenCalled(Times|With)?|toBeCalled(Times|With)?|verify\(.*times\(|"
+                         r"\.Times\(\d+\)|AssertNumberOfCalls|AssertCalled", r.code)
+    if not code_hit:
+        return None
+    return _search(r"(Expected|expected) .{0,40}(call|called|invocation)|call_count|Number of calls|"
+                   r"Wanted but not invoked|Too (many|few) actual invocations|toHaveBeenCalled|"
+                   r"Expected number of calls|assert_called", r.output)
+
+
+def _web_server_down(r: RuleInput) -> str | None:
+    return _search(r"ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|Connection refused|ConnectionError|"
+                   r"Max retries exceeded with url|getaddrinfo|dial tcp|503 Service Unavailable|"
+                   r"502 Bad Gateway|socket hang up|UnknownHostException|ConnectException", r.output)
+
+
+def _flakiness(r: RuleInput) -> str | None:
+    if r.test.is_flaky:
+        return "test outcome differed across reruns"
+    return _search(r"\b(time\.sleep|random\.|uuid\.uuid4|datetime\.now|Date\.now|new Date\(\)|Math\.random|"
+                   r"setTimeout|Thread\.sleep|System\.currentTimeMillis|time\.Now\(|rand\.)", r.code)
+
+
+FP_RULES: list[Rule] = [
+    Rule("broken_test_runner", "fp", "high", "execution log", _broken_test_runner),
+    Rule("reflection", "fp", "high", "test code", _reflection),
+    Rule("type_mismatch", "fp", "high", "execution log", _type_mismatch),
+    Rule("bad_mock_smell", "fp", "medium", "execution log, test code", _bad_mock_smell),
+    Rule("should_be_private_smell", "fp", "high", "execution log, test code", _should_be_private),
+    Rule("method_must_be_protected_smell", "fp", "high", "execution log", _must_be_protected),
+    Rule("mock_broken", "fp", "high", "execution log", _mock_broken),
+    Rule("data_provider_broken", "fp", "high", "execution log", _data_provider_broken),
+    Rule("not_implemented_exception", "fp", "high", "execution log, change", _not_implemented),
+    Rule("key_value_pair_change", "fp", "high", "execution log", _key_value_pair_change),
+    Rule("undefined_variable", "fp", "high", "execution log", _undefined_variable),
+    Rule("expecting_particular_calls_to_functions", "fp", "high", "execution log, test code", _expecting_calls),
+    Rule("web_server_down", "fp", "high", "execution log", _web_server_down),
+    Rule("flakiness", "fp", "low", "execution log, test code", _flakiness),
+]
+
+
+# --------------------------------------------------------------------------------------
+# True-positive patterns (Table 3). Each requires an execution-trace sign plus corroboration
+# that the change did not obviously intend the observed behaviour.
+# --------------------------------------------------------------------------------------
+
+def _unexpected_key_change(r: RuleInput) -> str | None:
+    for name, msg in fp.exceptions(r.output):
+        if name in ("KeyError", "IndexError", "ArrayIndexOutOfBoundsException", "IndexOutOfBoundsException",
+                    "NoSuchElementException") or (name == "runtime error" and "index out of range" in msg):
+            key = msg.strip("'\"") if msg else ""
+            if key and key in r.changed_text:
+                return None
+            if re.search(r"\b(key|keys|index|idx)\b", r.changed_text) and not key:
+                return None
+            return f"{name}: {msg}"[:200]
+    m = re.search(r"Cannot read propert(?:y|ies) of undefined \(reading '([^']+)'\)", r.output)
+    if m and m.group(1) not in r.changed_text:
+        return m.group(0)
+    return None
+
+
+def _empty_container(r: RuleInput) -> str | None:
+    for c in fp.comparisons(r.output):
+        if fp.is_empty_container(c.actual) and not fp.is_empty_container(c.expected):
+            if re.search(r"\.clear\(\)|=\s*(\[\]|\{\}|new (ArrayList|HashMap)|make\(|set\(\)|list\(\)|dict\(\))|"
+                         r"\.filter\(|\bdelete\b|\.pop\(|\.remove\(", r.changed_text):
+                return None
+            return f"container became empty: expected {c.expected[:80]}"
+    return None
+
+
+def _create_failure(r: RuleInput) -> str | None:
+    hit = _search(r"InstantiationException|is not a constructor|__init__\(\) (missing|got|takes)|"
+                  r"cannot instantiate|Can't instantiate|NoSuchMethodException: .*<init>|"
+                  r"could not (create|construct)", r.output)
+    if hit and not re.search(r"def __init__|constructor\s*\(|\bclass\s+\w+|func New\w*\(|public \w+\(", r.changed_text):
+        return hit
+    return None
+
+
+def _changed_bool(r: RuleInput) -> str | None:
+    for c in fp.comparisons(r.output):
+        a, e = fp.as_bool(c.actual), fp.as_bool(c.expected)
+        if a is not None and e is not None and a != e:
+            return f"boolean flipped: expected {c.expected}, got {c.actual}"
+    return None
+
+
+def _kind(r: RuleInput) -> str:
+    return (r.intent.change_kind if r.intent else "") or ""
+
+
+_REFACTOR_TITLE = re.compile(r"\b(refactor|rename|restructure|cleanup|clean up|tidy|reorganis|reorganiz|"
+                             r"extract|simplif|no functional change|nfc|move)\w*", re.I)
+_DEAD_CODE_TITLE = re.compile(r"\b(remove|delete|drop)\w*\b.*\b(unused|dead|obsolete|deprecated)\b", re.I)
+_ADDITIVE_TITLE = re.compile(r"\b(add|introduce|log|logging|metric|telemetry|instrument)\w*", re.I)
+
+
+def _behaviour_failure(r: RuleInput) -> bool:
+    """Failure is a behaviour difference (assertion/runtime), not a build error."""
+    return r.test.head_run is not None and r.test.head_run.outcome.value == "fail"
+
+
+def _refactor(r: RuleInput) -> str | None:
+    if _behaviour_failure(r) and (_kind(r) == "refactor" or _REFACTOR_TITLE.search(r.title or "")):
+        return "behaviour changed in a change intended as a refactoring"
+    return None
+
+
+def _dead_code_removal(r: RuleInput) -> str | None:
+    if _behaviour_failure(r) and (_kind(r) == "dead_code_removal" or _DEAD_CODE_TITLE.search(r.title or "")):
+        return "behaviour changed in a change intended as dead-code removal"
+    return None
+
+
+def _null_value(r: RuleInput) -> str | None:
+    for c in fp.comparisons(r.output):
+        if fp.is_null(c.actual) and not fp.is_null(c.expected):
+            if re.search(r"\breturn\s+(None|null|nil|undefined)\b|=\s*(None|null|nil|undefined)\b|\?\.", r.changed_text):
+                return None
+            return f"value became null: expected {c.expected[:80]}"
+    hit = _search(r"NullPointerException|'NoneType' object|nil pointer dereference|"
+                  r"Cannot read propert(?:y|ies) of null", r.output)
+    if hit and not re.search(r"\b(None|null|nil)\b", r.changed_text):
+        return hit
+    return None
+
+
+def _monotonic_change(r: RuleInput) -> str | None:
+    if not _behaviour_failure(r):
+        return None
+    if _kind(r) == "additive" or (_ADDITIVE_TITLE.search(r.title or "") and not re.search(r"\bfix", r.title or "", re.I)):
+        return "existing behaviour changed in a change intended only to add behaviour"
+    return None
+
+
+def _rbac(r: RuleInput) -> str | None:
+    hit = _search(r"\b(permission|forbidden|unauthori[sz]ed|access denied|not allowed|role|403|401|acl|rbac)\b",
+                  r.output, re.I)
+    if hit and not re.search(r"\b(permission|role|acl|rbac|authori[sz]|access|allow|deny)\w*", r.changed_text, re.I):
+        return hit
+    return None
+
+
+TP_RULES: list[Rule] = [
+    Rule("unexpected_key_change", "tp", "0.6", "execution log, change", _unexpected_key_change),
+    Rule("empty_container", "tp", "0.6", "execution log, change", _empty_container),
+    Rule("create_failure", "tp", "0.6", "execution log, change", _create_failure),
+    Rule("changed_bool", "tp", "0.4", "execution log", _changed_bool),
+    Rule("refactor", "tp", "0.7", "execution log, intent", _refactor),
+    Rule("dead_code_removal", "tp", "0.7", "execution log, intent", _dead_code_removal),
+    Rule("null_value", "tp", "0.6", "execution log, change", _null_value),
+    Rule("monotonic_change", "tp", "0.6", "execution log, intent", _monotonic_change),
+    Rule("RBAC", "tp", "0.6", "execution log, change", _rbac),
+]
+
+
+def ease_of_dismissal(r: RuleInput) -> float:
+    """Small bonus for failures that are quick for an author to confirm/dismiss (paper §5.1):
+    short scalar comparisons are cheap; large structure diffs are expensive."""
+    comps = fp.comparisons(r.output)
+    if not comps:
+        return 0.0
+    longest = max(len(c.actual) + len(c.expected) for c in comps)
+    if longest <= 40:
+        return 0.1
+    if longest >= 400:
+        return -0.1
+    return 0.0
+
+
+def assess(r: RuleInput, overrides: dict[str, str] | None = None) -> AssessorScore:
+    overrides = overrides or {}
+    fp_hits, tp_hits = [], []
+    for rule in FP_RULES:
+        level = overrides.get(rule.name, rule.level)
+        if level == "off":
+            continue
+        ev = rule.check(r)
+        if ev:
+            fp_hits.append({"rule": rule.name, "level": level, "evidence": ev, "sources": rule.sources})
+    for rule in TP_RULES:
+        if overrides.get(rule.name) == "off":
+            continue
+        ev = rule.check(r)
+        if ev:
+            tp_hits.append({"rule": rule.name, "strength": float(overrides.get(rule.name, rule.level)),
+                            "evidence": ev, "sources": rule.sources})
+    fp_score = min((FP_LIKELIHOOD[h["level"]] for h in fp_hits), default=0.0)
+    tp_score = max((h["strength"] for h in tp_hits), default=0.0)
+    if fp_score <= -1.0:
+        score = -1.0
+    elif not fp_hits and not tp_hits:
+        score = None     # no information
+    else:
+        score = tp_score + fp_score
+        if tp_hits:
+            score += ease_of_dismissal(r)
+        score = max(-1.0, min(1.0, round(score, 3)))
+    return AssessorScore(name="rules", score=score, details={
+        "false_positive_patterns": fp_hits, "true_positive_patterns": tp_hits,
+        "high_fp": any(h["level"] == "high" for h in fp_hits),
+    })

jitcatch/cli.py

@@ -0,0 +1,338 @@
+"""Command-line interface."""
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+from .adapters import build_adapters
+from .config import ConfigError, load_config
+from .engine import Engine, RunResult
+from .gitutil import GitError, auto_range, change_context, ensure_excluded, repo_root
+from .llm import LLMError, build_client
+from .report import markdown, to_dict, write_artifacts
+from .templates import CONFIG_TEMPLATE
+
+log = logging.getLogger("jitcatch")
+
+
+def _setup_logging(verbose: int) -> None:
+    level = logging.WARNING if verbose < 0 else logging.INFO if verbose == 0 else logging.DEBUG
+    logging.basicConfig(level=level, format="[jitcatch] %(message)s", stream=sys.stderr)
+
+
+def _clients(cfg):
+    roles = cfg.roles
+    gen_name = roles.get("generator")
+    if not gen_name:
+        if len(cfg.providers) == 1:
+            gen_name = next(iter(cfg.providers))
+        else:
+            raise ConfigError("set [roles] generator = \"<provider name>\" (or define exactly one provider)")
+    generator = build_client(cfg.providers[gen_name])
+    judge_names = list(roles.get("judges") or []) or [gen_name]
+    judges = [build_client(cfg.providers[n]) for n in judge_names]
+    lp = roles.get("logprob_judge")
+    return generator, judges, (build_client(cfg.providers[lp]) if lp else None)
+
+
+def _check_keys(cfg) -> list[str]:
+    missing = []
+    for p in cfg.providers.values():
+        if p.api_key_env and not p.resolve_api_key():
+            missing.append(f"{p.name}: no API key ({p.api_key_env} is not set and none is saved; "
+                           "run `jitcatch setup`)")
+    return missing
+
+
+def run_pipeline(repo: Path, base: str, head: str, cfg, title: str = "", description: str = "",
+                 force: bool = False) -> RunResult:
+    ctx = change_context(repo, base, head, title, description)
+    generator, judges, lp = _clients(cfg)
+    used = {generator.name, *(j.name for j in judges), *([lp.name] if lp else [])}
+    problems = [m for m in _check_keys(cfg) if m.split(":")[0] in used]
+    if problems:
+        raise ConfigError("; ".join(problems))
+    adapters = build_adapters(cfg.adapters, repo)
+    return Engine(cfg, repo, ctx, generator, judges, lp, adapters, force=force).run()
+
+
+def _emit(result: RunResult, cfg, args) -> int:
+    run_dir = write_artifacts(result, cfg.output_dir())
+    md = markdown(result)
+    if getattr(args, "markdown", None):
+        Path(args.markdown).write_text(md, encoding="utf-8")
+    if getattr(args, "json", None):
+        Path(args.json).write_text(json.dumps(to_dict(result), indent=2), encoding="utf-8")
+    if not getattr(args, "quiet", False):
+        print(md)
+    print(f"[jitcatch] artifacts: {run_dir}", file=sys.stderr)
+    return 1 if (getattr(args, "fail_on_catch", False) and result.candidates()) else 0
+
+
+# ---------------------------------------------------------------------------- commands
+
+def _ready_config(repo: Path, args):
+    """Load the config, running the (at most 3-question) first-time setup if something is missing."""
+    from .userconfig import ensure_setup
+    return ensure_setup(lambda: load_config(repo, Path(args.config) if args.config else None))
+
+
+def _exclude_output(repo: Path, cfg) -> None:
+    try:
+        rel = cfg.output_dir().resolve().relative_to(repo.resolve())
+    except ValueError:
+        return  # output outside the repository
+    try:
+        ensure_excluded(repo, rel.as_posix().rstrip("/") + "/")
+    except (GitError, OSError):
+        pass
+
+
+def cmd_run(args) -> int:
+    repo = repo_root(Path(args.repo).resolve())
+    cfg = _ready_config(repo, args)
+    _exclude_output(repo, cfg)
+    title = args.title or ""
+    if args.base is None:
+        base, head, what = auto_range(repo)
+        print(f"[jitcatch] testing {what}", file=sys.stderr)
+        if head != "HEAD" and not title:
+            title = "Uncommitted changes"
+    else:
+        base, head = args.base, args.head
+    result = run_pipeline(repo, base, head, cfg, title, args.description or "", args.force)
+    return _emit(result, cfg, args)
+
+
+def cmd_setup(args) -> int:
+    from .userconfig import user_config_path
+    repo_dir = Path(args.repo).resolve()
+    if args.reset and user_config_path().exists():
+        user_config_path().unlink()
+    try:
+        repo = repo_root(repo_dir)
+    except GitError:
+        repo = repo_dir  # setup is per user; a repository is not required
+    cfg = _ready_config(repo, args)
+    gen = cfg.roles.get("generator") or next(iter(cfg.providers))
+    p = cfg.providers[gen]
+    print(f"jitcatch is set up: {p.name} ({p.model}). Run `jitcatch` inside a git project; "
+          "`jitcatch setup --reset` to change provider or model.")
+    return 0
+
+
+def cmd_github(args) -> int:
+    from .github import GitHubAPI, read_event, set_output, write_step_summary
+    repo = repo_root(Path(args.repo).resolve())
+    cfg = load_config(repo, Path(args.config) if args.config else None)
+    pr = read_event()
+    if pr is None:
+        print("[jitcatch] not a pull_request event; nothing to do", file=sys.stderr)
+        return 0
+    result = run_pipeline(repo, pr.base_sha, pr.head_sha, cfg, pr.title, pr.body, args.force)
+    code = _emit(result, cfg, args)
+    md_comment = markdown(result, for_comment=True)
+    write_step_summary(md_comment)
+    set_output("catches", str(len(result.candidates())))
+    set_output("weak_catches", str(len(result.weak_catches)))
+    token = os.environ.get("GITHUB_TOKEN", "")
+    if args.comment and token and pr.repo:
+        try:
+            status = GitHubAPI(token).upsert_comment(pr.repo, pr.number, md_comment,
+                                                     create_if_missing=bool(result.candidates()) or args.always_comment)
+            print(f"[jitcatch] PR comment {status}", file=sys.stderr)
+        except Exception as e:  # never fail the job because of the comment
+            print(f"[jitcatch] could not post PR comment: {e}", file=sys.stderr)
+    return code
+
+
+def cmd_init(args) -> int:
+    repo = repo_root(Path(args.repo).resolve())
+    path = repo / ".jitcatch.toml"
+    if path.exists() and not args.force:
+        print(f"{path} already exists (use --force to overwrite)", file=sys.stderr)
+        return 1
+    path.write_text(CONFIG_TEMPLATE, encoding="utf-8")
+    gi = repo / ".gitignore"
+    lines = gi.read_text(encoding="utf-8").splitlines() if gi.exists() else []
+    if ".jitcatch/" not in lines:
+        with open(gi, "a", encoding="utf-8") as f:
+            f.write(("\n" if lines and lines[-1] else "") + ".jitcatch/\n")
+    print(f"wrote {path}; edit providers/models, then: jitcatch doctor")
+    return 0
+
+
+def cmd_doctor(args) -> int:
+    repo = repo_root(Path(args.repo).resolve())
+    cfg = load_config(repo, Path(args.config) if args.config else None)
+    ok = True
+    print(f"config OK ({len(cfg.providers)} providers)")
+    for m in _check_keys(cfg):
+        ok = False
+        print(f"  ✗ {m}")
+    try:
+        generator, judges, lp = _clients(cfg)
+        print(f"generator: {generator.name}; judges: {[j.name for j in judges]}; logprob judge: {lp.name if lp else '-'}")
+    except ConfigError as e:
+        print(f"  ✗ {e}")
+        return 2
+    for ad in build_adapters(cfg.adapters, repo):
+        good, why = ad.available()
+        print(f"  {'✓' if good else '·'} {ad.name}: {'available' if good else why}")
+    if args.ping:
+        seen = set()
+        for c in [generator, *judges, *([lp] if lp else [])]:
+            if c.name in seen:
+                continue
+            seen.add(c.name)
+            try:
+                r = c.complete("Reply with the single word: pong", "ping", max_tokens=1024,
+                               want_logprobs=(lp is not None and c.name == lp.name))
+                extra = f", logprobs={'yes' if r.logprobs else 'NO'}" if lp is not None and c.name == lp.name else ""
+                print(f"  ✓ {c.name} ({r.model}): {r.text.strip()[:40]!r}{extra}")
+            except LLMError as e:
+                ok = False
+                print(f"  ✗ {c.name}: {e}")
+    return 0 if ok else 1
+
+
+def cmd_install_hook(args) -> int:
+    from .hook import install
+    repo = repo_root(Path(args.repo).resolve())
+    path = install(repo, blocking=args.blocking, force=args.force)
+    print(f"installed {path} ({'blocking' if args.blocking else 'non-blocking'}); bypass once with JITCATCH_SKIP=1")
+    return 0
+
+
+def cmd_uninstall_hook(args) -> int:
+    from .hook import uninstall
+    repo = repo_root(Path(args.repo).resolve())
+    print("removed" if uninstall(repo) else "no jitcatch pre-push hook found")
+    return 0
+
+
+def cmd_hook_run(args) -> int:
+    from .hook import env_skip, ranges_from_stdin, stdin_text
+    if env_skip():
+        return 0
+    try:
+        repo = repo_root(Path.cwd())
+        cfg = load_config(repo)
+        ranges = ranges_from_stdin(repo, args.remote or "origin", cfg.hook.get("default_branch"), stdin_text())
+        blocking = args.blocking or bool(cfg.hook.get("blocking"))
+        found = 0
+        for base, head in ranges:
+            print(f"[jitcatch] checking {base[:12]}..{head[:12]} (bypass with JITCATCH_SKIP=1)", file=sys.stderr)
+            result = run_pipeline(repo, base, head, cfg)
+            write_artifacts(result, cfg.output_dir())
+            print(markdown(result), file=sys.stderr)
+            found += len(result.candidates())
+        if found and blocking:
+            print(f"[jitcatch] {found} possible regression(s); push blocked. Re-run with JITCATCH_SKIP=1 to override.",
+                  file=sys.stderr)
+            return 1
+        return 0
+    except (ConfigError, GitError, LLMError) as e:
+        print(f"[jitcatch] skipped: {e}", file=sys.stderr)
+        return 0   # never block a push on tool problems
+
+
+# ---------------------------------------------------------------------------- parser
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="jitcatch", description="Just-in-Time catching test generation")
+    p.add_argument("--version", action="version", version=f"jitcatch {__version__}")
+    p.add_argument("-v", "--verbose", action="count", default=0)
+    p.add_argument("-q", "--quiet-logs", action="store_true", help="only warnings on stderr")
+    sub = p.add_subparsers(dest="cmd", metavar="{run,setup,github,init,doctor,install-hook,uninstall-hook}")
+
+    def common(sp):
+        sp.add_argument("--repo", default=".", help="path inside the target git repository")
+        sp.add_argument("--config", help="path to config file (default: .jitcatch.toml)")
+
+    r = sub.add_parser("run", help="generate catching tests for a change (default command)")
+    common(r)
+    r.add_argument("--base", help="parent revision (merge-base with head is used). Default: automatic: "
+                                  "uncommitted changes vs HEAD, else commits not on the default branch, "
+                                  "else the last commit")
+    r.add_argument("--head", default="HEAD", help="changed revision")
+    r.add_argument("--title", help="change title (default: from commit messages)")
+    r.add_argument("--description", help="change description (default: from commit messages)")
+    r.add_argument("--force", action="store_true", help="ignore min_risk_score")
+    r.add_argument("--json", help="also write the JSON report here")
+    r.add_argument("--markdown", help="also write the Markdown report here")
+    r.add_argument("--quiet", action="store_true", help="don't print the report to stdout")
+    r.add_argument("--fail-on-catch", action="store_true", help="exit 1 if any catch is reported")
+    r.set_defaults(func=cmd_run)
+
+    g = sub.add_parser("github", help="run on a GitHub pull_request event and comment on the PR")
+    common(g)
+    g.add_argument("--force", action="store_true")
+    g.add_argument("--json")
+    g.add_argument("--markdown")
+    g.add_argument("--quiet", action="store_true")
+    g.add_argument("--fail-on-catch", action="store_true")
+    g.add_argument("--no-comment", dest="comment", action="store_false")
+    g.add_argument("--always-comment", action="store_true", help="comment even when nothing is reported")
+    g.set_defaults(func=cmd_github)
+
+    s = sub.add_parser("setup", help="choose provider, model and API key (asked once per machine)")
+    common(s)
+    s.add_argument("--reset", action="store_true", help="ask for provider and model again")
+    s.set_defaults(func=cmd_setup)
+
+    i = sub.add_parser("init", help="write a starter .jitcatch.toml")
+    common(i)
+    i.add_argument("--force", action="store_true")
+    i.set_defaults(func=cmd_init)
+
+    d = sub.add_parser("doctor", help="validate config, API keys and toolchains")
+    common(d)
+    d.add_argument("--ping", action="store_true", help="send a tiny request to each provider")
+    d.set_defaults(func=cmd_doctor)
+
+    h = sub.add_parser("install-hook", help="install a git pre-push hook")
+    common(h)
+    h.add_argument("--blocking", action="store_true", help="block the push when a catch is reported")
+    h.add_argument("--force", action="store_true", help="overwrite an existing pre-push hook")
+    h.set_defaults(func=cmd_install_hook)
+
+    u = sub.add_parser("uninstall-hook", help="remove the jitcatch pre-push hook")
+    common(u)
+    u.set_defaults(func=cmd_uninstall_hook)
+
+    hr = sub.add_parser("hook-run")
+    hr.add_argument("--remote")
+    hr.add_argument("--blocking", action="store_true")
+    hr.set_defaults(func=cmd_hook_run)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.cmd is None:  # plain `jitcatch` = `jitcatch run` with automatic base/head
+        args = parser.parse_args([*argv, "run"])
+    _setup_logging(-1 if args.quiet_logs else args.verbose)
+    try:
+        return args.func(args)
+    except (ConfigError, GitError, FileExistsError) as e:
+        print(f"jitcatch: error: {e}", file=sys.stderr)
+        return 2
+    except LLMError as e:
+        print(f"jitcatch: LLM error: {e}", file=sys.stderr)
+        return 3
+    except KeyboardInterrupt:
+        # Context managers have already restored swapped sources and removed temporary worktrees.
+        print("\njitcatch: interrupted; temporary worktrees cleaned up, no report written", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())