ci-guard-check 0.5.0__py3-none-any.whl

ci_guard/__init__.py

@@ -0,0 +1,3 @@
+"""ci-guard — CI failure classifier and flaky-test ledger."""
+
+__version__ = "0.5.0"

ci_guard/__main__.py

@@ -0,0 +1,6 @@
+"""ci-guard package entry point."""
+
+from ci_guard.cli import main
+
+if __name__ == "__main__":
+    main()

ci_guard/_providers/github.py

@@ -0,0 +1,105 @@
+"""GitHub provider — thin wrapper over the gh CLI.
+
+All GitHub-specific I/O is isolated here to ease future provider swaps (v2.0).
+Callers should import from ci_guard.watch, not directly from this module.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from datetime import datetime
+from typing import Optional
+
+
+def gh(*args: str, check: bool = True) -> str:
+    """Run a gh command and return stdout, or exit on failure."""
+    try:
+        result = subprocess.run(
+            ["gh", *args],
+            capture_output=True,
+            text=True,
+            check=check,
+        )
+        return result.stdout
+    except FileNotFoundError:
+        sys.stderr.write(
+            "ci-guard: 'gh' CLI not found. Install from https://cli.github.com.\n"
+        )
+        sys.exit(2)
+    except subprocess.CalledProcessError as e:
+        sys.stderr.write(f"ci-guard: gh failed: {e.stderr}\n")
+        if check:
+            sys.exit(2)
+        return ""
+
+
+def gh_returncode(*args: str) -> int:
+    try:
+        return subprocess.run(["gh", *args], capture_output=True, text=True).returncode
+    except FileNotFoundError:
+        sys.stderr.write("ci-guard: 'gh' CLI not found. Install from https://cli.github.com.\n")
+        sys.exit(2)
+
+
+def resolve_pr(arg: str) -> int:
+    if arg == "auto":
+        out = gh("pr", "view", "--json", "number")
+        return int(json.loads(out)["number"])
+    if arg.isdigit():
+        return int(arg)
+    parts = [p for p in arg.split("/") if p]
+    if "pull" in parts:
+        idx = parts.index("pull")
+        if idx + 1 < len(parts):
+            return int(parts[idx + 1])
+    raise ValueError(f"Could not resolve PR from: {arg}")
+
+
+def fetch_pr_state(pr: int) -> dict:
+    fields = ",".join([
+        "number", "state", "headRefOid", "mergeable", "mergeStateStatus",
+        "headRefName", "baseRefName",
+    ])
+    return json.loads(gh("pr", "view", str(pr), "--json", fields))
+
+
+def fetch_checks(pr: int) -> list[dict]:
+    out = gh("pr", "checks", str(pr), "--json",
+             "name,workflow,state,bucket,startedAt,completedAt,link")
+    return json.loads(out) if out.strip() else []
+
+
+def fetch_run_jobs(run_id: str) -> dict:
+    return json.loads(gh(
+        "run", "view", run_id,
+        "--json", "jobs,conclusion,status,name,workflowName,headSha,createdAt,updatedAt",
+    ))
+
+
+def fetch_failed_log(run_id: str, max_chars: int = 20000) -> str:
+    raw = gh("run", "view", run_id, "--log-failed", check=False)
+    if len(raw) > max_chars:
+        return raw[:max_chars // 2] + "\n...[truncated]...\n" + raw[-max_chars // 2:]
+    return raw
+
+
+def normalize_check(c: dict) -> tuple[str, Optional[str], Optional[int]]:
+    """Map gh pr checks fields to (status, conclusion, duration_seconds)."""
+    bucket = (c.get("bucket") or "").lower()
+    status = (
+        "completed" if bucket in {"pass", "fail", "cancel", "skipping"}
+        else (c.get("state") or "").lower() or "in_progress"
+    )
+    conclusion = {"pass": "success", "fail": "failure",
+                  "cancel": "cancelled", "skipping": "skipped"}.get(bucket)
+    duration_seconds = None
+    if c.get("startedAt") and c.get("completedAt"):
+        try:
+            s = datetime.fromisoformat(c["startedAt"].replace("Z", "+00:00"))
+            e = datetime.fromisoformat(c["completedAt"].replace("Z", "+00:00"))
+            duration_seconds = int((e - s).total_seconds())
+        except Exception:
+            pass
+    return status, conclusion, duration_seconds

ci_guard/actions.py

@@ -0,0 +1,219 @@
+"""Consume ci-guard watch JSONL and execute action directives.
+
+Pipe ci-guard watch output into this module:
+    ci-guard watch --pr auto | ci-guard run-actions
+
+Exit codes:
+    0 — pr_merged or pr_closed
+    2 — needs_help
+    3 — budget_exhausted
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+
+_EXIT_CODES: dict[str, int] = {
+    "pr_merged": 0,
+    "pr_closed": 0,
+    "needs_help": 2,
+    "budget_exhausted": 3,
+}
+
+_TERMINAL_EMOJI: dict[str, str] = {
+    "pr_merged": "✅",
+    "pr_closed": "🔒",
+    "needs_help": "🚨",
+    "budget_exhausted": "⚠️",
+}
+
+
+def _annotation(level: str, message: str) -> None:
+    print(f"::{level}::{message}", flush=True)
+
+
+def _post_pr_comment(pr_number: int, body: str) -> None:
+    if not os.environ.get("GH_TOKEN"):
+        return
+    subprocess.run(
+        ["gh", "pr", "comment", str(pr_number), "--body", body],
+        check=False,
+    )
+
+
+def _write_step_summary(text: str) -> None:
+    path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if path:
+        with open(path, "a", encoding="utf-8") as fh:
+            fh.write(text + "\n")
+
+
+def _format_report(snap: dict) -> str:
+    pr = snap.get("pr_number", "?")
+    sha = snap.get("head_sha_short", "?")
+    terminal = snap.get("terminal") or "—"
+    cost = snap.get("cost_summary", {})
+    checks = snap.get("checks", [])
+    qc = snap.get("quarantine_candidates", [])
+
+    failed = [
+        c for c in checks
+        if c.get("conclusion") in {"failure", "cancelled", "timed_out"}
+    ]
+
+    retries_used = cost.get("retries_used_pr", 0)
+    retries_max = cost.get("retries_max_pr", "?")
+    minutes = cost.get("minutes_spent", 0)
+    minutes_max = cost.get("minutes_max", "?")
+
+    blocked_failures = [
+        c for c in failed
+        if c.get("classification", {}).get("category") in {"branch_failure", "unknown"}
+        or c.get("classification", {}).get("category") not in {"infra_flake", "test_flake", "dependency_failure"}
+    ]
+    retries_avoided = cost.get("retries_avoided_pr")
+    if retries_avoided is None or retries_avoided == 0:
+        retries_avoided = len(blocked_failures)
+
+    minutes_saved = cost.get("minutes_saved")
+    if minutes_saved is None or minutes_saved == 0:
+        minutes_saved = sum(max(1, round((c.get("duration_seconds") or 300) / 60)) for c in blocked_failures)
+
+    emoji = _TERMINAL_EMOJI.get(terminal, "")
+
+    lines: list[str] = [
+        "<!-- ci-guard-report -->",
+        f"## 🛡️ **ci-guard** — PR #{pr} | `{sha}`\n",
+        "### 💰 Savings & Efficiency Summary",
+        "| Metric | Result | Context |",
+        "|:---|:---:|:---|",
+    ]
+
+    if minutes_saved > 0 or retries_avoided > 0:
+        lines.append(f"| ⏱️ **CI Minutes Saved** | **~{minutes_saved} min** | Avoided running doomed reruns |")
+        lines.append(f"| 🚫 **Blind Retries Avoided** | **{retries_avoided}** | Blocked retry on code/branch errors |")
+    else:
+        lines.append("| ⏱️ **CI Minutes Saved** | **Clean Run** | 0 wasted retries |")
+        lines.append("| 🚫 **Blind Retries Avoided** | **0** | No failure interventions needed |")
+
+    lines.append(f"| 🔄 **Flaky Retries Executed** | **{retries_used}/{retries_max}** | Safe, isolated reruns |")
+    lines.append(f"| ⏳ **CI Minutes Consumed** | **{minutes}/{minutes_max} min** | Run compute budget |")
+    lines.append(f"| 🎯 **PR Terminal Status** | {emoji} `{terminal}` | Gate conclusion |")
+    lines.append("")
+
+    if failed:
+        lines += [
+            "### 🔍 Failure Classifications",
+            "| Check | Classification | Confidence |",
+            "|---|---|---|",
+        ]
+        for c in failed:
+            clf = c.get("classification") or {}
+            lines.append(
+                f"| `{c.get('name', '?')}` "
+                f"| `{clf.get('category', '—')}` "
+                f"| {clf.get('confidence', '—')} |"
+            )
+        lines.append("")
+
+    lines.append(f"Budget: {retries_used}/{retries_max} retries · {minutes}/{minutes_max} min")
+
+    if qc:
+        lines.append(
+            f"\n⚠️ {len(qc)} quarantine candidate(s) — "
+            "run `ci-guard ledger quarantine-candidates`"
+        )
+
+    lines.append(f"\nTerminal: {emoji} `{terminal}`")
+    lines.append("\n---\n<sub>🛡️ Guarded by [ci-guard](https://github.com/Viniciuscarvalho/ci-guard) — stop burning CI minutes on blind retries.</sub>")
+
+    return "\n".join(lines)
+
+
+def _invoke_ci_guard(pr_number: int, *args: str) -> None:
+    subprocess.run(
+        [sys.executable, "-m", "ci_guard.cli", "--pr", str(pr_number), *args],
+        check=False,
+    )
+
+
+def run(stream=None) -> int:
+    if stream is None:
+        stream = sys.stdin
+
+    pr_number: int | None = None
+    last_snap: dict = {}
+
+    for raw in stream:
+        raw = raw.strip()
+        if not raw:
+            continue
+
+        try:
+            snap = json.loads(raw)
+        except json.JSONDecodeError:
+            print(f"[ci-guard run-actions] skipping non-JSON line: {raw}",
+                  file=sys.stderr, flush=True)
+            continue
+
+        if pr_number is None:
+            pr_number = snap.get("pr_number")
+
+        last_snap = snap
+        print(raw, flush=True)
+
+        for act in snap.get("actions", []):
+            action = act.get("action")
+
+            if action == "idle":
+                continue
+            elif action == "retry_failed_now":
+                if pr_number is not None:
+                    _invoke_ci_guard(pr_number, "--retry-failed-now")
+            elif action == "verify_flaky_green":
+                if pr_number is not None:
+                    _invoke_ci_guard(pr_number, "--verify-flaky-green")
+            elif action == "diagnose_branch_failure":
+                checks = ", ".join(act.get("checks", []))
+                _annotation("error", f"ci-guard: branch_failure — patch code before retrying: {checks}")
+                if pr_number is not None:
+                    _post_pr_comment(
+                        pr_number,
+                        f"**ci-guard** ⛔ `branch_failure` detected\n\n"
+                        f"The following checks failed due to changes on this branch "
+                        f"— **do not retry**, patch the code first:\n\n"
+                        + "\n".join(f"- `{c}`" for c in act.get("checks", [])),
+                    )
+            elif action == "diagnose_unknown":
+                checks = ", ".join(act.get("checks", []))
+                _annotation("warning", f"ci-guard: unknown failure — read logs before retrying: {checks}")
+                if pr_number is not None:
+                    _post_pr_comment(
+                        pr_number,
+                        f"**ci-guard** ❓ `unknown` failure — manual triage needed\n\n"
+                        f"Could not classify the following checks automatically. "
+                        f"Read the logs with `gh run view <run-id> --log-failed` "
+                        f"before any retry:\n\n"
+                        + "\n".join(f"- `{c}`" for c in act.get("checks", [])),
+                    )
+            elif action == "stop":
+                reason = act.get("reason", "")
+                code = _EXIT_CODES.get(reason, 0)
+                _annotation(
+                    "notice" if code == 0 else "warning",
+                    f"ci-guard: terminal={reason} exit={code}",
+                )
+                report = _format_report(last_snap)
+                if pr_number is not None:
+                    _post_pr_comment(pr_number, report)
+                _write_step_summary(report)
+                return code
+
+    return 0
+
+
+def main() -> int:
+    return run()

