prlens 0.1.0__tar.gz

prlens-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 lens contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

prlens-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: prlens
+Version: 0.1.0
+Summary: AI-powered GitHub PR code reviewer for teams
+License: MIT
+Project-URL: Homepage, https://github.com/jodohq/lens
+Project-URL: Issues, https://github.com/jodohq/lens/issues
+Keywords: code-review,github,ai,llm,pull-request
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyGithub>=2.1
+Requires-Dist: openai>=1.0
+Requires-Dist: anthropic>=0.25
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.12; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Dynamic: license-file
+
+# lens
+
+AI-powered GitHub PR code reviewer for teams. Fetches a pull request, reviews each changed file against your coding guidelines using Claude or GPT-4o, and posts inline comments directly on GitHub.
+
+## Features
+
+- Reviews only added/modified files — skips deleted files and binary assets
+- Supports **Anthropic Claude** and **OpenAI GPT-4o** as AI backends
+- Bring your own guidelines via a simple YAML config file
+- Posts inline review comments on the diff using the GitHub Review API
+- Runs as a **CLI tool** locally or as a **GitHub Action** automatically on every PR
+- Prevents duplicate comments across repeated runs
+- Filters known AI false positives (hallucinated suggestions)
+
+## Installation
+
+```bash
+pip install prlens
+```
+
+## Quick Start (CLI)
+
+```bash
+export GITHUB_TOKEN=ghp_...
+export ANTHROPIC_API_KEY=sk-ant-...
+
+prlens --repo owner/repo --pr 42 --model anthropic
+```
+
+Omit `--pr` to list open PRs and pick one interactively.
+
+## GitHub Action
+
+Add this workflow to your repository to automatically review every pull request:
+
+```yaml
+# .github/workflows/code-review.yml
+name: Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: jodohq/prlens/.github/actions/review@main
+        with:
+          model: anthropic
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+## Configuration
+
+Copy `.prlens.example.yml` to `.prlens.yml` in your repository root:
+
+```yaml
+# .prlens.yml
+model: anthropic          # anthropic | openai
+max_chars_per_file: 20000
+batch_limit: 60
+
+# Path to your team's coding guidelines (relative to repo root)
+# guidelines: ./docs/guidelines.md
+
+# Files/directories to skip — fnmatch globs or directory names
+# exclude:
+#   - migrations/
+#   - "*.min.js"
+
+# Set to true to review draft PRs (skipped by default)
+review_draft_prs: false
+```
+
+The `--model` and `--guidelines` CLI flags override the config file. The config file overrides built-in defaults.
+
+## Custom Guidelines
+
+Point `guidelines` in `.prlens.yml` to any Markdown file containing your team's coding standards:
+
+```yaml
+guidelines: ./docs/guidelines.md
+```
+
+When not set, built-in generic guidelines are used as a starting point. Copy them from [`prlens/guidelines/`](prlens/guidelines/) and customize.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `GITHUB_TOKEN` | Yes | GitHub personal access token with `pull_requests: write` |
+| `ANTHROPIC_API_KEY` | When using Claude | Anthropic API key |
+| `OPENAI_API_KEY` | When using GPT-4o | OpenAI API key |
+
+## CLI Reference
+
+```
+Usage: prlens [OPTIONS]
+
+  AI-powered GitHub PR code reviewer.
+
+Options:
+  --repo TEXT                GitHub repository in owner/name format. [required]
+  --pr INTEGER               Pull request number. Omit to list open PRs interactively.
+  --model [anthropic|openai] AI model provider. Overrides config file.
+  --config TEXT              Path to the configuration file. [default: .prlens.yml]
+  -y, --yes                  Skip confirmation prompts and post comments automatically.
+  --guidelines PATH          Path to a Markdown guidelines file. Overrides config file.
+  -s, --shadow               Dry-run mode: print review comments to the terminal without posting to GitHub.
+  --help                     Show this message and exit.
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a development environment, run tests, and add new AI providers.
+
+## License
+
+[MIT](LICENSE)

prlens-0.1.0/README.md

