code-review-graph는 AI 코딩 도구의 코드 리뷰 시 발생하는 광범위한 코드베이스 재탐색 및 이로 인한 토큰 낭비 문제를 해결하기 위한 시스템입니다. 이 시스템은 Tree-sitter를 활용하여 코드의 구조적 맵을 생성하고, 변경사항을 점진적으로 추적하며, MCP(Meta-Code Protocol)를 통해 AI 어시스턴트에게 필요한 정확한 컨텍스트만 제공하여 효율성을 극대화합니다.

핵심 방법론 (Core Methodology)

1. 그래프 구축 (Graph Construction):
   • 저장소의 코드를 Tree-sitter를 사용하여 AST(Abstract Syntax Tree)로 파싱합니다.
   • 파싱된 AST는 노드(Node)와 엣지(Edge)로 구성된 그래프로 저장됩니다.
     • 노드: 함수(functions), 클래스(classes), 임포트(imports) 등 코드 엔티티를 나타냅니다.
     • 엣지: 호출(calls), 상속(inheritance), 테스트 커버리지(test coverage) 등 엔티티 간의 관계를 나타냅니다.
   • 이 그래프는 코드베이스의 구조와 종속성을 표현하는 시맨틱(semantic) 맵으로 활용됩니다.

2. 증분 업데이트 (Incremental Updates):
   • hooks 또는 watch mode가 활성화되면 파일 저장 및 커밋 훅(commit hook)에 따라 그래프가 자동으로 증분 업데이트됩니다.
   • 변경된 파일을 감지하고, SHA-256 해시 체크를 통해 해당 파일의 종속성(dependents)을 식별합니다.
   • 전체 코드베이스를 재파싱하는 대신, 변경된 부분만 재파싱하여 그래프를 업데이트합니다. 이 과정은 2초 미만의 빠른 속도로 이루어집니다(예: 2,900 파일 프로젝트는 2초 미만에 재인덱싱).

3. 컨텍스트 제공 (Context Provisioning):
   • AI 코드 리뷰 시점에서 그래프를 쿼리하여 AI 어시스턴트가 읽어야 할 최소한의 파일 집합을 계산합니다.
   • 블래스트-반경 분석 (Blast-radius Analysis): 파일이 변경될 경우, 그래프는 해당 변경에 의해 영향을 받을 수 있는 모든 호출자(caller), 종속성(dependent), 테스트를 추적하여 "블래스트 반경"을 식별합니다. AI는 프로젝트 전체를 스캔하는 대신 이 반경 내의 파일만 읽습니다.
   • 토큰 효율성 (Token Efficiency): 전형적인 AI 질문(예: "인증은 어떻게 작동하는가?", "메인 엔트리 포인트는 무엇인가?")에 대해, code-review-graph는 전체 코퍼스를 AI가 읽게 하는 대신, 그래프 쿼리를 통해 약 2,000~3,500 토큰의 목표화된 검색 결과와 인접 엣지(neighbor edges)를 반환합니다. 이로 인해 38배에서 528배(질문당 중앙값 약 82배)의 토큰 절감 효과를 제공합니다. context_savings 추정치를 통해 실제 토큰 절감량을 AI 에이전트에게 명시적으로 제공합니다.

주요 기능 (Key Features)

