Farol: Bản đồ rủi ro cho pull request, giúp người duyệt biết nên đọc file nào trước

Trong bối cảnh các agent AI ngày càng viết nhiều mã và cũng chính các agent đó review lại, quyết định cuối cùng vẫn nằm ở con người: bấm duyệt hay không. Nhưng khi sự tập trung bị chia đều cho mọi pull request, việc duyệt biến thành "lướt qua" — và đó chính là lúc một thay đổi chỉ một dòng trong hook dùng chung có thể làm sập hàng chục trang.

Farol (tiếng Bồ Đào Nha nghĩa là "ngọn hải đăng") là một công cụ mã nguồn mở, miễn phí, ra đời để giải quyết đúng điểm nghẽn đó: cho người phê duyệt biết mức độ rủi ro của một lần merge và rủi ro nằm ở file nào.

Farol - bản đồ rủi ro cho pull request

Farol bổ sung cho AI review, không thay thế

Điểm cốt lõi cần hiểu: Farol chạy sau bước review bằng AI, không phải thay thế nó. Agent AI bình luận trên từng dòng trong diff; Farol trao cho người phê duyệt thứ mà agent không thể đưa ra một cách đáng tin cậy.

Agent review nói cho bạn biết "những dòng này có thể sai ở đâu". Farol nói cho bạn biết "những dòng này chạm tới đâu, lần merge này nguy hiểm đến mức nào, và nên bắt đầu đọc từ file nào".

Sự khác biệt lớn nhất nằm ở tính xác định. Farol hoạt động dựa trên phân tích tĩnh — dùng chính bộ kiểm tra kiểu của trình biên dịch (TypeScript type checker, go/types, Python ast) chứ không phải phỏng đoán của mô hình. Nhờ vậy, cùng một pull request luôn cho ra cùng một kết quả, và mỗi kết luận đều kèm theo chuỗi gọi hàm cụ thể.

Tiêu chí	Agent AI review	Farol
Đọc gì	Diff và ngữ cảnh vừa trong prompt	Toàn bộ chương trình ở nhánh gốc và nhánh đích, dùng trình biên dịch
Cho biết gì	Có thể sai gì ở các dòng này	Các dòng này chạm tới đâu, rủi ro merge, nên xem gì trước
Tính chất	Xác suất: mỗi lần chạy có thể diễn đạt khác	Tất định: cùng PR, cùng báo cáo
Khi không chắc chắn	Có thể vẫn trả lời rất tự tin	Ghi "unknown" và yêu cầu review kỹ
Môi trường chạy	Thường là dịch vụ hosted	Cục bộ hoặc trong CI, không chạy code, không gửi dữ liệu đi

Farol cho người duyệt thấy những gì?

Farol thực hiện bước phân loại (triage) trước khi người review mở diff:

• Thay đổi này chạm tới đâu? Liệt kê mọi trang, thao tác API, phương thức RPC, job và script hiện có đang chạy đoạn mã bị thay đổi, kèm chuỗi gọi hàm tới từng điểm.
• Merge nguy hiểm đến mức nào? Đưa ra phán quyết (duyệt nhanh, review nhanh, review kỹ) và điểm rủi ro 0–100 dựa trên độ phủ sóng, độ phủ kiểm thử của diff, phát hiện bảo mật, thay đổi hợp đồng (contract) và thay đổi dependency.
• Nên bắt đầu từ đâu? Xếp các file rủi ro nhất lên đầu, hiển thị diff nội tuyến, đánh dấu những dòng chưa có test, và kèm checklist những gì cần thử thủ công.

Ba mức phán quyết được giải thích rõ ràng: ✓ Duyệt nhanh (chỉ có mã mới, test hoặc thay đổi ít rủi ro — lướt diff và duyệt), ◐ Review nhanh (mã cũ bị sửa trong phạm vi hẹp, hoặc tín hiệu yếu như độ phủ thấp — xem các file "bắt đầu từ đây" rồi duyệt), và ⚠ Review kỹ (có khả năng hỏng diện rộng hoặc âm thầm: điểm từ 60 trở lên, thay đổi hợp đồng gây lỗi, phát hiện bảo mật nghiêm trọng, file trung tâm không có test, hoặc mã Farol không đọc được).

Vì sao điều này quan trọng với đội ngũ Việt Nam?

Với các nhóm phát triển ở Việt Nam đang làm outsource hoặc vận hành sản phẩm cho nhiều khách hàng, PR thường dồn dập vào cuối sprint. Một PR 40 file thường chỉ có hai đến ba file thực sự có thể gây hậu quả. Farol xếp hạng chúng để người review đọc kỹ đúng những file đó và yên tâm lướt nhanh phần còn lại.

