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

src/briefing/generator.py

@@ -0,0 +1,229 @@
+"""Generate structured PR briefings using LLM with senior-voice prompting."""
+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 SYSTEM_PROMPT
+from src.context.codebase_index import RelatedChunk
+from src.context.git_history import FileHistory, RecentPR
+from src.llm.base import LLMProvider
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Briefing:
+    """A structured PR briefing generated by the LLM."""
+
+    what_changed: str
+    blast_radius: str
+    risk_flags: str
+    questions: str
+    raw_response: str
+
+
+def generate_briefing(
+    provider: LLMProvider,
+    changes: list[FileChange],
+    changed_symbols: dict[str, list[str]],
+    flags: list[RiskFlag],
+    related_code: dict[str, list[RelatedChunk]] | None = None,
+    git_history: dict[str, FileHistory] | None = None,
+    recent_prs: list[RecentPR] | None = None,
+) -> Briefing:
+    """Generate a structured briefing from diff analysis.
+
+    Args:
+        provider: LLM provider instance to call for generation.
+        changes: List of parsed file changes from the diff.
+        changed_symbols: Mapping of file paths to changed function/class names.
+        flags: Risk flags detected by heuristic analysis.
+        related_code: Optional mapping of file paths to semantically similar chunks from the repo.
+        git_history: Optional mapping of file paths to their recent commit history.
+        recent_prs: Optional list of recently merged PRs touching the same files.
+
+    Returns:
+        A Briefing object with structured sections.
+
+    Raises:
+        RuntimeError: If the LLM provider fails to generate a response.
+    """
+    prompt = _assemble_prompt(changes, changed_symbols, flags, related_code, git_history, recent_prs)
+    logger.info("Assembled prompt (%d chars)", len(prompt))
+
+    try:
+        raw_response = provider.generate(prompt)
+    except Exception as exc:
+        raise RuntimeError(f"LLM provider failed to generate briefing: {exc}") from exc
+
+    logger.info("Generated briefing (%d chars)", len(raw_response))
+
+    # Parse the LLM response into structured sections.
+    # The LLM is prompted to follow a specific format, so we parse by section headers.
+    sections = _parse_sections(raw_response)
+
+    briefing = Briefing(
+        what_changed=sections.get("what_changed", ""),
+        blast_radius=sections.get("blast_radius", ""),
+        risk_flags=sections.get("risk_flags", ""),
+        questions=sections.get("questions", ""),
+        raw_response=raw_response,
+    )
+
+    _validate_briefing(briefing)
+    return briefing
+
+
+def _assemble_prompt(
+    changes: list[FileChange],
+    changed_symbols: dict[str, list[str]],
+    flags: list[RiskFlag],
+    related_code: dict[str, list[RelatedChunk]] | None = None,
+    git_history: dict[str, FileHistory] | None = None,
+    recent_prs: list[RecentPR] | None = None,
+) -> str:
+    """Assemble the full prompt: system prompt + structured context."""
+    parts: list[str] = [SYSTEM_PROMPT]
+
+    parts.append("\n---\n## CONTEXT\n")
+
+    parts.append("### Changed files\n")
+    for change in changes:
+        if change.is_new_file:
+            action = "new file"
+        elif change.is_deleted_file:
+            action = "deleted"
+        else:
+            action = "modified"
+
+        symbols = changed_symbols.get(change.path, [])
+        symbol_str = f" — symbols: {', '.join(symbols)}" if symbols else ""
+        parts.append(
+            f"- `{change.path}` ({change.language}, {action})"
+            f" +{len(change.added_lines)}/-{len(change.removed_lines)} lines{symbol_str}\n"
+        )
+
+    parts.append("\n### Risk flags\n")
+    if flags:
+        for flag in flags:
+            loc = f":{flag.line}" if flag.line is not None else ""
+            parts.append(f"- [{flag.flag}] `{flag.file}{loc}` — {flag.snippet}\n")
+    else:
+        parts.append("None detected.\n")
+
+    if git_history:
+        parts.append("\n### Recent activity on touched files\n")
+        for file_path, history in git_history.items():
+            if not history.recent_commits and not history.limited_history:
+                continue
+            parts.append(f"\n**`{file_path}`**")
+            if history.limited_history and not history.recent_commits:
+                parts.append(" — limited history (shallow clone)\n")
+            else:
+                if history.limited_history:
+                    parts.append(" (history may be truncated — shallow clone)")
+                parts.append("\n")
+                for commit in history.recent_commits:
+                    parts.append(f"- `{commit.sha}` {commit.message}\n")
+
+    if recent_prs:
+        parts.append("\n### Recent merged PRs touching these files\n")
+        for pr in recent_prs:
+            desc = f" — {pr.body_first_line}" if pr.body_first_line else ""
+            parts.append(f"- PR #{pr.number}: \"{pr.title}\"{desc}\n")
+
+    if related_code:
+        parts.append("\n### Related code (semantically similar, from elsewhere in repo)\n")
+        for file_path, chunks in related_code.items():
+            if not chunks:
+                continue
+            parts.append(f"\n**Related to `{file_path}`:**\n")
+            for chunk in chunks[:3]:
+                # Truncate long chunks to keep prompt under token budget
+                snippet = chunk.chunk_text[:400]
+                if len(chunk.chunk_text) > 400:
+                    snippet += "\n..."
+                parts.append(f"- `{chunk.file_path}` ({chunk.label}):\n```\n{snippet}\n```\n")
+
+    return "".join(parts)
+
+
+def _parse_sections(response: str) -> dict[str, str]:
+    """Parse LLM response into section keys.
+
+    The LLM is prompted to structure output as:
+    1. WHAT CHANGED
+    2. BLAST RADIUS
+    3. RISK FLAGS
+    4. QUESTIONS
+
+    This parser extracts content for each numbered section. If a section is not
+    found, it returns an empty string for that section.
+    """
+    sections: dict[str, str] = {
+        "what_changed": "",
+        "blast_radius": "",
+        "risk_flags": "",
+        "questions": "",
+    }
+
+    # Check for section headers in order of specificity (longest first)
+    # Only use full section names to avoid matching content lines like "1. Why?"
+    section_headers = [
+        ("1. WHAT CHANGED", "what_changed"),
+        ("2. BLAST RADIUS", "blast_radius"),
+        ("3. RISK FLAGS", "risk_flags"),
+        ("4. QUESTIONS", "questions"),
+    ]
+
+    lines = response.split("\n")
+    current_section = None
+    current_content: list[str] = []
+    found_sections = set()
+
+    for line in lines:
+        # Check if this line starts a new section (full header match only)
+        section_found = False
+        stripped = line.strip()
+        for section_header, section_key in section_headers:
+            if stripped.startswith(section_header):
+                # Save the previous section content
+                if current_section:
+                    sections[current_section] = "\n".join(current_content).strip()
+                current_section = section_key
+                found_sections.add(section_key)
+                current_content = []
+                section_found = True
+                break
+
+        # If this line doesn't start a new section and we're in a section, collect the content
+        if not section_found and current_section is not None:
+            current_content.append(line)
+
+    # Save the last section
+    if current_section:
+        sections[current_section] = "\n".join(current_content).strip()
+
+    # Log which sections were found for debugging
+    missing = set(sections.keys()) - found_sections
+    if missing:
+        logger.warning("Missing expected sections in LLM response: %s", ", ".join(sorted(missing)))
+
+    return sections
+
+
+def _validate_briefing(briefing: Briefing) -> None:
+    """Validate that briefing sections have meaningful content.
+
+    Logs warnings if any section is unexpectedly empty, which indicates the LLM
+    may not have followed the expected format or the parsing failed.
+    """
+    if not briefing.what_changed.strip():
+        logger.warning("Briefing section 'what_changed' is empty")
+    if not briefing.blast_radius.strip():
+        logger.warning("Briefing section 'blast_radius' is empty")
+    if not briefing.risk_flags.strip():
+        logger.warning("Briefing section 'risk_flags' is empty")
+    if not briefing.questions.strip():
+        logger.warning("Briefing section 'questions' is empty")

src/briefing/prompt_templates.py

@@ -0,0 +1,67 @@
+"""System prompt and prompt-assembly utilities for generating senior-voice PR briefings.
+
+FIX_SYSTEM_PROMPT is used exclusively by the fix generator for per-flag LLM calls.
+It is never merged into SYSTEM_PROMPT so the briefing behaviour is unchanged when
+ENABLE_FIXES=false.
+"""
+
+SYSTEM_PROMPT = """You are a senior backend engineer reviewing a pull request. You have 90 seconds.
+Your job is to brief the human reviewer so they can review effectively.
+
+You will receive:
+- A list of changed files with parsed function/class names
+- Risk flags detected by static heuristics
+- Recent commit history on touched files
+- Semantically related code from elsewhere in the repo
+
+Produce a briefing with exactly four sections:
+
+1. WHAT CHANGED — 2-3 sentences. Describe the *intent* of the change, not the
+   lines. Do not list files. If you can't tell the intent, say so.
+
+2. BLAST RADIUS — Which callers, services, contracts, or data could break?
+   Be specific. If the change is internal and self-contained, write "Self-contained."
+
+3. RISK FLAGS — Bullet list. Only include flags that are actually present.
+   If none, write "None."
+
+4. QUESTIONS — Exactly three questions a senior reviewer would ask before
+   approving. Questions must be answerable and specific. Bad question:
+   "Did you test this?" Good question: "The new retry loop in fetch_user
+   has no backoff — is that intentional given this is called per-request?"
+
+Rules:
+- Be terse. Aim for under 200 words total.
+- No praise. No "this looks good." No emojis except the section icons.
+- If the PR is trivial (typo fix, doc change), say so in one line and skip
+  the other sections.
+- Never speculate about things you can't see. If you don't have the context,
+  say "Cannot tell from diff."
+"""
+
+FIX_SYSTEM_PROMPT = """You are a senior backend engineer. A static-analysis heuristic has flagged \
+a specific line in a pull request. Your job is to suggest a minimal, correct fix — or decline \
+if you are not confident.
+
+You will receive:
+- The flag type and its location (file and line number)
+- The flagged code snippet
+- The surrounding diff context (lines prefixed with +, -, or space)
+
+Respond in this EXACT format with no extra text before or after:
+
+CONFIDENCE: <high|medium|low>
+RATIONALE: <one sentence explaining the problem and what the fix addresses>
+PATCH:
+<the replacement code for the flagged line(s), or NO_PATCH if confidence is low>
+
+Rules:
+- CONFIDENCE must be high, medium, or low — no other values.
+- If you are not confident the patch is correct and complete, label it low.
+- A wrong fix is worse than no fix. When in doubt, choose low.
+- PATCH must be a drop-in replacement for the flagged line(s) only.
+  Do not include surrounding context lines in the patch.
+- If CONFIDENCE is low, write NO_PATCH on the PATCH line.
+- The PATCH must be syntactically valid for the file's language.
+- Never produce a suggestion block for vague observations; only for concrete, specific problems.
+"""

src/cli.py

@@ -0,0 +1,329 @@
+"""Typer CLI — the single entrypoint; orchestrates fetch-diff, analyze, summarize, post."""
+import logging
+import os
+
+import requests
+import typer
+from dotenv import load_dotenv
+
+from src.analyzers.ast_walker import extract_changed_symbols
+from src.analyzers.diff_parser import FileChange, parse_diff
+from src.analyzers.risk_scorer import score
+from src.briefing.generator import Briefing, generate_briefing
+from src.config import get_failover_provider, is_fixes_enabled
+from src.context.codebase_index import CodebaseIndex, RelatedChunk
+from src.context.git_history import FileHistory, RecentPR, get_file_histories, get_recent_merged_prs
+from src.fixes.fix_generator import generate_fixes
+from src.github_api.comment_poster import fetch_pr_diff, format_fix_section, post_pr_comment
+
+load_dotenv()
+logger = logging.getLogger(__name__)
+
+app = typer.Typer(help="PR Context Engine — brief a pull request.")
+
+_MAX_DIFF_LINES = 4_000  # ~8k tokens; avoids hitting provider context limits on large PRs
+
+
+@app.callback()
+def main() -> None:
+    """PR Context Engine — brief a pull request for human reviewers.
+
+    This callback exists so Typer keeps `review` as an explicit subcommand. A
+    single-command Typer app otherwise collapses the command and drops its name,
+    which would break the documented `pr-context-engine review ...` invocation.
+    """
+    logging.basicConfig(level=logging.INFO)
+
+
+@app.command()
+def review(
+    pr: int = typer.Option(..., "--pr", help="Pull request number."),
+    repo: str = typer.Option(..., "--repo", help="Repository in owner/name form."),
+    github_token: str | None = typer.Option(
+        None, envvar="GITHUB_TOKEN", help="GitHub token with pull-requests:write."
+    ),
+    enable_fixes: bool = typer.Option(
+        False,
+        "--enable-fixes/--no-enable-fixes",
+        envvar="ENABLE_FIXES",
+        help="Generate confidence-gated fix suggestions (opt-in, default off).",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Print the briefing to stdout instead of posting it to GitHub.",
+    ),
+) -> None:
+    """Fetch a PR's diff, analyze it structurally, and post an AI-generated briefing."""
+    if not github_token and not dry_run:
+        raise typer.BadParameter("GITHUB_TOKEN is not set (flag or env var).")
+
+    # Typer's envvar= already handles ENABLE_FIXES for CLI invocations; this
+    # covers programmatic callers of review() that bypass Typer argument parsing.
+    enable_fixes = enable_fixes or is_fixes_enabled()
+
+    raw_diff = fetch_pr_diff(repo, pr, github_token)
+    logger.info("Fetched diff (%d chars)", len(raw_diff))
+
+    changes = parse_diff(raw_diff)
+    logger.info("Parsed %d file changes", len(changes))
+
+    # Drop whole FileChanges once the running line budget is exhausted so the parser
+    # always sees complete hunks — slicing raw diff text mid-file leaves incomplete objects.
+    budget = _MAX_DIFF_LINES
+    trimmed: list[FileChange] = []
+    for change in changes:
+        file_lines = len(change.added_lines) + len(change.removed_lines)
+        if budget <= 0:
+            break
+        trimmed.append(change)
+        budget -= file_lines
+    if len(trimmed) < len(changes):
+        logger.warning("Dropped %d files beyond %d-line budget", len(changes) - len(trimmed), _MAX_DIFF_LINES)
+    changes = trimmed
+
+    changed_symbols: dict[str, list[str]] = {}
+    for change in changes:
+        syms = extract_changed_symbols(change)
+        if syms:
+            changed_symbols[change.path] = syms
+
+    flags = score(changes)
+    logger.info("Detected %d risk flags", len(flags))
+
+    related_code = _build_related_code(changes, changed_symbols)
+    git_history, recent_prs = _build_git_context(changes, repo, github_token)
+
+    try:
+        provider = get_failover_provider()
+    except (RuntimeError, ValueError) as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    try:
+        briefing = generate_briefing(
+            provider, changes, changed_symbols, flags, related_code, git_history, recent_prs
+        )
+    except RuntimeError as exc:
+        logger.error("Briefing generation failed: %s", exc)
+        if dry_run:
+            typer.echo(_format_error(str(exc)))
+        elif github_token:
+            post_pr_comment(repo, pr, _format_error(str(exc)), github_token)
+        raise typer.Exit(code=1)
+
+    logger.info("Generated briefing sections (via %s)", provider.attribution())
+
+    fix_section = ""
+    if enable_fixes:
+        logger.info("Fix suggestions enabled — generating for eligible flags")
+        suggestions, extra_count = generate_fixes(provider, flags, changes)
+        logger.info(
+            "Generated %d fix suggestion(s) (%d skipped by cap)",
+            len(suggestions),
+            extra_count,
+        )
+        fix_section = format_fix_section(suggestions, extra_count)
+
+    comment_text = _format_briefing(
+        briefing,
+        provider_attribution=provider.attribution(),
+        fix_section=fix_section,
+    )
+    if dry_run:
+        typer.echo(comment_text)
+        logger.info("Dry-run mode — briefing printed to stdout, not posted to GitHub")
+    else:
+        if not github_token:
+            raise RuntimeError("github_token must be set when not in dry-run mode")
+        post_pr_comment(repo, pr, comment_text, github_token)
+        logger.info("Comment posted to %s PR #%d", repo, pr)
+
+
+def _build_related_code(
+    changes: list[FileChange],
+    changed_symbols: dict[str, list[str]],
+) -> dict[str, list[RelatedChunk]]:
+    """Build and query the codebase index for each changed file.
+
+    Returns an empty dict if indexing fails (e.g. sqlite-vec extension unavailable
+    on this platform) so the briefing still works without RAG context.
+    """
+    try:
+        index = CodebaseIndex(repo_root=".")
+        index.build_or_update()
+    except Exception as exc:
+        logger.warning("Codebase index unavailable — skipping related-code context: %s", exc)
+        return {}
+
+    exclude = {c.path for c in changes}
+    related: dict[str, list[RelatedChunk]] = {}
+    for change in changes:
+        query_text = _file_change_query(change, changed_symbols.get(change.path, []))
+        chunks = index.query(query_text, exclude_paths=exclude, top_k=5)
+        if chunks:
+            related[change.path] = chunks
+
+    return related
+
+
+def _file_change_query(change: FileChange, symbols: list[str]) -> str:
+    """Build a query string representing a file change for embedding lookup."""
+    parts = [change.path]
+    if symbols:
+        parts.append("functions: " + ", ".join(symbols[:10]))
+    if change.added_lines:
+        parts.append("\n".join(change.added_lines[:20]))
+    return "\n".join(parts)
+
+
+def _build_git_context(
+    changes: list[FileChange],
+    repo: str,
+    github_token: str | None,
+) -> tuple[dict[str, FileHistory], list[RecentPR]]:
+    """Fetch git history and recent merged PRs for changed files.
+
+    Returns an empty dict/list on any failure so the briefing still works
+    without history context.
+    """
+    file_paths = [c.path for c in changes]
+
+    try:
+        git_history = get_file_histories(file_paths, repo_root=".")
+        logger.info("Fetched git history for %d files", len(git_history))
+    except Exception as exc:
+        logger.warning("Git history unavailable: %s", exc)
+        git_history = {}
+
+    recent_prs: list[RecentPR] = []
+    if github_token:
+        try:
+            recent_prs = get_recent_merged_prs(file_paths, repo, github_token, repo_root=".")
+            logger.info("Found %d recent merged PRs", len(recent_prs))
+        except Exception as exc:
+            logger.warning("Recent PR lookup failed: %s", exc)
+
+    return git_history, recent_prs
+
+
+def _format_briefing(
+    briefing: Briefing,
+    provider_attribution: str | None = None,
+    fix_section: str = "",
+) -> str:
+    """Format structured briefing into markdown comment for GitHub.
+
+    Produces a professional briefing with sections for what changed, blast
+    radius, risk flags, and review questions. When fix_section is non-empty
+    (ENABLE_FIXES=true), it is inserted between the questions and the footer.
+    """
+    via = f" via {provider_attribution}" if provider_attribution else ""
+    parts: list[str] = [
+        "## 🤖 PR Briefing\n",
+        "**What changed**\n",
+        briefing.what_changed,
+        "\n\n**Blast radius**\n",
+        briefing.blast_radius,
+        "\n\n**Risk flags**\n",
+        briefing.risk_flags,
+        "\n\n**Questions for the reviewer**\n",
+        briefing.questions,
+        "\n\n---\n",
+    ]
+
+    if fix_section:
+        parts.append(fix_section)
+        parts.append("\n---\n")
+
+    parts.append(
+        f"\n<sub>Generated by [PR Context Engine](https://github.com/paramahastha/pr-context-engine){via}. "
+        "Not a substitute for human review.</sub>"
+    )
+
+    return "".join(parts)
+
+
+def _format_error(error: str) -> str:
+    """Format a briefing-failure notice as a GitHub PR comment."""
+    return (
+        "## 🤖 PR Briefing\n\n"
+        f"**Briefing failed:** {error}\n\n"
+        "Check your API keys and rate limits.\n\n"
+        "---\n"
+        "\n<sub>Generated by [PR Context Engine](https://github.com/paramahastha/pr-context-engine). "
+        "Not a substitute for human review.</sub>"
+    )
+
+
+@app.command()
+def quickstart() -> None:
+    """Check environment setup and print exactly what is missing before first use."""
+    ok = True
+
+    def check(name: str, present: bool, hint: str) -> None:
+        nonlocal ok
+        if present:
+            typer.echo(f"  [ok] {name}")
+        else:
+            typer.echo(f"  [!!] {name} — {hint}")
+            ok = False
+
+    provider = os.environ.get("LLM_PROVIDER", "groq")
+    typer.echo("\nChecking provider keys...")
+    if provider == "ollama":
+        typer.echo("  [ok] LLM_PROVIDER=ollama — no API key required")
+    else:
+        groq_key = bool(os.environ.get("GROQ_API_KEY"))
+        gemini_key = bool(os.environ.get("GEMINI_API_KEY"))
+        anthropic_key = bool(os.environ.get("ANTHROPIC_API_KEY"))
+        any_key = groq_key or gemini_key or anthropic_key
+
+        check("GROQ_API_KEY (default provider)", groq_key, "get a free key at https://console.groq.com/keys")
+        check("GEMINI_API_KEY (failover)", gemini_key, "optional but recommended — https://aistudio.google.com/apikey")
+        if not any_key:
+            typer.echo("\n  At least one provider key is required. GROQ_API_KEY is the easiest free option.")
+
+    typer.echo("\nChecking GitHub token...")
+    gh_token = os.environ.get("GITHUB_TOKEN", "")
+    check("GITHUB_TOKEN", bool(gh_token), "set via `export GITHUB_TOKEN=$(gh auth token)` or pass --github-token")
+
+    if gh_token:
+        typer.echo("\nVerifying GitHub token scope...")
+        try:
+            resp = requests.get(
+                "https://api.github.com/user",
+                headers={"Authorization": f"Bearer {gh_token}", "X-GitHub-Api-Version": "2022-11-28"},
+                timeout=8,
+            )
+            if resp.status_code == 200:
+                login = resp.json().get("login", "unknown")
+                typer.echo(f"  [ok] Authenticated as {login}")
+                scopes = resp.headers.get("X-OAuth-Scopes", "")
+                if not scopes:
+                    # Fine-grained PATs don't expose X-OAuth-Scopes; assume correct permissions.
+                    typer.echo("  [ok] Fine-grained PAT detected — scope check skipped")
+                else:
+                    has_repo = any(s.strip() in ("repo", "public_repo") for s in scopes.split(","))
+                    check(
+                        "Token scope (repo or public_repo)",
+                        has_repo,
+                        "the token needs pull-requests:write; regenerate with repo scope",
+                    )
+            else:
+                typer.echo(f"  [!!] Token check failed (HTTP {resp.status_code}) — token may be invalid")
+                ok = False
+        except Exception as exc:
+            typer.echo(f"  [!!] Could not reach GitHub API: {exc}")
+            ok = False
+
+    typer.echo("")
+    if ok:
+        typer.echo("All checks passed. Run a dry-run to see a briefing before granting write access:")
+        typer.echo("  pr-context-engine review --pr <N> --repo <owner/name> --dry-run")
+    else:
+        typer.echo("Fix the issues above, then re-run `pr-context-engine quickstart`.")
+        raise typer.Exit(code=1)
+
+
+if __name__ == "__main__":
+    app()