diffjudge 0.1.0__py3-none-any.whl

diffjudge/__init__.py

@@ -0,0 +1,5 @@
+"""diffjudge — AI-powered pull request reviewer."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

diffjudge/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

diffjudge/cli.py

@@ -0,0 +1,117 @@
+"""Command-line interface for diffjudge."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import List, Optional
+
+from . import __version__, github
+from .llm import LLMError
+from .github import GitHubError
+from .review import DEFAULT_MAX_DIFF_BYTES, format_comment, review_pr
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="diffjudge",
+        description="AI-powered pull request reviewer.",
+    )
+    parser.add_argument(
+        "--repo",
+        required=True,
+        metavar="OWNER/NAME",
+        help="GitHub repository slug, e.g. octocat/hello-world.",
+    )
+    parser.add_argument(
+        "--pr",
+        required=True,
+        type=int,
+        metavar="N",
+        help="pull request number to review.",
+    )
+    parser.add_argument(
+        "--model",
+        default=os.environ.get("DIFFJUDGE_MODEL", "gpt-4o-mini"),
+        metavar="NAME",
+        help="model name (default: gpt-4o-mini, or $DIFFJUDGE_MODEL).",
+    )
+    parser.add_argument(
+        "--base-url",
+        default=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
+        metavar="URL",
+        help="OpenAI-compatible base URL (default: $OPENAI_BASE_URL or OpenAI).",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=os.environ.get("OPENAI_API_KEY"),
+        metavar="KEY",
+        help="LLM API key (default: $OPENAI_API_KEY).",
+    )
+    parser.add_argument(
+        "--github-token",
+        default=os.environ.get("GITHUB_TOKEN"),
+        metavar="TOKEN",
+        help="GitHub token for fetching the diff and posting (default: $GITHUB_TOKEN).",
+    )
+    parser.add_argument(
+        "--max-diff-bytes",
+        type=int,
+        default=DEFAULT_MAX_DIFF_BYTES,
+        metavar="N",
+        help="truncate diffs larger than this many bytes (default: {0}).".format(
+            DEFAULT_MAX_DIFF_BYTES
+        ),
+    )
+    parser.add_argument(
+        "--post",
+        action="store_true",
+        help="post the review as a PR comment instead of printing it.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="%(prog)s {0}".format(__version__),
+    )
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.api_key:
+        parser.exit(2, "diffjudge: no API key (set $OPENAI_API_KEY or --api-key)\n")
+    if args.post and not args.github_token:
+        parser.exit(2, "diffjudge: --post needs a GitHub token (set $GITHUB_TOKEN)\n")
+
+    try:
+        review = review_pr(
+            args.repo,
+            args.pr,
+            model=args.model,
+            api_key=args.api_key,
+            base_url=args.base_url,
+            github_token=args.github_token,
+            max_diff_bytes=args.max_diff_bytes,
+        )
+    except (LLMError, GitHubError) as exc:
+        parser.exit(1, "diffjudge: {0}\n".format(exc))
+
+    if args.post:
+        try:
+            url = github.post_comment(
+                args.repo, args.pr, format_comment(review), token=args.github_token
+            )
+        except GitHubError as exc:
+            parser.exit(1, "diffjudge: {0}\n".format(exc))
+        sys.stderr.write("diffjudge: posted review -> {0}\n".format(url))
+    else:
+        sys.stdout.write(review.rstrip() + "\n")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

diffjudge/github.py

