replico 0.1.0__py3-none-any.whl

replico/__init__.py

@@ -0,0 +1,7 @@
+"""Replico — CI failures, reproduced locally.
+
+Replico turns a failed GitHub Actions run into a locally reproducible
+failure whenever it can reconstruct the relevant conditions.
+"""
+
+__version__ = "0.1.0"

replico/__main__.py

@@ -0,0 +1,6 @@
+"""Allow `python -m replico`."""
+
+from replico.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

replico/analysis/__init__.py

@@ -0,0 +1 @@
+"""Log analysis and failure classification."""

replico/analysis/classifier.py

@@ -0,0 +1,304 @@
+"""Evidence-based failure classification.
+
+Classification is a set of ordered rules over observed evidence. Replico
+never invents an explanation: when nothing matches, the category is UNKNOWN
+with a low confidence and a note saying so.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from replico.models import FailureEvidence
+
+# Failure categories (stable identifiers, documented in README).
+DEPENDENCY_FAILURE = "DEPENDENCY_FAILURE"
+VERSION_FAILURE = "VERSION_FAILURE"
+PYTHON_VERSION_FAILURE = "PYTHON_VERSION_FAILURE"
+NODE_VERSION_FAILURE = "NODE_VERSION_FAILURE"
+OS_DIFFERENCE = "OS_DIFFERENCE"
+ENVIRONMENT_VARIABLE = "ENVIRONMENT_VARIABLE"
+MISSING_TOOL = "MISSING_TOOL"
+MISSING_FILE = "MISSING_FILE"
+TEST_FAILURE = "TEST_FAILURE"
+BUILD_FAILURE = "BUILD_FAILURE"
+NETWORK_FAILURE = "NETWORK_FAILURE"
+TIMEOUT = "TIMEOUT"
+PERMISSION_FAILURE = "PERMISSION_FAILURE"
+WORKFLOW_CONFIGURATION = "WORKFLOW_CONFIGURATION"
+UNKNOWN = "UNKNOWN"
+
+CATEGORY_NAMES = {
+    DEPENDENCY_FAILURE: "dependency failure",
+    VERSION_FAILURE: "version failure",
+    PYTHON_VERSION_FAILURE: "Python version failure",
+    NODE_VERSION_FAILURE: "Node version failure",
+    OS_DIFFERENCE: "OS difference",
+    ENVIRONMENT_VARIABLE: "missing/different environment variable",
+    MISSING_TOOL: "missing tool/executable",
+    MISSING_FILE: "missing file",
+    TEST_FAILURE: "test failure",
+    BUILD_FAILURE: "build failure",
+    NETWORK_FAILURE: "network failure",
+    TIMEOUT: "timeout",
+    PERMISSION_FAILURE: "permission failure",
+    WORKFLOW_CONFIGURATION: "workflow configuration",
+    UNKNOWN: "unknown",
+}
+
+
+@dataclass
+class FailureClassification:
+    category: str = UNKNOWN
+    confidence: int = 0  # 0..100
+    explanation: list[str] = field(default_factory=list)
+    kind: str = ""
+
+
+@dataclass
+class _Rule:
+    name: str
+    patterns: list[re.Pattern]
+    category: str
+    confidence: int
+    explanation: str
+
+
+_RULES: list[_Rule] = []
+
+
+def _rule(name, category, confidence, explanation, *patterns):
+    _RULES.append(
+        _Rule(
+            name=name,
+            patterns=[re.compile(p, re.IGNORECASE) for p in patterns],
+            category=category,
+            confidence=confidence,
+            explanation=explanation,
+        )
+    )
+
+
+_rule(
+    "python_missing_package",
+    DEPENDENCY_FAILURE,
+    90,
+    "Python reported a missing module, which usually means CI installed a "
+    "dependency that is not present (or not installed) locally.",
+    r"ModuleNotFoundError:\s*No module named '([^']+)'",
+    r"ImportError:\s*No module named",
+    r"Could not import",
+)
+_rule(
+    "pip_resolution",
+    DEPENDENCY_FAILURE,
+    92,
+    "The package resolver could not find a satisfying set of versions; CI and "
+    "local dependency graphs are likely out of sync.",
+    r"ResolutionImpossible",
+    r"No matching distribution found",
+    r"Could not find a version that satisfies",
+    r"pip.*(?:conflict|resolution|incompatible)",
+    r"ERROR: Cannot install",
+)
+_rule(
+    "pytest_failure",
+    TEST_FAILURE,
+    94,
+    "A pytest test failed in CI. Compare the failing test id with the local run "
+    "to confirm the same test fails locally.",
+    r"FAILED\s+\S+::\S+",
+    r"short test summary info",
+)
+_rule(
+    "assertion",
+    TEST_FAILURE,
+    85,
+    "An assertion failed during execution — behavior differs between CI and the local environment.",
+    r"AssertionError",
+    r"assert\s",
+)
+_rule(
+    "python_version_required",
+    PYTHON_VERSION_FAILURE,
+    88,
+    "The toolchain reported a Python interpreter requirement that is not met.",
+    r"requires Python >=? ?\d+\.\d+",
+    r"Python \d+\.\d+.*(?:required|needed)",
+    r"not supported.*python",
+    r"RuntimeError: Python \d+\.\d+",
+)
+_rule(
+    "node_version_required",
+    NODE_VERSION_FAILURE,
+    88,
+    "Node reported an engine/version requirement that is not satisfied.",
+    r"Unsupported engine",
+    r"requires node >=? ?\d+",
+    r"engine \"node\"",
+    r"ENOTSUP",
+    r"v\d+\.\d+\.\d+.*not supported|not supported.*node",
+)
+_rule(
+    "missing_executable",
+    MISSING_TOOL,
+    88,
+    "A tool invoked by the workflow is not installed in the environment.",
+    r"(?:command not found|is not recognized|not recognized as an? internal)",
+    r"execvp\(.*No such file",
+    r"The process ['\"]?[^'\"]+['\"]? failed with exit code 127",
+    r"FileNotFoundError: \[Errno 2\].*No such file or directory: '([^']+)'",
+)
+_rule(
+    "missing_file",
+    MISSING_FILE,
+    86,
+    "A file referenced by the workflow does not exist in the repository or "
+    "was not produced before the failing step.",
+    r"No such file or directory",
+    r"cannot open file ['\"]?([^'\"]+)['\"]?",
+    r"error: pathspec ['\"]?[^'\"]+['\"]? did not match",
+)
+_rule(
+    "timeout",
+    TIMEOUT,
+    92,
+    "The run exceeded a time budget (step or job timeout).",
+    r"timed out|timed?out",
+    r"The operation was canceled",
+    r"##\[error\]The operation was canceled",
+    r"exit code 124",
+)
+_rule(
+    "network",
+    NETWORK_FAILURE,
+    86,
+    "A network operation failed (download, package registry, DNS).",
+    r"Could not resolve host|Temporary failure in name resolution",
+    r"Connection (?:refused|reset|timed out)",
+    r"Failed to (?:download|fetch|connect)",
+    r"ssl: (?:wrong version number|certificate verify failed)",
+    r"getaddrinfo failed",
+    r"EAI_AGAIN",
+)
+_rule(
+    "permission",
+    PERMISSION_FAILURE,
+    88,
+    "An operation failed because of missing permissions.",
+    r"Permission denied",
+    r"PermissionError",
+    r"EACCES|EPERM",
+    r"Access is denied",
+    r"denied \(publickey\)",
+)
+_rule(
+    "build_compile",
+    BUILD_FAILURE,
+    84,
+    "Compilation or a language build step failed.",
+    r"(^|[\s'\"])error(\[E\d+\])?:[^\n]*",
+    r"fatal error:",
+    r"error: linking",
+    r"Build FAILED",
+    r"gcc: error",
+    r"cargo build.*failed",
+)
+_rule(
+    "env_missing",
+    ENVIRONMENT_VARIABLE,
+    85,
+    "An environment variable that the code expects was not provided.",
+    r"KeyError: ['\"]([A-Z_]+)['\"]",
+    r"Environment variable ['\"]?([A-Z_]+)['\"]? (?:is|was) not (?:set|found)",
+    r"os\.environ\[[^\]]+\].*KeyError",
+    r"Missing environment variable",
+)
+_rule(
+    "workflow_config",
+    WORKFLOW_CONFIGURATION,
+    80,
+    "The workflow itself is invalid or references something that does not exist.",
+    r"Workflow does not have|Invalid workflow file",
+    r"Unable to resolve action",
+    r"Error: .*action.*not found",
+    r"Could not find action",
+)
+_rule(
+    "segfault_crash",
+    BUILD_FAILURE,
+    80,
+    "The process crashed (segfault / killed), often due to an environment "
+    "difference such as compiler flags or memory limits.",
+    r"Segmentation fault",
+    r"^Killed$",
+)
+_rule(
+    "docker_missing",
+    MISSING_TOOL,
+    90,
+    "Docker is required by the workflow but was not available in the runner.",
+    r"docker: (?:command not found|Cannot connect)",
+    r"Cannot connect to the Docker daemon",
+)
+_rule(
+    "git_missing",
+    MISSING_TOOL,
+    88,
+    "git reported a problem resolving the requested ref.",
+    r"fatal: (?:not a git repository|repository .* not found|ambiguous argument)",
+)
+
+
+def classify(evidence: FailureEvidence) -> FailureClassification:
+    """Classify CI (or local) failure evidence using ordered rules."""
+    haystack = "\n".join(evidence.lines)
+    if evidence.summary:
+        haystack = f"{haystack}\n{evidence.summary}"
+
+    best: FailureClassification | None = None
+    for rule in _RULES:
+        for pattern in rule.patterns:
+            match = pattern.search(haystack)
+            if match:
+                detail = ""
+                groups = [g for g in match.groups() if g]
+                if groups:
+                    detail = f" — {groups[0]}"
+                classification = FailureClassification(
+                    category=rule.category,
+                    confidence=rule.confidence,
+                    kind=rule.name,
+                    explanation=[f"{rule.explanation}{detail}"],
+                )
+                if best is None or classification.confidence > best.confidence:
+                    best = classification
+                break
+    if best is None:
+        return FailureClassification(
+            category=UNKNOWN,
+            confidence=25,
+            explanation=[
+                "Replico cannot map the log output to a known failure "
+                "category; treat any reproduction claim with care."
+            ],
+        )
+    # clamp confidence when the summary did not actually match much text
+    if len(evidence.lines) == 0:
+        best.confidence = min(best.confidence, 40)
+    return best
+
+
+def signature(evidence: FailureEvidence) -> str:
+    """A stable signature identifying *this* failure.
+
+    Prefers failing test ids; otherwise uses category + a normalized summary
+    prefix so identical errors compare equal while versions/dates do not.
+    """
+    if evidence.failing_tests:
+        return "tests:" + ",".join(sorted(evidence.failing_tests))
+    kind = evidence.category_hint or "?"
+    summary = re.sub(r"[0-9]+\.[0-9]+", "X.Y", evidence.summary)
+    normalized = re.sub(r"[^A-Za-z0-9]+", " ", summary).strip().lower()[:80]
+    return f"{kind}:{normalized or 'none'}"

replico/analysis/logs.py

@@ -0,0 +1,216 @@
+"""Smart log analysis.
+
+Turns hundreds of lines of CI output into a handful of relevant lines.
+These functions are pure (no I/O) so they can be unit tested with fixture
+logs. Redaction happens at display/persistence time, not here.
+"""
+
+from __future__ import annotations
+
+import re
+
+from replico.models import FailureEvidence
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+_GROUP_RE = re.compile(r"^##\[group\](.*)$")
+_GROUP_END_RE = re.compile(r"^##\[endgroup\]")
+
+_FAILED_TEST_RE = re.compile(r"^FAILED\s+([^\s]+?)(?:\s+-|$)")
+_FAILED_TEST_SUMMARY_RE = re.compile(r"^=+.*failed.*=+$")
+
+_MAX_RELEVANT_LINES = 30
+_CONTEXT_BEFORE = 3
+_CONTEXT_AFTER = 12
+
+
+def strip_ansi(line: str) -> str:
+    return _ANSI_RE.sub("", line)
+
+
+def split_step_segments(log: str) -> list[tuple[str | None, list[str]]]:
+    """Split a job log into per-step segments using GitHub's group markers.
+
+    Returns ``[(step_name_or_None, [lines...])]``. When markers are absent a
+    single segment covers the whole log.
+    """
+    segments: list[tuple[str | None, list[str]]] = []
+    current_name: str | None = None
+    current: list[str] = []
+    for raw in log.splitlines():
+        line = strip_ansi(raw)
+        match = _GROUP_RE.match(line)
+        if match:
+            if current or current_name is not None:
+                segments.append((current_name, current))
+            current = []
+            current_name = match.group(1).strip() or None
+            continue
+        if _GROUP_END_RE.match(line):
+            if current or current_name is not None:
+                segments.append((current_name, current))
+            current = []
+            current_name = None
+            continue
+        current.append(line)
+    if current or current_name is not None:
+        segments.append((current_name, current))
+    if not segments:
+        segments.append((None, [strip_ansi(line) for line in log.splitlines()]))
+    return segments
+
+
+class _Finding:
+    __slots__ = ("kind", "line", "snippet")
+
+    def __init__(self, kind: str, line: int, snippet: list[str]) -> None:
+        self.kind = kind
+        self.line = line
+        self.snippet = snippet
+
+
+def _python_traceback_finding(lines: list[str]) -> _Finding | None:
+    """Last traceback: exception summary + the frame that raised it."""
+    trace_indexes = [
+        i for i, line in enumerate(lines) if "Traceback (most recent call last)" in line
+    ]
+    if not trace_indexes:
+        return None
+    start = trace_indexes[-1]
+    snippet: list[str] = []
+    for i in range(start + 1, min(len(lines), start + 40)):
+        line = lines[i]
+        if not line.strip():
+            if snippet and snippet[-1].strip() == "":
+                break
+            snippet.append(line)
+            continue
+        if (
+            re.match(r"^\s*File \"", line)
+            and snippet
+            and re.match(r"^\s*(File \"|Traceback)", snippet[-1])
+        ):
+            # another frame; keep appending lines but only the last matters
+            pass
+        snippet.append(line)
+        if re.match(r"^(?:[A-Za-z_][\w.]*\.)*[A-Za-z_][\w]*Error", line.strip()):
+            break
+    snippet[-1].strip() if snippet else ""
+    return _Finding("traceback", start, snippet[:15])
+
+
+def _findings_in(lines: list[str]) -> list[_Finding]:
+    findings: list[_Finding] = []
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if not stripped or stripped.startswith(("##[group", "##[endgroup", "::")):
+            continue
+        if stripped.startswith("##[error]"):
+            findings.append(_Finding("error_marker", i, [stripped[:400]]))
+            continue
+        # pytest failure summary: FAILED path - reason
+        if _FAILED_TEST_RE.match(stripped):
+            snippet = lines[max(0, i - 1) : i + 1]
+            findings.append(_Finding("test_failure", i, snippet))
+        elif stripped.startswith("ModuleNotFoundError") or stripped.startswith("ImportError"):
+            findings.append(_Finding("import_error", i, [lines[max(0, i - 2)], line]))
+        elif stripped.startswith("##[error]"):
+            findings.append(_Finding("error_marker", i, [line[:400]]))
+        elif re.match(r"^Error: Process completed with exit code", stripped):
+            findings.append(_Finding("exit_code", i, [line]))
+        elif re.search(r"command not found|is not recognized|No such file or directory", stripped):
+            findings.append(_Finding("missing_command", i, [line]))
+        elif re.search(
+            r"permission denied|PermissionError|Access is denied|denied \(publickey\)", stripped
+        ):
+            findings.append(_Finding("permission", i, [line]))
+        elif re.search(
+            r"timed? ?out|The operation was canceled|OperationCanceledException", stripped, re.I
+        ):
+            findings.append(_Finding("timeout", i, [line]))
+        elif stripped.startswith("npm ERR!") or re.match(r"^npm error ", stripped):
+            findings.append(_Finding("npm_error", i, [line[:400]]))
+        elif re.match(r"^error(\[|:)", stripped, re.I):
+            findings.append(_Finding("compiler_error", i, [line[:400]]))
+        elif re.search(
+            r"error: .*Failed to download|Could not find a version|ResolutionImpossible|No matching distribution",
+            stripped,
+        ):
+            findings.append(_Finding("dependency_error", i, [line[:400]]))
+        elif stripped.startswith("Killed") or "Segmentation fault" in stripped:
+            findings.append(_Finding("crash", i, [line]))
+    tb = _python_traceback_finding(lines)
+    if tb is not None:
+        findings.append(tb)
+    return findings
+
+
+_STRONG = {
+    "test_failure",
+    "import_error",
+    "dependency_error",
+    "timeout",
+    "crash",
+    "permission",
+}
+
+
+def _failing_tests(lines: list[str]) -> list[str]:
+    tests: list[str] = []
+    for line in lines:
+        match = _FAILED_TEST_RE.match(line.strip())
+        if match:
+            tests.append(match.group(1))
+    return list(dict.fromkeys(tests))
+
+
+def _summary_for(lines: list[str], kind: str) -> str:
+    compact = [re.sub(r"\s+", " ", line).strip() for line in lines if line.strip()]
+    if kind == "test_failure":
+        return compact[-1][:300] if compact else ""
+    if kind == "traceback":
+        # exception line
+        return compact[-1][:300] if compact else ""
+    if kind == "exit_code":
+        return compact[-1][:200] if compact else ""
+    return compact[0][:300] if compact else ""
+
+
+def analyze_log(log: str, source: str = "") -> FailureEvidence:
+    """Condense a raw CI log into focused, relevant evidence."""
+    lines = [strip_ansi(line) for line in log.splitlines()]
+    tests = _failing_tests(lines)
+    findings = _findings_in(lines)
+
+    evidence = FailureEvidence(source=source, failing_tests=tests)
+    if not findings:
+        tail = [line for line in lines[-12:] if line.strip()]
+        if tail:
+            evidence.lines = tail
+            evidence.line_numbers = list(range(len(lines) - len(tail) + 1, len(lines) + 1))
+            evidence.summary = "no structured error found; showing the tail of the log"
+            evidence.category_hint = "unknown"
+        return evidence
+
+    # Pick the strongest finding, preferring a pytest failure / traceback.
+    def rank(f: _Finding) -> tuple[int, int]:
+        if f.kind in _STRONG:
+            return (0, 0 if f.kind == "test_failure" else 1)
+        return (1, 0)
+
+    findings.sort(key=lambda f: (rank(f)[0], f.line))
+    primary = findings[0]
+    window: list[str] = []
+    indexes: list[int] = []
+    start = max(0, primary.line - _CONTEXT_BEFORE)
+    end = min(len(lines), primary.line + _CONTEXT_AFTER)
+    for idx in range(start, end):
+        if lines[idx].strip() or idx == primary.line:
+            window.append(lines[idx])
+            indexes.append(idx + 1)
+        if len(window) >= _MAX_RELEVANT_LINES:
+            break
+    evidence.lines = window
+    evidence.line_numbers = indexes
+    evidence.category_hint = primary.kind
+    evidence.summary = _summary_for(primary.snippet or window, primary.kind)
+    return evidence