pr-context-engine 0.1.0__py3-none-any.whl

src/context/git_history.py

@@ -0,0 +1,225 @@
+"""Git history context for changed files.
+
+Fetches the last N commit messages per file via git log, and optionally
+resolves the most recent merged PRs that touched the same files via the
+GitHub REST API.
+
+Degrades gracefully on shallow clones (workflow uses fetch-depth: 50) or
+when git/network is unavailable — callers receive limited_history=True and
+an empty commit list rather than an exception.  See docs/design-decisions.md
+for the deliberate shallow-clone tradeoff.
+"""
+import logging
+import re
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import requests
+
+from src.github_api import GITHUB_API_URL
+
+logger = logging.getLogger(__name__)
+
+_GIT_LOG_LIMIT = 5
+_PR_MERGE_SCAN = 30  # merge commits to scan when searching for PR numbers
+_MAX_PRS = 3
+_REQUEST_TIMEOUT = 10
+
+
+@dataclass
+class CommitRecord:
+    """A single commit's abbreviated hash and subject line."""
+
+    sha: str
+    message: str
+
+
+@dataclass
+class FileHistory:
+    """Recent commit history for one changed file."""
+
+    file_path: str
+    recent_commits: list[CommitRecord] = field(default_factory=list)
+    limited_history: bool = False
+
+
+@dataclass
+class RecentPR:
+    """A recently merged PR that touched one of the changed files."""
+
+    number: int
+    title: str
+    body_first_line: str
+
+
+def get_file_histories(
+    file_paths: list[str],
+    repo_root: str = ".",
+    max_commits: int = _GIT_LOG_LIMIT,
+) -> dict[str, FileHistory]:
+    """Return recent commit history for each file path.
+
+    Args:
+        file_paths: Repo-relative paths of changed files.
+        repo_root: Root of the git repository.
+        max_commits: Maximum commits to fetch per file.
+
+    Returns:
+        Mapping of file_path -> FileHistory. Files with no discoverable
+        history still get an entry (empty commits, limited_history=True).
+    """
+    root = Path(repo_root).resolve()
+    return {path: _fetch_file_history(path, root, max_commits) for path in file_paths}
+
+
+def get_recent_merged_prs(
+    file_paths: list[str],
+    repo: str,
+    github_token: str,
+    repo_root: str = ".",
+    max_prs: int = _MAX_PRS,
+) -> list[RecentPR]:
+    """Find the most recent merged PRs that touched any of the given files.
+
+    Uses git merge-commit messages to locate PR numbers, then fetches details
+    via the GitHub API.  Returns an empty list when git or the API is
+    unavailable rather than raising.
+
+    Args:
+        file_paths: Repo-relative paths of changed files.
+        repo: Repository in "owner/name" form.
+        github_token: GitHub token used for API requests.
+        repo_root: Root of the git repository.
+        max_prs: Maximum number of PRs to return.
+
+    Returns:
+        List of RecentPR, most recent first.
+    """
+    if not file_paths:
+        return []
+
+    root = Path(repo_root).resolve()
+    pr_numbers = _find_pr_numbers_from_merges(file_paths, root)
+    if not pr_numbers:
+        return []
+
+    headers = {
+        "Authorization": f"token {github_token}",
+        "Accept": "application/vnd.github.v3+json",
+    }
+
+    prs: list[RecentPR] = []
+    for pr_number in pr_numbers:
+        if len(prs) >= max_prs:
+            break
+        pr = _fetch_pr_details(repo, pr_number, headers)
+        if pr is not None:
+            prs.append(pr)
+
+    return prs
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+def _fetch_file_history(path: str, root: Path, max_commits: int) -> FileHistory:
+    """Run git log for a single file and return its FileHistory."""
+    try:
+        result = subprocess.run(
+            [
+                "git",
+                "log",
+                "--follow",
+                f"--max-count={max_commits}",
+                "--format=%H %s",
+                "--",
+                path,
+            ],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=10,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired) as exc:
+        logger.warning("git log failed for %s: %s", path, exc)
+        return FileHistory(file_path=path, limited_history=True)
+
+    commits: list[CommitRecord] = []
+    for line in result.stdout.strip().splitlines():
+        if not line.strip():
+            continue
+        sha, _, message = line.partition(" ")
+        commits.append(CommitRecord(sha=sha[:8], message=message))
+
+    # git log silently returns fewer commits on shallow clones without any
+    # stderr output; hitting the limit is the only reliable signal.
+    limited = len(commits) == max_commits
+
+    return FileHistory(file_path=path, recent_commits=commits, limited_history=limited)
+
+
+def _find_pr_numbers_from_merges(file_paths: list[str], root: Path) -> list[int]:
+    """Extract PR numbers from merge commits that touched any of the given files."""
+    try:
+        result = subprocess.run(
+            [
+                "git",
+                "log",
+                "--merges",
+                f"--max-count={_PR_MERGE_SCAN}",
+                "--format=%s",
+                "--",
+                *file_paths,
+            ],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=15,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired) as exc:
+        logger.warning("git log --merges failed: %s", exc)
+        return []
+
+    # Matches:
+    #   "Merge pull request #N from ..." (GitHub standard merge)
+    #   "Merge PR #N ..."               (shorthand)
+    #   "feat: something (#N)"          (GitHub squash merge)
+    pattern = re.compile(r"(?:(?:pull\s+request|PR)\s+#(\d+)|\(#(\d+)\))", re.IGNORECASE)
+    seen: set[int] = set()
+    numbers: list[int] = []
+
+    for line in result.stdout.strip().splitlines():
+        match = pattern.search(line)
+        if match:
+            num = int(match.group(1) or match.group(2))
+            if num not in seen:
+                seen.add(num)
+                numbers.append(num)
+
+    return numbers
+
+
+def _fetch_pr_details(repo: str, pr_number: int, headers: dict[str, str]) -> RecentPR | None:
+    """Fetch PR title and body from GitHub API; returns None when unavailable."""
+    url = f"{GITHUB_API_URL}/repos/{repo}/pulls/{pr_number}"
+    try:
+        resp = requests.get(url, headers=headers, timeout=_REQUEST_TIMEOUT)
+        resp.raise_for_status()
+    except requests.RequestException as exc:
+        logger.warning("GitHub API request failed for PR #%d: %s", pr_number, exc)
+        return None
+
+    data = resp.json()
+    if not data.get("merged_at"):
+        return None  # ignore open or closed-unmerged PRs
+
+    title = (data.get("title") or "").strip()
+    body = data.get("body") or ""
+    body_first_line = body.split("\n")[0].strip()[:200]
+
+    return RecentPR(number=pr_number, title=title, body_first_line=body_first_line)

