code-review-graph: ngữ cảnh LLM local-first cho code review
tirth8205/code-review-graph
code-review-graph là một graph tri thức local-first, chỉ đưa cho AI coding assistant của bạn những file thực sự bị ảnh hưởng bởi một thay đổi, thay vì toàn bộ repo. Nên dùng nếu bạn đã trả token cho Claude Code, Cursor hay Copilot để review trên repo lớn và muốn ngữ cảnh theo blast-radius thay vì đoán mò bằng grep. Bỏ qua nếu codebase của bạn đủ nhỏ để agent đọc hết mọi thứ vẫn đã nhanh và rẻ.
Thách thức về ngữ cảnh LLM trong Code Review
Các công cụ AI code review thường đọc lại toàn bộ file hoặc toàn bộ repo chỉ để trả lời một câu hỏi mà một developer có kinh nghiệm có thể trả lời bằng cách lần theo ba lệnh gọi hàm. Với một repo cỡ fastapi, đọc thô toàn bộ corpus tốn 948,793 token cho thứ mà benchmark trong chính README trả lời chỉ trong khoảng 2,653 token qua một truy vấn graph — khoảng cách giữa những gì LLM cần thấy và những gì nó thực sự được đưa mới là chi phí thật, không phải kích thước context window của model.
Giới thiệu code-review-graph
code-review-graph là một CLI kèm MCP server, dùng Tree-sitter để parse codebase của bạn thành graph gồm function, class, import và call edge, sau đó chỉ trả cho AI assistant đúng phần liên quan đến một thay đổi cụ thể. Nó được cài qua pip/pipx, tự cấu hình cho các công cụ như Claude Code, Cursor, Codex, GitHub Copilot, và lưu mọi thứ trong một file SQLite cục bộ thay vì dịch vụ hosted.
Tính năng và khả năng cốt lõi
- ✓Blast-radius analysis lần theo mọi caller, dependent và test bị ảnh hưởng bởi một file thay đổi, để assistant chỉ đọc đúng những file đó thay vì quét toàn bộ project.
- ✓Incremental update chỉ parse lại các file có hash SHA-256 thay đổi; một thay đổi 2 file trên project ~3.000 file như Django re-index trong khoảng 2.5 giây, trong đó ~1.4 giây là thời gian khởi động process.
- ✓Tree-sitter parsing hỗ trợ một danh sách ngôn ngữ dài gồm Python, JavaScript/TypeScript/TSX, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, PHP và Jupyter notebook (.ipynb), cùng cơ chế languages.toml để bổ sung ngôn ngữ còn thiếu.
- ✓Dự án PHP được cộng thêm Composer PSR-4 resolution giới hạn trong repo, cùng Laravel Route-to-controller và Eloquent edge khi source code có đủ bằng chứng framework.
- ✓GitHub Action chạy cùng phân tích graph trên CI runner và đăng một sticky comment duy nhất trên PR với các function được chấm điểm rủi ro và các test gap, kèm tùy chọn fail-on-risk để chặn merge.
- ✓Semantic search thêm vector embedding từ sentence-transformers, Google Gemini, MiniMax hoặc bất kỳ endpoint tương thích OpenAI nào, chồng lên trên keyword search FTS5.
- ✓Community detection dùng thuật toán Leiden để gom nhóm code liên quan, và tự tách các community phình quá 25% kích thước graph.
- ✓Export graph sang GraphML, Neo4j Cypher, Obsidian vault kèm wikilink, hoặc SVG tĩnh.
Bắt đầu cài đặt
Chạy pip install code-review-graph (hoặc pipx install code-review-graph), sau đó code-review-graph install để tự phát hiện các công cụ AI coding bạn đang dùng — Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Zed, Continue, OpenCode, Copilot và nhiều công cụ khác — rồi ghi đúng cấu hình MCP cho từng cái, hoặc nhắm vào một nền tảng cụ thể bằng --platform <name>. Yêu cầu Python 3.10+; cài uv trước sẽ giúp cấu hình MCP dùng uvx thay vì rơi về lệnh gốc. code-review-graph build parse toàn bộ codebase, còn code-review-graph uninstall --dry-run xem trước việc gỡ đối xứng trước khi bạn thực hiện.
Sử dụng CLI và tích hợp
Sau khi install và build, chỉ cần hỏi thẳng assistant của bạn — README lấy ví dụ 'Build the code review graph for this project' — hoặc dùng ba slash command đi kèm: /code-review-graph:build-graph, /code-review-graph:review-delta để xem thay đổi từ commit gần nhất, và /code-review-graph:review-pr để review PR đầy đủ với blast-radius. Bản thân CLI còn có update để re-index gia tăng, status để xem thống kê graph, watch để cập nhật liên tục khi lưu file, và visualize --format json|graphml|svg để export graph ra ngoài công cụ.
Điểm mạnh
- ✓Re-index gia tăng đủ nhanh để chạy mỗi lần lưu file — khoảng 2.5 giây cho một thay đổi 2 file trên project 3.000 file — thay vì build lại toàn bộ.
- ✓Lưu trữ SQLite cục bộ và không gọi dịch vụ ngoài khi build graph nghĩa là GitHub Action có thể chạy hoàn toàn trên runner, README nói rõ không có source code nào được gửi ra ngoài.
- ✓Bảng benchmark blast-radius đưa ra số liệu thật, có thể tái lập (68.1x trên chính repo này, lên tới 375.6x trên fastapi) thay vì một tuyên bố marketing.
- ✓Ngôn ngữ tùy chỉnh được thêm qua file languages.toml, không cần fork hay sửa code.
Hạn chế và điểm yếu đã được ghi nhận
- △Recall 1.0 mà README báo cáo cho impact analysis mang tính circular theo cấu trúc — ground truth lấy từ chính các edge mà predictor duyệt qua — và chế độ co-change trung thực để kiểm chứng nó bằng lịch sử git thật hiện đang trả về 0 file dự đoán trên mọi commit được chấm điểm, theo chính README thừa nhận.
- △Keyword search xếp đúng kết quả trong top-4 với hầu hết query nhưng MRR chỉ đạt 0.35, và README ghi nhận query trên express trả về 0 kết quả do cách đặt tên theo module-pattern.
- △Flow detection recall chỉ đạt 33%, và README nói việc phát hiện entry-point cho JavaScript và Go vẫn cần cải thiện.
- △Với các thay đổi nhỏ chỉ một file, phản hồi ngữ cảnh graph có thể lớn hơn việc đọc thẳng file đã đổi, vì nó mang theo impact-radius edge và snippet cộng thêm vào diff.
Lựa chọn thay thế cho tối ưu ngữ cảnh AI code
Câu hỏi thường gặp
code-review-graph parse một danh sách dài gồm Python, JavaScript/TypeScript/TSX, Go, Rust, Java, C/C++, C#, VB.NET, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, Perl, Lua/Luau, Elixir, Zig, PowerShell, Julia và nhiều hơn nữa, cộng thêm Jupyter/Databricks notebook — kèm file languages.toml để bổ sung ngôn ngữ chưa hỗ trợ.
Nó trả lời câu hỏi từ một graph đã build sẵn thay vì đưa nguyên file cho model: benchmark trong README cho thấy 208,821 token nguồn của chính repo này giảm còn khoảng 3,190 token mỗi câu hỏi, tức giảm 68.1 lần, với mức trung vị trên 6 repo được test vào khoảng 65 lần.
Có — một composite GitHub Action chạy cùng phân tích trên CI runner và đăng một sticky comment chấm điểm rủi ro cho mỗi pull request, cập nhật lại sau mỗi lần push, kèm input fail-on-risk tùy chọn để chặn merge.
code-review-graph được phát hành theo giấy phép MIT, một giấy phép mở cho phép tự do sử dụng, sửa đổi và phân phối lại, đúng như metadata trên GitHub ghi nhận.
Mặc định là không — graph được build và truy vấn cục bộ trong SQLite, và README nói rõ bản GitHub Action vẫn local-first, không gửi source code ra ngoài. Semantic search là tùy chọn và chỉ gọi endpoint embedding bên ngoài như Gemini hay một API tương thích OpenAI nếu bạn cấu hình nó.
Thả một file languages.toml vào .code-review-graph/ ánh xạ đuôi file tới một grammar có sẵn trong tree_sitter_language_pack, cùng các node type cho function, class, import và call — bộ Tree-sitter walker chung sẽ xử lý phần extraction từ đó, không cần fork.
Các trường hợp sử dụng tốt nhất
- •Chạy GitHub Action đi kèm để mỗi pull request có comment chấm điểm rủi ro theo blast-radius, thay vì con người lướt qua một diff lớn từ đầu.
- •Cấp cho Claude Code, Cursor hay MCP client khác đúng những file bị đổi trong một phiên review trên repo lớn.
- •Phát triển ở watch mode, nơi graph cập nhật mỗi lần lưu file và luôn sẵn sàng cho câu hỏi tiếp theo bạn hỏi assistant.
- •Export dependency graph sang GraphML hoặc Obsidian vault để khám phá kiến trúc và coupling bên ngoài CLI.
Ai nên dùng — và ai nên bỏ qua
Nên dùng code-review-graph nếu bạn đã chạy Claude Code, Cursor, Codex hay assistant nào khác hỗ trợ MCP trên repo đủ lớn để việc đọc toàn bộ file tốn kém — bảng benchmark đưa ra số liệu tiết kiệm token thật cho từng repo. Bỏ qua nếu project nhỏ, agent đọc hết codebase đã đủ nhanh, hoặc nếu bạn cần impact recall 100% được xác thực bởi CI ngay hôm nay: README nói rõ chế độ co-change trung thực chưa cho ra số liệu dùng được.