<p align="center">
<img src="assets/branding/readme-banner.png" alt="prview — surfaces the signal before merge" width="760">
</p>
<p align="center">
<em>surfaces the signal before merge</em>
</p>
<p align="center">
<code>pull request</code> · <code>rust cli</code> · <code>diff intelligence</code>
</p>
<p align="center">
<a href="https://github.com/vetcoders/prview-rs/actions/workflows/ci.yml"><img src="https://github.com/vetcoders/prview-rs/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<a href="https://crates.io/crates/prview"><img src="https://img.shields.io/crates/v/prview.svg" alt="crates.io"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-BUSL--1.1-blue.svg" alt="License: BUSL-1.1"></a>
</p>
---
**prview** reads a pull request the way a good reviewer does: it separates signal from noise. It compares a branch against one or more bases, runs language-aware checks, computes structural heuristics, and emits both human- and machine-readable review packs — so you see the risk before you merge, not after.
No dashboards to babysit. No "powerful insights." Just the things that would block the merge, surfaced early.
```text
likely blocker in auth flow · coverage −2.1% · 1 breaking change in public API
```
## Why prview
- **Signal, not noise** — high-signal review pack: `PR_REVIEW.md`, compact failure summaries, coverage delta, breaking changes.
- **Merge decision support** — policy-aware `MERGE_GATE.json/.md` and optional per-finding `INLINE_FINDINGS.sarif`.
- **Multi-language** — JavaScript/TypeScript, Rust, Python, or mixed repos.
- **Fast** — native Rust binary, parallel checks, `git2` for git operations.
- **Structural heuristics** — Loctree (universal: cycles, dead code, twins across Rust/JS/TS/Python).
- **Made for agents** — a compact `AI_INDEX.md` entry point plus a native MCP server.
- **Shell completions** — bash, zsh, fish, elvish, powershell.
## Install
From a local checkout (recommended for contributors / maintainers):
```bash
make install # binary + local pre-commit / pre-push hooks
make install-bin # binary only
cargo install --path .
```
After the crates.io release:
```bash
cargo install prview
```
Or build without installing:
```bash
cargo build --release
./target/release/prview --help
```
Full instructions, including release binaries and checksums, live in [`docs/INSTALL.md`](docs/INSTALL.md).
## Quick start
```bash
# Fast local review of the current branch vs the default base
prview --quick
# Review a GitHub PR with stricter presets
prview --pr 23 --deep
# Open the latest generated dashboard
prview open
```
Every run writes an artifact pack:
- `AI_INDEX.md` — entry point for humans and agents
- `PR_REVIEW.md` — the unified review narrative
- `report.json` — machine-readable output
- `dashboard.html` — interactive exploration
- `00_summary/MERGE_GATE.json` — gate automation
## Usage
```bash
# Auto-detect profile, diff current branch vs the default base
prview
# Full analysis with stricter presets
prview --deep feature/x main
# Incremental update after new commits
prview --update feature/x main
# Python project
prview --profile python --with-tests --with-lint
# Compact JSON for CI / agents (stdout = JSON only)
prview --pr 23 --quick --json --quiet
# Interactive TUI for browsing results
prview --tui
```
The full flag reference is always one command away: `prview --help`. A written guide lives in [`docs/usage.md`](docs/usage.md).
## The review pack
| `AI_INDEX.md` | Compact entry point for human/agent review |
| `PR_REVIEW.md` | Unified review narrative |
| `report.json` | Machine-readable findings |
| `dashboard.html` | Visual summary of the analysis |
| `00_summary/MERGE_GATE.json` | Pass/fail gate for automation |
| `INLINE_FINDINGS.sarif` | Per-finding annotations (optional) |
The merge decision is a single enum — `PASS`, `CONDITIONAL`, or `BLOCK` — so both humans and automation read one truth. See [`docs/contracts/merge_gate.md`](docs/contracts/merge_gate.md).
## MCP server
Agents don't have to drive the CLI and parse files. prview ships a native MCP (Model Context Protocol) server so an agent can run a review and consume the verdict and artifacts through tools. The server speaks JSON-RPC over stdio:
```bash
prview mcp
```
Canonical client entry (e.g. in an `mcp.json`):
```json
{
"mcpServers": {
"prview": { "command": "prview", "args": ["mcp"] }
}
}
```
Six tools cover the loop end to end:
| `health` | Confirm prview is operational; report version, git, and per-repo tool availability. |
| `state` | Cheap repo snapshot: branch, HEAD, dirty, files changed, latest run for HEAD. |
| `run_review` | Generate a review pack (`quick` synchronous, `deep` detached — poll `verdict`). |
| `verdict` | Single decision truth for a run: `PASS`/`CONDITIONAL`/`BLOCK`, blocking issues, caveats, per-gate status. |
| `findings` | Paged structured findings, filterable by severity and path. |
| `read_artifact` | Raw artifact body, paged and guarded to stay inside the run directory. |
Every tool takes an explicit absolute `repo` path and reads truth from storage, so the server never depends on its own working directory. Every response carries `schema_version: "prview.mcp.v1"`, and failures are fail-loud — a structured `error_class`, never an empty success. Full reference: [`docs/mcp.md`](docs/mcp.md).
## Repository workflow
`prview-rs` is trunk-based on `main`:
- `main` — the trunk and the stable release branch
- feature / fix / chore branches are created from `main` and open PRs back into `main`
- PRs land as merge commits (no squash)
- release tags (`v*`) are cut from `main`
The `prview` tool itself analyzes repositories using any base branch (`develop`, `main`, `master`, …).
## Shell completions
```bash
prview completions bash > $HOME/.local/share/bash-completion/completions/prview
prview completions zsh > $HOME/.zfunc/_prview
prview completions fish > $HOME/.config/fish/completions/prview.fish
```
## Documentation
- [`docs/INSTALL.md`](docs/INSTALL.md) — installation details
- [`docs/usage.md`](docs/usage.md) — full usage guide
- [`docs/configuration.md`](docs/configuration.md) — policy & config
- [`docs/mcp.md`](docs/mcp.md) — MCP server for agents
- [`docs/architecture.md`](docs/architecture.md) — how it works
- [`docs/development.md`](docs/development.md) — contributing
- [`docs/contracts/merge_gate.md`](docs/contracts/merge_gate.md) — `MERGE_GATE.json` contract
## License
BUSL-1.1 — see [LICENSE](LICENSE). Package and binary are both named `prview`; the GitHub repo remains `prview-rs`.
<p align="center"><sub><code>prview</code> · surfaces the signal before merge</sub></p>