ci_guard/classify.py

@@ -0,0 +1,156 @@
+"""Heuristic CI failure classifier.
+
+Reads a failed-job log and emits a classification:
+branch_failure, infra_flake, test_flake, dependency_failure, or unknown.
+
+Patterns are intentionally conservative — when unsure, return 'unknown'
+so the caller diagnoses manually instead of acting on a false signal.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+
+# Each rule is (category, confidence, description, regex).
+# Order matters: branch_failure rules run first so a real bug doesn't get
+# masked by a coincidental network signal in the same log.
+RULES: list[tuple[str, str, str, re.Pattern]] = [
+    # ---------- branch_failure ----------
+    ("branch_failure", "high", "TAP/BATS test failure (not ok N)",
+     re.compile(r"^not ok \d+", re.M)),
+    ("branch_failure", "high", "TAP bail-out (suite aborted)",
+     re.compile(r"^Bail out!", re.M)),
+    ("branch_failure", "high", "pytest FAILED line",
+     re.compile(r"^FAILED ", re.M)),
+    ("branch_failure", "high", "pytest FAILURES section",
+     re.compile(r"^={3,} FAILURES ={3,}", re.M)),
+    ("branch_failure", "high", "Jest / Vitest FAIL file line",
+     re.compile(r"^\s*FAIL\s+\S+", re.M)),
+    ("branch_failure", "high", "Jest / Vitest test count: N failed",
+     re.compile(r"Tests?:\s+\d+ failed", re.I)),
+    ("branch_failure", "high", "Mocha / tap N failing",
+     re.compile(r"\b\d+ (failing|failed)\b", re.I)),
+    ("branch_failure", "medium", "AssertionError (test assertion failed)",
+     re.compile(r"\bAssertionError\b")),
+    ("branch_failure", "medium", "RSpec / Ruby failure summary",
+     re.compile(r"\d+ example[s]?,? \d+ failure", re.I)),
+    ("branch_failure", "medium", "JUnit / Go test FAIL line",
+     re.compile(r"^(FAIL\t|--- FAIL:)", re.M)),
+    ("branch_failure", "high", "Python SyntaxError",
+     re.compile(r"\bSyntaxError:", re.I)),
+    ("branch_failure", "high", "TypeScript/Flow type error",
+     re.compile(r"^.*?: error TS\d+:", re.M)),
+    ("branch_failure", "high", "Go compile error",
+     re.compile(r"^# .+\n.+\.go:\d+:\d+: ", re.M)),
+    ("branch_failure", "high", "Rust compile error (rustc)",
+     re.compile(r"error\[E\d{3,4}\]:", re.I)),
+    ("branch_failure", "high", "Java/Kotlin compilation failure",
+     re.compile(r"(error: )?compilation failed", re.I)),
+    ("branch_failure", "high", "Snapshot mismatch",
+     re.compile(r"snapshot (does not match|mismatch|doesn'?t match)", re.I)),
+    ("branch_failure", "high", "Lint error in changed code",
+     re.compile(r"\b(\d+) errors?, (\d+) warnings?", re.I)),
+    ("branch_failure", "medium", "Module not found",
+     re.compile(r"(Cannot find module|ModuleNotFoundError|No module named)", re.I)),
+    ("branch_failure", "medium", "Missing import / undefined symbol",
+     re.compile(r"(NameError|undefined reference to|cannot find symbol)", re.I)),
+
+    # ---------- dependency_failure ----------
+    ("dependency_failure", "high", "npm registry 5xx/429",
+     re.compile(r"npm (ERR! )?(429|5\d\d|registry returned)", re.I)),
+    ("dependency_failure", "high", "yarn lockfile mismatch",
+     re.compile(r"lockfile .* (out of date|mismatch)", re.I)),
+    ("dependency_failure", "medium", "PyPI fetch error",
+     re.compile(r"(could not fetch URL|HTTPSConnectionPool.*pypi)", re.I)),
+    ("dependency_failure", "medium", "Cargo registry error",
+     re.compile(r"error: failed to (fetch|download)", re.I)),
+    ("dependency_failure", "medium", "Docker pull failure",
+     re.compile(r"(error pulling image|failed to (pull|copy)|registry-1\.docker\.io)", re.I)),
+    ("dependency_failure", "medium", "Go module proxy error",
+     re.compile(r"proxy\.golang\.org.*\b5\d\d\b", re.I)),
+
+    # ---------- infra_flake ----------
+    ("infra_flake", "high", "Runner shutdown",
+     re.compile(r"the runner has received a shutdown signal", re.I)),
+    ("infra_flake", "high", "Lost communication with runner",
+     re.compile(r"lost communication with the server", re.I)),
+    ("infra_flake", "high", "GitHub Actions infra error",
+     re.compile(r"(GitHub Actions infrastructure|workflow run was canceled)", re.I)),
+    ("infra_flake", "medium", "DNS failure",
+     re.compile(r"(could not resolve host|getaddrinfo (failed|ENOTFOUND))", re.I)),
+    ("infra_flake", "medium", "Network reset/timeout",
+     re.compile(r"(connection reset by peer|i/o timeout|read: connection refused)", re.I)),
+    ("infra_flake", "low", "Generic 503/502",
+     re.compile(r"\b(502 Bad Gateway|503 Service Unavailable|504 Gateway Timeout)\b", re.I)),
+    ("infra_flake", "low", "Out of disk on runner",
+     re.compile(r"(no space left on device|disk quota exceeded)", re.I)),
+
+    # ---------- test_flake ----------
+    ("test_flake", "medium", "Race condition / timing pattern",
+     re.compile(r"(timed? out waiting for|expected .* but got .* \(retried\)|"
+                r"flaky test|known.{0,15}flaky)", re.I)),
+]
+
+
+def classify(log: str) -> dict:
+    """Apply rules in order; return first match. If none, return unknown."""
+    if not log.strip():
+        return {"category": "unknown", "confidence": "low",
+                "reason": "Empty log; cannot classify."}
+    for category, confidence, description, pattern in RULES:
+        m = pattern.search(log)
+        if m:
+            snippet = log[max(0, m.start() - 80): m.end() + 80].strip()
+            snippet = " ".join(snippet.split())
+            if len(snippet) > 240:
+                snippet = snippet[:240] + "…"
+            return {
+                "category": category,
+                "confidence": confidence,
+                "reason": description,
+                "matched_pattern": pattern.pattern,
+                "matched_snippet": snippet,
+            }
+    return {"category": "unknown", "confidence": "low",
+            "reason": "No heuristic matched; manual diagnosis recommended."}
+
+
+def fetch_log(run_id: str) -> str:
+    try:
+        r = subprocess.run(
+            ["gh", "run", "view", run_id, "--log-failed"],
+            capture_output=True, text=True, check=False,
+        )
+        return r.stdout
+    except FileNotFoundError:
+        sys.stderr.write("ci-guard: 'gh' CLI not found.\n")
+        sys.exit(2)
+
+
+def main() -> int:
+    import argparse
+    import json
+
+    p = argparse.ArgumentParser(
+        description="Classify a CI failure log as branch_failure, infra_flake, etc.")
+    src = p.add_mutually_exclusive_group(required=True)
+    src.add_argument("--run-id", help="Fetch failed log for this run via gh CLI.")
+    src.add_argument("--log-file", help="Path to a log file on disk.")
+    src.add_argument("--stdin", action="store_true", help="Read log from stdin.")
+    p.add_argument("--check-name", default=None)
+    args = p.parse_args()
+
+    if args.run_id:
+        log = fetch_log(args.run_id)
+    elif args.log_file:
+        log = open(args.log_file, encoding="utf-8", errors="replace").read()
+    else:
+        log = sys.stdin.read()
+
+    result = classify(log)
+    if args.check_name:
+        result["check_name"] = args.check_name
+    print(json.dumps(result, indent=2))
+    return 0