wehub/tirth8205--code-review-graph

Fork 0

Files

T

wehub-resource-sync 05f60106aa chore: import upstream snapshot with attribution

2026-07-13 12:42:18 +08:00

20 KiB

Raw Permalink Blame History

code-review-graph

참고: 이 번역은 이전 릴리스를 기준으로 합니다. 벤치마크 수치와 플랫폼 목록은 영문 README보다 오래되었을 수 있습니다.

토큰 낭비를 멈추세요. 더 스마트하게 리뷰하세요.

English | 简体中文 | 日本語 | 한국어 | हिन्दी

AI 코딩 도구는 리뷰 작업에서 코드베이스의 큰 부분을 반복해서 읽게 될 수 있습니다. code-review-graph는 이 문제를 해결합니다. Tree-sitter로 코드의 구조적 맵을 구축하고, 변경 사항을 점진적으로 추적하며, MCP를 통해 AI 어시스턴트에게 정확한 컨텍스트를 제공하여 필요한 부분만 읽도록 합니다.

빠른 시작

pip install code-review-graph                     # 또는: pipx install code-review-graph
code-review-graph install          # 지원되는 모든 플랫폼을 자동 감지하고 설정
code-review-graph build            # 코드베이스 파싱

하나의 명령으로 모든 설정이 완료됩니다. install은 사용 중인 AI 코딩 도구를 감지하고, 각 도구에 맞는 MCP 설정을 작성하며, 플랫폼 규칙에 그래프 인식 지침을 주입합니다. uvx 또는 pip/pipx 중 어떤 방식으로 설치했는지 자동 감지하여 올바른 설정을 생성합니다. 설치 후 에디터/도구를 재시작하세요.

특정 플랫폼만 설정하려면:

code-review-graph install --platform codex       # Codex만 설정
code-review-graph install --platform cursor      # Cursor만 설정
code-review-graph install --platform claude-code  # Claude Code만 설정
code-review-graph install --platform kiro         # Kiro만 설정

Python 3.10 이상이 필요합니다. 최상의 경험을 위해 uv를 설치하세요 (MCP 설정은 uvx가 있으면 이를 사용하고, 없으면 code-review-graph 명령을 직접 사용합니다).

프로젝트를 열고 AI 어시스턴트에게 다음과 같이 요청하세요:

Build the code review graph for this project

초기 빌드는 500개 파일 프로젝트 기준 약 10초가 소요됩니다. 이후에는 watch 모드와 지원되는 플랫폼 훅으로 그래프를 자동 업데이트할 수 있습니다.

작동 원리

저장소를 Tree-sitter로 AST로 파싱하고, 노드(함수, 클래스, import)와 엣지(호출, 상속, 테스트 커버리지)의 그래프로 SQLite에 저장한 후, 리뷰 시점에 쿼리하여 AI 어시스턴트가 읽어야 할 최소한의 파일 집합을 계산합니다.

영향 범위 분석

파일이 변경되면, 그래프는 영향을 받을 수 있는 모든 호출자, 의존 대상, 테스트를 추적합니다. 이것이 변경의 "영향 범위"입니다. AI는 전체 프로젝트를 스캔하는 대신 이 파일들만 읽습니다.

2초 미만의 점진적 업데이트

훅 또는 watch 모드를 사용하면 파일 저장과 지원되는 커밋 훅에서 점진적 업데이트가 실행됩니다. 그래프는 변경된 파일을 비교하고, SHA-256 해시 검사를 통해 의존 대상을 찾으며, 변경된 부분만 다시 파싱합니다. 2,900개 파일 프로젝트의 재인덱싱이 2초 이내에 완료됩니다.

모노레포 문제 해결

대규모 모노레포에서 토큰 낭비가 가장 심합니다. 그래프는 불필요한 파일을 제거합니다 -- 27,700개 이상의 파일이 리뷰 컨텍스트에서 제외되고, 실제로 읽는 파일은 약 15개뿐입니다.

폭넓은 언어 지원 + Jupyter 노트북

현재 파서가 지원하는 범위에서 함수, 클래스, import, 호출 위치, 상속, 테스트 감지를 추출합니다. 가능한 경우 Tree-sitter를 사용하고 필요한 곳에서는 대상별 fallback 파서를 사용합니다. 지원 범위에는 Python, JavaScript/TypeScript/TSX, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, Perl, Lua/Luau, Objective-C, shell scripts, Elixir, Zig, PowerShell, Julia, ReScript, GDScript, Nix, Verilog/SystemVerilog, SQL, Vue/Svelte SFC, TypeScript 파서로 처리되는 Astro 파일, Jupyter/Databricks 노트북(.ipynb), Perl XS 파일(.xs)이 포함됩니다.

