Blast radius no CodeGraph: como descobrir o que sua mudança de código pode quebrar

Fala aí, beleza? Toda base de código tem aquela função que ninguém quer tocar 😅

Você abre o arquivo, olha a assinatura, pensa em renomear um parâmetro e trava

porque não faz ideia de quantos lugares distantes vão explodir junto

Esse "quanto explode junto" tem nome: blast radius, ou raio de impacto

E é exatamente isso que o CodeGraph responde, lendo o grafo do seu projeto em vez de ler o texto dos arquivos

A diferença parece sutil, mas é ela que separa uma lista confiável de lugares a olhar de um Ctrl+Shift+F cheio de falso positivo

Por que o raio de impacto depende de referências resolvidas

Antes do como, o porquê

O CodeGraph indexa o projeto usando gramáticas tree-sitter pra extrair duas coisas: nós (funções, classes, métodos) e arestas (calls, imports, extends, implements)

Só que extrair não basta

Depois da extração vem a etapa que faz o trabalho pesado: a resolução de referências

É ali que chamadas de função são ligadas às definições de verdade, imports são ligados aos arquivos de origem, mais herança de classe e padrões específicos de framework

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 15min

Conhecer formação

Que diferença isso faz na prática? Toda

Sem esse elo, uma busca por nome só encontra texto parecido

Se o teu projeto tem três handle() em módulos diferentes, o grep te devolve os três e você que se vire

Com referência resolvida, a pergunta muda de "onde aparece essa string?" pra "quem chama ESTE símbolo?"

E tem um detalhe que eu acho MUITO massa no projeto: a cobertura de resolução é medida, não assumida

Durante o codegraph init aparece o indicador Resolving refs

Ou seja, você não fica no achismo sobre a qualidade do grafo que está sustentando a sua consulta de impacto

O que você precisa antes de rodar a análise de impacto

A lista é curta, felizmente

• Um agente suportado instalado na máquina: Claude Code, Codex, Gemini, Cursor, OpenCode, AntiGravity, Kiro ou Hermes Agent
• O projeto local, porque o CodeGraph roda 100% na tua máquina
• Conferir a linguagem, e aqui tem uma boa notícia

Sobre linguagem: o CodeGraph tem um kernel nativo em Rust com gramáticas tree-sitter compiladas pra 20 linguagens

As demais rodam a mesma lógica de extração no engine portátil e produzem grafos idênticos

A cobertura vai muito além do arroz com feijão TypeScript/JavaScript:

TypeScript/JavaScript, ArkTS, Python, Go, Rust, Java, Kotlin, Scala, C/C++, CUDA, C#, Visual Basic .NET, Swift, Objective-C, Metal, PHP, Ruby, Dart, Lua/Luau, R, Erlang, CFML, COBOL, Solidity, Terraform/OpenTofu (HCL), Nix, Svelte, Vue, Astro, Razor/Blazor, Liquid e Pascal/Delphi

Sim, COBOL e Solidity na mesma lista, hehe

E a parte que costuma resolver a objeção de quem trabalha com código sensível: o CodeGraph é gratuito, open source sob licença MIT, roda inteiramente na tua máquina, sem chaves de API e sem serviço externo no meio

Nada de "PC da Nasa" nem de mandar teu repositório privado pra nuvem de alguém

Como descobrir o blast radius de uma mudança, passo a passo

Bora ver na prática?

O caminho completo é esse: instalar, registrar nos agentes, reiniciar o agente, indexar o projeto, consultar o impacto e conferir o frescor do índice

1. Instale globalmente pelo npm (a versão mais recente publicada é a 1.5.0)

npm install -g @colbymchenry/codegraph

O pacote se chama @colbymchenry/codegraph, com escopo mesmo

2. Registre o CodeGraph nos seus agentes com o codegraph install

codegraph install --yes
codegraph install --target=cursor,claude --yes
codegraph install --target=auto --location=local

O --yes detecta os agentes automaticamente

O --target escolhe quais agentes receber o registro, e o --location define o escopo da instalação

O erro comum deste passo: achar que o install precisa ser repetido em cada projeto

Não precisa

Um único codegraph install global já cobre todos os teus projetos, e a flag de escopo fica aí só pra quem tem um motivo específico pra fugir do padrão

3. Reinicie o agente pra que o servidor MCP do CodeGraph carregue

O erro comum deste passo: pular o restart, abrir o agente, não ver nenhuma ferramenta nova e concluir que a instalação falhou

Já vi gente desinstalar tudo por causa disso

Fecha e abre o Claude Code, o Cursor, o Codex CLI, o opencode, o Hermes Agent, o Gemini CLI, o Antigravity IDE ou o Kiro, o que for o teu caso

4. Indexe o projeto rodando o init dentro da pasta dele

codegraph init

Esse comando cria o diretório local .codegraph/ e monta o grafo completo no mesmo passo

O erro comum deste passo: confundir com o install

