ci-whisper 0.1.1__tar.gz

ci_whisper-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mgkvibez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ci_whisper-0.1.1/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: ci-whisper
+Version: 0.1.1
+Summary: Read a failed CI log and get the first real error, its causal chain, and a fix.
+Author: mgkvibez
+License: MIT
+Keywords: ci,github-actions,logs,debugging,developer-tools,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# ci-whisper
+
+**Read a failed CI log. Get the first real error, its causal chain, and a fix.** One paragraph instead of ten thousand lines of noise.
+
+[![ci](https://github.com/mgkvibez/ci-whisper/actions/workflows/ci.yml/badge.svg)](https://github.com/mgkvibez/ci-whisper/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
+[![stars](https://img.shields.io/github/stars/mgkvibez/ci-whisper?style=flat&color=yellow)](https://github.com/mgkvibez/ci-whisper/stargazers)
+
+![ci-whisper demo](docs/demo/ci-whisper.svg)
+
+## Install
+
+```bash
+pipx install git+https://github.com/mgkvibez/ci-whisper.git
+```
+
+Until it is on PyPI, install from git. For development: `git clone && pip install -e ".[dev]"`.
+
+## Three ways to use it
+
+```bash
+# 1. The one you will use daily: pipe the failing job log
+gh run view --log-failed | ci-whisper
+
+# 2. From a downloaded log file
+ci-whisper --file /tmp/build.log
+
+# 3. Let it fetch the last failed run of the current repo
+ci-whisper --gh 16977481234
+
+# machine-readable, for a bot or an agent skill
+ci-whisper --file build.log --json
+```
+
+Exit code is `1` when no error signal is found, so you can gate on it.
+
+## Why it exists
+
+A red build hands you 10k lines. The actual cause is line 4, and everything after it is consequence: retries, cascading test failures, the polite `##[error]Process completed with exit code 1`.
+
+Two things go wrong when this hits an agent. It reads the *last* error and fixes a symptom, or it reads the header and summarises nothing. ci-whisper ranks signals so the cause outranks its own consequences, then shows the citations so anyone can check the call.
+
+## How it works
+
+1. **Clean** — strips ANSI and GitHub's `2026-10-29T08:01:02.1234567Z ` timestamp prefix, keeping a line-number map to the original file.
+2. **Scan** — matches a ranked rule set: `ModuleNotFoundError`/`Exception` (4) beat `Traceback`, test failures and compiler errors (3), which beat `npm ERR!` and `##[error]` (2), which beat a bare `exit code 1` (1).
+3. **Root cause** — highest severity, then earliest line. Noise (warnings, deprecations, `0 failed`, download progress) is filtered before ranking.
+4. **Chain** — the chosen line plus the following block: indented continuations, frames, and `caused by` style links.
+5. **Fix** — a rule per failure shape: peer dependency conflict, missing module, permissions, missing path, assertion, timeout, OOM.
+
+No network calls, no LLM, no dependencies.
+
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md). Tests:
+
+```bash
+python -m pytest -q
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

ci_whisper-0.1.1/README.md

@@ -0,0 +1,64 @@
+# ci-whisper
+
+**Read a failed CI log. Get the first real error, its causal chain, and a fix.** One paragraph instead of ten thousand lines of noise.
+
+[![ci](https://github.com/mgkvibez/ci-whisper/actions/workflows/ci.yml/badge.svg)](https://github.com/mgkvibez/ci-whisper/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
+[![stars](https://img.shields.io/github/stars/mgkvibez/ci-whisper?style=flat&color=yellow)](https://github.com/mgkvibez/ci-whisper/stargazers)
+
+![ci-whisper demo](docs/demo/ci-whisper.svg)
+
+## Install
+
+```bash
+pipx install git+https://github.com/mgkvibez/ci-whisper.git
+```
+
+Until it is on PyPI, install from git. For development: `git clone && pip install -e ".[dev]"`.
+
+## Three ways to use it
+
+```bash
+# 1. The one you will use daily: pipe the failing job log
+gh run view --log-failed | ci-whisper
+
+# 2. From a downloaded log file
+ci-whisper --file /tmp/build.log
+
+# 3. Let it fetch the last failed run of the current repo
+ci-whisper --gh 16977481234
+
+# machine-readable, for a bot or an agent skill
+ci-whisper --file build.log --json
+```
+
+Exit code is `1` when no error signal is found, so you can gate on it.
+
+## Why it exists
+
+A red build hands you 10k lines. The actual cause is line 4, and everything after it is consequence: retries, cascading test failures, the polite `##[error]Process completed with exit code 1`.
+
+Two things go wrong when this hits an agent. It reads the *last* error and fixes a symptom, or it reads the header and summarises nothing. ci-whisper ranks signals so the cause outranks its own consequences, then shows the citations so anyone can check the call.
+
+## How it works
+
+1. **Clean** — strips ANSI and GitHub's `2026-10-29T08:01:02.1234567Z ` timestamp prefix, keeping a line-number map to the original file.
+2. **Scan** — matches a ranked rule set: `ModuleNotFoundError`/`Exception` (4) beat `Traceback`, test failures and compiler errors (3), which beat `npm ERR!` and `##[error]` (2), which beat a bare `exit code 1` (1).
+3. **Root cause** — highest severity, then earliest line. Noise (warnings, deprecations, `0 failed`, download progress) is filtered before ranking.
+4. **Chain** — the chosen line plus the following block: indented continuations, frames, and `caused by` style links.
+5. **Fix** — a rule per failure shape: peer dependency conflict, missing module, permissions, missing path, assertion, timeout, OOM.
+
+No network calls, no LLM, no dependencies.
+
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md). Tests:
+
+```bash
+python -m pytest -q
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

ci_whisper-0.1.1/ci_whisper/__init__.py

@@ -0,0 +1,3 @@
+"""ci-whisper: read a failed CI log, report the first real error and its cause."""
+
+__version__ = "0.1.0"

ci_whisper-0.1.1/ci_whisper/cli.py

@@ -0,0 +1,80 @@
+"""Command line entry point for ci-whisper."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __version__
+from .parse import Diagnosis, diagnose
+
+
+def read_log(args: argparse.Namespace) -> str:
+    """Get the log text from a file, stdin, or `gh run view`."""
+    if args.file:
+        return Path(args.file).read_text(encoding="utf-8", errors="replace")
+    if args.gh:
+        result = subprocess.run(
+            ["gh", "run", "view", args.gh, "--log-failed"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0 and not result.stdout:
+            print(f"ci-whisper: gh failed: {result.stderr.strip()}", file=sys.stderr)
+            raise SystemExit(2)
+        return result.stdout
+    if sys.stdin.isatty():
+        print("ci-whisper: pass a log on stdin, --file, or --gh <run-id>", file=sys.stderr)
+        raise SystemExit(2)
+    return sys.stdin.read()
+
+
+def render(diagnosis: Diagnosis) -> str:
+    """Human-readable report."""
+    out: list[str] = []
+    if diagnosis.root_cause is None:
+        out.append("No error found in this log.")
+        out.append(f"Scanned {diagnosis.scanned} lines, {diagnosis.signals} signals.")
+        return "\n".join(out)
+
+    root = diagnosis.root_cause
+    out.append("FIRST REAL ERROR")
+    out.append(f"  line {root.line_no}: {root.text}")
+    out.append("")
+    out.append("CAUSAL CHAIN")
+    for hit in diagnosis.chain:
+        role = "root" if hit is root else hit.kind
+        out.append(f"  {role:12} line {hit.line_no}: {hit.text}")
+    out.append("")
+    out.append("SUGGESTED FIX")
+    out.append(f"  {diagnosis.fix}")
+    out.append("")
+    out.append(f"Scanned {diagnosis.scanned} lines, {diagnosis.signals} signals.")
+    return "\n".join(out)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="ci-whisper",
+        description="Read a failed CI log and report the first real error, its chain, and a fix.",
+    )
+    parser.add_argument("--file", "-f", help="log file to read")
+    parser.add_argument("--gh", metavar="RUN_ID", help="GitHub Actions run id (uses gh run view)")
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    parser.add_argument("--version", action="version", version=f"ci-whisper {__version__}")
+    args = parser.parse_args(argv)
+
+    diagnosis = diagnose(read_log(args))
+    if args.json:
+        print(json.dumps(diagnosis.as_dict(), indent=2))
+    else:
+        print(render(diagnosis))
+    return 0 if diagnosis.root_cause else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ci_whisper-0.1.1/ci_whisper/parse.py

@@ -0,0 +1,215 @@
+"""Turn a raw CI log into a diagnosis."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Iterable
+
+from .patterns import (
+    ANSI_RE,
+    CAUSAL_HINTS,
+    FIX_RULES,
+    GO_COMPILER_ERROR_RE,
+    GO_PACKAGE_FAILURE_RE,
+    GO_TEST_FAILURE_RE,
+    NOISE,
+    STRONG_ERRORS,
+    TIMESTAMP_RE,
+)
+
+
+@dataclass
+class Hit:
+    """One signal found in the log."""
+
+    line_no: int
+    text: str
+    kind: str
+    strength: int
+
+
+@dataclass
+class Diagnosis:
+    """Result of reading a log."""
+
+    root_cause: Hit | None
+    chain: list[Hit] = field(default_factory=list)
+    fix: str = ""
+    phase: str = ""
+    scanned: int = 0
+    signals: int = 0
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "phase": self.phase,
+            "scanned_lines": self.scanned,
+            "signals": self.signals,
+            "root_cause": (
+                {
+                    "line": self.root_cause.line_no,
+                    "kind": self.root_cause.kind,
+                    "text": self.root_cause.text,
+                }
+                if self.root_cause
+                else None
+            ),
+            "chain": [
+                {"line": h.line_no, "kind": h.kind, "text": h.text} for h in self.chain
+            ],
+            "suggested_fix": self.fix,
+        }
+
+
+def clean_lines(raw: str) -> list[str]:
+    """Strip ANSI escapes and CI timestamps, keeping one entry per log line."""
+    out: list[str] = []
+    for line in raw.splitlines():
+        line = ANSI_RE.sub("", line)
+        line = TIMESTAMP_RE.sub("", line)
+        out.append(line.rstrip("\r"))
+    return out
+
+
+def is_noise(line: str) -> bool:
+    """True when a line looks like an error but is not worth reporting."""
+    return any(pattern.search(line) for pattern in NOISE)
+
+
+def classify(line: str) -> tuple[str, int] | None:
+    """Return (kind, strength) for a matching error line, else None."""
+    text = line.strip()
+    if not text or is_noise(text):
+        return None
+    # Go compiler diagnostics have no "error:" prefix. Keep indentation here:
+    # a test's indented source location is context, not a compiler error.
+    if GO_COMPILER_ERROR_RE.search(line):
+        return "compiler-error", 3
+    for kind, pattern in STRONG_ERRORS:
+        if pattern.search(text):
+            # The exception line is the cause; the Traceback header is only its preface.
+            if kind in {"module-not-found", "exception"}:
+                strength = 4
+            elif kind in {"python-traceback", "test-failure", "go-test-failure", "compiler-error"}:
+                strength = 3
+            elif kind in {"npm-error", "github-error"}:
+                strength = 2
+            else:
+                strength = 1
+            return kind, strength
+    return None
+
+
+def find_signals(lines: Iterable[str]) -> list[Hit]:
+    """Collect every non-noise error signal with its original line number."""
+    hits: list[Hit] = []
+    for index, line in enumerate(lines, start=1):
+        found = classify(line)
+        if found:
+            kind, strength = found
+            hits.append(Hit(line_no=index, text=line.strip(), kind=kind, strength=strength))
+    return hits
+
+
+def find_phase(lines: list[str]) -> str:
+    """Name the step that was running when the first signal appeared."""
+    current = ""
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("##[group]"):
+            current = stripped[len("##[group]") :].strip() or current
+        elif stripped.startswith("##[endgroup]"):
+            continue
+    return current
+
+
+def pick_root_cause(hits: list[Hit]) -> Hit | None:
+    """Choose the earliest strong signal; prefer structured errors over exit codes."""
+    if not hits:
+        return None
+    structured = [h for h in hits if h.strength >= 3]
+    if structured:
+        # Highest severity first, then earliest line: the exception beats its own preface.
+        return sorted(structured, key=lambda h: (-h.strength, h.line_no))[0]
+    non_exit = [h for h in hits if h.kind != "non-zero-exit"]
+    return (non_exit or hits)[0]
+
+
+def build_chain(root: Hit | None, hits: list[Hit], lines: list[str]) -> list[Hit]:
+    """Collect related signals: the root cause, its context, and later consequences."""
+    if root is None:
+        return []
+    chain: list[Hit] = [root]
+    downstream = [h for h in hits if h.line_no > root.line_no][:3]
+    chain.extend(downstream)
+    for offset in range(root.line_no, min(root.line_no + 12, len(lines) + 1)):
+        text = lines[offset - 1].strip()
+        if offset == root.line_no:
+            continue
+        if any(hint.search(text) for hint in CAUSAL_HINTS) and not is_noise(text):
+            chain.append(Hit(line_no=offset, text=text, kind="causal", strength=1))
+            break
+    seen: set[int] = set()
+    unique: list[Hit] = []
+    for hit in chain:
+        if hit.line_no not in seen:
+            seen.add(hit.line_no)
+            unique.append(hit)
+    return unique
+
+
+TEST_ID_RE = re.compile(r"^(?:FAILED\s+)?(?P<test>[\w./-]+\.py::[\w:.\[\]-]+)")
+
+
+def suggest_fix(root: Hit | None, lines: list[str] | None = None) -> str:
+    """Map the root cause to a concrete first action."""
+    if root is None:
+        return "No error signal found. The log may be truncated or the failure is a cancelled step."
+    if root.kind == "go-test-failure":
+        match = GO_TEST_FAILURE_RE.search(root.text)
+        if match:
+            package = ""
+            for line in (lines or [])[root.line_no:]:
+                text = line.strip()
+                if text.startswith(("##[group]", "##[endgroup]", "Run ")):
+                    break
+                result = GO_PACKAGE_FAILURE_RE.search(text)
+                if result:
+                    package = f" in package {result.group(1)}"
+                    break
+            return (
+                f"Go test {match.group(1)}{package} failed. Re-run it alone and inspect "
+                "its assertion output, then fix the expectation or the code it exercises."
+            )
+    if root.kind == "test-failure":
+        match = TEST_ID_RE.search(root.text)
+        if match:
+            detail = root.text.split(" - ", 1)[1] if " - " in root.text else root.text
+            return (
+                f"{match.group('test')} failed with {detail}. Run it alone to reproduce, "
+                "then fix the expectation or the code it exercises."
+            )
+    for pattern, template in FIX_RULES:
+        match = pattern.search(root.text)
+        if match:
+            groups = [g for g in match.groups() if g]
+            return template.format(*groups) if groups else template
+    return (
+        f"Read {root.text!r} at line {root.line_no}. The first real error is usually "
+        "the one before the cascade of non-zero exits."
+    )
+
+
+def diagnose(raw: str) -> Diagnosis:
+    """Full pipeline: clean, find signals, pick root cause, chain, fix."""
+    lines = clean_lines(raw)
+    hits = find_signals(lines)
+    root = pick_root_cause(hits)
+    return Diagnosis(
+        root_cause=root,
+        chain=build_chain(root, hits, lines),
+        fix=suggest_fix(root, lines),
+        phase=find_phase(lines),
+        scanned=len(lines),
+        signals=len(hits),
+    )

ci_whisper-0.1.1/ci_whisper/patterns.py

@@ -0,0 +1,74 @@
+"""Signal and noise patterns for CI log classification."""
+
+from __future__ import annotations
+
+import re
+
+ANSI_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+TIMESTAMP_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z\s?")
+JOB_PREFIX_RE = re.compile(r"^[^\t]*\t(?=[a-z-]+\t)")
+GO_TEST_FAILURE_RE = re.compile(r"^--- FAIL: (\S+) \(\d+(?:\.\d+)?s\)$")
+GO_PACKAGE_FAILURE_RE = re.compile(r"^FAIL\s+(\S+)\s+(?:\d+(?:\.\d+)?s|\[build failed\])(?:\s|$)")
+GO_COMPILER_ERROR_RE = re.compile(r"^\S+\.go:\d+:\d+:\s+\S")
+
+# Errors that are almost always the real cause.
+STRONG_ERRORS: list[tuple[str, re.Pattern[str]]] = [
+    ("python-traceback", re.compile(r"^Traceback \(most recent call last\):")),
+    ("module-not-found", re.compile(r"^ModuleNotFoundError:|^ImportError:")),
+    ("npm-error", re.compile(r"^npm ERR!")),
+    ("github-error", re.compile(r"^##\[error\]")),
+    ("compiler-error", re.compile(r"\berror(\[E\d+\])?:")),
+    ("go-test-failure", GO_TEST_FAILURE_RE),
+    ("test-failure", re.compile(r"^(FAILED|FAIL|✕|×)\b")),
+    ("fatal", re.compile(r"^fatal:")),
+    ("exception", re.compile(r"^[A-Za-z_.]+(Error|Exception):\s")),
+    ("non-zero-exit", re.compile(r"process completed with exit code [1-9]")),
+]
+
+# Lines that look like errors but are noise.
+NOISE: list[re.Pattern[str]] = [
+    re.compile(r"\b\d+\s+(passed|failed)=?\s*0 failed", re.IGNORECASE),
+    re.compile(r"^warning:?|^W\d{4}\b|\bWARN\b", re.IGNORECASE),
+    re.compile(r"deprecat", re.IGNORECASE),
+    re.compile(r"^\s*$"),
+    re.compile(r"^\s*\d+%|\bDownloading\b|\bCollecting\b", re.IGNORECASE),
+    re.compile(r"^npm WARN", re.IGNORECASE),
+    re.compile(r"\b0 errors?\b", re.IGNORECASE),
+]
+
+# Markers that a previous phase ended; errors after these are the interesting ones.
+PHASE_MARKERS: list[re.Pattern[str]] = [
+    re.compile(r"^##\[group\](.*)$"),
+    re.compile(r"^Run\s+(.+)$"),
+]
+
+CAUSAL_HINTS: list[re.Pattern[str]] = [
+    re.compile(r"caused by:", re.IGNORECASE),
+    re.compile(r"\bduring handling of the above exception", re.IGNORECASE),
+    re.compile(r"\bdue to\b", re.IGNORECASE),
+    re.compile(r"^The above exception was the direct cause", re.IGNORECASE),
+    re.compile(r"^\s+npm ERR!.*\n?", re.IGNORECASE),
+]
+
+FIX_RULES: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"ModuleNotFoundError: No module named '([^']+)'"),
+     "Install the missing module (pip install {0}) and add it to your dependencies so CI installs it."),
+    (re.compile(r"npm ERR! code ERESOLVE"),
+     "Peer dependency conflict: align the conflicting versions or use a compatible lockfile."),
+    (re.compile(r"npm ERR!.*ETARGET|No matching version found for (\S+)"),
+     "The requested version does not exist in the registry. Pin an existing version."),
+    (re.compile(r"Permission denied \(publickey\)|Host key verification failed"),
+     "The deploy key or known_hosts entry is missing or rotated. Check repository secrets."),
+    (re.compile(r"No such file or directory: '([^']+)'"),
+     "A required file is missing at {0}. Verify the checkout path and that the file is committed."),
+    (re.compile(r"EADDRINUSE|address already in use", re.IGNORECASE),
+     "Port conflict: the service is already bound. Kill the stale process or choose a free port."),
+    (re.compile(r"AssertionError"),
+     "An assertion failed: the actual value differs from the expected one. Read the assertion line for both values."),
+    (re.compile(r"SyntaxError"),
+     "The file does not parse. Fix the syntax before investigating anything downstream."),
+    (re.compile(r"Timeout|timed out", re.IGNORECASE),
+     "The step exceeded its time budget. Look for a hang or an unbounded network call."),
+    (re.compile(r"Killed|signal: killed|OutOfMemory", re.IGNORECASE),
+     "The process was killed, usually out of memory. Reduce memory use or raise the runner limit."),
+]

ci_whisper-0.1.1/ci_whisper.egg-info/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: ci-whisper
+Version: 0.1.1
+Summary: Read a failed CI log and get the first real error, its causal chain, and a fix.
+Author: mgkvibez
+License: MIT
+Keywords: ci,github-actions,logs,debugging,developer-tools,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# ci-whisper
+
+**Read a failed CI log. Get the first real error, its causal chain, and a fix.** One paragraph instead of ten thousand lines of noise.
+
+[![ci](https://github.com/mgkvibez/ci-whisper/actions/workflows/ci.yml/badge.svg)](https://github.com/mgkvibez/ci-whisper/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
+[![stars](https://img.shields.io/github/stars/mgkvibez/ci-whisper?style=flat&color=yellow)](https://github.com/mgkvibez/ci-whisper/stargazers)
+
+![ci-whisper demo](docs/demo/ci-whisper.svg)
+
+## Install
+
+```bash
+pipx install git+https://github.com/mgkvibez/ci-whisper.git
+```
+
+Until it is on PyPI, install from git. For development: `git clone && pip install -e ".[dev]"`.
+
+## Three ways to use it
+
+```bash
+# 1. The one you will use daily: pipe the failing job log
+gh run view --log-failed | ci-whisper
+
+# 2. From a downloaded log file
+ci-whisper --file /tmp/build.log
+
+# 3. Let it fetch the last failed run of the current repo
+ci-whisper --gh 16977481234
+
+# machine-readable, for a bot or an agent skill
+ci-whisper --file build.log --json
+```
+
+Exit code is `1` when no error signal is found, so you can gate on it.
+
+## Why it exists
+
+A red build hands you 10k lines. The actual cause is line 4, and everything after it is consequence: retries, cascading test failures, the polite `##[error]Process completed with exit code 1`.
+
+Two things go wrong when this hits an agent. It reads the *last* error and fixes a symptom, or it reads the header and summarises nothing. ci-whisper ranks signals so the cause outranks its own consequences, then shows the citations so anyone can check the call.
+
+## How it works
+
+1. **Clean** — strips ANSI and GitHub's `2026-10-29T08:01:02.1234567Z ` timestamp prefix, keeping a line-number map to the original file.
+2. **Scan** — matches a ranked rule set: `ModuleNotFoundError`/`Exception` (4) beat `Traceback`, test failures and compiler errors (3), which beat `npm ERR!` and `##[error]` (2), which beat a bare `exit code 1` (1).
+3. **Root cause** — highest severity, then earliest line. Noise (warnings, deprecations, `0 failed`, download progress) is filtered before ranking.
+4. **Chain** — the chosen line plus the following block: indented continuations, frames, and `caused by` style links.
+5. **Fix** — a rule per failure shape: peer dependency conflict, missing module, permissions, missing path, assertion, timeout, OOM.
+
+No network calls, no LLM, no dependencies.
+
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md). Tests:
+
+```bash
+python -m pytest -q
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

ci_whisper-0.1.1/ci_whisper.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+ci_whisper/__init__.py
+ci_whisper/cli.py
+ci_whisper/parse.py
+ci_whisper/patterns.py
+ci_whisper.egg-info/PKG-INFO
+ci_whisper.egg-info/SOURCES.txt
+ci_whisper.egg-info/dependency_links.txt
+ci_whisper.egg-info/entry_points.txt
+ci_whisper.egg-info/requires.txt
+ci_whisper.egg-info/top_level.txt
+tests/test_parse.py

ci_whisper-0.1.1/ci_whisper.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ci_whisper-0.1.1/ci_whisper.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ci-whisper = ci_whisper.cli:main

ci_whisper-0.1.1/ci_whisper.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=8

ci_whisper-0.1.1/ci_whisper.egg-info/top_level.txt

@@ -0,0 +1 @@
+ci_whisper

ci_whisper-0.1.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ci-whisper"
+version = "0.1.1"
+description = "Read a failed CI log and get the first real error, its causal chain, and a fix."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "mgkvibez" }]
+keywords = ["ci", "github-actions", "logs", "debugging", "developer-tools", "agents"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+ci-whisper = "ci_whisper.cli:main"
+
+[tool.setuptools]
+packages = ["ci_whisper"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ci_whisper-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ci_whisper-0.1.1/tests/test_parse.py

@@ -0,0 +1,123 @@
+"""Tests for ci_whisper.parse."""
+
+from pathlib import Path
+
+from ci_whisper.parse import classify, clean_lines, diagnose, suggest_fix
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def load(name: str) -> str:
+    return (FIXTURES / name).read_text(encoding="utf-8")
+
+
+def test_pytest_failure_finds_assertion_not_exit_code():
+    diagnosis = diagnose(load("pytest_fail.log"))
+    assert diagnosis.root_cause is not None
+    assert diagnosis.root_cause.kind == "test-failure"
+    assert "test_render_header" in diagnosis.root_cause.text
+    assert "test_render_header" in diagnosis.fix
+
+
+def test_npm_failure_reports_eresolve_and_ignores_deprecation():
+    diagnosis = diagnose(load("npm_fail.log"))
+    assert diagnosis.root_cause is not None
+    assert diagnosis.root_cause.kind == "npm-error"
+    assert "ERESOLVE" in diagnosis.root_cause.text
+    assert "Peer dependency" in diagnosis.fix
+
+
+def test_traceback_uses_module_not_found_rule():
+    diagnosis = diagnose(load("traceback.log"))
+    assert diagnosis.root_cause is not None
+    assert "No module named 'yaml'" in diagnosis.root_cause.text
+    assert "pip install yaml" in diagnosis.fix
+
+
+def test_noise_only_log_reports_no_error():
+    diagnosis = diagnose(load("noise_only.log"))
+    assert diagnosis.root_cause is None
+    assert "No error signal found" in diagnosis.fix
+
+
+def test_line_numbers_point_at_the_source_line():
+    raw = load("pytest_fail.log")
+    diagnosis = diagnose(raw)
+    lines = clean_lines(raw)
+    root = diagnosis.root_cause
+    assert root is not None
+    assert lines[root.line_no - 1].strip() == root.text
+
+
+def test_chain_is_ordered_and_unique():
+    diagnosis = diagnose(load("pytest_fail.log"))
+    numbers = [hit.line_no for hit in diagnosis.chain]
+    assert numbers == sorted(numbers)
+    assert len(numbers) == len(set(numbers))
+    assert diagnosis.chain[0].line_no == diagnosis.root_cause.line_no
+
+
+def test_suggest_fix_handles_none():
+    assert suggest_fix(None).startswith("No error signal found")
+
+
+def test_exit_code_only_log_falls_back_to_exit_signal():
+    diagnosis = diagnose("##[error]Process completed with exit code 1.")
+    assert diagnosis.root_cause is not None
+    assert diagnosis.root_cause.kind == "github-error"
+
+
+def test_go_failure_names_test_and_package_not_summary():
+    diagnosis = diagnose(load("go_fail.log"))
+    assert diagnosis.root_cause is not None
+    assert diagnosis.root_cause.kind == "go-test-failure"
+    assert diagnosis.root_cause.strength == 3
+    assert diagnosis.root_cause.line_no == 3
+    assert diagnosis.root_cause.text == "--- FAIL: TestTotal (0.00s)"
+    assert "TestTotal" in diagnosis.fix
+    assert "example.com/shop/cart" in diagnosis.fix
+    assert "example.com/shop/cache" not in diagnosis.fix
+
+
+def test_go_failure_does_not_outrank_earlier_compiler_error():
+    raw = (
+        "2026-10-29T08:01:01.0000000Z # example.com/shop/broken\n"
+        "2026-10-29T08:01:01.0000000Z broken/main.go:3:9: undefined: missing\n"
+        "2026-10-29T08:01:01.0000000Z FAIL\texample.com/shop/broken [build failed]\n"
+        + load("go_fail.log")
+    )
+    diagnosis = diagnose(raw)
+    assert diagnosis.root_cause is not None
+    assert diagnosis.root_cause.kind == "compiler-error"
+    assert diagnosis.root_cause.line_no == 2
+    assert "undefined: missing" in diagnosis.root_cause.text
+    assert "TestTotal" not in diagnosis.fix
+
+
+def test_go_subtest_and_missing_package_summary():
+    diagnosis = diagnose(
+        "    --- FAIL: TestTotal/discount (0.01s)\n"
+        "        cart_test.go:12: total = 12, want 10\n"
+    )
+    assert diagnosis.root_cause is not None
+    assert diagnosis.root_cause.kind == "go-test-failure"
+    assert "TestTotal/discount" in diagnosis.fix
+    assert "package" not in diagnosis.fix
+    assert suggest_fix(diagnosis.root_cause) == diagnosis.fix
+
+
+def test_go_package_lookup_stops_at_next_ci_step():
+    diagnosis = diagnose(
+        "--- FAIL: TestTotal (0.00s)\n"
+        "##[endgroup]\n"
+        "##[group]Run go test ./other\n"
+        "FAIL\texample.com/other\t0.001s\n"
+    )
+    assert "TestTotal" in diagnosis.fix
+    assert "example.com/other" not in diagnosis.fix
+
+
+def test_go_passing_tests_and_indented_source_locations_are_not_errors():
+    assert classify("--- PASS: TestTotal (0.00s)") is None
+    assert classify("    cart_test.go:12:9: a diagnostic from a test") is None
+    assert classify("--- FAIL: this is not a Go test result") is None