jitcatch 0.2.0__py3-none-any.whl

jitcatch/engine.py

@@ -0,0 +1,521 @@
+"""The Just-in-Time catching pipeline.
+
+    change ──► targeting ──► intent & risks ──► mutants of the parent ──► tests (pass parent, kill mutant)
+                                     │                                                │
+                                     └──── dodgy diff: tests that pass parent ────────┤
+                                                                                      ▼
+                                       run on change: fail = weak catch, pass = hardening test
+                                                                                      ▼
+                                       assessors (rules + LLM ensemble) ──► ranked strong-catch candidates
+"""
+from __future__ import annotations
+
+import difflib
+import fnmatch
+import logging
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from . import prompts
+from .adapters import Adapter, TestPlacement, adapter_for
+from .assessors import assess_weak_catch
+from .config import Config
+from .gitutil import show_file, worktree
+from .jsonutil import LLMFormatError, extract_code, extract_json
+from .llm import LLMClient, LLMError
+from .models import (Assessment, ChangeContext, GeneratedTest, Intent, Mutant, Outcome, Risk, TestRun)
+from .targeting import RiskScore, score_change
+
+log = logging.getLogger("jitcatch")
+
+CHANGE_KINDS = {"refactor", "dead_code_removal", "additive", "bugfix", "feature", "other"}
+
+
+@dataclass
+class Target:
+    path: str
+    adapter: Adapter
+    base_text: str
+    head_text: str
+    patch: str
+
+
+@dataclass
+class RunResult:
+    ctx: ChangeContext
+    risk: RiskScore | None = None
+    intent: Intent | None = None
+    targets: list[str] = field(default_factory=list)
+    skipped: list[dict[str, str]] = field(default_factory=list)
+    mutants: list[Mutant] = field(default_factory=list)
+    tests: list[GeneratedTest] = field(default_factory=list)
+    assessments: dict[str, Assessment] = field(default_factory=dict)
+    errors: list[str] = field(default_factory=list)
+    llm_calls: int = 0
+    started_at: float = field(default_factory=time.time)
+    finished_at: float = 0.0
+    threshold: float = 0.2
+
+    @property
+    def weak_catches(self) -> list[GeneratedTest]:
+        return [t for t in self.tests if t.is_weak_catch]
+
+    @property
+    def hardening(self) -> list[GeneratedTest]:
+        return [t for t in self.tests if t.is_hardening and not t.is_flaky]
+
+    def candidates(self) -> list[tuple[GeneratedTest, Assessment]]:
+        """Weak catches above the reporting threshold, best first."""
+        by_id = {t.id: t for t in self.tests}
+        ranked = sorted(
+            ((by_id[a.test_id], a) for a in self.assessments.values() if not a.discarded),
+            key=lambda ta: ta[1].combined, reverse=True,
+        )
+        return [(t, a) for t, a in ranked if a.combined >= self.threshold]
+
+
+class Engine:
+    def __init__(self, cfg: Config, repo: Path, ctx: ChangeContext, generator: LLMClient,
+                 judges: list[LLMClient], logprob_judge: LLMClient | None, adapters: list[Adapter],
+                 force: bool = False):
+        self.cfg = cfg
+        self.repo = repo
+        self.ctx = ctx
+        self.gen = generator
+        self.judges = judges
+        self.logprob_judge = logprob_judge
+        self.adapters = adapters
+        self.force = force
+        self.run_cfg = cfg.run
+        self.result = RunResult(ctx=ctx, threshold=float(cfg.run["report_threshold"]))
+        self._placements: dict[str, TestPlacement] = {}
+        self._adapter_ok: dict[str, tuple[bool, str]] = {}
+        self._existing_baseline: dict[str, bool | None] = {}
+
+    # ------------------------------------------------------------------ orchestration
+    def run(self) -> RunResult:
+        r = self.result
+        targets = self._select_targets()
+        r.targets = [t.path for t in targets]
+        r.risk = score_change(self.ctx, self.cfg.targeting["sensitive_paths"],
+                              lambda p: any(a.is_test_file(p) for a in self.adapters))
+        if not targets:
+            log.info("no testable modified source files in this change")
+            return self._finish()
+        if not self.force and r.risk.score < float(self.run_cfg["min_risk_score"]):
+            r.skipped.append({"path": "*", "reason": f"risk score {r.risk.score} below min_risk_score"})
+            log.info("change risk %.3f below threshold; skipping (use --force to override)", r.risk.score)
+            return self._finish()
+
+        log.info("%d target file(s): %s", len(targets), ", ".join(t.path for t in targets))
+        log.info("creating worktrees for parent %s and change %s…", self.ctx.base_sha[:8], self.ctx.head_sha[:8])
+        link = list(self.run_cfg.get("link_paths") or [])
+        with worktree(self.repo, self.ctx.base_sha, "base", link) as base_wt, \
+                worktree(self.repo, self.ctx.head_sha, "head", link) as head_wt:
+            log.info("inferring the change's intent and risks…")
+            r.intent = self._infer_intent(targets)
+            for target in targets:
+                if "intent_aware" in self.run_cfg["workflows"] and r.intent:
+                    self._intent_aware(target, base_wt, head_wt)
+                if "dodgy_diff" in self.run_cfg["workflows"]:
+                    self._dodgy_diff(target, base_wt, head_wt)
+            self._assess()
+        return self._finish()
+
+    def _finish(self) -> RunResult:
+        self.result.finished_at = time.time()
+        return self.result
+
+    # ------------------------------------------------------------------ targeting
+    def _select_targets(self) -> list[Target]:
+        inc = self.run_cfg.get("include") or []
+        exc = self.run_cfg.get("exclude") or []
+        chosen: list[Target] = []
+        for f in self.ctx.files:
+            if inc and not any(fnmatch.fnmatch(f.path, g) for g in inc):
+                continue
+            if any(fnmatch.fnmatch(f.path, g) for g in exc):
+                self._skip(f.path, "excluded by config")
+                continue
+            ad = adapter_for(self.adapters, f.path)
+            if ad is None:
+                continue
+            if f.status not in ("M", "T"):
+                self._skip(f.path, {"A": "new file (no parent behaviour to regress)", "D": "deleted file",
+                                    "R": "renamed file (not supported)", "C": "copied file (not supported)"}
+                           .get(f.status, f"unsupported change status {f.status}"))
+                continue
+            ok, why = self._adapter_available(ad)
+            if not ok:
+                self._skip(f.path, f"{ad.name} toolchain unavailable: {why}")
+                continue
+            ok, why = ad.can_test(f.path)
+            if not ok:
+                self._skip(f.path, why)
+                continue
+            base_text = show_file(self.repo, self.ctx.base_sha, f.old_path)
+            head_text = show_file(self.repo, self.ctx.head_sha, f.path)
+            if base_text is None or head_text is None:
+                self._skip(f.path, "could not read file at base/head")
+                continue
+            if len(base_text) > int(self.run_cfg["max_file_chars"]):
+                self._skip(f.path, f"file larger than max_file_chars ({len(base_text)} chars)")
+                continue
+            chosen.append(Target(f.path, ad, base_text, head_text, f.patch))
+        chosen.sort(key=lambda t: -len(t.patch))
+        limit = int(self.run_cfg["max_target_files"])
+        for t in chosen[limit:]:
+            self._skip(t.path, f"over max_target_files={limit}")
+        return chosen[:limit]
+
+    def _adapter_available(self, ad: Adapter) -> tuple[bool, str]:
+        if ad.name not in self._adapter_ok:
+            self._adapter_ok[ad.name] = ad.available()
+        return self._adapter_ok[ad.name]
+
+    def _skip(self, path: str, reason: str) -> None:
+        self.result.skipped.append({"path": path, "reason": reason})
+        log.info("skip %s: %s", path, reason)
+
+    # ------------------------------------------------------------------ LLM helpers
+    def _ask(self, user: str, max_tokens: int | None = None) -> str:
+        self.result.llm_calls += 1
+        t0 = time.monotonic()
+        text = self.gen.complete(prompts.GEN_SYSTEM, user, max_tokens=max_tokens).text
+        log.info("  model replied in %.0fs", time.monotonic() - t0)
+        return text
+
+    def _clip(self, s: str, key: str = "max_patch_chars") -> str:
+        n = int(self.run_cfg[key])
+        return s if len(s) <= n else s[: n // 2] + "\n... [truncated] ...\n" + s[-n // 2 :]
+
+    # ------------------------------------------------------------------ intent & risks
+    def _infer_intent(self, targets: list[Target]) -> Intent | None:
+        files_block = "\n".join(
+            f"### `{t.path}`\n```{t.adapter.fence_langs[0]}\n{self._clip(t.head_text, 'max_file_chars')}\n```"
+            for t in targets
+        )
+        user = prompts.INTENT_USER.format(
+            title=self.ctx.title or "(none)", description=self.ctx.description or "(none)",
+            patch=self._clip(self.ctx.full_patch), files=files_block,
+            max_risks=int(self.run_cfg["max_risks_per_file"]),
+        )
+        try:
+            data = extract_json(self._ask(user, 4000))
+        except (LLMError, LLMFormatError) as e:
+            self.result.errors.append(f"intent inference failed: {e}")
+            log.warning("intent inference failed: %s", e)
+            return None
+        if not isinstance(data, dict):
+            self.result.errors.append("intent inference returned non-object JSON")
+            return None
+        kind = str(data.get("change_kind", "other")).strip().lower()
+        paths = {t.path for t in targets}
+        per_file: dict[str, int] = {}
+        risks: list[Risk] = []
+        for item in data.get("risks") or []:
+            if not isinstance(item, dict) or not item.get("description"):
+                continue
+            path = str(item.get("file", "")).strip().lstrip("./")
+            if path not in paths:
+                if len(paths) == 1:
+                    path = next(iter(paths))
+                else:
+                    match = [p for p in paths if p.endswith(path) or path.endswith(PurePosixPath(p).name)]
+                    if len(match) != 1:
+                        continue
+                    path = match[0]
+            if per_file.get(path, 0) >= int(self.run_cfg["max_risks_per_file"]):
+                continue
+            per_file[path] = per_file.get(path, 0) + 1
+            risks.append(Risk(id=f"r{len(risks) + 1}", description=str(item["description"]).strip(), file=path))
+        intent = Intent(summary=str(data.get("intent", "")).strip(),
+                        change_kind=kind if kind in CHANGE_KINDS else "other", risks=risks)
+        log.info("intent: %s [%s]; %d risks", intent.summary, intent.change_kind, len(risks))
+        return intent
+
+    # ------------------------------------------------------------------ intent-aware workflow
+    def _intent_aware(self, t: Target, base_wt: Path, head_wt: Path) -> None:
+        assert self.result.intent is not None
+        risks = [r for r in self.result.intent.risks if r.file == t.path]
+        for i, risk in enumerate(risks, 1):
+            log.info("[%s] risk %d/%d: generating mutant…", t.path, i, len(risks))
+            mutant = self._make_mutant(t, risk, base_wt)
+            if mutant is None:
+                continue
+            log.info("[%s] risk %d/%d: writing a test that should catch mutant %s…", t.path, i, len(risks), mutant.id)
+            test = self._generate_test(t, "intent_aware", mutant=mutant)
+            if test is not None:
+                self._evaluate(test, t, base_wt, head_wt, mutant)
+
+    def _make_mutant(self, t: Target, risk: Risk, base_wt: Path) -> Mutant | None:
+        fence = t.adapter.fence_langs[0]
+        user = prompts.MUTANT_USER.format(path=t.path, intent=self.result.intent.summary if self.result.intent else "",
+                                          risk=risk.description, lang=fence, source=t.base_text)
+        mid = f"m{len(self.result.mutants) + 1}"
+        try:
+            data = extract_json(self._ask(user, 4000))
+            edits = data.get("edits") if isinstance(data, dict) else None
+            if not edits:
+                raise LLMFormatError("no edits")
+            mutated = apply_edits(t.base_text, edits)
+        except (LLMError, LLMFormatError, ValueError) as e:
+            log.info("mutant for %s/%s rejected: %s", t.path, risk.id, e)
+            self.result.mutants.append(Mutant(mid, risk, t.path, t.base_text, t.base_text,
+                                              survived_existing_tests=None, note=f"invalid: {e}"))
+            return None
+        mutant = Mutant(mid, risk, t.path, t.base_text, mutated,
+                        note=str(data.get("explanation", ""))[:500] if isinstance(data, dict) else "")
+        self.result.mutants.append(mutant)
+        if mutated == t.base_text:
+            mutant.note = "invalid: identical to parent"
+            return None
+        syntax = _syntax_error(t.adapter, mutated, t.path)
+        if syntax:
+            mutant.note = f"invalid: {syntax}"
+            return None
+        if self.run_cfg.get("check_mutants_with_existing_tests"):
+            if t.path not in self._existing_baseline:
+                log.info("[%s] running existing tests on the parent (once per file)…", t.path)
+            if self._existing_tests_pass_on_parent(t, base_wt) is False:
+                mutant.note += " | existing tests already fail on parent; check skipped"
+                return mutant
+            log.info("[%s] running existing tests against mutant %s…", t.path, mid)
+            with _swapped(base_wt / t.path, mutated):
+                run = t.adapter.run_existing_tests(base_wt, t.path, float(self.run_cfg["existing_tests_timeout_s"]))
+            if run is not None and run.outcome in (Outcome.FAIL, Outcome.ERROR):
+                mutant.survived_existing_tests = False
+                mutant.note += " | killed or broken by existing tests (discarded)"
+                log.info("mutant %s discarded: existing tests %s", mid, run.outcome.value)
+                return None
+            mutant.survived_existing_tests = True if run is not None and run.passed else None
+        return mutant
+
+    def _existing_tests_pass_on_parent(self, t: Target, base_wt: Path) -> bool | None:
+        """Run the existing tests once on the unmodified parent. A mutant can only be judged
+        "killed by existing tests" if those tests pass without it. None = no runner for this target."""
+        if t.path not in self._existing_baseline:
+            run = t.adapter.run_existing_tests(base_wt, t.path, float(self.run_cfg["existing_tests_timeout_s"]))
+            ok = None if run is None else run.passed
+            self._existing_baseline[t.path] = ok
+            if ok is False:
+                msg = (f"existing tests do not pass on the parent for {t.path} ({run.outcome.value}); "
+                       "mutants are kept without the existing-tests check")
+                self.result.errors.append(msg)
+                log.warning(msg)
+        return self._existing_baseline[t.path]
+
+    # ------------------------------------------------------------------ dodgy-diff workflow
+    def _dodgy_diff(self, t: Target, base_wt: Path, head_wt: Path) -> None:
+        n = int(self.run_cfg["dodgy_tests_per_file"])
+        for i in range(n):
+            log.info("[%s] dodgy-diff test %d/%d: writing a test for the parent's behaviour…", t.path, i + 1, n)
+            test = self._generate_test(t, "dodgy_diff", variation=i)
+            if test is not None:
+                self._evaluate(test, t, base_wt, head_wt, None)
+
+    # ------------------------------------------------------------------ test generation
+    def _example_block(self, t: Target) -> str:
+        rel = t.adapter.related_test(t.path) or t.adapter.any_test_example()
+        if not rel:
+            return ""
+        code = show_file(self.repo, self.ctx.base_sha, rel)
+        if code is None:
+            p = self.repo / rel
+            code = p.read_text(encoding="utf-8", errors="replace") if p.exists() else None
+        if not code:
+            return ""
+        code = code if len(code) < 6000 else code[:6000] + "\n# ... (truncated)\n"
+        return prompts.EXAMPLE_BLOCK.format(path=rel, lang=t.adapter.fence_langs[0], code=code)
+
+    def _generate_test(self, t: Target, workflow: str, mutant: Mutant | None = None,
+                       variation: int = 0) -> GeneratedTest | None:
+        tid = uuid.uuid4().hex[:6]
+        pl = t.adapter.placement(t.path, tid, t.base_text)
+        fence = t.adapter.fence_langs[0]
+        if mutant is not None:
+            user = prompts.TEST_FOR_MUTANT_USER.format(
+                path=t.path, risk=mutant.risk.description, instructions=pl.instructions, test_path=pl.rel_path,
+                lang=fence, source=t.base_text, mutant_diff=unified(t.base_text, mutant.mutated, t.path),
+                example=self._example_block(t))
+        else:
+            variation_txt = ("" if variation == 0 else
+                             f"\n(Variation {variation + 1}: cover different inputs/branches of the changed code "
+                             "than an obvious first test would.)\n")
+            user = prompts.TEST_DODGY_USER.format(
+                path=t.path, instructions=pl.instructions, test_path=pl.rel_path, lang=fence,
+                source=t.base_text, patch=self._clip(t.patch), example=self._example_block(t),
+                variation=variation_txt)
+        try:
+            code = extract_code(self._ask(user, 6000), t.adapter.fence_langs)
+        except LLMError as e:
+            self.result.errors.append(f"test generation failed for {t.path}: {e}")
+            return None
+        if not code.strip():
+            return None
+        test = GeneratedTest(id=tid, workflow=workflow, target_file=t.path, test_path=pl.rel_path, code=code,
+                             risk=mutant.risk if mutant else None, mutant_id=mutant.id if mutant else None)
+        self._placements[tid] = pl
+        self.result.tests.append(test)
+        return test
+
+    # ------------------------------------------------------------------ execution
+    def _run(self, test: GeneratedTest, t: Target, wt: Path) -> TestRun:
+        pl = self._placements[test.id]
+        with _temp_file(wt / test.test_path, test.code):
+            return t.adapter.run_test(wt, test.test_path, pl, float(self.run_cfg["test_timeout_s"]))
+
+    def _evaluate(self, test: GeneratedTest, t: Target, base_wt: Path, head_wt: Path, mutant: Mutant | None) -> None:
+        max_fix = int(self.run_cfg["max_fix_attempts"])
+        pl = self._placements[test.id]
+        fence = t.adapter.fence_langs[0]
+        # 1. must build and pass on the parent (with an LLM repair loop)
+        while True:
+            test.attempts += 1
+            log.info("  test %s: running on parent (attempt %d)…", test.id, test.attempts)
+            run = self._run(test, t, base_wt)
+            test.base_run = run
+            if run.passed or run.outcome == Outcome.INFRA or test.attempts > max_fix:
+                break
+            log.info("  test %s: %s on parent; asking the model to repair it (%d/%d)…",
+                     test.id, run.outcome.value, test.attempts, max_fix)
+            user = prompts.TEST_FIX_USER.format(
+                path=t.path, instructions=pl.instructions, lang=fence, source=t.base_text,
+                test_path=test.test_path, test_code=test.code, outcome=run.outcome.value,
+                output=self._clip(run.output, "max_patch_chars"))
+            try:
+                test.code = extract_code(self._ask(user, 6000), t.adapter.fence_langs)
+            except LLMError as e:
+                self.result.errors.append(f"test repair failed: {e}")
+                break
+        if not test.base_run.passed:
+            test.discarded_reason = f"does not pass on parent ({test.base_run.outcome.value})"
+            log.info("test %s discarded: %s", test.id, test.discarded_reason)
+            return
+        reruns = int(self.run_cfg["flaky_reruns"])
+        if reruns > 0:
+            test.base_rerun = self._run(test, t, base_wt)
+            if not test.base_rerun.passed:
+                test.discarded_reason = "flaky on parent"
+                return
+        # 2. mutant kill (informational; intent-aware workflow)
+        if mutant is not None:
+            log.info("  test %s: running on mutant %s…", test.id, mutant.id)
+            with _swapped(base_wt / t.path, mutant.mutated):
+                test.mutant_run = self._run(test, t, base_wt)
+        # 3. run on the change
+        log.info("  test %s: running on the change…", test.id)
+        test.head_run = self._run(test, t, head_wt)
+        if not test.head_run.passed and reruns > 0:
+            test.head_rerun = self._run(test, t, head_wt)
+        state = ("WEAK CATCH" if test.is_weak_catch else "hardening" if test.is_hardening else test.head_run.outcome.value)
+        log.info("test %s [%s] on %s: %s", test.id, test.workflow, t.path, state)
+
+    # ------------------------------------------------------------------ assessment
+    def _assess(self) -> None:
+        by_path = {}
+        for f in self.ctx.files:
+            by_path[f.path] = adapter_for(self.adapters, f.path)
+        catches = self.result.weak_catches
+        for i, test in enumerate(catches, 1):
+            log.info("judging weak catch %d/%d (test %s)…", i, len(catches), test.id)
+            ad = by_path.get(test.target_file)
+            fence = ad.fence_langs[0] if ad else ""
+            a = assess_weak_catch(test, self.ctx, self.result.intent, ad.name if ad else "", fence,
+                                  self.judges, self.logprob_judge, self.cfg.assessors,
+                                  int(self.run_cfg["max_patch_chars"]))
+            self.result.llm_calls += 0 if a.discarded else len(self.judges) + (1 if self.logprob_judge else 0)
+            self.result.assessments[test.id] = a
+            log.info("assessed %s: combined=%.3f%s", test.id, a.combined, " (discarded)" if a.discarded else "")
+
+
+# ---------------------------------------------------------------------- utilities
+
+def apply_edits(text: str, edits: list[dict[str, Any]]) -> str:
+    out = text
+    for e in edits:
+        if not isinstance(e, dict):
+            raise ValueError("edit is not an object")
+        search, replace = e.get("search"), e.get("replace")
+        if not isinstance(search, str) or not isinstance(replace, str) or not search:
+            raise ValueError("edit needs non-empty 'search' and string 'replace'")
+        count = out.count(search)
+        if count == 0:
+            # tolerate trailing-whitespace differences
+            stripped = "\n".join(l.rstrip() for l in search.splitlines())
+            norm = "\n".join(l.rstrip() for l in out.splitlines())
+            if norm.count(stripped) == 1:
+                out = norm.replace(stripped, replace, 1) + ("\n" if text.endswith("\n") else "")
+                continue
+            raise ValueError(f"search text not found: {search[:80]!r}")
+        if count > 1:
+            raise ValueError(f"search text is not unique ({count} matches): {search[:80]!r}")
+        out = out.replace(search, replace, 1)
+    return out
+
+
+def unified(a: str, b: str, path: str) -> str:
+    return "".join(difflib.unified_diff(a.splitlines(True), b.splitlines(True),
+                                        fromfile=f"a/{path}", tofile=f"b/{path}"))
+
+
+def _syntax_error(adapter: Adapter, text: str, path: str) -> str | None:
+    if adapter.name == "python":
+        try:
+            compile(text, path, "exec")
+        except SyntaxError as e:
+            return f"syntax error: {e}"
+    return None
+
+
+class _swapped:
+    """Temporarily replace a file's contents."""
+
+    def __init__(self, path: Path, content: str):
+        self.path, self.content = path, content
+        self.original: bytes | None = None
+
+    def __enter__(self):
+        self.original = self.path.read_bytes()
+        self.path.write_text(self.content, encoding="utf-8")
+        return self.path
+
+    def __exit__(self, *exc):
+        assert self.original is not None
+        self.path.write_bytes(self.original)
+        return False
+
+
+class _temp_file:
+    """Write a file for the duration of a block, creating (and later removing) missing parent dirs."""
+
+    def __init__(self, path: Path, content: str):
+        self.path, self.content = path, content
+        self.created: list[Path] = []
+
+    def __enter__(self):
+        d = self.path.parent
+        missing = []
+        while not d.exists():
+            missing.append(d)
+            d = d.parent
+        for m in reversed(missing):
+            m.mkdir()
+            self.created.append(m)
+        self.path.write_text(self.content, encoding="utf-8")
+        return self.path
+
+    def __exit__(self, *exc):
+        try:
+            self.path.unlink()
+        except FileNotFoundError:
+            pass
+        for d in reversed(self.created):
+            try:
+                d.rmdir()
+            except OSError:
+                pass
+        return False

jitcatch/github.py

@@ -0,0 +1,90 @@
+"""GitHub Actions integration: read the PR event, post/update a sticky PR comment."""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+from .report import COMMENT_MARKER
+
+
+@dataclass
+class PullRequest:
+    number: int
+    title: str
+    body: str
+    base_sha: str
+    head_sha: str
+    repo: str
+
+
+def read_event() -> PullRequest | None:
+    path = os.environ.get("GITHUB_EVENT_PATH")
+    if not path or not os.path.exists(path):
+        return None
+    with open(path, encoding="utf-8") as f:
+        ev = json.load(f)
+    pr = ev.get("pull_request")
+    if not pr:
+        return None
+    return PullRequest(
+        number=int(pr["number"]), title=pr.get("title") or "", body=pr.get("body") or "",
+        base_sha=pr["base"]["sha"], head_sha=pr["head"]["sha"],
+        repo=os.environ.get("GITHUB_REPOSITORY") or ev.get("repository", {}).get("full_name", ""),
+    )
+
+
+class GitHubAPI:
+    def __init__(self, token: str, api_url: str | None = None):
+        self.token = token
+        self.api = (api_url or os.environ.get("GITHUB_API_URL") or "https://api.github.com").rstrip("/")
+
+    def _req(self, method: str, path: str, body: dict | None = None):
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(self.api + path, data=data, method=method, headers={
+            "Authorization": f"Bearer {self.token}", "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28", "Content-Type": "application/json",
+            "User-Agent": "jitcatch",
+        })
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            raw = resp.read()
+            return json.loads(raw) if raw else None
+
+    def find_comment(self, repo: str, number: int) -> int | None:
+        page = 1
+        while True:
+            items = self._req("GET", f"/repos/{repo}/issues/{number}/comments?per_page=100&page={page}") or []
+            for c in items:
+                if COMMENT_MARKER in (c.get("body") or ""):
+                    return int(c["id"])
+            if len(items) < 100:
+                return None
+            page += 1
+
+    def upsert_comment(self, repo: str, number: int, body: str, create_if_missing: bool = True) -> str:
+        if len(body) > 65000:  # GitHub comment limit is 65536 chars
+            body = body[:64000] + "\n\n… report truncated; see the workflow artifact for the full report.\n"
+        existing = self.find_comment(repo, number)
+        if existing is not None:
+            self._req("PATCH", f"/repos/{repo}/issues/comments/{existing}", {"body": body})
+            return "updated"
+        if not create_if_missing:
+            return "skipped"
+        self._req("POST", f"/repos/{repo}/issues/{number}/comments", {"body": body})
+        return "created"
+
+
+def set_output(name: str, value: str) -> None:
+    path = os.environ.get("GITHUB_OUTPUT")
+    if path:
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(f"{name}={value}\n")
+
+
+def write_step_summary(md: str) -> None:
+    path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if path:
+        with open(path, "a", encoding="utf-8") as f:
+            f.write(md)