prxref 0.2.0__py3-none-any.whl

prxref/__init__.py

@@ -0,0 +1,3 @@
+"""prxref — fast automated AI code review for Bitbucket, GitLab, and GitHub."""
+
+__version__ = "0.2.0"

prxref/cli.py

@@ -0,0 +1,214 @@
+"""prxref command-line interface.
+
+Provides two subcommands:
+  * ``review --pr-url URL`` — one-shot PR/MR review from a forge URL.
+  * ``serve [--port N] [--host H]`` — webhook listener daemon.
+
+Non-blocking doctrine: ``review`` exits 0 on all review errors (empty diffs,
+network failures, LLM timeouts, bad credentials), printing diagnostic notes to
+stderr so a pipeline step never fails the build over an advisor's error. The one
+exception is a missing-configuration error, which is a usage error rather than a
+review outcome and exits 2.
+"""
+from __future__ import annotations
+
+import argparse
+import importlib
+import logging
+import sys
+import time
+from typing import Any
+
+import prxref
+from prxref.config import load_config, make_forge
+from prxref.forges.base import detect_forge
+from prxref.llm import ConfigError
+
+logger = logging.getLogger("prxref")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="prxref",
+        description="Fast automated AI code review for Bitbucket, GitLab, and GitHub.",
+    )
+    parser.add_argument(
+        "--version",
+        action="store_true",
+        help="print version and exit",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    rev = sub.add_parser("review", help="review one PR/MR from its web URL")
+    rev.add_argument(
+        "--pr-url",
+        required=True,
+        help="full URL of the PR or MR on Bitbucket, GitHub, or GitLab",
+    )
+    rev.add_argument(
+        "--no-post",
+        action="store_true",
+        help="dry run: do not post comments to the forge",
+    )
+    rev.add_argument(
+        "--max-chunks",
+        type=int,
+        default=None,
+        help="override the maximum number of diff chunks to review",
+    )
+    rev.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="print timing, token, and findings breakdown to stdout",
+    )
+
+    srv = sub.add_parser("serve", help="run webhook listener daemon")
+    srv.add_argument(
+        "--port",
+        type=int,
+        default=8080,
+        help="HTTP port to listen on (default 8080)",
+    )
+    srv.add_argument(
+        "--host",
+        default="0.0.0.0",
+        help="bind address (default 0.0.0.0)",
+    )
+
+    return parser
+
+
+def _fmt_counts(result: Any) -> str:
+    if not isinstance(result, dict):
+        return "-"
+    active = result.get("findings_active")
+    if not isinstance(active, list):
+        return "-"
+    sev: dict[str, int] = {}
+    for f in active:
+        sev[getattr(f, "severity", "?")] = sev.get(getattr(f, "severity", "?"), 0) + 1
+    items = [f"{k}={v}" for k, v in sorted(sev.items())]
+    return " ".join(items) if items else "0"
+
+
+def _fmt_tokens(result: Any) -> str:
+    if not isinstance(result, dict):
+        return "0+0"
+    tokens = result.get("tokens")
+    if isinstance(tokens, dict):
+        return f"{tokens.get('input', 0)}+{tokens.get('output', 0)}"
+    inp = result.get("input_tokens", 0)
+    out = result.get("output_tokens", 0)
+    return f"{inp}+{out}"
+
+
+def _print_summary(
+    result: Any,
+    elapsed_s: float,
+    *,
+    verbose: bool,
+    out=None,
+) -> None:
+    target = sys.stdout if out is None else out
+    verdict = result.get("verdict") if isinstance(result, dict) else result
+    print(f"verdict: {verdict if verdict is not None else 'done'}", file=target)
+    failed = result.get("chunks_failed", 0) if isinstance(result, dict) else 0
+    if failed:
+        reviewed = result.get("chunks_reviewed", 0)
+        print(f"coverage: {reviewed}/{reviewed + failed} chunks reviewed", file=target)
+    if not verbose:
+        return
+    dropped = result.get("findings_dropped", []) if isinstance(result, dict) else []
+    dropped = len(dropped) if isinstance(dropped, list) else 0
+    print(f"counts: {_fmt_counts(result)} (dropped: {dropped})", file=target)
+    print(f"elapsed: {elapsed_s:.1f}s tokens: {_fmt_tokens(result)}", file=target)
+
+
+def _run_review(
+    url: str,
+    *,
+    post: bool = True,
+    max_chunks: int | None = None,
+    config: dict | None = None,
+) -> Any:
+    ref = detect_forge(url)
+    if ref is None:
+        return None
+    cfg = config if config is not None else load_config(max_chunks=max_chunks)
+    forge = make_forge(ref)
+    llm = importlib.import_module("prxref.llm_backends").create_llm_client(cfg)
+    orchestrate = importlib.import_module("prxref.orchestrator").orchestrate_review
+    return orchestrate(
+        forge=forge,
+        ref=ref,
+        llm=llm,
+        post=post,
+        max_chunks=max_chunks if max_chunks is not None else cfg.get("MAX_CHUNKS", 8),
+    )
+
+
+def _webhook_handler(url: str) -> None:
+    try:
+        _run_review(url, post=True)
+    except Exception:
+        logger.exception("webhook review failed for %s", url)
+
+
+def _cmd_review(args: argparse.Namespace) -> int:
+    t0 = time.perf_counter()
+    try:
+        result = _run_review(
+            args.pr_url,
+            post=not args.no_post,
+            max_chunks=args.max_chunks,
+        )
+    except ConfigError as exc:
+        print(f"configuration error: {exc}", file=sys.stderr)
+        return 2
+    except Exception as exc:
+        print(f"review failed: {exc}", file=sys.stderr)
+        logger.debug("review failed with traceback", exc_info=True)
+        return 0
+
+    if result is None:
+        print(
+            f"unrecognized PR URL {args.pr_url!r} — expected bitbucket.org, "
+            "github.com, or gitlab.com PR/MR link",
+            file=sys.stderr,
+        )
+        return 0
+
+    elapsed = time.perf_counter() - t0
+    _print_summary(result, elapsed, verbose=args.verbose)
+    return 0
+
+
+def _cmd_serve(args: argparse.Namespace) -> int:
+    serve_fn = importlib.import_module("prxref.webhooks").serve
+    serve_fn(port=args.port, host=args.host, handler=_webhook_handler)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point dispatching ``review``, ``serve``, or ``--version``."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.DEBUG if getattr(args, "verbose", False) else logging.INFO,
+        format="%(levelname)s %(message)s",
+        stream=sys.stderr,
+    )
+
+    if getattr(args, "version", False):
+        print(prxref.__version__)
+        return 0
+
+    if args.command == "review":
+        return _cmd_review(args)
+    if args.command == "serve":
+        return _cmd_serve(args)
+
+    parser.print_help(sys.stderr)
+    return 2