@@ -0,0 +1,121 @@
+# lens
+
+AI-powered GitHub PR code reviewer for teams. Fetches a pull request, reviews each changed file against your coding guidelines using Claude or GPT-4o, and posts inline comments directly on GitHub.
+
+## Features
+
+- Reviews only added/modified files — skips deleted files and binary assets
+- Supports **Anthropic Claude** and **OpenAI GPT-4o** as AI backends
+- Bring your own guidelines via a simple YAML config file
+- Posts inline review comments on the diff using the GitHub Review API
+- Runs as a **CLI tool** locally or as a **GitHub Action** automatically on every PR
+- Prevents duplicate comments across repeated runs
+- Filters known AI false positives (hallucinated suggestions)
+
+## Installation
+
+```bash
+pip install prlens
+```
+
+## Quick Start (CLI)
+
+```bash
+export GITHUB_TOKEN=ghp_...
+export ANTHROPIC_API_KEY=sk-ant-...
+
+prlens --repo owner/repo --pr 42 --model anthropic
+```
+
+Omit `--pr` to list open PRs and pick one interactively.
+
+## GitHub Action
+
+Add this workflow to your repository to automatically review every pull request:
+
+```yaml
+# .github/workflows/code-review.yml
+name: Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: jodohq/prlens/.github/actions/review@main
+        with:
+          model: anthropic
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
+## Configuration
+
+Copy `.prlens.example.yml` to `.prlens.yml` in your repository root:
+
+```yaml
+# .prlens.yml
+model: anthropic          # anthropic | openai
+max_chars_per_file: 20000
+batch_limit: 60
+
+# Path to your team's coding guidelines (relative to repo root)
+# guidelines: ./docs/guidelines.md
+
+# Files/directories to skip — fnmatch globs or directory names
+# exclude:
+#   - migrations/
+#   - "*.min.js"
+
+# Set to true to review draft PRs (skipped by default)
+review_draft_prs: false
+```
+
+The `--model` and `--guidelines` CLI flags override the config file. The config file overrides built-in defaults.
+
+## Custom Guidelines
+
+Point `guidelines` in `.prlens.yml` to any Markdown file containing your team's coding standards:
+
+```yaml
+guidelines: ./docs/guidelines.md
+```
+
+When not set, built-in generic guidelines are used as a starting point. Copy them from [`prlens/guidelines/`](prlens/guidelines/) and customize.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `GITHUB_TOKEN` | Yes | GitHub personal access token with `pull_requests: write` |
+| `ANTHROPIC_API_KEY` | When using Claude | Anthropic API key |
+| `OPENAI_API_KEY` | When using GPT-4o | OpenAI API key |
+
+## CLI Reference
+
+```
+Usage: prlens [OPTIONS]
+
+  AI-powered GitHub PR code reviewer.
+
+Options:
+  --repo TEXT                GitHub repository in owner/name format. [required]
+  --pr INTEGER               Pull request number. Omit to list open PRs interactively.
+  --model [anthropic|openai] AI model provider. Overrides config file.
+  --config TEXT              Path to the configuration file. [default: .prlens.yml]
+  -y, --yes                  Skip confirmation prompts and post comments automatically.
+  --guidelines PATH          Path to a Markdown guidelines file. Overrides config file.
+  -s, --shadow               Dry-run mode: print review comments to the terminal without posting to GitHub.
+  --help                     Show this message and exit.
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a development environment, run tests, and add new AI providers.
+
+## License
+
+[MIT](LICENSE)

prlens-0.1.0/prlens/__init__.py

@@ -0,0 +1,3 @@
+"""lens: AI-powered GitHub PR code reviewer for teams."""
+
+__version__ = "0.1.0"

prlens-0.1.0/prlens/cli.py