벤치마크

모든 수치는 6개 실제 오픈소스 저장소(총 13개 커밋)에 대한 자동화된 평가 실행 결과입니다. code-review-graph eval --all로 재현할 수 있습니다. 전체 재현 절차와 기준 수치는 docs/REPRODUCING.md에 있습니다.

전체 벤치마크 결과는 영문 README를 참조하세요.

기능

기능	세부 사항
점진적 업데이트	변경된 파일만 다시 파싱합니다. 이후 업데이트는 2초 이내에 완료됩니다.
폭넓은 언어 지원 + 노트북	Python, JavaScript/TypeScript/TSX, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, Perl, Lua/Luau, Objective-C, shell, Elixir, Zig, PowerShell, Julia, ReScript, GDScript, Nix, Verilog/SystemVerilog, SQL, Vue/Svelte SFCs, Astro files parsed as TypeScript, Jupyter/Databricks (.ipynb)
영향 범위 분석	변경에 의해 영향 받을 가능성이 있는 함수, 클래스, 파일을 보여줍니다
자동 업데이트 훅	수동 개입 없이 파일 편집 및 git 커밋마다 그래프가 업데이트됩니다
시맨틱 검색	sentence-transformers, Google Gemini, MiniMax, 또는 OpenAI 호환 엔드포인트(실제 OpenAI, Azure, new-api, LiteLLM, vLLM, LocalAI)를 통한 선택적 벡터 임베딩
인터랙티브 시각화	검색, 커뮤니티 범례 토글, 차수 기반 노드 크기 조정이 가능한 D3.js 포스 다이렉티드 그래프
허브 및 브릿지 감지	가장 많이 연결된 노드와 매개 중심성을 통한 아키텍처 병목 지점 탐색
서프라이즈 스코어링	예상치 못한 결합 감지: 커뮤니티 간, 언어 간, 주변부-허브 엣지
지식 격차 분석	고립된 노드, 테스트되지 않은 핫스팟, 얇은 커뮤니티, 구조적 약점 식별
질문 제안	그래프 분석(브릿지, 허브, 서프라이즈)을 기반으로 자동 생성되는 리뷰 질문
엣지 신뢰도	엣지에 실수 점수를 포함한 3단계 신뢰도 평가 (EXTRACTED/INFERRED/AMBIGUOUS)
그래프 탐색	임의 노드에서 설정 가능한 깊이와 토큰 예산으로 자유 형식 BFS/DFS 탐색
내보내기 형식	GraphML (Gephi/yEd), Neo4j Cypher, Obsidian vault (위키링크), SVG 정적 그래프
그래프 비교	시간에 따른 그래프 스냅샷 비교: 새로운/삭제된 노드, 엣지, 커뮤니티 변경
토큰 벤치마킹	전체 코퍼스 토큰 대비 그래프 쿼리 토큰을 질문별 비율로 측정
메모리 루프	Q&A 결과를 마크다운으로 저장하여 재수집, 쿼리로 그래프가 성장
커뮤니티 자동 분할	과대 커뮤니티(그래프의 25% 초과)를 Leiden 알고리즘으로 재귀적 분할
실행 흐름	가중 중요도 순으로 정렬된 진입점에서의 호출 체인 추적
커뮤니티 감지	대규모 그래프를 위한 해상도 스케일링이 포함된 Leiden 알고리즘으로 관련 코드 클러스터링
아키텍처 개요	결합 경고가 포함된 자동 생성 아키텍처 맵
위험 점수 리뷰	`detect_changes`가 diff를 영향 받는 함수, 흐름, 테스트 격차에 매핑
리팩토링 도구	이름 변경 미리보기, 프레임워크 인식 데드 코드 감지, 커뮤니티 기반 제안
위키 생성	커뮤니티 구조에서 마크다운 위키 자동 생성
멀티 레포 레지스트리	여러 저장소를 등록하고 모든 저장소에서 검색
MCP 프롬프트	5개 워크플로 템플릿: 리뷰, 아키텍처, 디버그, 온보딩, 사전 머지 검사
전문 검색	FTS5 기반 키워드와 벡터 유사도를 결합한 하이브리드 검색
로컬 스토리지	`.code-review-graph/`에 SQLite 파일 저장. 핵심 그래프 저장에는 외부 데이터베이스나 클라우드 서비스가 필요 없습니다.
감시 모드	작업 중 지속적인 그래프 업데이트