prxref/config.py

@@ -0,0 +1,147 @@
+"""Configuration loading and forge-factory wiring.
+
+Canonical environment-variable table (every name prefixed PRXREF_):
+
+LLM / pipeline:
+  PRXREF_LLM_BACKEND            LLM backend: openai-compat | ferry | http (aliases) | litellm
+  PRXREF_LLM_BASE_URL           Base URL for the chosen backend (optional)
+  PRXREF_LLM_API_KEY            API key for the chosen backend (optional)
+  PRXREF_LLM_MODELS             Comma-separated model fallback chain, first
+                                that answers wins; empty = backend default
+  PRXREF_LLM_REASONING_EFFORT   Reasoning effort for models that cannot
+                                disable reasoning; provider-specific string,
+                                passed through unvalidated; empty = omit
+  PRXREF_CONFIDENCE_FLOOR       Findings below this confidence are dropped
+                                (default 0.6)
+  PRXREF_MAX_ERROR_FINDINGS     Max error-severity findings reported per
+                                review (legacy alias: PRXREF_MAX_ERRORS)
+  PRXREF_MAX_CHUNKS             Max diff chunks reviewed per PR (default 8)
+
+Per-forge auth:
+  PRXREF_BITBUCKET_TOKEN        Bitbucket bearer token
+  PRXREF_BITBUCKET_USER         Bitbucket username (app-password pair)
+  PRXREF_BITBUCKET_APP_PASSWORD Bitbucket app password
+  PRXREF_GITHUB_TOKEN           GitHub token (github.com)
+  PRXREF_GITHUB_ENTERPRISE_TOKEN GitHub Enterprise token (GHES hosts)
+  PRXREF_GITLAB_TOKEN           GitLab token
+
+Webhooks:
+  PRXREF_BITBUCKET_WEBHOOK_SECRET HMAC secret for Bitbucket webhook payloads
+  PRXREF_GITHUB_WEBHOOK_SECRET    HMAC secret for GitHub webhook payloads
+  PRXREF_GITLAB_WEBHOOK_SECRET    HMAC secret for GitLab webhook payloads
+  PRXREF_ALLOW_UNSIGNED           literal "1" accepts unsigned
+                                  webhooks (default off; insecure)
+
+Precedence: built-in defaults < environment < ``overrides`` kwargs.
+``None``-valued overrides are ignored (callers may pass optional values).
+Unknown override keys raise ``ValueError`` so typos surface immediately.
+"""
+from __future__ import annotations
+
+import os
+
+from prxref.forges.base import Forge, PRRef
+
+from .quality import DEFAULT_MAX_ERRORS
+
+_ENV_PREFIX = "PRXREF_"
+
+_DEFAULTS: dict[str, object] = {
+    "llm_backend": "openai-compat",
+    "llm_base_url": "",
+    "llm_api_key": "",
+    "llm_models": [],
+    "llm_reasoning_effort": "",
+    "confidence_floor": 0.6,
+    "max_error_findings": DEFAULT_MAX_ERRORS,
+    "max_chunks": 8,
+    "bitbucket_token": "",
+    "bitbucket_user": "",
+    "bitbucket_app_password": "",
+    "github_token": "",
+    "github_enterprise_token": "",
+    "gitlab_token": "",
+    "bitbucket_webhook_secret": "",
+    "github_webhook_secret": "",
+    "gitlab_webhook_secret": "",
+    "allow_unsigned": False,
+}
+
+_INT_KEYS = frozenset({"max_error_findings", "max_chunks"})
+_FLOAT_KEYS = frozenset({"confidence_floor"})
+_BOOL_KEYS = frozenset({"allow_unsigned"})
+_LIST_KEYS = frozenset({"llm_models"})
+
+_LEGACY_ENV_ALIASES: dict[str, str] = {
+    "max_error_findings": _ENV_PREFIX + "MAX_ERRORS",
+}
+
+
+def _truthy(raw: str) -> bool:
+    """Parse a security-gating boolean; only the literal "1" enables it.
+
+    Deliberately rejects "true"/"yes"/"on" so a typo or a shell quirk fails safe
+    with verification left ON. Must stay identical to
+    prxref.webhooks._allow_unsigned, which is the gate that actually runs;
+    TestAllowUnsignedAgreesWithGate pins the two together.
+    """
+    return raw.strip() == "1"
+
+
+def _coerce_env(key: str, raw: str) -> object:
+    try:
+        if key in _INT_KEYS:
+            return int(raw)
+        if key in _FLOAT_KEYS:
+            return float(raw)
+        if key in _BOOL_KEYS:
+            return _truthy(raw)
+        if key in _LIST_KEYS:
+            return [part.strip() for part in raw.split(",") if part.strip()]
+        return raw
+    except ValueError as exc:
+        raise ValueError(f"{_ENV_PREFIX}{key.upper()}: {exc}") from exc
+
+
+def load_config(**overrides: object) -> dict:
+    """Build the runtime config dict from defaults, environment, then overrides.
+
+    Keys mirror the env table above (lowercase, no prefix). Env values are
+    type-coerced per key (int / float / bool / comma-list / str); a malformed
+    env value raises ``ValueError`` naming the offending variable.
+    """
+    cfg: dict[str, object] = dict(_DEFAULTS)
+    for key in _DEFAULTS:
+        raw = os.environ.get(_ENV_PREFIX + key.upper())
+        if raw is None or raw == "":
+            legacy = _LEGACY_ENV_ALIASES.get(key)
+            raw = os.environ.get(legacy) if legacy else None
+        if raw is None or raw == "":
+            continue
+        cfg[key] = _coerce_env(key, raw)
+    for key, value in overrides.items():
+        if key not in _DEFAULTS:
+            raise ValueError(f"unknown config key: {key!r}")
+        if value is None:
+            continue
+        cfg[key] = value
+    return cfg
+
+
+def make_forge(ref: PRRef, session=None) -> Forge:
+    """Instantiate the ForgeImpl matching ``ref.forge``.
+
+    ``session`` optionally injects a custom ``requests.Session`` (tests,
+    shared connection pools). Unknown forge names raise ``ValueError``.
+    """
+    from prxref.forges import bitbucket, github, gitlab
+
+    impls = {
+        "bitbucket": bitbucket.ForgeImpl,
+        "github": github.ForgeImpl,
+        "gitlab": gitlab.ForgeImpl,
+    }
+    impl = impls.get(ref.forge)
+    if impl is None:
+        raise ValueError(f"unknown forge: {ref.forge!r}")
+    return impl(session=session)