@@ -0,0 +1,88 @@
+"""CLI entry point for lens."""
+
+import click
+from rich.console import Console
+
+from prlens.config import load_config
+from prlens.gh.pull_request import get_repo, get_pull_requests
+from prlens.reviewer import run_review
+
+console = Console()
+
+
+@click.command()
+@click.option("--repo", required=True, help="GitHub repository in owner/name format.")
+@click.option(
+    "--pr",
+    "pr_number",
+    type=int,
+    default=None,
+    help="Pull request number. Omit to list open PRs interactively.",
+)
+@click.option(
+    "--model",
+    type=click.Choice(["anthropic", "openai"]),
+    default=None,
+    help="AI model provider. Overrides config file.",
+)
+@click.option(
+    "--guidelines",
+    "guidelines_path",
+    default=None,
+    help="Path to a Markdown guidelines file. Overrides config file.",
+)
+@click.option(
+    "--config",
+    "config_path",
+    default=".prlens.yml",
+    show_default=True,
+    help="Path to the configuration file.",
+)
+@click.option(
+    "--yes",
+    "-y",
+    is_flag=True,
+    help="Skip confirmation prompts and post comments automatically.",
+)
+@click.option(
+    "--shadow",
+    "-s",
+    is_flag=True,
+    help="Dry-run mode: print review comments to the terminal without posting to GitHub.",
+)
+def main(repo: str, pr_number: int | None, model: str | None, guidelines_path: str | None, config_path: str, yes: bool, shadow: bool):
+    """AI-powered GitHub PR code reviewer.
+
+    Fetches a pull request, reviews each changed file against your coding
+    guidelines using Claude or GPT-4o, and posts inline comments on GitHub.
+
+    \b
+    Required environment variables:
+      GITHUB_TOKEN         GitHub personal access token
+      ANTHROPIC_API_KEY    Required when using --model anthropic
+      OPENAI_API_KEY       Required when using --model openai
+    """
+    config = load_config(config_path, cli_overrides={"model": model, "guidelines": guidelines_path})
+
+    if not config.get("github_token"):
+        raise click.UsageError(
+            "GITHUB_TOKEN environment variable is not set. "
+            "Create a token at https://github.com/settings/tokens"
+        )
+    if config["model"] == "anthropic" and not config.get("anthropic_api_key"):
+        raise click.UsageError("ANTHROPIC_API_KEY environment variable is not set.")
+    if config["model"] == "openai" and not config.get("openai_api_key"):
+        raise click.UsageError("OPENAI_API_KEY environment variable is not set.")
+
+    if pr_number is None:
+        this_repo = get_repo(repo, token=config["github_token"])
+        prs = list(get_pull_requests(this_repo))
+        if not prs:
+            console.print("[yellow]No open pull requests found.[/yellow]")
+            return
+        console.print("\nOpen pull requests:")
+        for pr in prs:
+            console.print(f"  [bold]#{pr.number}[/bold]  {pr.title}")
+        pr_number = click.prompt("\nEnter the pull request number", type=int)
+
+    run_review(repo=repo, pr_number=pr_number, config=config, auto_confirm=yes, shadow=shadow)

prlens-0.1.0/prlens/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-0.1.0/prlens/gh/pull_request.py

@@ -0,0 +1,17 @@
+from github import Github
+
+
+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()

prlens-0.1.0/prlens/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-0.1.0/prlens/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-0.1.0/prlens/providers/anthropic.py

@@ -0,0 +1,114 @@
+import json
+import logging
+import time
+
+from anthropic import Anthropic
+from anthropic.types import TextBlock
+
+from prlens.providers.base import BaseReviewer
+
+logger = logging.getLogger(__name__)
+
+
+class AnthropicReviewer(BaseReviewer):
+    MODEL = "claude-sonnet-4-20250514"
+    MAX_TOKENS = 4096
+    MAX_RETRIES = 3
+
+    def __init__(self, api_key: str):
+        self.client = Anthropic(api_key=api_key)
+
+    def review(
+        self,
+        description: str,
+        file_name: str,
+        diff_patch: str,
+        file_content: str,
+        guidelines: str,
+    ) -> list[dict]:
+        prompt = self._build_prompt(description, file_name, diff_patch, file_content, guidelines)
+        raw = self._call_with_retry(prompt)
+        if raw is None:
+            return []
+        return self._parse(raw)
+
+    def _call_with_retry(self, prompt: str) -> str | None:
+        for attempt in range(self.MAX_RETRIES):
+            try:
+                response = self.client.messages.create(
+                    model=self.MODEL,
+                    messages=[{"role": "user", "content": prompt}],
+                    temperature=0.3,
+                    max_tokens=self.MAX_TOKENS,
+                )
+                text_blocks = [block.text for block in response.content if isinstance(block, TextBlock)]
+                return "".join(text_blocks).strip()
+            except Exception as e:
+                if attempt == self.MAX_RETRIES - 1:
+                    logger.error("Anthropic API failed after %d attempts: %s", self.MAX_RETRIES, e)
+                    return None
+                delay = 2**attempt
+                logger.warning(
+                    "Anthropic API error (attempt %d/%d): %s. Retrying in %ds...",
+                    attempt + 1,
+                    self.MAX_RETRIES,
+                    e,
+                    delay,
+                )
+                time.sleep(delay)
+
+    def _build_prompt(
+        self, description: str, file_name: str, diff_patch: str, file_content: str, guidelines: str
+    ) -> str:
+        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.
+
+You are reviewing file `{file_name}`.
+
+PR description:
+{description}
+
+Diff:
+{diff_patch}
+
+File content (for context):
+{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]:
+        try:
+            cleaned = raw.replace("```json", "").replace("```", "").strip()
+            return json.loads(cleaned)
+        except json.JSONDecodeError:
+            logger.warning("Failed to parse Anthropic response as JSON: %s", raw[:200])
+            return []