pr-audit

Find the small risky changes hiding inside huge pull requests.

pr-audit is a local-first CLI for reviewing large diffs. It scans a pull request, local branch, staged change set, or plain .diff file and turns the noisy parts into a short, risk-ordered review list.

It is built for the kind of PR that looks mostly mechanical: AI-assisted refactors, migrations, dependency churn, generated patches, and sweeping renames. Those PRs are hard because the dangerous edits are usually boring and small: a skipped test, a weaker assertion, an unsafe block, a new any, a type-check suppression, or a secret-like value in a config file.

pr-audit does not try to prove that code was written by AI. It does not replace review. It gives reviewers a sharper starting point.

Try it

No repo setup is needed for the built-in demo:

npx pr-audit demo

The demo fixture is checked into this repository, so the first run works without network access:

Risk 100/100 | findings 10 | files 5 | report: examples/reports/demo-report.md

Analyze your own diff:

npx pr-audit analyze --diff ./changes.diff --format markdown

Analyze a local branch:

npx pr-audit analyze --base main --head HEAD

Analyze staged changes before committing:

npx pr-audit analyze --staged --format oneline

Analyze a public GitHub PR:

npx pr-audit analyze https://github.com/owner/repo/pull/123

For GitHub input, set GITHUB_TOKEN or PR_AUDIT_GITHUB_TOKEN if you need higher API rate limits. Local diff and local git analysis never send code to a service.

What it catches

The first release focuses on deterministic, diff-only signals that are cheap to explain and hard to hand-wave away.

Test weakening:

• removed assertions
• changed expectations in the same hunk
• skipped tests
• TODO or placeholder tests
• sleeps and timers added to tests
• large snapshot churn

Unsafe or review-sensitive code:

• Rust unsafe
• Rust unwrap() / expect()
• TypeScript any
• TypeScript diagnostic suppressions
• suspicious TypeScript casts
• Go unsafe
• Go panic

Security and hygiene smoke checks:

• merge conflict markers
• secret-like values added in the diff

List the shipped rules:

npx pr-audit rules

Explain a rule before deciding whether to act on it:

npx pr-audit explain test-mutation/assertion-removed

Example report

pr-audit demo writes a reproducible Markdown report to examples/reports/demo-report.md.

The top of that report is intentionally short:

Risk score: 100 / 100
Files changed: 5
Findings: 10

Top risks
1. Removed assertion in test file in 2 places
2. Assertion appears weakened in 1 place
3. Rust unsafe added in 1 place
4. Skipped test added in 1 place
5. TypeScript check suppression added in 1 place

Each finding includes the rule id, severity, confidence, changed file, evidence, recommendation, and a stable fingerprint that future baseline/suppression features can reuse.

Supported inputs

• Unified diff files: --diff ./changes.diff
• Public GitHub pull requests: https://github.com/owner/repo/pull/123
• Public GitHub pull requests by parts: --repo owner/repo --pr 123
• Local git comparisons: --base main --head HEAD
• Staged changes: --staged
• Offline local runs: --offline

The CLI works best when the diff is available locally. Very large GitHub-hosted diffs can hit platform limits, so the local --base/--head path is the most reliable option for serious reviews.

Output formats

npx pr-audit analyze --diff changes.diff --format table
npx pr-audit analyze --diff changes.diff --format markdown --output pr-audit.md
npx pr-audit analyze --diff changes.diff --format json --output pr-audit.json
npx pr-audit analyze --staged --format oneline

Supported in v0.1:

• table for humans in the terminal
• markdown for GitHub Step Summary, PR comments, and issues
• json for scripts and integrations
• oneline for hooks and compact CI logs

SARIF, HTML, persistent config files, suppressions, baselines, and GitHub annotations are planned, but they are not enabled in v0.1. Reserved flags fail with a clear not supported in this version message instead of pretending to work.

CI

This is the minimal GitHub Actions setup:

name: PR Audit

on:
  pull_request:

permissions:
  contents: read
  pull-requests: read

jobs:
  pr-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: >
          npx pr-audit analyze
          --base origin/main
          --head HEAD
          --ci
          --format markdown
          --output pr-audit.md
          --fail-on high
      - run: cat pr-audit.md >> "$GITHUB_STEP_SUMMARY"

Exit codes:

• 0: analysis completed and configured thresholds passed
• 1: a configured risk threshold failed
• 2: argument or config error
• 3: input source, API, git, or malformed diff error
• 4: parser or rule engine failure
• 5: report generation failure

Privacy model

pr-audit is deliberately boring here:

• no telemetry
• no SaaS backend
• no account
• no hidden model call
• no project install, build, test, or lint scripts are executed
• local git commands are read-only
• secret-like evidence is redacted in JSON and Markdown reports
• --offline disables network input and still works with local diff, git, and demo sources

Limitations

pr-audit is a review aid, not a verdict.

In v0.1, it does not perform full semantic analysis, run tests, prove safety, or infer whether a PR was written by AI. Binary files are counted but not inspected by content rules. Findings should be treated as places to look first, not as automatic blockers.

That tradeoff is intentional. A deterministic diff pass is fast, explainable, and easy to run before a reviewer has spent an hour reading generated churn.

Docs

• Getting started
• Rules
• Report formats
• Configuration
• GitHub Actions
• Suppressions and baseline
• Custom rules
• Limitations
• Privacy

Development

corepack enable
pnpm install
pnpm run typecheck
pnpm test
pnpm run lint
pnpm run build
node dist/index.js demo

The implementation is TypeScript on Node.js 20+. The current rule engine is diff-only by design, with fixtures covering malformed diffs, empty diffs, binary changes, test mutation, unsafe usage, and secret redaction.

Roadmap

• v0.2: config files, SARIF, GitHub annotations, CI summary automation, stronger security/config/dependency rules, .pr-auditignore
• v0.3: Tree-sitter-backed rules for TypeScript, JavaScript, Rust, and Go
• v1.0: stable JSON schema, HTML report, custom rules API, suppressions, and baseline workflows with required reasons

Contributing

Small, focused PRs are welcome. The most useful contributions reduce false positives, improve evidence, add fixtures, tighten reports, or document behavior that is currently easy to misunderstand.

Please keep launch and promotion boringly honest: no fake stars, no spam, and no automated comments on unrelated repositories.