Aqui é o contrário: o init é um por projeto, então cada repositório novo pede o seu

5. Consulte o impacto

Pelo agente, você usa a ferramenta codegraph_explore, que é a única listada por padrão na superfície MCP

Ela já traz uma seção compacta de blast radius: quem depende de cada símbolo (apenas as localizações, não o código-fonte inteiro) e quais arquivos de teste cobrem aquele símbolo

Isso dispensa uma consulta separada de impacto na maioria dos casos

Se você prefere terminal, os equivalentes de CLI estão lá:

codegraph impact
codegraph callers
codegraph callees
codegraph node
codegraph query
codegraph files

O codegraph impact é o que analisa o blast radius de um símbolo: ele percorre o grafo em largura a partir dele, seguindo callers, importers e dependentes, até uma profundidade configurável

6. Confira o frescor do índice antes de confiar no resultado

codegraph status

O índice sincroniza automaticamente quando o código muda, então na maior parte do tempo você nem pensa nisso

Mas o status mostra a seção Pending sync: com os arquivos pendentes e a idade da edição

O erro comum deste passo: pedir impacto logo depois de um rebase gordo e tratar o retorno como verdade absoluta sem olhar o pending sync

Tome cuidado! Grafo desatualizado responde com convicção a pergunta errada

Onde o blast radius rende mais: revisão de PR e refatoração

O conceito é bonito, mas onde ele paga a conta?

Dois cenários bem concretos

Revisão de PR:

O fluxo é simples: você pega os símbolos tocados no diff e pergunta o blast radius de cada um

O retorno te dá os dependentes e os arquivos de teste que cobrem aquele símbolo

Aí o "parece seguro pra mim, aprovado 👍" vira uma lista de lugares a olhar

É outro nível de revisão, porque você para de revisar só o que está na tela e passa a revisar o que está atrás da tela

E quando um símbolo tocado volta sem nenhum arquivo de teste cobrindo ele, isso por si só já é um recado

Quem já montou fluxo automatizado sabe que o segredo nunca é a ferramenta, é o gatilho certo na hora certa

A lógica é a mesma de quem resolve aprender n8n para automação: o ganho aparece quando o passo chato acontece sozinho, no momento em que ele importa

Refatoração:

Aqui é onde eu acho que o negócio brilha

Antes de renomear, mudar assinatura ou mover um módulo de lugar, você olha callers e importers

E como a profundidade da travessia é configurável, dá pra separar duas coisas que normalmente vêm emboladas:

• impacto direto: quem chama ou importa o símbolo agora
• impacto de segunda ordem: quem depende de quem chama

Essa separação muda a decisão

Mudança com impacto direto pequeno e segunda ordem gigante é aquela que parece inofensiva na revisão e derruba a build meia hora depois

Excluir função sem deixar órfão:

Uso curto e ÓBVIO depois que você vê

Antes de apagar uma função, o blast radius te mostra o que fica pendurado no vazio

Código morto de verdade some sem dor, o resto aparece na lista

Superfície MCP enxuta: uma ferramenta só, e o resto sob demanda

Essa decisão de design merece um parágrafo

Rodando como servidor MCP, o CodeGraph expõe por padrão uma única ferramenta: a codegraph_explore

Por quê? Porque o retorno das outras já chega embutido nela

As demais continuam funcionais, só não ficam listadas na superfície do agente

Se você quiser as ferramentas de volta na superfície MCP, dá pra reexpor por variável de ambiente:

CODEGRAPH_MCP_TOOLS=explore,node,search,callers

Ou simplesmente ir pela linha de comando, que é o caminho mais direto pra quem já vive no terminal

E tem um horizonte anunciado: existe uma plataforma CodeGraph hospedada, em getcodegraph.com, voltada a analisar impacto de mudança por pull request

Ela ainda não foi lançada, está aceitando inscrições em lista de espera pro beta

Enquanto isso, a versão open source segue gratuita do jeito que está

Pra situar o cenário de IA pra dev

Pra quem quer contexto do momento que a gente está vivendo com os modelos e ferramentas de desenvolvimento, este vídeo do canal mostra o panorama:

Conclusão

Se tem uma frase pra levar deste post é essa: consulta de impacto vale o quanto vale o grafo por trás dela

O blast radius não é mágica nem prompt secreto, é consequência de tree-sitter extraindo nós e arestas e da resolução de referências ligando chamada com definição e import com arquivo de origem

Próximo passo bem concreto pra hoje: roda codegraph init no teu repositório e pede o blast radius daquele símbolo que você tem medo de tocar

Depois compara o retorno com o que a busca por texto te devolve pelo mesmo nome

A diferença entre as duas listas é o tamanho do teu ponto cego, e faça o teste! 😀

O projeto é o colbymchenry/codegraph, mantido pelo Colby McHenry, e já passa de 65 mil estrelas no GitHub (66,7 mil segundo o star-history)

Até o próximo post!