Công cụ cũng đặc biệt hữu ích khi làm việc với các monorepo lớn: Farol theo dõi mã, không theo tên file. Một thay đổi ở hàm formatPrice sẽ liệt kê đúng 12 trang đang render nó, thay vì chỉ báo "1 file thay đổi".

Farol hỗ trợ Node.js 22+

Cài đặt và sử dụng

Farol chạy trên Node.js 22+ và git (thêm go cho dự án Go, python3 3.11+ cho dự án Python). Không cần cài đặt gì, chỉ cần chạy qua npx.

Đầu tiên, mô tả dự án trong file farol.config.json ở thư mục gốc. Với ứng dụng React dùng React Router, chỉ một dòng là đủ:

{ "routes": { "file": "src/routes.tsx" } }

Với Next.js:

{ "routes": { "adapter": "next" } }

Với dịch vụ Python (FastAPI, Flask, Django, Celery…):

{ "language": "python", "surface": "backend" }

Sau đó kiểm tra những gì Farol nhìn thấy, phân tích nhánh so với nhánh đích, và mở báo cáo HTML:

npx @winninjs/farol routes
npx @winninjs/farol analyze --base origin/main --head HEAD --out farol.json
npx @winninjs/farol html --in farol.json --out farol.html

Báo cáo sẽ hiển thị phán quyết, điểm rủi ro, các file cần bắt đầu, những trang mà thay đổi chạm tới và danh sách việc cần thử thủ công.

Phạm vi hỗ trợ

Farol hỗ trợ khá rộng các stack phổ biến:

• Frontend TypeScript/React: React Router, Next.js (Pages và App Router), TanStack Router (file-based).
• Backend TypeScript/JavaScript: GraphQL và REST (kiểu Fastify/Express).
• Go: định tuyến chi, gin, echo, net/http; phương thức gRPC; binary main.
• Python: FastAPI, Flask, Django URLs, MCP tools/resources/prompts, Celery, Temporal, Prefect và các script __main__.

Với mỗi ngôn ngữ, Farol đọc được báo cáo độ phủ (Istanbul, go test -coverprofile, coverage.py), lint (ESLint, golangci-lint, Ruff), bảo mật (gosec qua golangci-lint, flake8-bandit) và lỗ hổng dependency (npm audit, govulncheck, pip-audit). Đáng chú ý, công cụ có thể tận dụng báo cáo có sẵn trong CI, nên không chạy lại test hay lint lần hai.

Yếu tố bảo mật

Đây là điểm mà nhiều đội ngũ sẽ quan tâm: lệnh analyze không bao giờ thực thi mã của repository được phân tích và không bao giờ dùng mạng. Các helper Go và Python chỉ dùng thư viện chuẩn và chỉ phân tích cú pháp.

Trong CI, job chạy mã của bạn không có secret và không có token ghi; job bình luận không bao giờ chạy mã của bạn. Farol hoạt động ở chế độ "shadow": nó chỉ thông tin, không bao giờ tự duyệt, yêu cầu thay đổi hay làm fail check — merge vẫn phải do con người quyết định.

Những giới hạn cần biết

Farol phân tích tĩnh, nên những giá trị được xây dựng lúc chạy sẽ không thấy được: đường dẫn route được tính toán động, getattr, importlib, các DI container, hay registry được điền trong vòng lặp. Khi không đọc được một điểm vào, PR sẽ bị đánh dấu là "unknown" chứ không phải "an toàn". Khi một lời gọi không giải quyết được, Farol giả định nó chạm tới nhiều hơn chứ không phải ít hơn — tức là fail closed, một nguyên tắc an toàn đáng ghi nhận.

Về frontend, chỉ hỗ trợ React Router, Next.js và TanStack Router dạng file-based; chưa hỗ trợ Remix, Vue hay Svelte. Điểm số và ngưỡng phán quyết được tác giả kiểm chứng trên 662 commit cũ của bốn repository: mức "duyệt nhanh" không gặp vấn đề nào trong 56 commit, còn AUC của điểm số đạt 0,72–0,83. Tuy vậy, tác giả khuyến nghị người dùng nên chạy farol calibrate trên lịch sử của chính mình để hiệu chỉnh ngưỡng.

Kết luận

Farol giải quyết một khoảng trống rất thực tế: AI có thể viết và review mã, nhưng trách nhiệm phê duyệt cuối cùng vẫn là con người, và con người cần biết rủi ro nằm ở đâu. Với giấy phép MIT, không cần tài khoản, không dịch vụ hosted và không gửi mã đi bất cứ đâu, đây là công cụ đáng để các đội phát triển thử vào quy trình review của mình.

Dự án có sẵn tại repository GitHub winnin/farol, kèm demo trực tiếp trên một pull request thật của FastAPI full-stack template.