src/fixes/__init__.py

@@ -0,0 +1 @@
+"""Opt-in fix suggestion generation with confidence gating (Milestone 8)."""

src/fixes/confidence.py

@@ -0,0 +1,60 @@
+"""Confidence gating: decides which fix suggestions become collapsed code blocks vs prose.
+
+High and medium confidence fixes (with a non-None patch) are formatted as collapsed
+<details> blocks with a fenced code snippet. Low confidence (or missing patch) is
+rendered as a prose warning only.
+
+Note: GitHub's ```suggestion fence only works in line-level review comments, not in
+general PR body comments. We use language-inferred fences so the patch renders as
+readable code regardless of comment type.
+"""
+from src.analyzers.diff_parser import detect_language
+from src.fixes.fix_generator import FixSuggestion
+
+
+def _lang_from_path(path: str) -> str:
+    return detect_language(path)
+
+_CONFIDENCE_ICONS = {
+    "high": "🔴",
+    "medium": "🟡",
+    "low": "⚠️",
+}
+
+
+def is_block_eligible(suggestion: FixSuggestion) -> bool:
+    """True when confidence is high or medium AND a patch is present.
+
+    Low confidence suggestions must never produce a suggestion block even if
+    the LLM accidentally emitted patch text — the parser already nulls the patch
+    on low confidence, but this gate adds a second layer of enforcement.
+    """
+    return suggestion.confidence in ("high", "medium") and suggestion.patch is not None
+
+
+def format_suggestion_block(suggestion: FixSuggestion) -> str:
+    """Render a high/medium confidence fix as a collapsed <details> block with a code patch."""
+    icon = _CONFIDENCE_ICONS.get(suggestion.confidence, "💡")
+    flag_label = suggestion.flag.flag
+    location = f"`{suggestion.flag.file}:{suggestion.flag.line}`"
+    lang = _lang_from_path(suggestion.flag.file)
+
+    return (
+        f"<details>\n"
+        f"<summary>{icon} <strong>{suggestion.confidence} confidence</strong>"
+        f" — {flag_label} in {location}</summary>\n\n"
+        f"**Rationale:** {suggestion.rationale}\n\n"
+        f"```{lang}\n{suggestion.patch}\n```\n\n"
+        f"</details>\n"
+    )
+
+
+def format_prose_note(suggestion: FixSuggestion) -> str:
+    """Render a low-confidence fix (or missing patch) as a prose-only warning."""
+    icon = _CONFIDENCE_ICONS.get(suggestion.confidence, "⚠️")
+    flag_label = suggestion.flag.flag
+    location = f"`{suggestion.flag.file}:{suggestion.flag.line}`"
+    return (
+        f"> {icon} **{suggestion.confidence}** — {flag_label} in {location}: "
+        f"{suggestion.rationale}\n"
+    )