사용법

슬래시 명령

명령	설명
`/code-review-graph:build-graph`	코드 그래프 빌드 또는 재빌드
`/code-review-graph:review-delta`	마지막 커밋 이후 변경 사항 리뷰
`/code-review-graph:review-pr`	영향 범위 분석을 포함한 전체 PR 리뷰

CLI 레퍼런스

code-review-graph install          # 모든 플랫폼 자동 감지 및 설정
code-review-graph install --platform <name>  # 특정 플랫폼 지정
code-review-graph build            # 전체 코드베이스 파싱
code-review-graph update           # 점진적 업데이트 (변경 파일만)
code-review-graph status           # 그래프 통계
code-review-graph watch            # 파일 변경 시 자동 업데이트
code-review-graph visualize        # 인터랙티브 HTML 그래프 생성
code-review-graph visualize --format graphml   # GraphML로 내보내기
code-review-graph visualize --format svg       # SVG로 내보내기
code-review-graph visualize --format obsidian  # Obsidian vault로 내보내기
code-review-graph visualize --format cypher    # Neo4j Cypher로 내보내기
code-review-graph wiki             # 커뮤니티에서 마크다운 위키 생성
code-review-graph detect-changes   # 위험 점수 기반 변경 영향 분석
code-review-graph register <path>  # 멀티 레포 레지스트리에 저장소 등록
code-review-graph unregister <id>  # 레지스트리에서 저장소 제거
code-review-graph repos            # 등록된 저장소 목록
code-review-graph eval             # 평가 벤치마크 실행
code-review-graph serve            # MCP 서버 시작

30개 MCP 도구

그래프가 빌드되면 AI 어시스턴트가 이 도구들을 자동으로 사용합니다.

도구	설명
`build_or_update_graph_tool`	그래프 빌드 또는 점진적 업데이트
`run_postprocess_tool`	실행 흐름, 커뮤니티, 전체 텍스트 색인 후처리 다시 실행
`get_minimal_context_tool`	초소형 컨텍스트 (~100 토큰) -- 이것을 먼저 호출
`get_impact_radius_tool`	변경된 파일의 영향 범위
`get_review_context_tool`	구조적 요약이 포함된 토큰 최적화 리뷰 컨텍스트
`query_graph_tool`	호출자, 피호출자, 테스트, import, 상속 쿼리
`traverse_graph_tool`	토큰 예산으로 임의 노드에서 BFS/DFS 탐색
`semantic_search_nodes_tool`	이름이나 의미로 코드 엔티티 검색
`embed_graph_tool`	시맨틱 검색을 위한 벡터 임베딩 계산
`list_graph_stats_tool`	그래프 크기 및 상태
`get_docs_section_tool`	문서 섹션 조회
`find_large_functions_tool`	줄 수 임계값을 초과하는 함수/클래스 찾기
`list_flows_tool`	중요도 순으로 정렬된 실행 흐름 목록
`get_flow_tool`	단일 실행 흐름의 세부 정보
`get_affected_flows_tool`	변경된 파일에 영향 받는 흐름 찾기
`list_communities_tool`	감지된 코드 커뮤니티 목록
`get_community_tool`	단일 커뮤니티의 세부 정보
`get_architecture_overview_tool`	커뮤니티 구조의 아키텍처 개요
`detect_changes_tool`	코드 리뷰를 위한 위험 점수 기반 변경 영향 분석
`get_hub_nodes_tool`	가장 많이 연결된 노드 (아키텍처 핫스팟) 찾기
`get_bridge_nodes_tool`	매개 중심성을 통한 병목 지점 찾기
`get_knowledge_gaps_tool`	구조적 약점 및 테스트되지 않은 핫스팟 식별
`get_surprising_connections_tool`	예상치 못한 커뮤니티 간 결합 감지
`get_suggested_questions_tool`	분석에서 자동 생성된 리뷰 질문
`refactor_tool`	이름 변경 미리보기, 데드 코드 감지, 제안
`apply_refactor_tool`	미리보기한 리팩토링 적용
`generate_wiki_tool`	커뮤니티에서 마크다운 위키 생성
`get_wiki_page_tool`	특정 위키 페이지 조회
`list_repos_tool`	등록된 저장소 목록
`cross_repo_search_tool`	등록된 모든 저장소에서 검색

