prlens-core 0.1.4__tar.gz

prlens_core-0.1.4/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: prlens-core
+Version: 0.1.4
+Summary: Core review engine for prlens — AI-powered GitHub PR code reviewer
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: PyGithub>=2.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.25; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: all
+Requires-Dist: anthropic>=0.25; extra == "all"
+Requires-Dist: openai>=1.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: flake8>=7.0; extra == "dev"

prlens_core-0.1.4/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "prlens-core"
+version = "0.1.4"
+description = "Core review engine for prlens — AI-powered GitHub PR code reviewer"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+dependencies = [
+    "PyGithub>=2.1",
+    "pyyaml>=6.0",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.25"]
+openai = ["openai>=1.0"]
+all = ["anthropic>=0.25", "openai>=1.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "pytest-mock>=3.12",
+    "black>=24.0",
+    "flake8>=7.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+prlens_core = ["guidelines/*.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 120
+target-version = ["py39", "py310", "py311", "py312"]

prlens_core-0.1.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

prlens_core-0.1.4/src/prlens_core/config.py

@@ -0,0 +1,65 @@
+import os
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+DEFAULT_CONFIG: dict = {
+    "model": "anthropic",
+    "max_chars_per_file": 20000,
+    "batch_limit": 60,
+    "guidelines": None,  # None = use built-in default; set to a path string to override
+    "exclude": [],  # fnmatch patterns or directory names to skip (e.g. "migrations/", "*.min.js")
+    "review_draft_prs": False,
+}
+
+BUILTIN_GUIDELINES_DIR = Path(__file__).parent / "guidelines"
+_BUILTIN_DEFAULT = BUILTIN_GUIDELINES_DIR / "backend.md"
+
+
+def load_config(config_path: str = ".prlens.yml", cli_overrides: Optional[dict] = None) -> dict:
+    """
+    Load configuration by merging (in order of precedence):
+      1. Built-in defaults
+      2. .prlens.yml in the current directory
+      3. CLI argument overrides
+    """
+    config = {**DEFAULT_CONFIG, "exclude": list(DEFAULT_CONFIG["exclude"])}
+
+    path = Path(config_path)
+    if path.exists():
+        with open(path) as f:
+            file_config = yaml.safe_load(f) or {}
+        config.update(file_config)
+
+    if cli_overrides:
+        for key, value in cli_overrides.items():
+            if value is not None:
+                config[key] = value
+
+    # Resolve credentials from environment variables
+    config["github_token"] = os.environ.get("GITHUB_TOKEN")
+    config["anthropic_api_key"] = os.environ.get("ANTHROPIC_API_KEY")
+    config["openai_api_key"] = os.environ.get("OPENAI_API_KEY")
+
+    return config
+
+
+def load_guidelines(config: dict) -> str:
+    """
+    Load review guidelines.
+
+    If ``guidelines`` is set in config, loads from that path (relative to cwd).
+    Otherwise falls back to the built-in default.
+    """
+    custom_path = config.get("guidelines")
+    if custom_path:
+        p = Path(custom_path)
+        if not p.exists():
+            raise FileNotFoundError(f"Guidelines file not found: {custom_path}")
+        return p.read_text()
+
+    if _BUILTIN_DEFAULT.exists():
+        return _BUILTIN_DEFAULT.read_text()
+
+    raise FileNotFoundError("No guidelines configured and built-in default is missing.")

prlens_core-0.1.4/src/prlens_core/gh/pull_request.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import re
+
+from github import Github
+
+_SHA_MARKER_RE = re.compile(r"<!-- prlens-sha: ([0-9a-f]{40}) -->")
+
+
+def get_repo(repo_name: str, token: str):
+    return Github(token).get_repo(repo_name)
+
+
+def get_pull(repo, pr_number: int):
+    return repo.get_pull(pr_number)
+
+
+def get_pull_requests(repo, state: str = "open"):
+    return repo.get_pulls(state=state)
+
+
+def get_diff(pr):
+    return pr.get_files()
+
+
+def get_last_reviewed_sha(pr) -> str | None:
+    """Return the most recent HEAD SHA stored by prlens in a review body, or None."""
+    last_sha = None
+    for review in pr.get_reviews():
+        match = _SHA_MARKER_RE.search(review.body or "")
+        if match:
+            last_sha = match.group(1)
+    return last_sha
+
+
+def get_incremental_files(repo, base_sha: str, head_sha: str):
+    """Return files changed between two commits using GitHub's compare API."""
+    comparison = repo.compare(base_sha, head_sha)
+    return comparison.files

prlens_core-0.1.4/src/prlens_core/guidelines/backend.md

@@ -0,0 +1,37 @@
+# Backend Code Review Guidelines
+
+## REST & Architecture
+
+- Use proper HTTP verbs (e.g., `POST /users` not `POST /users/create`).
+- Keep business logic in service layers — views/controllers should only orchestrate.
+- Avoid putting business logic in model `save()` methods or view handlers.
+- Avoid boolean flags that alter method behavior; create explicit, separate methods instead.
+
+## Code Structure & Reusability
+
+- Place shared logic in a shared library if it is reused across multiple services.
+- Wrap external integrations (e.g., Slack, email, storage) in clean service layers that do not depend on internal app logic.
+- Avoid adding executable code in `__init__.py` files — use them only for imports and package exposure.
+
+## Django-Specific Practices (if applicable)
+
+- Use `select_related` / `prefetch_related` to avoid N+1 queries.
+- Validate inputs in serializers, not in views or services.
+- Use custom domain exceptions instead of generic ones for consistent error handling.
+- Organize code modularly by domain (e.g., `users`, `payments`, `notifications`).
+
+## Python Best Practices
+
+- Use type hints in all function and method signatures.
+- Avoid wildcard imports (`from module import *`).
+- Use `logging` with appropriate levels instead of `print()`.
+- Replace magic strings and numbers with named constants or enums.
+- Prefer `pathlib.Path` over string-based file paths.
+- Use context managers (`with` statements) for files and resources.
+
+## Testing & Maintainability
+
+- Write unit tests for all new service logic.
+- Keep tests fast and deterministic; mock all external dependencies.
+- Use environment variables for secrets and configuration — never hardcode them.
+- Add docstrings and API documentation for new public endpoints and logic.

prlens_core-0.1.4/src/prlens_core/guidelines/frontend.md

@@ -0,0 +1,65 @@
+# Frontend Code Review Guidelines
+
+## API Handling
+
+- Store API responses in global state (e.g., Redux) only if needed across multiple components.
+- Use component-local state (`useState`/`useEffect`) for view-specific or session-specific data.
+- Avoid flag-based conditional API logic inside components — extract it to helper functions or hooks.
+- Optimize for performance: debounce search inputs, paginate large datasets, cache static responses.
+
+## State Management
+
+- Use global state slices for shared state only.
+- Avoid duplicating state between global state and component-local state.
+- Encapsulate side effects and data-fetching in reusable custom hooks.
+
+## Component Architecture
+
+- Follow a clean separation of concerns:
+  - `components/` — Dumb, reusable UI elements
+  - `containers/` — Smart components with data-fetching
+  - `hooks/` — Reusable logic for side effects
+  - `utils/`, `constants/` — Low-level modules and config
+
+## Do's
+
+- Use constants or enums for repeated value-label pairs (e.g., statuses, categories).
+- Keep components small and composable.
+- Write tests for custom hooks, logic, and critical UI behaviors.
+
+## Don'ts
+
+- Don't use wildcard imports (e.g., `import * as lib`) — prefer named imports.
+- Don't hardcode magic values — define them as constants or enums.
+- Don't embed conditional API logic directly in components.
+- Don't bloat container components — move logic to hooks or services.
+
+## Value-to-Label Mapping
+
+Use a structured class with static getters for value-label constants:
+
+```js
+// Good
+class DocumentType {
+  static get PASSPORT() {
+    return { code: "passport", title: "Passport" };
+  }
+  static get ALL() {
+    return [DocumentType.PASSPORT];
+  }
+}
+
+// Bad
+const DocumentType = {
+  PASSPORT: { code: "passport", title: "Passport" },
+};
+```
+
+Using a class prevents unintentional mutation and supports lazy initialization.
+
+## Syntax & Language Notes
+
+- Use named imports: `import { Button } from "antd";`
+- Avoid wildcard imports: `import * as antd from "antd";`
+- Do not suggest removing fallback logic (e.g., `|| []`) unless the value is guaranteed non-null.
+  Note: JavaScript's `Map.get()` does not support default values like Python's `dict.get()`.

prlens_core-0.1.4/src/prlens_core/providers/anthropic.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from prlens_core.providers.base import BaseReviewer
+
+
+class AnthropicReviewer(BaseReviewer):
+    MODEL = "claude-sonnet-4-20250514"
+    # temperature=0.3 for Anthropic — slightly higher than OpenAI's 0.2 to
+    # allow more natural phrasing in review comments while keeping the output
+    # deterministic enough for consistent JSON structure.
+    TEMPERATURE = 0.3
+
+    def __init__(self, api_key: str):
+        try:
+            from anthropic import Anthropic
+        except ImportError:
+            raise ImportError(
+                "The 'anthropic' package is required for this provider. "
+                "Install it with: pip install 'prlens[anthropic]'"
+            )
+        self.client = Anthropic(api_key=api_key)
+
+    def _call_api(self, system_prompt: str, user_prompt: str) -> str:
+        # Imported inside the method because the anthropic package is optional;
+        # __init__ already validated it is installed before we reach here.
+        from anthropic.types import TextBlock
+
+        response = self.client.messages.create(
+            model=self.MODEL,
+            system=system_prompt,
+            messages=[{"role": "user", "content": user_prompt}],
+            temperature=self.TEMPERATURE,
+            max_tokens=self.MAX_TOKENS,
+        )
+        text_blocks = [block.text for block in response.content if isinstance(block, TextBlock)]
+        return "".join(text_blocks).strip()

prlens_core-0.1.4/src/prlens_core/providers/base.py

@@ -0,0 +1,194 @@
+"""Base reviewer implementing the Template Method pattern.
+
+All providers share the same review algorithm:
+    review() → _build_system_prompt() + _build_user_prompt()
+             → _call_with_retry() → _call_api()   ← only this differs per provider
+             → _parse()
+
+Subclasses implement two things only:
+  - __init__: validate and store the SDK client
+  - _call_api: make one raw API call and return the text response
+
+Everything else — prompt construction, JSON parsing, retry logic — lives here
+so it is defined once and inherited consistently by every provider.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from prlens_core.utils.context import build_context_section
+
+if TYPE_CHECKING:
+    from prlens_core.utils.context import RepoContext
+
+logger = logging.getLogger(__name__)
+
+# Shared defaults — subclasses may override as class attributes if needed.
+_MAX_RETRIES = 3
+_MAX_TOKENS = 4096
+
+
+class BaseReviewer(ABC):
+    MAX_RETRIES: int = _MAX_RETRIES
+    MAX_TOKENS: int = _MAX_TOKENS
+
+    # ------------------------------------------------------------------ #
+    # Public interface                                                     #
+    # ------------------------------------------------------------------ #
+
+    def review(
+        self,
+        description: str,
+        file_name: str,
+        diff_patch: str,
+        file_content: str,
+        guidelines: str,
+        repo_context: RepoContext | None = None,
+    ) -> list[dict]:
+        """Orchestrate a single-file review and return inline comments.
+
+        Concrete here because the algorithm is identical for every provider:
+        build prompts → call API with retry → parse JSON response.
+        Only the raw API call (_call_api) is delegated to subclasses.
+        """
+        system = self._build_system_prompt(guidelines)
+        user = self._build_user_prompt(description, file_name, diff_patch, file_content, repo_context)
+        raw = self._call_with_retry(system, user)
+        if raw is None:
+            return []
+        return self._parse(raw)
+
+    # ------------------------------------------------------------------ #
+    # Abstract — implement in each provider                               #
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def _call_api(self, system_prompt: str, user_prompt: str) -> str:
+        """Make a single API call and return the raw text response.
+
+        This is the only method subclasses must implement. It should raise
+        on failure — _call_with_retry handles retries and logging.
+        """
+
+    # ------------------------------------------------------------------ #
+    # Shared implementations                                               #
+    # ------------------------------------------------------------------ #
+
+    def _call_with_retry(self, system_prompt: str, user_prompt: str) -> str | None:
+        """Retry _call_api up to MAX_RETRIES times with exponential backoff.
+
+        Separating retry logic from the raw API call means each provider's
+        _call_api stays focused on a single attempt, and the backoff/logging
+        behaviour is defined once rather than copied into every provider.
+        """
+        for attempt in range(self.MAX_RETRIES):
+            try:
+                return self._call_api(system_prompt, user_prompt)
+            except Exception as e:
+                if attempt == self.MAX_RETRIES - 1:
+                    logger.error(
+                        "%s API failed after %d attempts: %s",
+                        self.__class__.__name__,
+                        self.MAX_RETRIES,
+                        e,
+                    )
+                    return None
+                delay = 2**attempt
+                logger.warning(
+                    "%s API error (attempt %d/%d): %s. Retrying in %ds...",
+                    self.__class__.__name__,
+                    attempt + 1,
+                    self.MAX_RETRIES,
+                    e,
+                    delay,
+                )
+                time.sleep(delay)
+
+    def _build_system_prompt(self, guidelines: str) -> str:
+        """Build the system prompt injected once per review call.
+
+        Kept in base so all providers produce a consistent reviewer persona
+        and rule set — the only variable is the guidelines content itself.
+        """
+        return f"""You are a strict and precise senior code reviewer.
+Review the patch below and identify issues according to the guidelines.
+
+{guidelines}
+
+Rules:
+- Focus on added lines (starting with '+') for direct violations.
+- Also consider implications of removed lines (starting with '-') — e.g. deleted null checks,
+  removed error handling, dropped permission guards.
+- Do not comment on code that already follows best practices.
+- Avoid assumptions when context is unclear. Be concise and actionable."""
+
+    def _build_user_prompt(
+        self,
+        description: str,
+        file_name: str,
+        diff_patch: str,
+        file_content: str,
+        repo_context: RepoContext | None = None,
+    ) -> str:
+        """Build the per-file user prompt including any codebase context.
+
+        Kept in base so both providers produce structurally identical prompts.
+        The output format instructions are here rather than in the system
+        prompt because they are specific to the file being reviewed, not to
+        the reviewer's general behaviour.
+        """
+        context_section = build_context_section(repo_context)
+        return f"""You are reviewing `{file_name}` in the context of the full repository.
+{context_section}
+## PR Description
+{description}
+
+## Diff
+{diff_patch}
+
+## Full File Content
+{file_content}
+
+### Output Format:
+Respond with **only** a valid JSON list:
+
+[
+  {{
+    "line": <line number in the new file (integer)>,
+    "severity": "<critical|major|minor|nitpick>",
+    "comment": "<concise, actionable comment>"
+  }},
+  ...
+]
+
+Severity guide:
+- critical: security vulnerability, data loss risk, crash
+- major: logic bug, missing error handling, significant performance issue
+- minor: code smell, unclear naming, missing type hint
+- nitpick: style preference, minor formatting
+
+If there are no issues, return: []
+Do not return any text outside the JSON block."""
+
+    def _parse(self, raw: str) -> list[dict]:
+        """Parse the model's raw text response into a list of comment dicts.
+
+        Kept in base because the expected JSON schema is identical for every
+        provider — stripping markdown fences and loading JSON is not
+        provider-specific behaviour.
+        """
+        try:
+            cleaned = raw.replace("```json", "").replace("```", "").strip()
+            return json.loads(cleaned)
+        except json.JSONDecodeError:
+            logger.warning(
+                "%s: failed to parse response as JSON: %s",
+                self.__class__.__name__,
+                raw[:200],
+            )
+            return []

prlens_core-0.1.4/src/prlens_core/providers/openai.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+try:
+    from openai import OpenAI as _OpenAI
+except ImportError:
+    _OpenAI = None  # type: ignore[assignment,misc]
+
+from prlens_core.providers.base import BaseReviewer
+
+
+class OpenAIReviewer(BaseReviewer):
+    MODEL = "gpt-4o"
+    # temperature=0.2 for OpenAI — lower than Anthropic's 0.3 to lean toward
+    # more deterministic, structured JSON output from GPT-4o.
+    TEMPERATURE = 0.2
+
+    def __init__(self, api_key: str):
+        if _OpenAI is None:
+            raise ImportError(
+                "The 'openai' package is required for this provider. " "Install it with: pip install 'prlens[openai]'"
+            )
+        self.client = _OpenAI(api_key=api_key)
+
+    def _call_api(self, system_prompt: str, user_prompt: str) -> str:
+        response = self.client.chat.completions.create(
+            model=self.MODEL,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+            temperature=self.TEMPERATURE,
+            max_tokens=self.MAX_TOKENS,
+        )
+        return response.choices[0].message.content