src/fixes/fix_generator.py

@@ -0,0 +1,152 @@
+"""Generate fix suggestions for located risk flags via a separate LLM call.
+
+Each call targets a single RiskFlag with a concrete line number and asks the LLM
+for a minimal replacement patch plus a confidence self-assessment. Low-confidence
+responses intentionally produce no patch — a wrong fix is worse than no fix.
+"""
+import logging
+from dataclasses import dataclass
+
+from src.analyzers.diff_parser import FileChange
+from src.analyzers.risk_scorer import RiskFlag
+from src.briefing.prompt_templates import FIX_SYSTEM_PROMPT
+from src.llm.base import LLMProvider
+
+logger = logging.getLogger(__name__)
+
+_MAX_CONTEXT_LINES = 40
+
+
+@dataclass
+class FixSuggestion:
+    """A suggested fix for a specific risk flag."""
+
+    flag: RiskFlag
+    patch: str | None  # replacement code; None when confidence is low or generation failed
+    rationale: str
+    confidence: str  # "high" | "medium" | "low"
+
+
+def generate_fixes(
+    provider: LLMProvider,
+    flags: list[RiskFlag],
+    changes: list[FileChange],
+    max_fixes: int = 3,
+) -> tuple[list[FixSuggestion], int]:
+    """Generate fix suggestions for up to max_fixes eligible flags.
+
+    Only flags with a non-null line number are fix-eligible. Returns a tuple of
+    (suggestions, extra_count) where extra_count is how many eligible flags were
+    skipped due to the cap.
+
+    Args:
+        provider: LLM provider instance for generation calls.
+        flags: All risk flags from the current PR.
+        changes: Parsed file changes (used to extract surrounding code context).
+        max_fixes: Maximum number of fix suggestions to generate (default 3).
+
+    Returns:
+        Tuple of (list of FixSuggestion, number of eligible flags beyond the cap).
+    """
+    eligible = [f for f in flags if f.line is not None]
+    capped = eligible[:max_fixes]
+    extra_count = len(eligible) - len(capped)
+
+    suggestions: list[FixSuggestion] = []
+    for flag in capped:
+        suggestion = _generate_single_fix(provider, flag, changes)
+        suggestions.append(suggestion)
+
+    return suggestions, extra_count
+
+
+def _generate_single_fix(
+    provider: LLMProvider,
+    flag: RiskFlag,
+    changes: list[FileChange],
+) -> FixSuggestion:
+    """Make one LLM call to generate a fix for a single located flag."""
+    context = _get_flag_context(flag, changes)
+    prompt = _build_fix_prompt(flag, context)
+
+    try:
+        response = provider.generate(prompt)
+    except Exception as exc:
+        logger.warning("Fix generation failed for %s:%s: %s", flag.file, flag.line, exc)
+        return FixSuggestion(
+            flag=flag,
+            patch=None,
+            rationale="Fix generation failed — see briefing for details.",
+            confidence="low",
+        )
+
+    return _parse_fix_response(flag, response)
+
+
+def _get_flag_context(flag: RiskFlag, changes: list[FileChange]) -> str:
+    """Extract the diff hunk containing the flagged line as context.
+
+    Checks both old-file and new-file line ranges so both modifies_auth
+    (new-file lines) and deletes_public_api (old-file lines) are handled.
+    Falls back to the flag snippet if no matching hunk is found.
+    """
+    for change in changes:
+        if change.path != flag.file:
+            continue
+        for hunk in change.hunks:
+            new_end = hunk.new_start + max(hunk.new_count, 1)
+            old_end = hunk.old_start + max(hunk.old_count, 1)
+            line = flag.line or 0
+            if hunk.new_start <= line < new_end or hunk.old_start <= line < old_end:
+                return "\n".join(hunk.lines[:_MAX_CONTEXT_LINES])
+    return flag.snippet
+
+
+def _build_fix_prompt(flag: RiskFlag, context: str) -> str:
+    """Assemble the full prompt: system instructions + flag context."""
+    user_section = (
+        f"Flag type: {flag.flag}\n"
+        f"File: {flag.file}\n"
+        f"Line: {flag.line}\n"
+        f"Flagged snippet: {flag.snippet}\n\n"
+        f"Surrounding diff context:\n```\n{context}\n```"
+    )
+    return f"{FIX_SYSTEM_PROMPT}\n\n---\n\n{user_section}"
+
+
+def _parse_fix_response(flag: RiskFlag, response: str) -> FixSuggestion:
+    """Parse structured fix response (CONFIDENCE / RATIONALE / PATCH) from LLM."""
+    confidence = "low"
+    rationale = ""
+    patch_lines: list[str] = []
+    in_patch = False
+
+    for line in response.strip().splitlines():
+        stripped = line.strip()
+        if stripped.upper().startswith("CONFIDENCE:"):
+            raw = stripped.split(":", 1)[1].strip().lower()
+            if raw in ("high", "medium", "low"):
+                confidence = raw
+        elif stripped.upper().startswith("RATIONALE:"):
+            rationale = stripped.split(":", 1)[1].strip()
+        elif stripped.upper().startswith("PATCH:"):
+            in_patch = True
+        elif in_patch:
+            patch_lines.append(line)
+
+    patch: str | None = None
+    if patch_lines:
+        raw_patch = "\n".join(patch_lines).strip()
+        if raw_patch and raw_patch.upper() != "NO_PATCH":
+            patch = raw_patch
+
+    # Enforce hard rule: low confidence must never carry a patch block.
+    if confidence == "low":
+        patch = None
+
+    return FixSuggestion(
+        flag=flag,
+        patch=patch,
+        rationale=rationale or flag.snippet,
+        confidence=confidence,
+    )

