tirth8205/code-review-graph

Local-first code intelligence graph for MCP and CLI. Builds a persistent map of your codebase so AI coding tools read only what matters, with benchmarked context reductions on reviews and large-repo workflows.

code‑review‑graph – AI 기반 코드 리뷰를 위한 로컬 코드 지식 그래프

이것이 무엇인가 – Tree‑sitter로 저장소를 파싱하고, 결과로 생성된 추상 구문 트리 정보를 SQLite 그래프에 저장하며, Model Context Protocol (MCP) 을 지원하는 모든 AI 기반 코딩 어시스턴트에게 관련성 중심의 그래프 일부를 제공하는 Python 패키지입니다. 목표는 단순한 "전체 코드베이스 읽기" 방식을 blast-radius 쿼리로 대체하여 변경으로 영향을 받을 수 있는 파일, 함수, 테스트만 반환하는 것입니다.

왜 중요한가 – 대규모 프로젝트는 수십만 개의 소스 토큰을 포함할 수 있습니다. 전체 말뭉치를 LLM에 제공하면 요청당 수천 개의 토큰이 소모되고 리뷰 루프가 느려집니다. 동일한 질문에 수천 개의 토큰(일반 저장소 기준 약 65배 감소)으로 답하면 어시스턴트는 더 빠르고, 저렴하며, 환각 위험도 줄일 수 있습니다.

핵심 아이디어

단계	수행 작업
파싱	지원되는 모든 언어(Python, JS/TS, Go, Rust, Java, C/C++, … 및 노트북)에 대해 Tree‑sitter 파서를 실행합니다. 함수, 클래스, 임포트, 호출 지점, 테스트 정의와 같은 노드를 추출하고 이를 그래프 노드/엣지(호출, 상속, 임포트 관계)로 기록합니다.
저장	모든 노드/엣지는 로컬 SQLite 데이터베이스에 저장됩니다. 의미 검색을 위해 선택적 벡터 임베딩(sentence‑transformers, Gemini, MiniMax, Voyage AI 또는 모든 OpenAI 호환 엔드포인트)이 추가됩니다.
업데이트	pre‑commit 훅, watch‑모드 데몬 또는 수동 `code-review-graph build` 명령이 SHA‑256 해시가 변경된 파일만 증분 재파싱한 후 영향을 받는 하위 그래프를 업데이트합니다.
쿼리	AI 도구가 리뷰 컨텍스트를 요청하면 MCP 서버는 blast-radius 쿼리를 실행합니다. 변경된 파일에서 시작해 호출/임포트 엣지를 따라가며 의존 파일과 관련 테스트를 추가하고, 최소한의 소스 스니펫과 소량의 구조적 메타데이터를 반환합니다.

빠른 시작 (README에서)

pip install code-review-graph          # 또는 pipx install
code-review-graph install              # AI 코딩 도구 자동 감지, MCP 항목 작성, 훅/스킬 설치
code-review-graph build                # 저장소 초기 파싱

*install*은 다양한 지원 플랫폼(Codex, Claude Code, Cursor, Zed, Continue, GitHub Copilot, Gemini CLI 등)을 감지하고 적절한 MCP 구성을 주입하여 어시스턴트가 자동으로 그래프를 사용하게 합니다.

깔끔하게 제거할 수도 있습니다:

code-review-graph uninstall --dry-run   # 미리보기
code-review-graph uninstall --yes       # 확인 없이 적용

주요 기능 (README에 나열된 대로)

증분 업데이트 – 변경된 파일만 다시 파싱합니다. 3천 개 파일 저장소에서 두 파일 편집 시 약 2.5초 소요.
광범위한 언어 지원 – 30개 이상 언어와 Jupyter/Databricks 노트북 지원; PHP/Laravel 및 Java/Spring용 프레임워크 인식 파싱.
프레임워크 인식 엣지 – Laravel 라우트, Blade 템플릿, Spring DI 호출, WebFlux 라우트, Temporal 워크플로 등.
Blast-radius 분석 – 변경으로 영향을 받을 수 있는 가장 작은 파일/함수/테스트 집합을 반환합니다.
MCP 호환 서버 – Model Context Protocol을 이해하는 모든 어시스턴트와 작동합니다.
GitHub Action – CI에서 동일한 분석을 실행하고, 위험 점수가 매겨진 함수로 고정 PR 댓글을 게시하며, fail-on-risk로 병합을 차단할 수 있습니다.
의미 검색 – 다양한 공급자의 선택적 벡터 임베딩으로 더 풍부한 키워드 쿼리 지원.
사용자 정의 언어 지원 – languages.toml을 추가하여 알 수 없는 확장자를 기존 Tree‑sitter 문법에 매핑할 수 있습니다.

벤치마크 (README에서)

토큰 감소 – 6개 오픈소스 저장소(fastapi, flask 등)에서 질문당 중앙값 약 63배 적은 토큰. 최고 사례는 358배였습니다.
영향 분석 품질 – 그래프 기반 ground truth 대비 평균 F1 약 0.69 (재현율은 구조상 1.0, 정밀도는 의도적으로 낮춰 누락된 의존성을 방지).
빌드 통계 – 일반 저장소(약 6천 노드, 3만 엣지)는 깨끗한 체크아웃에서 약 40초에 빌드됩니다.

한계 (인정된 대로)

"재현율 = 1.0" 지표는 순환적입니다. ground truth가 동일한 그래프에서 파생되기 때문입니다.
아주 작은 단일 파일 편집의 경우 그래프 페이로드가 파일을 직접 읽는 것보다 클 수 있습니다.
검색 순위는 여전히 개선이 필요합니다. 일부 쿼리(예: Express 모듈)는 결과가 없을 수 있습니다.
흐름 감지는 Python과 PHP/Laravel에서 가장 강력하며, JavaScript와 Go는 개선이 필요합니다.
분석은 의도적으로 보수적이어서 대규모 의존성 그래프에서 정밀도가 낮을 수 있습니다.

누가 사용해야 하나요?

개발자 – LLM 기반 코드 리뷰 어시스턴트에 의존하며 대규모 코드베이스의 진정으로 관련된 부분만 보길 원하는 경우.
팀 – AI 지원 CI 검사를 실행하며 위험 점수가 매겨진 리뷰 컨텍스트를 계산하는 결정적이고 오프라인 방식이 필요한 경우.
도구 제작자 – 새로운 MCP 호환 에이전트를 구축하는 경우 제공된 서버를 모든 편집기나 CLI에 연결할 수 있습니다.

더 알아보기

전체 사용 가이드: docs/USAGE.md
명령 참조: docs/COMMANDS.md
GitHub Action 세부 정보: docs/GITHUB_ACTION.md
벤치마크 재현 단계: docs/REPRODUCING.md
커뮤니티: 배지 바의 Discord 링크, 웹사이트 code‑review‑graph.com.

결론 – code‑review‑graph는 언어 인식, 증분 업데이트 코드 그래프를 구축하고 MCP를 통해 노출하여 LLM 기반 리뷰어가 훨씬 더 작고 정확한 컨텍스트로 작업할 수 있게 하는 진정한 오픈소스 AI 도구 프로젝트입니다.