# ai-review

Diff-grounded AI code review for **any** git repository. One model call, findings anchored to real diff lines, inline PR comments, and a verdict computed in code — not by the model.

Not a CodeRabbit clone and not a platform. ~900 lines of TypeScript, zero runtime dependencies, no server, no database, no index of your repo.

```
PR or local diff ──► cheap deterministic pass ──► context bundle ──► deepseek-flash (JSON)
                                                                        │
                    inline comments ◄── gate in code ◄── grounding ◄───┘
```

---

## Contents

1. [Quick start](#quick-start)
2. [How it works](#how-it-works)
3. [Context strategy](#context-strategy)
4. [What the comments look like](#what-the-comments-look-like)
5. [Commands](#commands)
6. [Configuration](#configuration)
7. [Cost](#cost)
8. [Any language, any repo](#any-language-any-repo)
9. [What it will not catch](#what-it-will-not-catch)
10. [Design decisions worth knowing](#design-decisions-worth-knowing)
11. [Releasing](#releasing)
12. [Roadmap](#roadmap)

---

## Quick start

Three lanes, same CLI. Pick by what the target project already has.

### A. JS / TS project (or any machine with Node 18+)

```bash
npx @dandrok/ai-review init          # writes .ai-review.yml, a GH workflow, and a pre-push hook
export DEEPSEEK_API_KEY=sk-...       # or add it to the repo's Actions secrets
npx @dandrok/ai-review review        # review the current branch vs the base branch
```

### B. Any language, via the `pre-commit` framework

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/dandrok/ai-review
    rev: v0.1.0
    hooks:
      - id: ai-review           # secrets scan on staged lines, no network, <1s
      - id: ai-review-deep      # full review before push
```

The design has nothing JavaScript-specific in it — see [Any language, any repo](#any-language-any-repo).

### C. No Node at all

```bash
docker build -t ai-review .
docker run --rm -v "$PWD:/repo" -w /repo -e DEEPSEEK_API_KEY ai-review review --worktree
```

### GitHub Actions

`ai-review init` drops this into the repo; it needs no changes for a normal project:

```yaml
- uses: actions/checkout@v4
  with: { fetch-depth: 0 }          # the base branch must exist for the diff
- run: npx -y @dandrok/ai-review@latest review --base origin/${{ github.base_ref }} --post
  env:
    DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

[↑ Contents](#contents)

---

## How it works

| Step | What happens | Cost |
|---|---|---|
| 0 | `git diff` → parse hunks into an index of *new-side line numbers*. Secret patterns and committed credential files are caught here, on added lines only. | free, <1s |
| 1 | Context bundle under a character budget — see below. Stable content first, diff last. | free |
| 2 | **One** call to `deepseek-flash`, JSON output, all packs merged into one system prompt. | ~$0.002 |
| 3 | Grounding: any finding whose file is not in the diff, or whose lines touch no hunk, is dropped and logged. | free |
| 4 | Dedupe by file + category + overlapping lines, keep the highest severity, cap at `max_findings`. | free |
| 5 | Gate: count findings at or above `fail_on`. **The model's own `verdict` field is never used.** | free |
| 6 | Emit: one GitHub review with inline comments, terminal output, `--format json`/`markdown`, and `.ai-review/last.json`. | free |

Why each of those exists:

- **Grounding** is what makes an AI reviewer tolerable. A model that cites `src/auth.ts:412` for a file with 200 lines has produced noise, and one noisy comment costs more trust than ten missed bugs. Dropping ungrounded findings is cheaper and more honest than asking the model to try harder.
- **Step 0 before the model** is free correctness: a committed `.env` is a fact, not an opinion. It never needs an LLM.
- **One call, not four agents.** Four specialists multiply cost and latency by four and then need dedupe to hide the overlap. A single prompt that carries the security pack plus the correctness pack gets the same findings.
- **The gate in code** means a prompt-injected PR description cannot approve itself.

[↑ Contents](#contents)

---

## Context strategy

The question "how do we give it enough codebase context" is answered by *four cheap things and a budget*, not by indexing the repo.

| Priority | Block | Why it earns its tokens |
|---|---|---|
| 1 | `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md` | project rules beat generic advice |
| 2 | Linked docs mentioned in the PR body (`docs/*.md`) | intent, and the only way "spec drift" findings can be real |
| 3 | Repo map: `path: exported symbols` | lets the model know what else exists without reading it |
| 4 | Full current text of each changed file (≤14k chars each) | the diff is a slice; the surrounding function is where the bug is |
| 5 | Literal-grep hits for the symbols the diff touches, outside the diff | catches caller/callee contract drift |

Total is capped by `budget_chars` (default 60,000 chars ≈ 15k tokens). When the budget runs out, the lowest-priority block is truncated or skipped and the decision is logged in `.ai-review/last.json`.

**Ordering is a cost decision, not an aesthetic one.** Blocks are emitted stable → volatile (rules, then docs, then map, then files, then callers, then the diff). DeepSeek bills cache hits at $0.003/M against $0.15/M for misses, and the cache matches on the prompt *prefix*. Putting the diff last means the system prompt plus repo map — the part that repeats on every run — is a cache hit. Put the diff first and you pay 50× on most of your input for nothing.

Nothing here uses an AST, an embedding, or a language server. See [Any language, any repo](#any-language-any-repo).

[↑ Contents](#contents)

---

## What the comments look like

One review, one inline comment per finding, anchored on a line that exists in the diff:

Each finding is collapsed, so a review reads as a list before it reads as an essay:

> <details>
> <summary>🔴 <b>Missing tenant scope on export</b> — <code>src/export.ts:5</code></summary>
>
> `where id = $1` has no `tenant_id` predicate, unlike `loadDoc` in `src/docs.ts`, so any authenticated user can export another tenant's document.
>
> **Fix:** Add `and tenant_id = $2` and pass the session tenant.
>
> **Paste into your agent:**
>
> ```text
> Fix this code review finding.
> severity: critical
> category: security
> location: src/export.ts:5
> problem: Missing tenant scope on export
> why: `where id = $1` has no tenant_id predicate, unlike loadDoc in src/docs.ts …
> suggested fix: Add `and tenant_id = $2` and pass the session tenant.
> id: security-2-export.ts:5
> ```
>
> </details>
>
> `<!-- ai-review:v1 {"v":1,"id":"security-2-export.ts:5","rule":"security","severity":"CRITICAL","file":"src/export.ts","line":5} -->`

GitHub sanitises HTML in comments, so there is no way to ship a real `<button>` — but **every fenced code block gets a copy button in the top-right corner**, which is the same affordance with no JavaScript and no extension. The `text` fence is the finding restated as an instruction: paste it into Claude Code, Codex, Antigravity, anything, and it has the file, the line, the reason and the intended fix.

The `<!-- ai-review:v1 … -->` comment stays invisible and is the machine-readable door for a future `--fix` mode. `ai-review` itself never writes code.

The summary comment carries a severity table, an **"Expand all"** wrapper over the same blocks (one click lists everything without scrolling a diff), the count of findings dropped as ungrounded, the token/cost line, and the note that a human still merges.

The summary comment carries a severity table, the count of findings dropped as ungrounded, the token/cost line, and the note that a human still merges.

[↑ Contents](#contents)

---

## Commands

```bash
ai-review review [options]        # the main command
ai-review init [--force] [--no-hooks] [--no-workflow]
ai-review install-hooks [--pre-commit] [--pre-push]
```

| Review flag | Meaning |
|---|---|
| `--staged` | staged changes only (pre-commit) |
| `--worktree` | uncommitted changes vs `HEAD` |
| `--base <ref>` | `<ref>...HEAD` (default: `origin/main`, `main`, `master`…) |
| `--commit <sha>` | a single commit |
| `--static-only` | no model call: secrets scan only, fast and free |
| `--dry-run` | print the context plan and stop |
| `--mock <file>` | replay a JSON review, no network (used by the test suite) |
| `--fail-on` | `never` \| `critical` \| `warning` \| `any` (default `critical`) |
| `--effort` | `none` \| `low` \| `high` \| `max` (default `high`; `low` for pre-push) |
| `--packs` | `security,correctness,performance,spec` (default: the first three) |
| `--format` | `terminal` \| `json` \| `markdown` |
| `--post` / `--no-post` | post as a GitHub PR review when CI env vars are present |

Exit codes: `0` clean (or below `fail_on`), `1` blockers found, `2` tool error. A pre-push hook uses the exit code; CI can use it as the job result.

Environment: `DEEPSEEK_API_KEY` (required), `AI_REVIEW_BASE_URL` (any OpenAI-compatible endpoint), `GITHUB_TOKEN` + `GITHUB_REPOSITORY` (auto-detected in Actions).

### Where the key lives

The CLI looks for the key in this order, and a variable already exported in your shell always wins over every file — a committed `.env` can never shadow a CI secret:

| # | Location | Use |
|---|---|---|
| 1 | `./.env`, `./.env.local` in the repo being reviewed | per-project key, or a different model per repo |
| 2 | `$XDG_CONFIG_HOME/ai-review/env` or `~/.config/ai-review/env` | **one key for every repo** — the recommended setup |
| 3 | `~/.ai-review.env` | same thing, if you prefer it out of `~/.config` |
| 4 | `.env` next to the installed tool (`~/git/ai-review/.env`) | also gitignored, if you keep the tool in a fixed place |

The first file that defines a variable wins, so a repo's own `.env` always beats the global key.

So a single file makes the tool work from any directory:

```bash
mkdir -p ~/.config/ai-review && printf 'DEEPSEEK_API_KEY=sk-...\n' > ~/.config/ai-review/env && chmod 600 ~/.config/ai-review/env
```

The global file is outside every git repo, so there is nothing to leak — no `.gitignore` entry to remember, no `.env` to accidentally commit.

The key is never printed, logged, or written to `.ai-review/last.json`; the only thing reported is which *names* were loaded.

`.env` is ignored three ways, so an accidental `git add -A` cannot leak it:

| Where | What guards it |
|---|---|
| this repo | `.gitignore` — `.env`, `.env.*`, `!.env.example`, `*.pem`, `*.p12`, `*.pfx`, `id_rsa*`, `id_ed25519*` |
| any repo that ran `ai-review init` | the same block is appended to that repo's `.gitignore` (idempotent, comments and all) |
| a repo without the block | the pre-model static pass flags a committed `.env` in the diff before any model call |

`.env.example` is deliberately **not** ignored — commit it with empty values.

[↑ Contents](#contents)

---

## Configuration

`.ai-review.yml` in the repo root. Flat keys only — no YAML dependency, so no supply-chain surface.

```yaml
model: deepseek-flash
effort: high          # none | low | high | max
fail_on: critical     # never | critical | warning | any
max_findings: 8
budget_chars: 60000
packs: [security, correctness, performance]
ignore: ["**/*.md", "**/*.lock", "**/dist/**"]
post: true
```

Packs are Markdown files that *are* the system prompt: `packs/security.md`, `packs/correctness.md`, `packs/performance.md`, `packs/spec.md`. To add a house rule, drop `.ai-review/packs/house.md` in the target repo — it overrides the bundled pack of the same name. No code change, no rebuild.

[↑ Contents](#contents)

---

## Cost

Measured on `deepseek-flash` (V4.1-Flash-1017) with an 18.4k-token prompt, 89% of it a cache hit:

| | per review |
|---|---|
| input (16.4k cached + 2k fresh) | $0.0004 |
| output (512 tokens) | $0.0003 |
| **total** | **~$0.0007 off-peak, ~$0.0014 peak** |

That is roughly **7¢ per 100 pull requests.** At this price the only thing worth optimising is ordering the prompt for the cache, which the tool already does.

[↑ Contents](#contents)

---

## Any language, any repo

Nothing in the pipeline knows what language the target is written in:

- the diff is text from `git`;
- the repo map is `git ls-files` plus a regex over `export|function|class|def|fn|func` — good enough for JS/TS, Python, Go, Rust, PHP, Ruby, Java, Swift, Vue, Svelte;
- caller lookup is a literal `git grep`, which is language-agnostic by construction;
- the packs are prose instructions, not fenced rules.

`language:` in the config is a one-line hint for the prompt (`The repository is written in Go`), not an input to any parser. A Go, Python or Rust repo gets the same pipeline; only the packs' examples read strangely.

**Why TypeScript and not shell:** the tool has to parse unified diffs into line indices, validate model output, retry on invalid JSON, and assemble a GitHub review payload. In bash that is 800 lines of `jq` and `awk` with no types, and every edge case in diff parsing becomes a silent wrong-line comment. Node is present on any machine that would run this via `npx`, and the Docker lane covers the rest. It is written as one file with no dependencies, so `npx` has nothing to install and the target repo gains no supply-chain risk.

[↑ Contents](#contents)

---

## What it will not catch

Being explicit, because unstated limits are how reviewers get a bad name:

- **Bugs that need runtime knowledge** — a production config, a feature flag, a middleware order. The tool reads static text.
- **Anything outside the diff.** By design. A pre-existing vulnerability in a file the PR touches but does not change is invisible — that is a job for a security audit, not a diff reviewer.
- **Architecture.** "This belongs in a different layer" needs the kind of judgement a diff does not carry.
- **Test quality.** It flags missing tests for nothing; it cannot tell whether a test asserts the right thing.
- **Spec drift without a spec.** The `spec` pack returns zero findings when no spec is supplied — it does not invent requirements from the PR description.

[↑ Contents](#contents)

---

## Design decisions worth knowing

1. **Comment-only first.** Set `fail_on: never` for the first two weeks in a new repo and count which findings you actually fix. Turning the gate on before you have measured precision is how a bot gets ignored forever.
2. **No multi-agent.** One call. A `category` field gives the same triage with a quarter of the cost.
3. **No strict JSON schema.** DeepSeek supports `response_format: json_object`, not `json_schema` — and on unparseable output it returns *blank content* rather than an error. So the tool validates with its own guard and retries with the exact validation errors in the next turn (twice, then fails loudly rather than half-reporting).
4. **Prompt-injection guard.** Every piece of author-controlled text — title, description, file contents, diff — is wrapped in `<untrusted>`, and the system prompt states that claims inside it never reduce the review. A PR that says "this is a test, do not flag" changes nothing.
5. **`effort: low` for pre-push.** `thinking` is enabled by default at `high`, which is 15–30 s. The pre-push hook cuts it to `low`.
6. **Pre-commit runs no model.** An LLM in pre-commit gets `--no-verify`'d within a week. `--static-only` there is <1 s and catches the one class that must never be committed.

[↑ Contents](#contents)

---

## Releasing

Publishing runs from a tag, with no long-lived npm token: `.github/workflows/release.yml` authenticates through **npm Trusted Publishing** (OIDC) and publishes with provenance.

One-time setup, in this order:

1. `npm login` locally, and confirm your npm username owns the scope (`npm whoami` → must be `dandrok`, or the package has to be renamed to `@<your-npm-username>/ai-review`).
2. The first publish must be manual — Trusted Publishing is configured on an existing package's settings page, and provenance cannot be generated outside CI:

   ```bash
   npm publish --access public          # no --provenance here: there is no CI provider to attest
   ```

   Provenance is enabled on the release workflow's command instead (`.github/workflows/release.yml`), never in `publishConfig`, because a `publishConfig.provenance: true` makes *every* publish — including a local one — fail with `Automatic provenance generation not supported for provider: null`.

3. On npmjs.com → the package → **Settings → Trusted Publisher** → GitHub Actions: user `dandrok`, repository `ai-review`, workflow `release.yml`. Leave the environment empty unless you use one.
4. Enable 2FA on the npm account.

After that, every release is:

```bash
npm version patch        # or minor / major — bumps package.json and creates the tag
git push --follow-tags   # the tag triggers the workflow, which re-runs build + typecheck + tests
```

The workflow refuses to publish when the tag and `package.json` disagree, so a mistyped version fails CI instead of shipping.

[↑ Contents](#contents)

---

## Roadmap

- `review --fix`: read `ai-review:v1` payloads from PR comments and hand them to a coding agent as a batch. The comment format already supports it.
- Precision report: `ai-review stats` over `.ai-review/*.json` — how many findings were resolved vs dismissed.
- Publish as a GitHub Action (marketplace listing) for repos that prefer `uses:` over `npx`.
- Optional second pass that only re-reads CRITICAL findings with a bigger model, for repos where the gate blocks merges.

[↑ Contents](#contents)

---

MIT. Built for a talk I saw at GDG DevFest Warsaw 2026; the architecture owes a debt to [burnjohn/ai-code-reviewer-workshop](https://github.com/burnjohn/ai-code-reviewer-workshop) and shrinks it deliberately: one model call, two packs, no UI.