MCP 프롬프트 (5개 워크플로 템플릿): review_changes, architecture_map, debug_issue, onboard_developer, pre_merge_check

설정

인덱싱에서 경로를 제외하려면 저장소 루트에 .code-review-graphignore 파일을 생성하세요:

generated/**
*.generated.ts
vendor/**
node_modules/**

참고: git 저장소에서는 추적되는 파일만 인덱싱됩니다 (git ls-files). gitignore된 파일은 자동으로 건너뜁니다. .code-review-graphignore는 추적되는 파일을 제외하거나 git을 사용할 수 없을 때 사용합니다.

선택적 의존성 그룹:

pip install code-review-graph[embeddings]          # 로컬 벡터 임베딩 (sentence-transformers)
pip install code-review-graph[google-embeddings]   # Google Gemini 임베딩
pip install code-review-graph[communities]         # 커뮤니티 감지 (igraph)
pip install code-review-graph[enrichment]          # Python 호출 해결 보강 (Jedi)
pip install code-review-graph[eval]                # 평가 벤치마크 (matplotlib)
pip install code-review-graph[wiki]                # LLM 요약 위키 생성 (ollama)
pip install code-review-graph[all]                 # 모든 선택적 의존성

OpenAI 호환 임베딩(실제 OpenAI, Azure, 또는 자체 호스팅 게이트웨이 new-api / LiteLLM / vLLM / LocalAI / Ollama openai 모드)은 추가 설치가 필요하지 않습니다. 환경 변수만 설정하고 embed_graph에 provider="openai"를 전달하면 됩니다:

export CRG_OPENAI_BASE_URL=http://127.0.0.1:3000/v1     # 또는 https://api.openai.com/v1
export CRG_OPENAI_API_KEY=sk-...
export CRG_OPENAI_MODEL=text-embedding-3-small          # 게이트웨이에서 제공하는 모델
# 선택:
export CRG_OPENAI_DIMENSION=1536                        # 차원 고정 (v3 모델은 차원 축소 지원)
export CRG_OPENAI_BATCH_SIZE=100                        # 배치 제한이 엄격한 게이트웨이에서 낮추기
                                                        # (예: Qwen text-embedding-v4 는 최대 10)

base URL이 localhost(127.0.0.1, localhost, 0.0.0.0, ::1)를 가리킬 때는 클라우드 egress 경고가 자동으로 생략됩니다.

모델 선택 팁. -preview / -beta / -exp 접미사가 붙은 model ID(예: google/gemini-embedding-2-preview)는 장기 운영용으로 피하세요. preview 모델은 가중치가 바뀌거나(차원 변경 시 전체 re-embed 필수) 예고 없이 deprecate될 수 있습니다. 안정 GA 모델 권장: text-embedding-3-small / text-embedding-3-large(OpenAI), Qwen/Qwen3-Embedding-8B(vLLM / LocalAI 자체 호스팅 경유), 또는 gemini-embedding-001(네이티브 Gemini provider 경유, GOOGLE_API_KEY 필요).

참고로 현재 code-review-graph는 함수 시그니처만 임베딩합니다(노드당 약 10 토큰, 예: "parse_file function (path: str) returns Tree"). 긴 context로 함수 body를 이해하는 능력으로 차별화되는 모델(Gemini 2 또는 Qwen3-8B의 MTEB-code SOTA 점수)은 이 입력 길이에서 소형 모델과의 품질 차이가 훨씬 좁아집니다. Body / docstring 임베딩은 후속 개선 과제로 추적 중입니다.

기여

git clone https://github.com/tirth8205/code-review-graph.git
cd code-review-graph
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

새 언어 추가

code_review_graph/parser.py를 편집하여 EXTENSION_TO_LANGUAGE에 확장자를 추가하고, _CLASS_TYPES, _FUNCTION_TYPES, _IMPORT_TYPES, _CALL_TYPES에 노드 타입 매핑을 추가하세요. 테스트 픽스처를 포함하여 PR을 제출하세요.

라이선스

MIT. LICENSE를 참조하세요.

code-review-graph.com

pip install code-review-graph && code-review-graph install
_{Codex, Claude Code, Cursor, Windsurf, Zed, Continue, OpenCode, Antigravity, Gemini CLI, Qwen, Kiro, Qoder, GitHub Copilot 등 지원되는 AI 코딩 도구를 자동 감지하고 설정합니다}

20 KiB Raw Permalink Blame History