Farol scores pull request merge risk per file for the humans who approve

Farol, an open-source tool from Winnin, surfaced on Hacker News on October 25. It is a free CLI and GitHub Action aimed at the person who approves a pull request: it estimates how risky the merge is, shows which files carry that risk, and runs as a step after AI review agents rather than as a replacement for them.

What it does

According to the project's README, Farol answers three questions for an approver: what the change reaches, how risky the merge is, and where to start reading. For every change it lists the existing pages, API operations, RPC methods, background jobs and scripts that execute the modified code, along with the call chain to each. It then produces a verdict — fast track, quick review or careful review — plus a 0–100 risk score computed from reach, diff coverage, security findings, contract breaks and dependency changes. Files are ranked so the riskiest ones get read line by line while low-risk pull requests can move quickly.

The README frames the underlying problem as attention allocation: as agents increasingly write and review code, the final approval is still a human call, and spreading that attention evenly across every pull request turns review into a skim. It cites the Claude Code team's published approach, in which review depth follows the risk of the change rather than who authored it.

How it works

Farol is built on static analysis using real compilers — the TypeScript type checker, Go's go/types and Python's ast module — rather than a model. The README says this makes the output deterministic: identical pull requests produce identical reports, and each claim about reach is traceable through a call chain. When the tool cannot understand part of a change, it reports "unknown" and requests a careful review instead of treating the unclear part as safe.

It also tries to catch contract breaks before clients do: removed response fields, newly required parameters and changed types across GraphQL, FastAPI, Go handlers and gRPC, together with the services that call each endpoint. Existing CI artifacts — coverage, lint, security and audit reports — are folded into per-line findings on the changed code, so nothing runs twice. Every push generates two reports: one covering the full pull request and one covering only the commits since the previous push, so a reviewer can check a round of fixes without starting over.

The README also contrasts the tool with AI review agents: agents read the diff plus whatever context fits a prompt and give probabilistic answers, while Farol reads the whole program at the base and head and gives reproducible ones. The recommended order is agent first, Farol second.

Running it

The project is MIT-licensed, with no account and no hosted service. Per the README, it runs on a local machine or a CI runner, never executes project code, never uploads it anywhere, comments on every pull request and never blocks a merge. The CLI runs via npx @winninjs/farol or a global npm install, and a winnin/farol/action GitHub Action runs it on every PR. Requirements are Node.js 22+ and git, plus Go or Python 3.11+ for projects in those languages. Setup is a one-line farol.config.json declaring the stack, with recipes for React Router, Next.js, TanStack Router, TypeScript APIs, Go and Python services.

The repository ships a live demo: CI-generated reports for a pull request against a FastAPI-plus-React full-stack template that deliberately contains the kind of problems a reviewer should catch — a breaking API change, SQL assembled with an f-string and an untested shared component. Both the backend and frontend reports come back flagged for careful review, and the reports are interactive, letting reviewers mark files as reviewed, mark pages as behind a feature flag and export a record of what was checked.

Why it matters

The interesting bet here is not another AI reviewer but a deterministic complement to one. Model-based review is probabilistic and can sound confident when it is wrong; Farol's pitch is that a compiler-grounded map of blast radius — what a one-line change to a shared helper actually touches — is exactly the information both agents and humans tend to miss, and the kind that can be computed locally and reproducibly. Whether teams adopt a separate triage step in an already crowded review pipeline remains an open question, but as AI-generated pull requests multiply, tooling that tells an approver where a finite budget of human attention is best spent targets a real and growing bottleneck.