• 광범위한 언어 및 노트북 지원: Python, JavaScript/TypeScript/TSX, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, Perl, Lua/Luau, Objective-C, 셸 스크립트, Elixir, Zig, PowerShell, Julia, ReScript, GDScript, Nix, Verilog/SystemVerilog, SQL, Vue/Svelte SFCs, Astro files, Jupyter/Databricks notebooks(.ipynb), Perl XS files(.xs) 등을 지원합니다.
• 시맨틱 검색 (Semantic Search): sentence-transformers, Google Gemini, MiniMax 또는 OpenAI 호환 엔드포인트를 통한 벡터 임베딩(vector embeddings)을 사용하여 코드 엔티티를 이름이나 의미로 검색합니다.
• 대화형 시각화 (Interactive Visualisation): D3.js 기반의 강제 방향성 그래프(force-directed graph)로 검색, 커뮤니티 범례 토글, 노드 스케일링 기능을 제공합니다.
• 허브 및 브리지 감지 (Hub & Bridge Detection): Betweenness centrality를 통해 가장 연결성이 높은 노드(아키텍처 핫스팟) 및 병목 지점(chokepoints)을 식별합니다.
• 지식 격차 분석 (Knowledge Gap Analysis): 고립된 노드, 테스트되지 않은 핫스팟, 얇은 커뮤니티, 구조적 약점을 파악합니다.
• 제안된 질문 (Suggested Questions): 그래프 분석을 기반으로 자동 생성된 코드 리뷰 질문을 제공합니다.
• 그래프 탐색 (Graph Traversal): 구성 가능한 깊이와 토큰 예산으로 모든 노드에서 BFS/DFS 탐색을 지원합니다.
• 내보내기 형식 (Export Formats): GraphML, Neo4j Cypher, Obsidian Vault, SVG 정적 그래프 등 다양한 형식으로 내보내기를 지원합니다.
• 커뮤니티 자동 분할 (Community Auto-split): Leiden 알고리즘을 통해 관련된 코드를 클러스터링하며, 너무 큰 커뮤니티는 재귀적으로 분할합니다.
• 아키텍처 개요 (Architecture Overview): 커뮤니티 구조로부터 아키텍처 맵을 자동 생성하고 결합(coupling) 경고를 제공합니다.
• 위험 점수화된 리뷰 (Risk-scored Reviews): 변경 사항을 affected functions, flows, test gaps에 매핑하여 위험을 점수화합니다.
• 멀티-레포 관리 (Multi-repo Registry & Daemon): 여러 저장소를 등록하고 검색하며, crg-daemon을 통해 백그라운드에서 그래프 업데이트를 자동화합니다.
• 로컬 저장소 (Local Storage): .code-review-graph/ 디렉터리에 SQLite 파일을 사용하여 데이터를 저장하며, 외부 데이터베이스나 클라우드 서비스가 필요 없습니다.

성능 및 벤치마크 (Performance & Benchmarks)

• 토큰 효율성: 6개 실제 오픈소스 저장소에 대한 평가에서 질문당 38배에서 528배의 토큰 절감 효과(중앙값 약 82배)를 보였습니다. 이는 AI가 코드베이스 전체를 읽는 대신 타겟팅된 컨텍스트만 제공받기 때문입니다.
• 영향 분석 정확도 (Impact Accuracy): 13개 평가 커밋 모두에서 100%의 재현율(recall)을 달성했습니다. 일부 경우 과대 예측(over-prediction)이 발생하지만, 이는 깨진 종속성을 놓치는 것보다 많은 파일을 플래그하는 보수적인 전략입니다(평균 F1 스코어 0.71).
• 구축 성능 (Build Performance): 141개 파일의 express 프로젝트는 그래프 구축에 106ms, 검색에 0.7ms가 소요되는 등 빠른 처리 속도를 보입니다.

제한사항 (Limitations)

• 작은 단일 파일 변경: 사소한 수정의 경우 구조적 메타데이터 오버헤드로 인해 그래프 컨텍스트가 순수한 파일 읽기보다 클 수 있습니다.
• 검색 품질 (Search Quality): 키워드 검색은 대부분의 쿼리에 대해 상위 4개에서 올바른 결과를 찾지만, 순위 개선이 필요합니다(MRR 0.35).
• 흐름 감지 (Flow Detection): Python 저장소에서 프레임워크 패턴을 통해 엔트리 포인트를 안정적으로 감지하지만, JavaScript 및 Go에서의 흐름 감지 개선이 필요합니다(재현율 33%).
• 정밀도 vs. 재현율 트레이드오프 (Precision vs. Recall Trade-off): 영향 분석은 의도적으로 보수적이며, 이는 대규모 종속성 그래프에서 일부 오탐(false positives)을 유발할 수 있습니다.

code-review-graph는 AI 기반 코드 리뷰의 효율성을 획기적으로 개선하고, 개발자가 복잡한 코드베이스를 더 잘 이해하며 관리할 수 있도록 돕는 강력한 도구입니다.