mirror of
https://github.com/Sea-Haven-Industries/pr-reviewer.git
synced 2026-09-30 04:33:14 +00:00
99 lines
7.2 KiB
Markdown
99 lines
7.2 KiB
Markdown
# pr-reviewer
|
|
|
|
[](https://github.com/Sea-Haven-Industries/pr-reviewer/actions/workflows/ci.yaml)
|
|
|
|
|
|
A local dashboard that pulls open PRs from your GitHub org, reviews each one with a Fireworks model using the BLOCK / FIX / NIT / QUESTION skill format, and lets you request revisions or post the review to GitHub as yourself.
|
|
|
|
A background worker pre-reviews non-draft PRs on an interval, so a review is usually ready the moment you open one in the queue. You still decide whether and how to post; nothing is ever posted automatically.
|
|
|
|
Reviews are grounded in the Sea Haven [engineering-handbook](https://github.com/Sea-Haven-Industries/engineering-handbook): the app keeps its own clone, distills the review-relevant pages into a compact conventions digest once a day, and feeds that to the model so findings reflect the handbook's naming, commit, PR, secrets, and IaC rules.
|
|
|
|
Everything runs on your machine. This is a local, single-user tool. It is not deployed anywhere, so there is no AWS stack, no CI deploy path, and secrets live only in a local `.env` (gitignored). Your GitHub token and Fireworks key stay in the backend and never reach the browser.
|
|
|
|
## Setup
|
|
|
|
```bash
|
|
cp .env.example .env # then fill in FIREWORKS_API_KEY (and GITHUB_TOKEN if not using gh CLI)
|
|
./run.sh
|
|
```
|
|
|
|
Open http://127.0.0.1:8765
|
|
|
|
## Auth
|
|
|
|
- **GitHub**: leave `GITHUB_TOKEN` blank to use your local `gh auth token`, or set a token. Reviews are posted as whoever the token belongs to, so use the token for the account you want to appear as the reviewer.
|
|
|
|
A **fine-grained personal access token** is recommended (least privilege). Set the resource owner to `Sea-Haven-Industries` and grant only these repository permissions:
|
|
|
|
| Permission | Level | Why |
|
|
|---|---|---|
|
|
| Pull requests | Read and write | read PR data and submit the review |
|
|
| Contents | Read-only | fetch the PR diff |
|
|
| Metadata | Read-only | mandatory (auto-added) |
|
|
|
|
Give it access to all repositories you review (the search silently skips any it can't see). Fine-grained tokens are single-owner, so this token only covers the `Sea-Haven-Industries` org, which is all this tool searches; an org owner may need to approve the token before it works. A classic PAT with `repo` scope also works but is broader than needed.
|
|
- **Fireworks**: set `FIREWORKS_API_KEY`. Change `FIREWORKS_MODEL` in `.env` to swap models.
|
|
|
|
## How it works
|
|
|
|
1. **Background worker** polls your filter (`PR_SEARCH_FILTER`) every `POLL_INTERVAL` seconds and pre-reviews any new or changed non-draft PR, caching the result. The queue is grouped into a collapsible section per repo (collapse state persists), with PRs ordered oldest to newest. Each shows its status: `reviewing`, `ready`, `error`, or `closed`. **Refresh now** forces an immediate poll.
|
|
2. **Open a PR** — if its review is `ready`, it appears instantly. Otherwise you see its status, and you can **Run review now** on demand.
|
|
- **Dependabot PRs** get a dependency-risk assessment instead of code-review notes: the semver update type, a `safe` / `low_risk` / `risky` / `breaking` call, the packages bumped, and reasons, grounded in the handbook's Dependabot merge policy (patch/minor generally safe; majors need changelog review). Feedback focuses on PR title/description quality, not code style.
|
|
- Sidebar tools: **Expand all** / **Collapse all**, and a **Dependabot only** filter.
|
|
3. **Request revision** re-runs the review with your notes folded in as a trusted instruction, separate from the untrusted diff.
|
|
4. **Post review to GitHub** submits it as a PR review. You confirm the event type (COMMENT / APPROVE / REQUEST_CHANGES) and can edit the body first.
|
|
5. **Enable auto-merge** (optional) from the PR detail view: pick a method (squash/merge/rebase, squash default per handbook) and GitHub merges the PR automatically once required checks pass. Nothing merges without you clicking it.
|
|
|
|
### Auto-review worker
|
|
|
|
- Reviews are cached in a local SQLite file (`CACHE_DB`, default `pr_cache.db` in the repo root, gitignored) so they survive restarts and aren't recomputed for unchanged PRs.
|
|
- Change detection is two-level: a PR is skipped if its `updated_at` hasn't moved since the last review, and even when it has, the diff's SHA-256 is compared so a comment-only bump doesn't burn tokens.
|
|
- Drafts are skipped. Failed reviews are retried on later cycles up to `MAX_REVIEW_ATTEMPTS`, then left until the PR changes. Rate-limit (HTTP 429) responses back off and retry.
|
|
- `WORKER_CONCURRENCY` controls how many PRs are reviewed in parallel per cycle (default 2).
|
|
|
|
### Handbook grounding
|
|
|
|
- On the first cycle (and daily after), the worker clones/pulls the engineering-handbook into `~/.cache/pr-reviewer/handbook`, distills the review-relevant pages into a conventions checklist via the Fireworks model, and caches it (`~/.cache/pr-reviewer/handbook_digest.json`). The digest is injected into every review's system prompt.
|
|
- The header shows which handbook commit the reviews are grounded in (`handbook @ <sha>`).
|
|
- The GitHub token must be able to read the (private) handbook repo. If the clone or distillation fails, reviews continue on the base prompt with the last good digest, and failures back off (retried at most hourly). Set `HANDBOOK_ENABLED=false` to turn the feature off. If the clone gets wedged, `rm -rf ~/.cache/pr-reviewer/handbook` and it re-clones.
|
|
|
|
## The @mention rule
|
|
|
|
Any PR whose author login is in `MENTION_AUTHORS` (default `openswe`) gets an `@author` mention prepended to the review summary. Add more logins comma-separated.
|
|
|
|
## Notes
|
|
|
|
- The diff is treated as untrusted input; the model is instructed to ignore any embedded instructions.
|
|
- Cached reviews persist in a local SQLite file. This is a single-user local tool, not a shared service.
|
|
- Large diffs are truncated at `MAX_DIFF_BYTES` to control token cost.
|
|
|
|
## Configuration
|
|
|
|
Set in `.env` (see `.env.example`). Beyond the GitHub/Fireworks keys:
|
|
|
|
| Var | Default | Purpose |
|
|
|---|---|---|
|
|
| `POLL_INTERVAL` | `300` | seconds between background poll cycles |
|
|
| `WORKER_CONCURRENCY` | `2` | PRs reviewed in parallel per cycle |
|
|
| `MAX_REVIEW_ATTEMPTS` | `3` | error retries before giving up until the PR changes |
|
|
| `MAX_PRS` | `100` | cap on PRs pulled per cycle (GitHub search page max) |
|
|
| `CACHE_DB` | `pr_cache.db` | SQLite cache path (absolute, repo root by default) |
|
|
| `HANDBOOK_ENABLED` | `true` | ground reviews in the engineering-handbook |
|
|
| `HANDBOOK_REFRESH_HOURS` | `24` | how often to re-pull + re-distill the handbook |
|
|
| `HANDBOOK_REPO_URL` | handbook repo | git URL cloned for the conventions digest |
|
|
|
|
## Layout
|
|
|
|
```
|
|
app/
|
|
config.py settings from .env
|
|
github_client.py search PRs, fetch diffs, post reviews
|
|
reviewer.py Fireworks call + skill format + markdown rendering
|
|
store.py SQLite cache of pre-computed reviews
|
|
worker.py background poll + auto-review (run_cycle)
|
|
handbook.py clone + daily-distill the engineering-handbook conventions
|
|
main.py FastAPI endpoints (incl. /api/reviews, /api/refresh, /api/handbook)
|
|
static/
|
|
index.html the dashboard
|
|
```
|