src/github_api/__init__.py

@@ -0,0 +1,3 @@
+"""GitHub API access: fetch pull request diffs and post review comments."""
+
+GITHUB_API_URL = "https://api.github.com"

src/github_api/comment_poster.py

@@ -0,0 +1,95 @@
+"""GitHub REST access for a PR: fetch its unified diff and post a comment.
+
+format_fix_section() renders Milestone 8 fix suggestions as collapsed <details>
+blocks (high/medium confidence) or prose warnings (low confidence) suitable for
+appending to the main briefing comment body.
+"""
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import requests
+from github import Auth, Github
+
+from src.github_api import GITHUB_API_URL
+
+if TYPE_CHECKING:
+    from src.fixes.fix_generator import FixSuggestion
+
+logger = logging.getLogger(__name__)
+
+_API_VERSION = "2022-11-28"
+
+
+def fetch_pr_diff(repo: str, pr_number: int, github_token: str | None) -> str:
+    """Fetch the unified diff of a pull request.
+
+    `repo` is in `owner/name` form. Returns the raw unified-diff text.
+    Omits the Authorization header when `github_token` is None (anonymous, public repos only).
+    """
+    url = f"{GITHUB_API_URL}/repos/{repo}/pulls/{pr_number}"
+    headers: dict[str, str] = {
+        "Accept": "application/vnd.github.diff",
+        "X-GitHub-Api-Version": _API_VERSION,
+    }
+    if github_token:
+        headers["Authorization"] = f"Bearer {github_token}"
+    logger.info("Fetching diff for %s PR #%d", repo, pr_number)
+    try:
+        response = requests.get(url, headers=headers, timeout=30)
+    except requests.RequestException as exc:
+        raise RuntimeError(f"Network error fetching PR diff: {exc}") from exc
+    if not response.ok:
+        logger.error("GitHub API error %d: %s", response.status_code, response.text[:300])
+    response.raise_for_status()
+    return response.text
+
+
+def post_pr_comment(repo: str, pr_number: int, body: str, github_token: str) -> None:
+    """Post `body` as a general (issue-level) comment on the pull request.
+
+    `repo` is in `owner/name` form.
+    """
+    logger.info("Posting comment to %s PR #%d", repo, pr_number)
+    gh = Github(auth=Auth.Token(github_token))
+    pull_request = gh.get_repo(repo).get_pull(pr_number)
+    pull_request.create_issue_comment(body)
+
+
+def format_fix_section(suggestions: list[FixSuggestion], extra_count: int = 0) -> str:
+    """Render fix suggestions as a markdown section for appending to the briefing comment.
+
+    High/medium confidence suggestions with a patch become collapsed <details> blocks.
+    Low confidence (or missing patch) suggestions become prose warnings only.
+    If extra_count > 0, a trailing note indicates how many eligible flags were skipped.
+
+    Args:
+        suggestions: List of FixSuggestion objects (may mix confidence levels).
+        extra_count: Number of fix-eligible flags beyond the 3-suggestion cap.
+
+    Returns:
+        Markdown string ready to append after the briefing's closing `---` line.
+        Returns empty string if suggestions is empty.
+    """
+    # Deferred to avoid pulling src.fixes into comment_poster at module load time;
+    # this module is imported by cli.py regardless of whether fixes are enabled.
+    from src.fixes.confidence import format_prose_note, format_suggestion_block, is_block_eligible
+
+    if not suggestions:
+        return ""
+
+    parts: list[str] = ["\n\n### 💡 Fix Suggestions\n\n"]
+
+    for suggestion in suggestions:
+        if is_block_eligible(suggestion):
+            parts.append(format_suggestion_block(suggestion))
+            parts.append("\n")
+        else:
+            parts.append(format_prose_note(suggestion))
+
+    if extra_count > 0:
+        noun = "issue" if extra_count == 1 else "issues"
+        parts.append(f"\n_{extra_count} more {noun} detected — see Risk Flags above._\n")
+
+    return "".join(parts)

