Farol 开源发布 基于静态分析评估 PR 合并风险
Farol 是一款开源命令行工具与 GitHub Action，旨在 AI 代码审查后为人工审批者提供合并风险评估。它利用编译器视角的静态分析而非模型猜测，确定性地指出高风险文件位置，帮助开发者将注意力集中在关键变更上，从而优化人机协作的代码审查流程。
报道正文
本文目录4 个章节
Know the risk of merging a pull request, and where it lives.
A free, open-source CLI and GitHub Action. After your AI review, farol tells the person who approves how risky the merge is and which files carry the risk, so the riskiest changes get the most attention.
Website · Live demo · Get started · Reference
Agents write the code and agents review it. The last call is still a person's: approve the merge or not. That approval is the scarce part, and spread evenly over every pull request it turns into a skim, which is how a one-line change to a shared hook takes down forty pages.
farol comes after the AI review, not instead of it. Your review agent comments on the lines in the diff. farol gives the person who approves what the agent cannot reliably give: the risk of accepting the change, and where it lives. The goal is not only a faster review: low-risk pull requests can go fast, and the risky ones get read line by line, starting with the files that carry the risk. It works from static analysis (the compilers' own view of your code, not a model's guess), so the same pull request always gets the same answer.
The Claude Code team describes the same principle in How the Claude Code team does code review: review effort follows the risk of the change. As they put it, "The change sets the tier, not the author."
farol (Portuguese for lighthouse) does the triage before the reviewer opens the diff:
- What does this change reach? Every existing page, API operation, RPC method, job and script that runs the changed code, with the call chain to each.
- How risky is the merge? A verdict (fast track, quick review, careful review) and a 0–100 risk score from reach, diff coverage, security findings, contract breaks and dependency changes.
- Where do I start? The riskiest files first, with inline diffs, untested lines marked, and a checklist of what to try by hand.
Free and open source (MIT). Run it as a CLI with npx @winninjs/farol, or on every pull request with the GitHub
Action winnin/farol/action. No account, no hosted service: it runs on your machine or in your CI runner, comments on
every PR and never blocks a merge. It never executes your code and never sends it anywhere.
Live demo
See farol on a real pull request →
The demo holds the reports farol produced in CI for a pull request on the FastAPI full-stack template: a FastAPI backend and a React frontend with TanStack Router. The pull request adds a status to items and an Insights page, with the kind of problems a reviewer should catch: a breaking API change, SQL built with an f-string, a shared component without tests.
- Backend report: ⚠ careful review, a breaking contract change and a high-severity security finding.
- Frontend report: ⚠ careful review, a new page and the existing pages a shared component reaches.
The reports are interactive: mark files as reviewed, mark a page as behind a feature flag, open the inline diffs,
follow the test plan and copy the review record from the Result tab. They are the same files the pull request's
comments link to (the pull request); the
copies live in docs/demo/.
farol after your AI review
| AI review agents | farol | |
|---|---|---|
| Reads | the diff, and whatever context fits in the prompt | the whole program at the base and the head, with the compilers (TypeScript type checker, go/types, Python ast) |
| Tells you | what may be wrong in these lines | what these lines reach, how risky the merge is, and where to look first |
| Answers are | probabilistic: worded differently on every run | deterministic: the same PR gives the same report, and every claim comes with its call chain |
| When unsure | may sound confident anyway | says unknown and asks for a careful review |
| Runs | a model, usually a hosted service | locally or in your CI: it never executes your code and never sends it anywhere |
Use both, in that order. The agent reviews the lines first; then farol tells the person who approves how much attention the merge needs, which files deserve it, which pages and endpoints to test by hand and which contract changes need their clients checked. The agent's review is not enough exactly when a small change has a large reach, and that is what farol shows.
Why farol
- Review attention goes where the risk is. A 40-file PR usually has two or three files that can actually hurt. farol ranks them, so the reviewer reads those closely and skims the rest with a clear conscience.
- It follows the code, not the file names. farol builds a declaration graph with the real compilers (the TypeScript type checker,
go/types, Python'sast). A change toformatPricelists the twelve pages that render it, not "1 file changed". - Contract breaks are caught before clients are. Removed response fields, new required parameters, changed types in GraphQL, FastAPI, Go handlers and gRPC, with the services that call each endpoint.
- Review the whole PR, or just what changed since your last look. Every push gets two reports: the full pull request, and only the commits since the previous push. After a round of fixes, the reviewer checks the new commits instead of starting over.
- It uses what your CI already has. Coverage, lint, security and audit reports become diff coverage and findings on the changed lines. Nothing runs twice.
- Fail closed. When farol cannot read part of a change, it says so (
unknown) and asks for a careful review. It never calls something safe because it did not understand it. - Built for the human in the loop. Mark files as reviewed, mark pages as behind a feature flag, check off findings, and paste the result back in the PR as a record of what was reviewed.
（注：更多技术实现细节与完整 API 文档请查阅原项目 README）