prxref/forges/base.py

@@ -0,0 +1,101 @@
+"""Forge contract: one Protocol, three implementations (bitbucket, github, gitlab).
+
+Every value that flows through the pipeline is forge-agnostic past this module.
+Diff handling is deliberately unified: each forge returns ONE raw unified diff
+string; parsing/chunking happens downstream in triage.py, identically for all
+three forges.
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class PRRef:
+    """A pull/merge request identity, normalized across forges."""
+
+    forge: str  # "bitbucket" | "github" | "gitlab"
+    host: str  # e.g. "bitbucket.org", "github.com", "gitlab.com", or self-hosted host
+    owner: str  # workspace / org / group
+    repo: str
+    number: int
+    url: str
+
+
+@dataclass
+class InlineComment:
+    """A comment anchored to one line of the new file."""
+
+    path: str
+    line: int  # line in the NEW file
+    body: str
+    side: str = "RIGHT"
+
+
+@dataclass
+class Thread:
+    """An existing discussion thread on a PR (for dedup against re-review)."""
+
+    path: str | None
+    line: int | None
+    resolved: bool
+    author: str
+    body_snippet: str
+
+
+@dataclass
+class PRData:
+    """Normalized PR metadata returned by get_pr()."""
+
+    title: str
+    description: str
+    author: str
+    source_branch: str
+    target_branch: str
+    source_sha: str
+    target_sha: str
+    raw: dict  # forge-native payload, for forge-specific needs
+
+
+class Forge(Protocol):
+    """The contract every forge adapter implements."""
+
+    name: str
+
+    @staticmethod
+    def parse_pr_url(url: str) -> PRRef | None:
+        """Return a PRRef if this forge recognizes the URL, else None."""
+        ...
+
+    def get_pr(self, ref: PRRef) -> PRData:
+        """Fetch normalized PR metadata."""
+        ...
+
+    def get_diff(self, ref: PRRef) -> str:
+        """Fetch the raw unified diff of the PR (all files)."""
+        ...
+
+    def post_summary(self, ref: PRRef, body: str) -> None:
+        """Post (or update) the top-level review summary comment."""
+        ...
+
+    def post_inline_comments(self, ref: PRRef, comments: Sequence[InlineComment]) -> int:
+        """Post inline comments; returns the number actually posted."""
+        ...
+
+    def list_threads(self, ref: PRRef) -> list[Thread]:
+        """List existing threads so re-reviews skip already-discussed findings."""
+        ...
+
+
+def detect_forge(url: str) -> PRRef | None:
+    """Try each registered forge's URL parser in order."""
+    from . import bitbucket, github, gitlab
+
+    for forge in (bitbucket, github, gitlab):
+        ref = forge.ForgeImpl.parse_pr_url(url)
+        if ref is not None:
+            return ref
+    return None