pullwise 0.1.0__py3-none-any.whl

pr_pilot/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pr_pilot/analyzer.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+import json
+import subprocess
+from dataclasses import dataclass, field
+
+from openai import OpenAI
+
+from .templates import DESCRIBE_SYSTEM, DESCRIBE_USER, LABEL_SYSTEM, REVIEW_SYSTEM
+
+_MAX_DIFF_CHARS = 24_000   # stay well within context limits
+_MODEL = "gpt-4o"
+
+
+@dataclass
+class PRDescription:
+    title: str
+    summary: str
+    changes: list[str]
+    breaking: bool
+    breaking_notes: str | None
+    test_plan: str
+    labels: list[str]
+
+    def to_markdown(self) -> str:
+        lines = [
+            f"## Summary\n{self.summary}\n",
+            "## Changes",
+        ]
+        for c in self.changes:
+            lines.append(f"- {c}")
+        if self.breaking:
+            lines.append(f"\n## ⚠️ Breaking Changes\n{self.breaking_notes}")
+        lines.append(f"\n## Test Plan\n{self.test_plan}")
+        return "\n".join(lines)
+
+
+def _git(*args: str) -> str:
+    result = subprocess.run(["git"] + list(args), capture_output=True, text=True)
+    return result.stdout.strip()
+
+
+def get_diff(base: str = "main") -> str:
+    diff = _git("diff", f"{base}...HEAD")
+    if len(diff) > _MAX_DIFF_CHARS:
+        diff = diff[:_MAX_DIFF_CHARS] + "\n\n[diff truncated — showing first 24k chars]"
+    return diff
+
+
+def get_commits(base: str = "main") -> str:
+    return _git("log", f"{base}...HEAD", "--oneline", "--no-merges")
+
+
+def get_branch() -> str:
+    return _git("rev-parse", "--abbrev-ref", "HEAD")
+
+
+def describe_pr(api_key: str, base: str = "main", model: str = _MODEL) -> PRDescription:
+    client = OpenAI(api_key=api_key)
+    diff = get_diff(base)
+    commits = get_commits(base)
+    branch = get_branch()
+
+    if not diff and not commits:
+        raise ValueError(f"No changes found between '{branch}' and '{base}'")
+
+    user_msg = DESCRIBE_USER.format(
+        branch=branch, base=base, commits=commits or "(none)", diff=diff or "(empty)"
+    )
+    resp = client.chat.completions.create(
+        model=model,
+        max_tokens=1024,
+        messages=[
+            {"role": "system", "content": DESCRIBE_SYSTEM},
+            {"role": "user", "content": user_msg},
+        ],
+    )
+    raw = resp.choices[0].message.content or "{}"
+    raw = raw.strip()
+    if raw.startswith("```"):
+        raw = "\n".join(raw.splitlines()[1:])
+    if raw.endswith("```"):
+        raw = "\n".join(raw.splitlines()[:-1])
+
+    data = json.loads(raw.strip())
+    return PRDescription(
+        title=data.get("title", branch),
+        summary=data.get("summary", ""),
+        changes=data.get("changes", []),
+        breaking=data.get("breaking", False),
+        breaking_notes=data.get("breaking_notes"),
+        test_plan=data.get("test_plan", ""),
+        labels=data.get("labels", ["feature"]),
+    )
+
+
+def suggest_labels(api_key: str, title: str, body: str, model: str = _MODEL) -> list[str]:
+    client = OpenAI(api_key=api_key)
+    resp = client.chat.completions.create(
+        model=model,
+        max_tokens=64,
+        messages=[
+            {"role": "system", "content": LABEL_SYSTEM},
+            {"role": "user", "content": f"Title: {title}\n\nBody: {body[:2000]}"},
+        ],
+    )
+    raw = resp.choices[0].message.content or "[]"
+    return json.loads(raw.strip())
+
+
+def review_pr(api_key: str, base: str = "main", model: str = _MODEL) -> str:
+    client = OpenAI(api_key=api_key)
+    diff = get_diff(base)
+    if not diff:
+        return "No changes to review."
+    resp = client.chat.completions.create(
+        model=model,
+        max_tokens=1024,
+        messages=[
+            {"role": "system", "content": REVIEW_SYSTEM},
+            {"role": "user", "content": f"Diff:\n\n{diff}"},
+        ],
+    )
+    return (resp.choices[0].message.content or "").strip()