src/llm/__init__.py

@@ -0,0 +1,106 @@
+"""LLM provider abstraction: a provider-agnostic interface and its implementations.
+
+Exports FailoverProvider — wraps an ordered list of providers and tries each in
+sequence, recording which one succeeded and why others were skipped. This is the
+runtime payoff for the ADR-0 provider abstraction built in Milestone 2.
+"""
+import logging
+from dataclasses import dataclass
+
+from src.llm.base import LLMProvider
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class _ProviderAttempt:
+    name: str
+    was_rate_limited: bool
+
+
+class FailoverProvider(LLMProvider):
+    """Try providers in order; fall back on rate-limit or any error.
+
+    After a successful generate() call:
+      - provider_used: name of the provider that responded
+      - skipped: records of providers that were tried and failed
+
+    Call attribution() after generate() to get a footer-friendly string such as
+    "groq" or "gemini (groq rate-limited)".
+    """
+
+    def __init__(self, providers: list[tuple[str, LLMProvider]]) -> None:
+        """
+        Args:
+            providers: Ordered list of (name, provider) pairs. First is tried first.
+        """
+        if not providers:
+            raise ValueError("FailoverProvider requires at least one provider")
+        self._providers = providers
+        self.provider_used: str | None = None
+        self.skipped: list[_ProviderAttempt] = []
+
+    def generate(self, prompt: str) -> str:
+        """Try each provider in order; return the first successful response."""
+        self.provider_used = None
+        self.skipped = []
+        last_exc: Exception | None = None
+
+        for name, provider in self._providers:
+            try:
+                result = provider.generate(prompt)
+                self.provider_used = name
+                logger.info("Provider %s succeeded", name)
+                return result
+            except (TypeError, AttributeError):
+                raise
+            except Exception as exc:
+                is_rate_limited = _is_rate_limit_error(exc)
+                self.skipped.append(_ProviderAttempt(name=name, was_rate_limited=is_rate_limited))
+                if is_rate_limited:
+                    logger.warning("Provider %s rate-limited; trying next", name)
+                else:
+                    logger.warning("Provider %s failed (%s); trying next", name, exc)
+                last_exc = exc
+
+        raise RuntimeError(
+            f"All {len(self._providers)} provider(s) failed. Last error: {last_exc}"
+        ) from last_exc
+
+    def attribution(self) -> str:
+        """One-line attribution for the PR comment footer.
+
+        Must be called after generate(). Raises RuntimeError if generate() has not
+        been called yet.
+
+        Examples:
+            "groq"
+            "gemini (groq rate-limited)"
+            "gemini (groq failed)"
+            "all providers failed"
+        """
+        if self.provider_used is None and not self.skipped:
+            raise RuntimeError("attribution() called before generate()")
+        if self.provider_used is None:
+            return "all providers failed"
+        if not self.skipped:
+            return self.provider_used
+
+        rate_limited = [s.name for s in self.skipped if s.was_rate_limited]
+        errors = [s.name for s in self.skipped if not s.was_rate_limited]
+        reasons: list[str] = []
+        if rate_limited:
+            reasons.append(f"{', '.join(rate_limited)} rate-limited")
+        if errors:
+            reasons.append(f"{', '.join(errors)} failed")
+        return f"{self.provider_used} ({'; '.join(reasons)})"
+
+
+def _is_rate_limit_error(exc: Exception) -> bool:
+    """Return True if exc represents a rate-limit or quota exhaustion error."""
+    msg = str(exc).lower()
+    keywords = ("rate limit", "rate_limit", "quota", "429", "resource exhausted", "too many requests")
+    if any(kw in msg for kw in keywords):
+        return True
+    status = getattr(exc, "status_code", None) or getattr(exc, "code", None)
+    return status == 429

