원문 캡처 · github.com
원문 캡처 · github.com

farol은 AI 코드 리뷰 뒤에 실행하는 무료 오픈소스 도구로, 풀 리퀘스트를 승인하는 사람이 병합 위험도와 위험이 큰 파일을 파악하도록 돕는다. CLI나 GitHub Action으로 사용할 수 있으며, 코드를 실행하거나 외부로 보내지 않고 병합을 차단하지도 않는다.

farol은 변경된 코드가 어떤 페이지, API 작업, RPC 메서드, 작업(job), 스크립트에 닿는지 정적 분석으로 추적한다. 그 결과를 바탕으로 0~100 위험 점수와 ‘빠른 승인’, ‘간단한 검토’, ‘주의 깊은 검토’ 판정, 위험이 큰 파일 순서, 수동 테스트 체크리스트를 제공한다. 점수에는 영향 범위, 변경분의 테스트 커버리지, 보안 탐지 결과, 계약 변경, 의존성 변경이 반영된다. 코드를 읽지 못하는 부분이 있으면 안전하다고 간주하지 않고 unknown으로 표시해 주의 깊은 검토를 요청한다.

도구는 AI 리뷰 에이전트를 대체하는 대신 함께 쓰도록 설계됐다. AI 에이전트가 변경된 줄에서 문제를 찾는 동안, farol은 프로그램 전체에서 변경 사항이 미치는 범위와 검토 우선순위를 보여준다. 같은 풀 리퀘스트에는 같은 보고서를 내며, 각 영향 주장에 호출 경로를 제시한다고 제작 측은 설명한다.

  • 지원 대상은 TypeScript·JavaScript, Go, Python 프로젝트다. React Router, Next.js, TanStack Router, GraphQL·REST, Go 웹 프레임워크, FastAPI·Flask·Django 등에서 지원하는 진입점과 기능은 저장소 문서에 정리돼 있다.
  • Node.js 22 이상과 git이 필요하다. Go 프로젝트에는 go, Python 프로젝트에는 Python 3.11 이상도 필요하다. 기본 실행 명령은 npx @winninjs/farol이다.
  • 실시간 데모에서는 FastAPI 백엔드와 React 프런트엔드가 포함된 예시 풀 리퀘스트의 보고서를 볼 수 있다. 파일 검토 표시, 기능 플래그 표시, 변경 내용 확인, 테스트 계획 점검 기능을 체험할 수 있다.

보고서는 GitHub 댓글과 단일 파일 HTML 형식으로 제공된다. GitHub Action은 풀 리퀘스트마다 보고서를 댓글로 남기며, 새 푸시가 있으면 전체 변경 보고서와 이전 푸시 이후 커밋만 다룬 보고서를 각각 만든다. 테스트·린터·감사 도구의 기존 결과를 재사용할 수 있다. 다만 초안 풀 리퀘스트는 건너뛰고, 포크에서 온 풀 리퀘스트에는 댓글을 달지 않는다. 분석은 GitHub 밖에서도 쓸 수 있지만 댓글 기능은 GitHub 전용이다.

설정과 사용법은 시작 안내와 명령·옵션 참고 문서에서 확인할 수 있다. 제작 측은 4개 저장소의 과거 커밋 662개를 대상으로 평가했을 때 ‘빠른 승인’ 판정이 나온 56개 커밋에서는 문제가 0건이었고, 점수의 AUC는 0.72~0.83이었다고 밝혔다. 점수와 판정 기준은 몇 개 저장소에서 확인한 휴리스틱이므로, 각 프로젝트의 이력에 맞춰 보정하라고 안내한다.

주요 제약은 정적 분석 방식에서 나온다. 실행 중에 만들어지는 경로 값이나 동적으로 채워지는 등록 정보 등은 보이지 않을 수 있다. 지원하지 않는 프레임워크와 라우팅 방식도 있으며, 제작 측은 제한된 수의 저장소에서 점수 기준을 점검했다고 밝힌다.