@@ -0,0 +1,97 @@
+"""Tiny GitHub REST client (stdlib only): fetch a PR diff and post a comment."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Optional
+
+API_ROOT = "https://api.github.com"
+Opener = Callable[..., Any]
+
+
+class GitHubError(RuntimeError):
+    """Raised when a GitHub API request fails."""
+
+
+def pr_url(repo: str, pr: int) -> str:
+    return "{0}/repos/{1}/pulls/{2}".format(API_ROOT, repo, pr)
+
+
+def comments_url(repo: str, pr: int) -> str:
+    return "{0}/repos/{1}/issues/{2}/comments".format(API_ROOT, repo, pr)
+
+
+def _request(
+    url: str,
+    *,
+    token: Optional[str] = None,
+    method: str = "GET",
+    accept: str = "application/vnd.github+json",
+    data: Optional[bytes] = None,
+    opener: Optional[Opener] = None,
+    timeout: int = 60,
+) -> bytes:
+    req = urllib.request.Request(url, data=data, method=method)
+    req.add_header("Accept", accept)
+    req.add_header("User-Agent", "diffjudge")
+    req.add_header("X-GitHub-Api-Version", "2022-11-28")
+    if token:
+        req.add_header("Authorization", "Bearer " + token)
+    if data is not None:
+        req.add_header("Content-Type", "application/json")
+
+    do_open = opener or urllib.request.urlopen
+    try:
+        with do_open(req, timeout=timeout) as resp:
+            return resp.read()
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", "replace")
+        raise GitHubError(
+            "GitHub API error (HTTP {0}): {1}".format(exc.code, body[:300])
+        )
+    except urllib.error.URLError as exc:
+        raise GitHubError("GitHub request failed: {0}".format(exc.reason))
+
+
+def get_pr_diff(
+    repo: str, pr: int, *, token: Optional[str] = None, opener: Optional[Opener] = None
+) -> str:
+    """Return the unified diff for a pull request."""
+    raw = _request(
+        pr_url(repo, pr),
+        token=token,
+        accept="application/vnd.github.v3.diff",
+        opener=opener,
+    )
+    return raw.decode("utf-8", "replace")
+
+
+def get_pr_title(
+    repo: str, pr: int, *, token: Optional[str] = None, opener: Optional[Opener] = None
+) -> str:
+    """Return the pull request title (best effort, empty string on absence)."""
+    raw = _request(pr_url(repo, pr), token=token, opener=opener)
+    data = json.loads(raw.decode("utf-8"))
+    return data.get("title", "") or ""
+
+
+def post_comment(
+    repo: str,
+    pr: int,
+    body: str,
+    *,
+    token: str,
+    opener: Optional[Opener] = None,
+) -> str:
+    """Post a comment on a pull request, returning the created comment URL."""
+    payload = json.dumps({"body": body}).encode("utf-8")
+    raw = _request(
+        comments_url(repo, pr),
+        token=token,
+        method="POST",
+        data=payload,
+        opener=opener,
+    )
+    return json.loads(raw.decode("utf-8")).get("html_url", "")

diffjudge/llm.py

@@ -0,0 +1,67 @@
+"""Minimal client for OpenAI-compatible chat-completion APIs, using only stdlib.
+
+Works against the OpenAI API, OpenRouter, a local llama.cpp server, or anything
+else exposing a ``/chat/completions`` endpoint.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Dict, List, Optional
+
+Message = Dict[str, str]
+Opener = Callable[..., Any]
+
+
+class LLMError(RuntimeError):
+    """Raised when the LLM request fails or returns an unexpected shape."""
+
+
+def extract_message(data: Dict[str, Any]) -> str:
+    """Pull the assistant message text out of a chat-completions response."""
+    try:
+        content = data["choices"][0]["message"]["content"]
+    except (KeyError, IndexError, TypeError):
+        raise LLMError(
+            "unexpected LLM response shape: {0}".format(json.dumps(data)[:300])
+        )
+    if not isinstance(content, str):
+        raise LLMError("LLM returned non-text content")
+    return content.strip()
+
+
+def chat_completion(
+    messages: List[Message],
+    *,
+    model: str,
+    api_key: str,
+    base_url: str = "https://api.openai.com/v1",
+    temperature: float = 0.2,
+    timeout: int = 120,
+    opener: Optional[Opener] = None,
+) -> str:
+    """Call an OpenAI-compatible chat-completions endpoint and return the text."""
+    url = base_url.rstrip("/") + "/chat/completions"
+    payload = json.dumps(
+        {"model": model, "messages": messages, "temperature": temperature}
+    ).encode("utf-8")
+
+    req = urllib.request.Request(url, data=payload, method="POST")
+    req.add_header("Content-Type", "application/json")
+    req.add_header("Authorization", "Bearer " + api_key)
+
+    do_open = opener or urllib.request.urlopen
+    try:
+        with do_open(req, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", "replace")
+        raise LLMError(
+            "LLM request failed (HTTP {0}): {1}".format(exc.code, body[:500])
+        )
+    except urllib.error.URLError as exc:
+        raise LLMError("LLM request failed: {0}".format(exc.reason))
+
+    return extract_message(json.loads(raw))

diffjudge/prompts.py

@@ -0,0 +1,54 @@
+"""Prompt construction for the reviewer."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+Message = Dict[str, str]
+
+SYSTEM_PROMPT = (
+    "You are a meticulous senior software engineer reviewing a pull request. "
+    "Review the unified diff and give a focused, useful review.\n\n"
+    "Priorities, in order:\n"
+    "1. Correctness bugs and logic errors introduced by the change.\n"
+    "2. Security issues (injection, auth, secrets, unsafe input handling).\n"
+    "3. Missing edge cases, error handling, or tests for new behavior.\n"
+    "4. Clear, concrete improvements.\n\n"
+    "Rules:\n"
+    "- Be specific: reference file names and, where you can, the relevant lines.\n"
+    "- Do not nitpick formatting or style unless it affects correctness.\n"
+    "- Do not invent issues. If the change looks good, say so plainly.\n"
+    "- Keep it concise. No filler.\n\n"
+    "Respond in GitHub-flavored markdown with exactly these sections:\n"
+    "## Summary\n"
+    "A two or three sentence overview of what the PR does.\n\n"
+    "## Findings\n"
+    "A bullet list of concrete issues, each prefixed with a severity "
+    "(**blocker** / **major** / **minor** / **nit**). Write 'No significant "
+    "issues found.' if there are none.\n\n"
+    "## Suggestions\n"
+    "Optional improvements that are nice-to-have, or 'None.'"
+)
+
+
+def build_messages(
+    diff: str, *, title: Optional[str] = None, truncated: bool = False
+) -> List[Message]:
+    """Build the chat messages for reviewing a diff."""
+    header = "Pull request"
+    if title:
+        header += ': "{0}"'.format(title)
+
+    note = ""
+    if truncated:
+        note = (
+            "\n\nNote: the diff was truncated because it is large. Review what is "
+            "shown and say so if you cannot assess the whole change."
+        )
+
+    user = "{0}\n\nUnified diff:\n\n```diff\n{1}\n```{2}".format(header, diff, note)
+
+    return [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": user},
+    ]

diffjudge/review.py

@@ -0,0 +1,50 @@
+"""Orchestration: fetch a PR diff, ask the model, return the review markdown."""
+
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+from . import github, llm, prompts
+
+DEFAULT_MAX_DIFF_BYTES = 60_000
+COMMENT_HEADER = "## diffjudge review\n\n"
+
+
+def truncate_diff(diff: str, max_bytes: int) -> Tuple[str, bool]:
+    """Truncate a diff to at most ``max_bytes`` UTF-8 bytes.
+
+    Returns the (possibly shortened) text and whether truncation happened.
+    """
+    encoded = diff.encode("utf-8")
+    if len(encoded) <= max_bytes:
+        return diff, False
+    clipped = encoded[:max_bytes].decode("utf-8", "ignore")
+    return clipped, True
+
+
+def review_pr(
+    repo: str,
+    pr: int,
+    *,
+    model: str,
+    api_key: str,
+    base_url: str = "https://api.openai.com/v1",
+    github_token: Optional[str] = None,
+    max_diff_bytes: int = DEFAULT_MAX_DIFF_BYTES,
+) -> str:
+    """Produce a markdown review for a pull request."""
+    diff = github.get_pr_diff(repo, pr, token=github_token)
+    if not diff.strip():
+        return "_diffjudge: this pull request has an empty diff, nothing to review._"
+
+    title = github.get_pr_title(repo, pr, token=github_token)
+    text, truncated = truncate_diff(diff, max_diff_bytes)
+    messages = prompts.build_messages(text, title=title, truncated=truncated)
+    return llm.chat_completion(
+        messages, model=model, api_key=api_key, base_url=base_url
+    )
+
+
+def format_comment(review: str) -> str:
+    """Wrap a review in the comment header used when posting to a PR."""
+    return COMMENT_HEADER + review.strip() + "\n"

diffjudge-0.1.0.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: diffjudge
+Version: 0.1.0
+Summary: AI-powered pull request reviewer. Reviews diffs with any OpenAI-compatible model and posts the review. Zero dependencies.
+Project-URL: Homepage, https://github.com/Sev7nOfNine/diffjudge
+Project-URL: Repository, https://github.com/Sev7nOfNine/diffjudge
+Project-URL: Issues, https://github.com/Sev7nOfNine/diffjudge/issues
+Author: Seven Of Nine
+License: MIT
+License-File: LICENSE
+Keywords: ai,automation,cli,code-review,github,github-action,llm,maintainer,openai,pull-request
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# diffjudge
+
+**AI-powered pull request reviewer — with zero dependencies.**
+
+`diffjudge` fetches a pull request's diff, asks a language model to review it, and
+either prints the review or posts it back as a PR comment. It works with any
+OpenAI-compatible API: the OpenAI platform, OpenRouter, or a local
+`llama.cpp` / Ollama server. The whole thing is built on the Python standard
+library — no `requests`, no SDKs, nothing to audit but a few hundred lines.
+
+Use it as a CLI for ad-hoc reviews, or drop the bundled GitHub Action into a
+workflow to get an automatic review on every pull request.
+
+## What a review looks like
+
+```markdown
+## diffjudge review
+
+## Summary
+Adds retry handling to the upload client and a backoff helper.
+
+## Findings
+- **major** `client.py`: the retry loop never breaks on a 4xx response, so a bad
+  request is retried 5 times before failing.
+- **minor** `client.py`: `backoff()` ignores the `jitter` argument.
+
+## Suggestions
+- Consider adding a test for the 4xx-no-retry path.
+```
+
+## Install
+
+```bash
+pip install diffjudge
+# or, for an isolated CLI:
+pipx install diffjudge
+```
+
+Requires Python 3.8+.
+
+## CLI usage
+
+```bash
+export OPENAI_API_KEY=sk-...
+export GITHUB_TOKEN=ghp_...        # only needed to fetch private diffs or to --post
+
+# Print a review to your terminal
+diffjudge --repo octocat/hello-world --pr 42
+
+# Post the review as a comment on the PR
+diffjudge --repo octocat/hello-world --pr 42 --post
+
+# Use a different model or provider
+diffjudge --repo octocat/hello-world --pr 42 --model gpt-4o
+diffjudge --repo me/proj --pr 7 --base-url http://localhost:8080/v1 --model local-model
+```
+
+### Options
+
+| Flag | Description |
+| --- | --- |
+| `--repo OWNER/NAME` | Repository to review (required). |
+| `--pr N` | Pull request number (required). |
+| `--model NAME` | Model name (default `gpt-4o-mini`, or `$DIFFJUDGE_MODEL`). |
+| `--base-url URL` | OpenAI-compatible base URL (default `$OPENAI_BASE_URL` or OpenAI). |
+| `--api-key KEY` | LLM API key (default `$OPENAI_API_KEY`). |
+| `--github-token TOKEN` | GitHub token (default `$GITHUB_TOKEN`). |
+| `--max-diff-bytes N` | Truncate diffs larger than this (default 60000). |
+| `--post` | Post the review as a PR comment instead of printing it. |
+
+## GitHub Action
+
+Add a workflow that reviews every pull request. Store your provider key as a
+repository secret (e.g. `OPENAI_API_KEY`):
+
+```yaml
+name: diffjudge
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: Sev7nOfNine/diffjudge@v0.1.0
+        with:
+          api-key: ${{ secrets.OPENAI_API_KEY }}
+          model: gpt-4o-mini
+```
+
+Point `base-url` at any OpenAI-compatible endpoint to use a different provider or
+a self-hosted model.
+
+## Privacy note
+
+`diffjudge` sends the pull request diff to whatever provider you configure. Only
+point it at providers you trust with your code, and prefer a self-hosted model
+(`--base-url`) for private repositories where that matters.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+python -m pytest
+```
+
+The HTTP layers accept an injectable opener, so the whole suite runs offline
+with no real API calls.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

diffjudge-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+diffjudge/__init__.py,sha256=jLI64M6OleZILOtN76jMhuqSnO7n50REF8CiA9v1OCI,104
+diffjudge/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+diffjudge/cli.py,sha256=b9bjNjl9__OdLwuD8XGh-m6z20JApMKaD1Ybq_-Bv4Y,3437
+diffjudge/github.py,sha256=ai075cduqajw2TusVn6-48gqLxd1oi2H21HcYHg0Hp0,2848
+diffjudge/llm.py,sha256=3cqvwLpp_3z7cCxtM0m09nT31nLS92PbQ_DQZy69DlY,2199
+diffjudge/prompts.py,sha256=l372yd7Qc-SxLZPTH69x7EDm6ox-bRGSkIjb2a_arvc,2025
+diffjudge/review.py,sha256=upUT1GD-c6CF2SG8WWQit55s7RqY9_-jNJbsj5I0xOA,1589
+diffjudge-0.1.0.dist-info/METADATA,sha256=W-qWjQjj7BnuzGK8Z7PK3lYhTSbZ18B503wnHpWTqSg,4381
+diffjudge-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+diffjudge-0.1.0.dist-info/entry_points.txt,sha256=7_Ji9ft4HAH4d0LbyFzyQoLeNd3ENob_Ag45H_lLodQ,49
+diffjudge-0.1.0.dist-info/licenses/LICENSE,sha256=z_MXotUe6DP_vu70fPgxIdzHdFq5mHzyHp7p3j22NRA,1070
+diffjudge-0.1.0.dist-info/RECORD,,

diffjudge-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

diffjudge-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+diffjudge = diffjudge.cli:main

diffjudge-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seven Of Nine
+
+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.