src/llm/anthropic_provider.py

@@ -0,0 +1,32 @@
+"""Anthropic Claude-backed LLMProvider implementation (model: claude-sonnet-4-6)."""
+import logging
+
+import anthropic
+
+from src.llm.base import LLMProvider
+
+logger = logging.getLogger(__name__)
+
+_MODEL = "claude-sonnet-4-6"
+_MAX_TOKENS = 1024
+
+
+class AnthropicProvider(LLMProvider):
+    """Calls the Anthropic Messages API to satisfy the LLMProvider contract."""
+
+    def __init__(self, api_key: str) -> None:
+        """Build an Anthropic client from an explicit API key."""
+        self._client = anthropic.Anthropic(api_key=api_key)
+
+    def generate(self, prompt: str) -> str:
+        """Send `prompt` as a single user message and return the completion text."""
+        logger.info("Requesting Anthropic completion (model=%s)", _MODEL)
+        message = self._client.messages.create(
+            model=_MODEL,
+            max_tokens=_MAX_TOKENS,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        if not message.content or not message.content[0].text:
+            raise RuntimeError("Anthropic returned an empty completion")
+        text = message.content[0].text
+        return text

src/llm/base.py

@@ -0,0 +1,11 @@
+"""Abstract LLM provider contract — the single interface all providers implement."""
+from abc import ABC, abstractmethod
+
+
+class LLMProvider(ABC):
+    """Provider-agnostic LLM interface. One method; no provider types leak out."""
+
+    @abstractmethod
+    def generate(self, prompt: str) -> str:
+        """Return the model's text completion for the given prompt."""
+        ...