Projeto Open Source #126: code-review-graph — Construa um Mapa Estrutural do Seu Código para Reduzir Tokens de Revisão em 82x
Introdução
"Pare de queimar tokens. Comece a revisar de forma mais inteligente."
Este é o artigo #126 da série "Um Projeto de Código Aberto por Dia". O projeto de hoje é code-review-graph — uma ferramenta de primeira local que constrói um mapa estrutural persistente da sua base de código e fornece contexto preciso para ferramentas de codificação de IA via MCP.
Agentes de codificação de IA têm uma ineficiência oculta durante as revisões de código: eles não sabem "se eu mudar esta função, o que mais quebra?" — então eles ou leem grandes porções da base de código para construir contexto, ou confiam no grep e torcem para que dê certo. A solução do code-review-graph: pré-construir um gráfico estrutural (funções, classes, arestas de chamada, herança, cobertura de teste), então, no momento da revisão, consultar o gráfico para calcular o "raio de explosão" de uma mudança e dar à IA apenas os arquivos que realmente importam.
Benchmark: ~82x de redução média de tokens. 528x no melhor caso.
19.762 Estrelas. Criado em fevereiro de 2026. Suporta 14 plataformas de codificação de IA.
O que você aprenderá
- Como funciona a análise de raio de explosão: rastreando arquivos alterados para chamadores, dependentes e testes
- A arquitetura completa: Tree-sitter AST → gráfico SQLite → cadeia de ferramentas MCP
- O mecanismo de atualização incremental: por que um repositório de 2.900 arquivos reindexa em menos de 2 segundos
- Três níveis de pontuação de confiança de arestas (EXTRAÍDO/INFERIDO/AMBÍGUO) e o que isso significa
- Uma leitura honesta dos números de benchmark: 528x é o melhor caso, não a mediana
Pré-requisitos
- Experiência básica com Claude Code ou outras ferramentas de codificação de IA
- Familiaridade com MCP (Modelo de Protocolo de Contexto)
- Compreensão básica de análise estática e gráficos de chamadas
Histórico do Projeto
Visão Geral
code-review-graph (CRG) é uma ferramenta de inteligência de código de primeira local com quatro funções principais:
- Analise sua base de código com Tree-sitter em um gráfico de funções, classes, imports e relacionamentos de chamada
- Persistir o gráfico como um arquivo SQLite em
.code-review-graph/— zero dependências de rede - Expor 30 ferramentas MCP para que seu assistente de IA possa consultar "o que essa mudança afeta?"
- Suportar atualizações incrementais — em uma mudança, reanalise apenas os arquivos modificados
Autor / Equipe
- Autor: tirth8205
- Linguagem: Python 3.10+
- Licença: MIT
- Versão: v2.3.6
- Website: code-review-graph.com
Estatísticas do Projeto
- ⭐ Estrelas no GitHub: 19.762+
- 🍴 Forks: 2.107+
- 📄 Licença: MIT
- 📅 Criado: 26 de fevereiro de 2026
Recursos
Início Rápido
pip install code-review-graph # ou: pipx install code-review-graph
code-review-graph install # detecta automaticamente plataformas, escreve configurações MCP
code-review-graph build # analisa a base de código, constrói o gráfico
Três comandos. install detecta todas as ferramentas de codificação de IA em sua máquina, escreve a configuração MCP correta para cada uma, injeta instruções cientes do gráfico em seus arquivos de regras de plataforma e instala ganchos/habilidades nativos da plataforma. Reinicie seu editor e, em seguida, pergunte à IA:
Construa o gráfico de revisão de código para este projeto
Construção inicial: ~10 segundos para um projeto de 500 arquivos. Depois disso, incremental.
Suporte a Plataformas
Uma instalação, 14 plataformas: Codex, Claude Code, CodeBuddy Code, Cursor, Windsurf, Zed, Continue, OpenCode, Antigravity, Gemini CLI, Qwen, Qoder, Kiro, GitHub Copilot.
Instalações específicas para alvos:
code-review-graph install --platform claude-code
code-review-graph install --platform cursor
code-review-graph install --platform codex
Painel de Economia de Tokens
┌─────────────────────── Economia de Tokens ────────────────────────┐
│ O contexto completo seria: 12.921 tokens │
│ O contexto do gráfico usado: 762 tokens │
│ Economizado: 12.159 tokens (~94%) │
│ Detalhamento: Funções 244 · Testes 191 · Risco 244 · Outros 83 │
└──────────────────────────────────────────────────────────────┘
Imprimido por detect-changes --brief ou update --brief. Adicione --verify para verificar contra o tokenizador cl100k_base da OpenAI; a estimativa permanece dentro de ~1% dos tokens reais na prática.
Análise Profunda
Arquitetura Principal
Repositório
│
▼ git ls-files (apenas arquivos rastreados indexados)
Analisadores Tree-sitter
│ extrai: funções / classes / imports / chamadas / herança / cobertura de teste
▼
Banco de dados gráfico SQLite
(.code-review-graph/, ignorado pelo git por padrão)
│
├── servidor MCP (30 ferramentas)
│ ↓ Consultas do assistente de IA
│ get_impact_radius_tool
│ get_review_context_tool
│ detect_changes_tool
│ ...
│
└── CLI
detect-changes --brief
update --brief
visualize
...
Nós do gráfico: funções, classes, arquivos, módulos
Arestas do gráfico: relacionamentos de chamada, relacionamentos de importação, herança, cobertura de teste
Análise de Raio de Explosão
O conceito central. Quando um arquivo muda:
Arquivo alterado (por exemplo, login() em auth/login.py)
↓
Consultar gráfico: quais funções chamam diretamente login()?
↓
Consultar gráfico: quais funções chamam esses chamadores?
(profundidade configurável; profundidade padrão=2)
↓
Consultar gráfico: quais arquivos de teste cobrem essas funções?
↓
Saída: raio de explosão = conjunto mínimo de funções/arquivos afetados
A IA lê apenas esse conjunto mínimo em vez de escanear toda a base de código.
Nota de precisão (do README, incomumente franca):
- A atual recall=1.0 é um limite superior derivado do gráfico — a verdade fundamental vem das mesmas arestas do gráfico que o preditor percorre, então a medição é circular por construção
- O modo "co-mudança" classifica contra arquivos que o autor realmente co-editou no mesmo commit — evidência independente do histórico do git, não do gráfico — e produzirá números substancialmente mais baixos
- A análise de raio de explosão é deliberadamente conservadora: é melhor sinalizar arquivos extras do que perder uma dependência quebrada
Atualizações Incrementais: < 2 Segundos
Arquivo salvo (gancho dispara / modo de vigilância / crg-daemon)
│
▼
Verificação de hash SHA-256: quais arquivos realmente mudaram?
│
▼
Reanalise apenas os arquivos alterados
│
▼
Encontre dependentes dos arquivos alterados, marque arestas para atualização
│
▼
Gráfico atualizado
Benchmark: repositório de 2.900 arquivos → < 2 segundos
repositório de 500 arquivos, construção inicial → ~10 segundos
Confiança de Aresta em Três Níveis
Arestas do gráfico carregam níveis de confiança:
