devtrust-apr 0.2.0__py3-none-any.whl

apr/__init__.py

@@ -0,0 +1,14 @@
+"""Agent-PR Reviewer (`apr`) - the Wave 2 lead bet of the DevTrust platform.
+
+Consolidates the patterns from three existing GitHub Apps into one
+deterministic, fast, AI-pattern-aware PR reviewer:
+
+  - ai-quality-gate    -> AI-likelihood + verbose-pattern detection
+  - pr-coach           -> coaching feedback (description quality, TODOs)
+  - commit-craft       -> commit-message review and normalization
+
+v0.0.1 ships the deterministic rule layer; LLM-backed review is layered
+on top in v0.1+ once the rule output is stable enough to grade against.
+"""
+
+__version__ = "0.2.0"

apr/__main__.py

@@ -0,0 +1,6 @@
+"""Enables `python -m apr ...`."""
+
+from apr.cli import app
+
+if __name__ == "__main__":
+    app()

apr/cli.py

@@ -0,0 +1,150 @@
+"""Agent-PR Reviewer command-line interface.
+
+apr version
+apr review [--repo PATH] [--changed FILE ...] [--title S] [--description S]
+           [--diff PATH] [--enable-ai] [--ai-provider null|anthropic]
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from apr import __version__
+from apr.engine import review as review_engine
+from apr.llm import LLMProvider, build_provider
+from apr.output import write_json, write_markdown
+
+app = typer.Typer(
+    name="apr",
+    help="Agent-PR Reviewer - deterministic + AI-pattern review for PRs.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+console = Console()
+
+
+@app.command()
+def version() -> None:
+    """Print the installed Agent-PR Reviewer version."""
+    console.print(f"apr [bold]v{__version__}[/bold]")
+
+
+@app.command()
+def review(
+    repo: Annotated[
+        Path,
+        typer.Option("--repo", "-r", help="Repo to review. Defaults to current directory."),
+    ] = Path("."),
+    changed: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--changed",
+            "-c",
+            help="Path(s) that changed. Repeat for multiple files.",
+        ),
+    ] = None,
+    title: Annotated[
+        str | None,
+        typer.Option("--title", "-t", help="The PR title (for metadata checks)."),
+    ] = None,
+    description: Annotated[
+        str | None,
+        typer.Option("--description", "-d", help="The PR description / body."),
+    ] = None,
+    diff_path: Annotated[
+        Path | None,
+        typer.Option(
+            "--diff",
+            help=(
+                "Path to a unified-diff file. Required for the "
+                "ai-review:diff-comprehension rule when --enable-ai."
+            ),
+        ),
+    ] = None,
+    enable_ai: Annotated[
+        bool,
+        typer.Option(
+            "--enable-ai/--no-enable-ai",
+            help=(
+                "Run the ai-review:* rule pack. Off by default. "
+                "ai-review:hallucinated-symbol needs a "
+                ".repox/architecture.json (run `repox build .` first)."
+            ),
+        ),
+    ] = False,
+    ai_provider: Annotated[
+        str,
+        typer.Option(
+            "--ai-provider",
+            help="LLM backend: 'null' (default, no calls) or 'anthropic'.",
+        ),
+    ] = "null",
+    quiet: Annotated[
+        bool,
+        typer.Option("--quiet", "-q", help="Suppress non-essential output."),
+    ] = False,
+) -> None:
+    """Run the review and emit `.apr/review.{json,md}`."""
+    if not repo.exists() or not repo.is_dir():
+        console.print(f"[red]Error:[/red] not a directory: {repo}")
+        raise typer.Exit(code=2)
+
+    repo = repo.resolve()
+    files = list(changed or [])
+
+    diff_text: str | None = None
+    if diff_path is not None:
+        try:
+            diff_text = diff_path.read_text(encoding="utf-8", errors="replace")
+        except OSError as exc:
+            console.print(f"[red]Error:[/red] cannot read diff: {exc}")
+            raise typer.Exit(code=2) from exc
+
+    provider: LLMProvider | None = None
+    if enable_ai:
+        # Anthropic API key from the conventional env var.
+        api_key = os.environ.get("ANTHROPIC_API_KEY")
+        provider = build_provider(ai_provider, api_key)
+
+    if not quiet:
+        console.print(f"[bold]Reviewing[/bold] {repo}")
+        console.print(f"[dim]Changed files:[/dim] {len(files)}")
+        if enable_ai:
+            console.print(f"[dim]AI rules:[/dim] enabled (provider: {ai_provider})")
+
+    report = review_engine(
+        repo,
+        files,
+        pr_title=title,
+        pr_description=description,
+        enable_ai=enable_ai,
+        llm_provider=provider,
+        diff=diff_text,
+    )
+    json_path = write_json(report, repo)
+    md_path = write_markdown(report, repo)
+
+    if quiet:
+        return
+
+    s = report.stats
+    table = Table(title="\nReview summary", show_header=True, header_style="bold")
+    table.add_column("Severity", style="cyan")
+    table.add_column("Count", justify="right")
+    table.add_row("info", str(s.info))
+    table.add_row("warning", str(s.warning))
+    table.add_row("error", str(s.error))
+    table.add_row("critical", str(s.critical))
+    table.add_row("[bold]total[/bold]", f"[bold]{s.total}[/bold]")
+    console.print(table)
+    if s.blocking > 0:
+        console.print(f"[red]Blocking findings:[/red] {s.blocking} (error + critical)")
+    console.print(f"\n[green]✓[/green] wrote [bold]{json_path}[/bold]")
+    console.print(f"[green]✓[/green] wrote [bold]{md_path}[/bold]")

apr/engine.py

@@ -0,0 +1,114 @@
+"""Top-level review orchestration.
+
+The engine takes a repo root, a list of changed files, optional PR
+metadata (title + description), and optional AI configuration (provider
++ diff). It runs:
+
+  1. PR-level checks (title, description) -- once per review.
+  2. File-level checks for each changed file in a known language.
+  3. AI rule pack (apr.rules_ai), gated behind `enable_ai=True`.
+
+Findings are deduplicated and stable-sorted (file, line, severity).
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from datetime import UTC, datetime
+from pathlib import Path
+
+from apr import __version__
+from apr.llm import LLMProvider, NullProvider
+from apr.models import (
+    Finding,
+    ReviewInputs,
+    ReviewReport,
+    ReviewStats,
+    Severity,
+)
+from apr.repox_integration import load as load_repox_artifact
+from apr.rules import check_file, check_pr_metadata
+from apr.rules_ai import run_ai_rules
+
+_SEVERITY_ORDER: dict[Severity, int] = {
+    "info": 0,
+    "warning": 1,
+    "error": 2,
+    "critical": 3,
+}
+
+
+def _stable_key(f: Finding) -> tuple[str, int, int, str]:
+    """Stable sort key: file, line, severity rank (asc), rule_id."""
+    return (
+        f.file or "",
+        f.line or 0,
+        _SEVERITY_ORDER[f.severity],
+        f.rule_id,
+    )
+
+
+def review(
+    repo_root: Path,
+    changed_files: list[str],
+    pr_title: str | None = None,
+    pr_description: str | None = None,
+    *,
+    enable_ai: bool = False,
+    llm_provider: LLMProvider | None = None,
+    diff: str | None = None,
+) -> ReviewReport:
+    """Run all checks and produce a ReviewReport.
+
+    AI rules are off by default. Pass `enable_ai=True` AND optionally
+    a `llm_provider` (defaults to NullProvider) to enable
+    `ai-review:hallucinated-symbol` (deterministic, uses repox call
+    graph) and `ai-review:diff-comprehension` (delegates to the
+    provider).
+    """
+    findings: list[Finding] = []
+
+    findings.extend(check_pr_metadata(pr_title, pr_description))
+    for rel in changed_files:
+        findings.extend(check_file(repo_root, rel))
+
+    if enable_ai:
+        artifact = load_repox_artifact(repo_root)
+        provider: LLMProvider = llm_provider or NullProvider()
+        findings.extend(
+            run_ai_rules(
+                repo_root,
+                changed_files,
+                artifact=artifact,
+                provider=provider,
+                diff=diff,
+                pr_title=pr_title,
+                pr_description=pr_description,
+            )
+        )
+
+    findings.sort(key=_stable_key)
+
+    counts: Counter[Severity] = Counter()
+    for f in findings:
+        counts[f.severity] += 1
+
+    stats = ReviewStats(
+        info=counts["info"],
+        warning=counts["warning"],
+        error=counts["error"],
+        critical=counts["critical"],
+    )
+
+    return ReviewReport(
+        generated_at=datetime.now(UTC),
+        tool_version=__version__,
+        inputs=ReviewInputs(
+            repo_root=str(repo_root),
+            changed_files=sorted(changed_files),
+            pr_title=pr_title,
+            pr_description=pr_description,
+        ),
+        stats=stats,
+        findings=findings,
+    )

apr/llm.py

@@ -0,0 +1,188 @@
+"""LLM provider interface for AI-backed apr rules.
+
+  - `LLMProvider`        Protocol every backend implements
+  - `NullProvider`       returns no findings; used when AI is disabled
+  - `AnthropicProvider`  Claude-backed provider (real, v0.1.1+)
+
+The rule modules talk to this interface, never to a vendor SDK directly.
+Swapping providers (Anthropic / OpenAI / Bedrock / a local model) is a
+matter of writing a new `LLMProvider` implementation -- not touching the
+rule code or the engine.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Protocol
+
+from apr.models import Finding
+from apr.prompts import (
+    DEFAULT_MAX_DIFF_CHARS,
+    DEFAULT_MAX_TOKENS,
+    SYSTEM_PROMPT,
+    build_prompt,
+    parse_response,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class LLMProvider(Protocol):
+    """Anything that can answer 'does this PR description match the diff'."""
+
+    name: str
+
+    def analyze_diff(
+        self,
+        diff: str,
+        pr_title: str | None,
+        pr_description: str | None,
+    ) -> list[Finding]:
+        """Return findings (possibly empty) about diff/description coherence.
+
+        Implementations MUST be idempotent and side-effect-free other than
+        outbound HTTP. They MUST handle their own timeouts and rate limits;
+        the engine treats any exception as 'no findings' and continues.
+        """
+        ...
+
+
+class NullProvider:
+    """No-op provider. Returned when AI is disabled or no key configured."""
+
+    name = "null"
+
+    def analyze_diff(
+        self,
+        diff: str,
+        pr_title: str | None,
+        pr_description: str | None,
+    ) -> list[Finding]:
+        return []
+
+
+class AnthropicProvider:
+    """Anthropic Claude as the LLM backend.
+
+    Uses the official `anthropic` Python SDK (Messages API, non-streaming).
+    The provider builds a JSON-shaped prompt via `apr.prompts.build_prompt`,
+    parses the reply via `apr.prompts.parse_response`, and returns
+    `Finding` rows that the engine re-namespaces under
+    `ai-review:diff-comprehension`.
+
+    Cost / safety:
+      - Diff is truncated to `max_diff_chars` (default 60,000) before
+        sending. A typical PR fits comfortably; runaway lockfile diffs
+        are bounded.
+      - `max_tokens` on the reply is capped (default 1024). Plenty for
+        a JSON list of findings; not enough for the model to spiral.
+      - On any SDK exception (auth, rate limit, network), we log and
+        return [] rather than letting the engine die.
+    """
+
+    name = "anthropic"
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = "claude-sonnet-4-6",
+        max_tokens: int = DEFAULT_MAX_TOKENS,
+        max_diff_chars: int = DEFAULT_MAX_DIFF_CHARS,
+        client: Any | None = None,
+    ) -> None:
+        try:
+            import anthropic  # noqa: F401  -- intentional probe
+        except ImportError as exc:
+            raise RuntimeError(
+                "AnthropicProvider requires the `anthropic` package. "
+                "Install with `pip install apr[ai]` or "
+                "`uv add anthropic` in this workspace."
+            ) from exc
+        self.api_key = api_key
+        self.model = model
+        self.max_tokens = max_tokens
+        self.max_diff_chars = max_diff_chars
+        # Tests inject `client`. Production builds a fresh client per provider.
+        self._client = client
+
+    def _ensure_client(self) -> Any:
+        if self._client is not None:
+            return self._client
+        from anthropic import Anthropic
+
+        self._client = Anthropic(api_key=self.api_key)
+        return self._client
+
+    def analyze_diff(
+        self,
+        diff: str,
+        pr_title: str | None,
+        pr_description: str | None,
+    ) -> list[Finding]:
+        prompt = build_prompt(
+            diff=diff,
+            pr_title=pr_title,
+            pr_description=pr_description,
+            max_diff_chars=self.max_diff_chars,
+        )
+        try:
+            client = self._ensure_client()
+            resp = client.messages.create(
+                model=self.model,
+                max_tokens=self.max_tokens,
+                system=SYSTEM_PROMPT,
+                messages=[{"role": "user", "content": prompt}],
+            )
+        except Exception as exc:
+            logger.warning("AnthropicProvider request failed: %s", exc)
+            return []
+
+        text = _extract_text(resp)
+        if text is None:
+            return []
+        return parse_response(text)
+
+
+def _extract_text(resp: Any) -> str | None:
+    """Pull the text body out of an `anthropic.Message` response.
+
+    The SDK exposes `.content` as a list of content blocks; the simplest
+    case is one `text` block. We concatenate all text-shaped blocks
+    together for robustness against future models that prepend a
+    'thinking' segment or similar.
+    """
+    content = getattr(resp, "content", None)
+    if content is None:
+        return None
+    pieces: list[str] = []
+    for block in content:
+        block_type = getattr(block, "type", None)
+        if block_type == "text":
+            text = getattr(block, "text", None)
+            if isinstance(text, str):
+                pieces.append(text)
+    if not pieces:
+        return None
+    return "\n".join(pieces)
+
+
+def build_provider(name: str | None, api_key: str | None) -> LLMProvider:
+    """Map a provider name to a concrete provider instance.
+
+    Returns NullProvider when the input doesn't name a real provider or
+    when credentials are missing -- the engine never raises because the
+    operator forgot to set an env var.
+    """
+    if not name or name == "null":
+        return NullProvider()
+    if name == "anthropic":
+        # Allow a per-process model override via env var.
+        model = os.environ.get("APR_ANTHROPIC_MODEL", "claude-sonnet-4-6")
+        if not api_key:
+            return NullProvider()
+        try:
+            return AnthropicProvider(api_key=api_key, model=model)
+        except RuntimeError:
+            return NullProvider()
+    return NullProvider()

apr/models.py

@@ -0,0 +1,111 @@
+"""Pydantic models for the Agent-PR Reviewer.
+
+The schema in this file is the public API of `apr`. Downstream consumers
+(the GitHub App that posts comments, dashboards, anyone reading
+`.apr/review.json`) read this shape. Treat changes as breaking.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+SCHEMA_VERSION = "0.0.1"
+
+
+# ---------------------------------------------------------------------------
+# Findings
+# ---------------------------------------------------------------------------
+
+Severity = Literal["info", "warning", "error", "critical"]
+
+Category = Literal[
+    "quality",  # general code-quality smells
+    "security",  # potentially unsafe patterns
+    "style",  # convention / readability nits
+    "ai-pattern",  # signs of AI-generated boilerplate or hallucinations
+    "todo",  # TODO / FIXME / XXX bookkeeping
+    "commit",  # commit-message issues (when `apr` is fed commit data)
+]
+
+
+class Finding(BaseModel):
+    """One reviewer finding tied to a file and (optionally) a line."""
+
+    model_config = ConfigDict(frozen=True)
+
+    rule_id: str = Field(
+        ...,
+        description=(
+            "Stable identifier for the rule that produced this finding "
+            "(e.g. 'bare-except', 'todo-no-ticket', 'pr-description-too-short')."
+        ),
+    )
+    severity: Severity
+    category: Category
+    message: str
+    file: str | None = Field(
+        default=None,
+        description="Repo-relative POSIX path. None for repo-level findings.",
+    )
+    line: int | None = Field(default=None, ge=1)
+    suggestion: str | None = Field(
+        default=None,
+        description="Optional human-readable suggested fix.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Review report
+# ---------------------------------------------------------------------------
+
+
+class ReviewInputs(BaseModel):
+    """The inputs the reviewer saw -- captured for reproducibility."""
+
+    model_config = ConfigDict(frozen=True)
+
+    repo_root: str
+    changed_files: list[str] = Field(default_factory=list)
+    pr_title: str | None = None
+    pr_description: str | None = None
+
+
+class ReviewStats(BaseModel):
+    """Aggregate counts useful for terminal display + CI gates."""
+
+    model_config = ConfigDict(frozen=True)
+
+    info: int = Field(..., ge=0)
+    warning: int = Field(..., ge=0)
+    error: int = Field(..., ge=0)
+    critical: int = Field(..., ge=0)
+
+    @property
+    def total(self) -> int:
+        return self.info + self.warning + self.error + self.critical
+
+    @property
+    def blocking(self) -> int:
+        """Findings severe enough that a CI gate should stop the merge."""
+        return self.error + self.critical
+
+
+class ReviewReport(BaseModel):
+    """The full report emitted by `apr review`.
+
+    JSON layout:    `.apr/review.json`
+    Human companion: `.apr/review.md`
+    """
+
+    model_config = ConfigDict(frozen=False)
+
+    schema_version: str = SCHEMA_VERSION
+    generated_at: datetime
+    tool_version: str
+
+    inputs: ReviewInputs
+    stats: ReviewStats
+    findings: list[Finding] = Field(default_factory=list)

apr/output.py

@@ -0,0 +1,93 @@
+"""Writers for the review report.
+
+Two outputs:
+  - review.json - canonical, machine-readable artifact (versioned)
+  - review.md   - human-readable companion derived from the JSON
+
+Both land in `.apr/` at the analyzed repo root.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apr.models import ReviewReport
+
+OUTPUT_DIR_NAME = ".apr"
+
+
+def write_json(report: ReviewReport, root: Path) -> Path:
+    out_dir = root / OUTPUT_DIR_NAME
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / "review.json"
+    out_path.write_text(
+        report.model_dump_json(indent=2, exclude_none=False),
+        encoding="utf-8",
+    )
+    return out_path
+
+
+def write_markdown(report: ReviewReport, root: Path) -> Path:
+    out_dir = root / OUTPUT_DIR_NAME
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = out_dir / "review.md"
+
+    lines: list[str] = []
+    lines.append("# Code review")
+    lines.append("")
+    lines.append(
+        f"> Generated by **apr v{report.tool_version}** at "
+        f"{report.generated_at.isoformat(timespec='seconds')}"
+    )
+    lines.append(f"> Schema: `{report.schema_version}`")
+    lines.append("")
+    lines.append("---")
+    lines.append("")
+
+    s = report.stats
+    lines.append("## Summary")
+    lines.append("")
+    lines.append(
+        f"- **Total findings:** {s.total}  "
+        f"(info: {s.info}, warning: {s.warning}, "
+        f"error: {s.error}, critical: {s.critical})"
+    )
+    lines.append(f"- **Blocking (error + critical):** {s.blocking}")
+    lines.append(f"- **Changed files reviewed:** {len(report.inputs.changed_files)}")
+    lines.append("")
+
+    if not report.findings:
+        lines.append("_No findings. Nice work._")
+        lines.append("")
+    else:
+        lines.append("## Findings")
+        lines.append("")
+        lines.append("| Severity | File | Line | Rule | Message |")
+        lines.append("|---|---|---:|---|---|")
+        for f in report.findings:
+            file_disp = f"`{f.file}`" if f.file else "_(repo-level)_"
+            line_disp = str(f.line) if f.line else ""
+            # Pipes inside messages would break the table - escape.
+            msg = f.message.replace("|", "\\|")
+            lines.append(f"| `{f.severity}` | {file_disp} | {line_disp} | `{f.rule_id}` | {msg} |")
+        lines.append("")
+
+        # Surface up to 10 suggestions in a separate block, since they're
+        # the most actionable thing for the author.
+        with_suggestions = [f for f in report.findings if f.suggestion]
+        if with_suggestions:
+            lines.append("### Suggested fixes")
+            lines.append("")
+            for f in with_suggestions[:10]:
+                where = (
+                    f"`{f.file}:{f.line}`"
+                    if f.file and f.line
+                    else f"`{f.file}`"
+                    if f.file
+                    else "_(repo-level)_"
+                )
+                lines.append(f"- {where} ({f.rule_id}) — {f.suggestion}")
+            lines.append("")
+
+    out_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return out_path