pr_pilot/cli.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+import argparse
+import os
+import sys
+
+from .analyzer import describe_pr, suggest_labels, review_pr
+
+_RESET = "\033[0m"
+_BOLD  = "\033[1m"
+_GREEN = "\033[32m"
+_CYAN  = "\033[36m"
+_DIM   = "\033[2m"
+_YELLOW = "\033[33m"
+
+
+def _key() -> str:
+    k = os.environ.get("OPENAI_API_KEY", "")
+    if not k:
+        print("pr-pilot: OPENAI_API_KEY is not set", file=sys.stderr)
+        sys.exit(1)
+    return k
+
+
+def cmd_describe(args: argparse.Namespace) -> None:
+    print(f"\n  {_DIM}Analyzing diff against '{args.base}'...{_RESET}\n")
+    desc = describe_pr(_key(), base=args.base, model=args.model)
+
+    print(f"{_BOLD}Title:{_RESET}  {desc.title}\n")
+    print(f"{_BOLD}Summary:{_RESET}")
+    print(f"  {desc.summary}\n")
+    print(f"{_BOLD}Changes:{_RESET}")
+    for c in desc.changes:
+        print(f"  {_GREEN}•{_RESET} {c}")
+    if desc.breaking:
+        print(f"\n  {_YELLOW}⚠ Breaking:{_RESET} {desc.breaking_notes}")
+    print(f"\n{_BOLD}Test plan:{_RESET}")
+    print(f"  {desc.test_plan}")
+    print(f"\n{_BOLD}Suggested labels:{_RESET} {', '.join(desc.labels)}")
+
+    if args.markdown:
+        path = args.markdown
+        with open(path, "w") as f:
+            f.write(desc.to_markdown())
+        print(f"\n  {_GREEN}✓{_RESET} Written to {path}")
+    print()
+
+
+def cmd_review(args: argparse.Namespace) -> None:
+    print(f"\n  {_DIM}Reviewing diff against '{args.base}'...{_RESET}\n")
+    review = review_pr(_key(), base=args.base, model=args.model)
+    print(review)
+    print()
+
+
+def cmd_action(args: argparse.Namespace) -> None:
+    """Run as a GitHub Action — reads env vars set by the Actions runner."""
+    import json as _json
+    from .github_client import get_pr, update_pr, add_labels
+
+    repo     = os.environ.get("GITHUB_REPOSITORY", "")
+    pr_num   = int(os.environ.get("PR_NUMBER", "0"))
+    token    = os.environ.get("GITHUB_TOKEN", "")
+    skip_labels = os.environ.get("SKIP_LABELS", "false").lower() == "true"
+    update_title = os.environ.get("UPDATE_TITLE", "false").lower() == "true"
+
+    if not repo or not pr_num or not token:
+        print("pr-pilot action: GITHUB_REPOSITORY, PR_NUMBER, GITHUB_TOKEN must be set", file=sys.stderr)
+        sys.exit(1)
+
+    pr = get_pr(repo, pr_num)
+    print(f"  PR #{pr_num}: {pr.title}")
+    print(f"  Base: {pr.base}  Head: {pr.head}")
+
+    desc = describe_pr(_key(), base=pr.base, model=args.model)
+    body = desc.to_markdown()
+
+    # Don't overwrite if user already wrote a substantial description
+    if pr.body and len(pr.body.strip()) > 100:
+        print("  PR already has a description — skipping body update")
+        body = None
+
+    update_pr(repo, pr_num, title=desc.title if update_title else None, body=body or pr.body)
+    print(f"  ✓ Description updated")
+
+    if not skip_labels:
+        add_labels(repo, pr_num, desc.labels)
+        print(f"  ✓ Labels added: {', '.join(desc.labels)}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="pr-pilot",
+        description="AI-powered PR descriptions and labels using OpenAI.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # --- describe ---
+    p_desc = sub.add_parser("describe", help="Generate a PR description for the current branch")
+    p_desc.add_argument("--base", default="main", help="Base branch to diff against (default: main)")
+    p_desc.add_argument("--model", default="gpt-4o", help="OpenAI model to use")
+    p_desc.add_argument("--markdown", metavar="FILE", help="Write description as markdown to FILE")
+    p_desc.set_defaults(func=cmd_describe)
+
+    # --- review ---
+    p_rev = sub.add_parser("review", help="Get a quick code review of the current branch")
+    p_rev.add_argument("--base", default="main", help="Base branch to diff against (default: main)")
+    p_rev.add_argument("--model", default="gpt-4o", help="OpenAI model to use")
+    p_rev.set_defaults(func=cmd_review)
+
+    # --- action (internal, called by entrypoint.sh) ---
+    p_act = sub.add_parser("action", help="Run as a GitHub Action (internal)")
+    p_act.add_argument("--model", default="gpt-4o")
+    p_act.set_defaults(func=cmd_action)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

pr_pilot/github_client.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+import json
+import os
+import sys
+import urllib.request
+import urllib.error
+from dataclasses import dataclass
+
+
+@dataclass
+class PRInfo:
+    number: int
+    title: str
+    body: str
+    base: str
+    head: str
+
+
+def _api(method: str, path: str, body: dict | None = None) -> dict:
+    token = os.environ.get("GITHUB_TOKEN", "")
+    url = f"https://api.github.com{path}"
+    data = json.dumps(body).encode() if body else None
+    req = urllib.request.Request(
+        url, data=data, method=method,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+            "Content-Type": "application/json",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        print(f"GitHub API error {e.code}: {e.read().decode()}", file=sys.stderr)
+        sys.exit(1)
+
+
+def get_pr(repo: str, pr_number: int) -> PRInfo:
+    data = _api("GET", f"/repos/{repo}/pulls/{pr_number}")
+    return PRInfo(
+        number=data["number"],
+        title=data["title"],
+        body=data.get("body") or "",
+        base=data["base"]["ref"],
+        head=data["head"]["ref"],
+    )
+
+
+def update_pr(repo: str, pr_number: int, title: str | None, body: str) -> None:
+    payload: dict = {"body": body}
+    if title:
+        payload["title"] = title
+    _api("PATCH", f"/repos/{repo}/pulls/{pr_number}", payload)
+
+
+def add_labels(repo: str, pr_number: int, labels: list[str]) -> None:
+    # Ensure labels exist first
+    existing = {l["name"] for l in _api("GET", f"/repos/{repo}/labels")}
+    _COLORS = {
+        "bug": "d73a4a", "feature": "0075ca", "docs": "0075ca",
+        "refactor": "e4e669", "test": "bfd4f2", "chore": "ffffff",
+        "performance": "f9d0c4", "security": "ee0701", "breaking-change": "b60205",
+    }
+    for label in labels:
+        if label not in existing:
+            try:
+                _api("POST", f"/repos/{repo}/labels", {
+                    "name": label,
+                    "color": _COLORS.get(label, "ededed"),
+                })
+            except SystemExit:
+                pass  # label might already exist in race condition
+
+    _api("POST", f"/repos/{repo}/issues/{pr_number}/labels", {"labels": labels})
+
+
+def post_comment(repo: str, pr_number: int, body: str) -> None:
+    _api("POST", f"/repos/{repo}/issues/{pr_number}/comments", {"body": body})

pr_pilot/templates.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+DESCRIBE_SYSTEM = """\
+You are an expert software engineer writing a pull request description.
+Given a git diff and commit messages, produce a clear, structured PR description.
+
+Return a JSON object with exactly these keys:
+{
+  "title": "short imperative title, max 72 chars",
+  "summary": "1-3 sentence plain-English explanation of WHAT changed and WHY",
+  "changes": ["bullet point list of key changes (max 8 items)"],
+  "breaking": true or false,
+  "breaking_notes": "describe breaking changes if any, else null",
+  "test_plan": "how to verify this PR works (be specific, not generic)",
+  "labels": ["one or more of: bug, feature, docs, refactor, test, chore, performance, security, breaking-change"]
+}
+
+Rules:
+- Be concrete. Never write "various improvements" or "updates code".
+- title must be imperative: "Add X", "Fix Y", "Remove Z" — not "Added" or "Adding"
+- If the diff is too large, summarize the most impactful changes
+- Return ONLY the JSON object, no markdown fences
+"""
+
+DESCRIBE_USER = """\
+Branch: {branch}
+Target: {base}
+Commits:
+{commits}
+
+Diff (may be truncated):
+{diff}
+"""
+
+LABEL_SYSTEM = """\
+You are a PR triage bot. Given a PR title, description, and diff summary,
+return ONLY a JSON array of label strings from this set:
+["bug", "feature", "docs", "refactor", "test", "chore", "performance", "security", "breaking-change"]
+Return between 1 and 3 labels. No prose, just the array.
+"""
+
+REVIEW_SYSTEM = """\
+You are a senior engineer doing a quick PR review pass.
+Given a diff, summarize:
+1. What this PR does (2-3 sentences)
+2. Potential concerns or risks (if any)
+3. Suggested improvements (if any, max 3)
+
+Be direct and specific. No flattery. Format as plain markdown.
+"""

pullwise-0.1.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: pullwise
+Version: 0.1.0
+Summary: AI-powered PR descriptions, labels, and code review using OpenAI
+License: MIT
+Project-URL: Homepage, https://github.com/albertusreza/pr-pilot
+Project-URL: Issues, https://github.com/albertusreza/pr-pilot/issues
+Project-URL: GitHub Action, https://github.com/marketplace/actions/pr-pilot
+Keywords: github,pull-request,openai,ai,automation,devtools,cli,github-actions
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: openai>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# pr-pilot ✈️
+
+**Stop writing PR descriptions.** Let AI do it.
+
+`pr-pilot` is a GitHub Action + CLI that analyzes your diff and commit history, then automatically writes a clear, structured PR description — with a summary, change list, test plan, and labels.
+
+```yaml
+# .github/workflows/pr-description.yml
+- uses: albertusreza/pr-pilot@main
+  with:
+    openai-api-key: ${{ secrets.OPENAI_API_KEY }}
+```
+
+That's it. Every new PR gets a description like this:
+
+---
+
+> **Add rate limiting to upload endpoint**
+>
+> ## Summary
+> Adds per-IP rate limiting to `/api/upload` using a sliding window algorithm.
+> Without this, a single client could saturate the server with concurrent uploads.
+>
+> ## Changes
+> - Add `RateLimiter` middleware with configurable window and max requests
+> - Apply limiter to `/api/upload` route (100 req/min default)
+> - Return `429 Too Many Requests` with `Retry-After` header
+> - Add unit tests for edge cases (burst, reset, concurrent)
+>
+> ## Test Plan
+> 1. Run `pytest tests/test_rate_limiter.py`
+> 2. Send 101 rapid requests to `/api/upload` — 101st should return 429
+> 3. Wait 60 seconds — requests should succeed again
+>
+> **Labels:** `feature`, `security`
+
+---
+
+## Install
+
+### As a GitHub Action (zero-config)
+
+```yaml
+name: PR Pilot
+on:
+  pull_request:
+    types: [opened, reopened]
+
+jobs:
+  describe:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: albertusreza/pr-pilot@main
+        with:
+          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
+```
+
+Add `OPENAI_API_KEY` to your repo secrets and you're done. Works with any language, any repo size.
+
+### As a CLI
+
+```bash
+pip install pr-pilot
+export OPENAI_API_KEY=sk-...
+
+# Generate a description for your current branch
+pr-pilot describe
+
+# Diff against a different base
+pr-pilot describe --base develop
+
+# Get a quick code review
+pr-pilot review
+
+# Save description as markdown
+pr-pilot describe --markdown pr_description.md
+```
+
+## Options
+
+| Input | Default | Description |
+|---|---|---|
+| `openai-api-key` | — | **Required.** Your OpenAI API key |
+| `model` | `gpt-4o` | OpenAI model to use |
+| `skip-labels` | `false` | Skip adding labels to the PR |
+| `update-title` | `false` | Also rewrite the PR title |
+
+## How it works
+
+1. On PR open, checks out the branch with full history
+2. Runs `git diff <base>...HEAD` to get the full diff
+3. Collects commit messages with `git log --oneline`
+4. Sends both to GPT-4o with a structured prompt
+5. Parses the JSON response and updates the PR body + labels via GitHub API
+6. Skips update if the PR already has a substantial description (>100 chars)
+
+## Why
+
+Over 60% of PRs are merged with descriptions like "fix bug", "WIP", or nothing at all. This makes code review harder, changelogs meaningless, and git history useless for future maintainers.
+
+`pr-pilot` takes 30 seconds to set up and runs on every PR automatically — no discipline required.
+
+## Cost
+
+Each PR description costs roughly **$0.01–0.03** with `gpt-4o` depending on diff size. For a team of 5 opening ~20 PRs/week, that's about **$1–3/month**.
+
+## Self-hosted / private repos
+
+Works with private repos. Just add the secret and the workflow file — no data leaves your GitHub Actions runner except the diff sent to OpenAI.
+
+## Contributing
+
+```bash
+git clone https://github.com/albertusreza/pr-pilot
+cd pr-pilot
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

pullwise-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pr_pilot/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+pr_pilot/analyzer.py,sha256=GiAlySWBUBOGb_wovbJ_ilPgiP_Jw0eSOMBdzYwH62Q,3716
+pr_pilot/cli.py,sha256=N90-y5wKT7Cxv2iapxh0JiRaixCRS1x0NWR7koGsTzI,4253
+pr_pilot/github_client.py,sha256=mk359AVH4GJfQdDdz_D1gZupJJb68ov3HzvmbyEeGcU,2521
+pr_pilot/templates.py,sha256=_Z9OLyYTYK5Y4x8ByFfnjHykr4KRUDnS5x3k47my8JQ,1738
+pullwise-0.1.0.dist-info/METADATA,sha256=p4rLEvM-PifOYx1wXJbymAmOA3c3ne_uqvdDjuvMPB4,4391
+pullwise-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pullwise-0.1.0.dist-info/entry_points.txt,sha256=1s4fb04UXwbcdX5_doW8Kj01NhN9EF_9STLYXKorjqU,76
+pullwise-0.1.0.dist-info/top_level.txt,sha256=shJVaJpBrxFmcPsqjDgBLAwoQKdDOj0DuE5i2oJZbl8,9
+pullwise-0.1.0.dist-info/RECORD,,

pullwise-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pullwise-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pr-pilot = pr_pilot.cli:main
+pullwise = pr_pilot.cli:main

pullwise-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pr_pilot