prview 0.4.0

PR Review & Artifact Generator - cross-language PR analysis tool
Documentation

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.

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):

make install        # binary + local pre-commit / pre-push hooks
make install-bin    # binary only
cargo install --path .

After the crates.io release:

cargo install prview

Or build without installing:

cargo build --release
./target/release/prview --help

Full instructions, including release binaries and checksums, live in docs/INSTALL.md.

Quick start

# 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

# 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.

The review pack

File What it's for
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.

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:

prview mcp

Canonical client entry (e.g. in an mcp.json):

{
  "mcpServers": {
    "prview": { "command": "prview", "args": ["mcp"] }
  }
}

Six tools cover the loop end to end:

Tool Purpose
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.

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

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

License

BUSL-1.1 — see LICENSE. Package and binary are both named prview; the GitHub repo remains prview-rs.