Grafo de código: da tela do produto até o endpoint

No post sobre o Cobli Intelligence, descrevi um grafo de conhecimento que liga documentação, tickets, times e pull requests. Ele tinha um limite: a menor unidade de código era o repositório. Um bug chegava ao PR, o PR chegava ao repositório, e dali para dentro o grafo era opaco. Um mapa que mostra as cidades, mas não as ruas.
A pergunta que faltava responder é de análise de impacto: “este PR no serviço quebra o quê no painel?”.
Este texto mostra como respondemos com análise estática puramente sintática, sobre 175 repositórios e dezesseis linguagens. Os nomes nos exemplos são fictícios; os números são medidos.
O problema: três abas e um grep
Dentro de um repositório, o compilador verifica as dependências. Entre repositórios, o contrato é uma string: o nome de um campo GraphQL, o caminho de uma rota HTTP. Nenhum sistema de tipos garante que o /v1/fuel-cards montado num data source TypeScript corresponde a um @GetMapping num controller Kotlin, em outro repositório.
O painel sabe qual componente desenha /combustivel. O gateway sabe qual resolver atende Query.fuelCards. O serviço sabe qual controller responde GET /v1/fuel-cards. Nenhum deles sabe que os três são o mesmo fluxo.
Quem junta as pontas hoje é uma pessoa com três abas abertas, um grep e boa memória. Funciona muito bem, até essa pessoa sair de férias.
Por que tree-sitter
Quatro restrições guiaram a escolha: grafo determinístico, sem build dos projetos, incremental (roda de hora em hora num container de 2 GB) e com proveniência por aresta.
- Indexadores semânticos (LSIF, SCIP, language servers) têm a precisão do compilador, mas exigem o build de cada projeto. Para 175 repositórios, isso é um segundo CI.
- Um LLM lendo arquivos não é determinístico nem explica uma aresta errada. Pergunte duas vezes e ganhe dois grafos.
- O tree-sitter faz o parse de cada arquivo isoladamente e devolve uma árvore sintática concreta, tolerante a erro. Rodamos no Bun, com gramáticas em WebAssembly.
O preço é não ter tipos. Lemos só o que está escrito: declarações, imports, anotações e literais. A regra do projeto decorre disso: extrair apenas o que a sintaxe prova.
Avaliamos o graphify, que também usa tree-sitter. No mesmo commit de um serviço Kotlin, ele gerou 3 arestas de import que o nosso extrator não gerou, e as 3 eram falsas. Quando o nome qualificado não resolve, ele casa pelo nome curto, e ligou a classe Analytics de uma biblioteca a uma classe local homônima. Xará não é parente. Ficou como referência, não como dependência.
O modelo
(Repository)-[:HAS_FILE]->(CodeFile)-[:DEFINES]->(CodeSymbol)
(CodeFile)-[:IMPORTS {names, via}]->(CodeFile)
(CodeFile)-[:EXPOSES {handler}]->(Endpoint {method, path})
(CodeFile)-[:USES_OPERATION]->(GraphQLField)<-[:RESOLVES_FIELD]-(CodeFile)
(GraphQLField)-[:DELEGATES_TO {caller, via}]->(CodeFile)
(CodeFile)-[:CALLS_ENDPOINT {tier, caller}]->(Endpoint)
(ProductPage)-[:RENDERED_BY]->(CodeFile)
(PullRequest)-[:TOUCHES]->(CodeFile)
- A granularidade é o símbolo de nível superior. É a unidade que outro arquivo importa. Sem tipos, não resolveríamos membros de classe de qualquer forma.
- A identidade inclui o repositório.
Endpointérepo + método + caminho. O handler fica na aresta, porque dois métodos podem servir a mesma rota. - Código gerado fica de fora. Testes entram marcados e são excluídos de todo casamento entre repositórios: mocks repetem contratos sem consumi-los.
Imports sem compilador
IMPORTS só liga o que o arquivo escreveu, resolvido pelas regras da linguagem, nunca pelo nome curto. Na JVM, pelo nome qualificado. Em TypeScript, reimplementamos a resolução do tsc e do Node a partir do tsconfig.json e dos package.json do mesmo commit: caminho relativo, paths, pacote do workspace pelo exports e baseUrl.
Barrels são atravessados. O import de um index.ts que só reexporta liga direto ao arquivo que declara o nome. No painel, 37% das arestas passam por um barrel; sem isso, “quem usa este arquivo?” perderia um terço dos consumidores.
O resolvedor tem uma métrica de saúde. Import interno que não acha nenhum arquivo é contado à parte. No painel são 21 em 42.952 imports, e os 21 apontam para arquivos que de fato não existem: código morto, não erro de resolução. O resolvedor estava certo; o repositório é que tinha fantasmas.
As gramáticas falham. A de Scala dava erro de parse em 1.058 de 2.082 arquivos reais, mais da metade; a de Kotlin perdia anotações de controller. Cada caso ganhou uma correção pontual. Vale medir a taxa de erro de parse por gramática antes de confiar na árvore.
O caminho de sete saltos
Sete saltos separam o clique do cliente da linha de Kotlin que responde.
RENDERED_BY: os objetos de rota do painel ({ path, component }) ligam a url de cada tela ao componente, com a semântica do React Router. 127 de 130 telas ligadas.IMPORTS: do componente até o arquivo da operação GraphQL, em até três saltos.USES_OPERATION: a operação escrita emgql`…`liga ao campo do gateway, pelo tipo raiz e pelo nome. O parse é dographql-js.RESOLVES_FIELD: pela chave exata no mapa de resolvers. Conferido contra o schema que o próprio gateway gera: 252 campos de 252.DELEGATES_TO: o resolver recebe o data source por injeção de dependência, não por import. O extrator segue a cadeia escrita no código:services.fuelService.list()→ composition root →this.fuelDataSource.list()→ o método que fazthis.get(…). 245 de 252 campos têm cadeia completa.CALLS_ENDPOINT: o caminho HTTP é reconstruído com propagação de constantes restrita ao arquivo (literal, template, constante, ternário). Valor de execução vira{}.EXPOSES: a rota vem da anotação do controller Spring, só quando o caminho é literal.
Com o caminho no grafo, “o que esta tela consome?” é uma travessia:
MATCH (p:ProductPage {url: '/combustivel'})-[:RENDERED_BY]->(page:CodeFile)
MATCH (page)-[:IMPORTS*0..3]->(:CodeFile)-[:USES_OPERATION]->(q:GraphQLField)
MATCH (q)-[d:DELEGATES_TO]->(:CodeFile)-[c:CALLS_ENDPOINT]->(e:Endpoint)
WHERE c.caller = d.caller
RETURN q.name AS campo, e.method + ' ' + e.path AS rota, c.tier AS tier
O predicado c.caller = d.caller é o que dá precisão: a rota de um campo é a chamada daquele método, não todas as chamadas do data source.
Lido, derivado ou inferido
Toda aresta declara sua classe. Fonte é o que está escrito no arquivo (EXPOSES). Derivada é reconstruída de forma determinística (IMPORTS, USES_OPERATION, DELEGATES_TO). Inferida é só CALLS_ENDPOINT: o serviço de destino está numa base url que vem de variável de ambiente, e o único sinal estático é o caminho.
O casamento acontece em níveis, e a aresta guarda qual casou:
tier | condição |
|---|---|
exato | mesmos segmentos, sem parâmetro |
parametro | o {} da chamada só cai onde a rota tem path variable |
prefixo | uma única rota começa como a chamada |
Prefixo com dois candidatos não liga. Caminho sem segmento literal (POST /) também não: na primeira execução, a chamada a um webhook externo casou com a raiz de um serviço interno que não tinha nada a ver com a história.
Auditamos à mão as arestas entre o gateway e o primeiro serviço: 18 de 18 corretas. A amostra é pequena, e por isso a aresta continua marcada como não calibrada.
O princípio é precisão antes de recall, com o recall medido. Tudo que o extrator descarta é contado no grafo. Uma lacuna contada é um item de trabalho; uma aresta errada é uma resposta errada que ninguém questiona.
O que dá para responder agora
Cinco perguntas que antes exigiam três repositórios abertos e hoje são uma chamada, pelo MCP ou pelo bot do Slack, sem Cypher. Os exemplos usam dados fictícios e formato resumido.
“Este PR atingiu o quê?” O modo pr_impact anda no sentido inverso do diagrama: do PR mergeado aos arquivos alterados, às rotas que eles expõem, aos campos do gateway que chamam essas rotas e às telas que chegam a esses campos. Serve para avaliar um deploy e para investigar um incidente.
pr_impact servico-combustivel#412
arquivo FuelCardController.kt
rota GET /v1/fuel-cards/{id} fonte
campo Query.fuelCard inferida, tier parametro
telas /combustivel, /combustivel/cartoes derivada
revisores @time-abastecimento CODEOWNERS
“O bug está nesta tela. Onde eu olho?” O modo screen recebe a url ou o título da tela e devolve os campos GraphQL que ela consulta, o resolver de cada um e as rotas candidatas no serviço. A triagem de um chamado chega ao serviço e ao time certos sem depender de quem lembra do fluxo.
“Posso remover esta rota?” O modo consumers lista os data sources que a chamam, os campos que delegam para eles e as telas no fim do caminho. Vale também para arquivo: quem importa este componente, e por qual barrel. Foi assim que apareceram 47 campos do gateway, de 252, sem consumidor no painel nem na IA. São candidatos a remoção, não prova: pode haver cliente fora do grafo, e a resposta diz isso.
“Onde isto está implementado?” O modo where aceita símbolo, campo, rota, tela ou tópico Kafka e devolve arquivo, linha e os revisores declarados no CODEOWNERS. É a pergunta mais comum de quem acabou de chegar ao time, e de agentes de código que não têm os repositórios clonados.
“Cliente e servidor ainda concordam?” Essa ninguém precisa perguntar: o que não casa fica contado. Na primeira execução apareceram dois desvios de contrato. O painel consultava um campo que o gateway não declara, e o codegen do painel já excluía aquele arquivo, com um TODO. E uma mutation estava no schema com o resolver comentado, devolvendo null.
Toda resposta carrega a classe e o tier de cada ligação e o SHA de cada repositório. Um agente sabe qual salto é frágil e a qual versão do código a resposta se refere. E vale sempre a regra: ausência de aresta não prova ausência de uso.
De hora em hora, sem reler o mundo
| o que mudou | o que é refeito |
|---|---|
| nenhum push | nada, nem chamada de rede |
| mesmo SHA no branch padrão | nada (um git ls-remote) |
| o blob de um arquivo | o arquivo, e os IMPORTS do repositório |
| a versão do extrator | o repositório inteiro |
| execução anterior interrompida | o repositório inteiro |
A versão do extrator faz parte da chave de cache: sem ela, uma regra nova nunca chegaria a um arquivo cujo blob não mudou. E o repositório é marcado como sujo antes da primeira escrita, para que uma execução interrompida seja refeita em vez de confiada pela metade.
O clone é shallow, parcial (--filter=blob:none) e esparso. O motivo tem nome: um repositório de firmware custava 14 GB de cache para indexar 21 arquivos TypeScript. São uns 670 MB por arquivo lido. Com o clone esparso, a primeira carga completa caiu de 16 GB para 548 MB de cache. Uma execução sem push leva 10 segundos, e um PR mergeado no painel, 7.
O Bun não devolve o que pega. O pico da primeira carga foi de 3,5 GB, num container de 2 GB. Medimos que o runtime não devolve ao sistema a memória de um repositório grande, nem pedindo com educação (Bun.gc(true)). A saída foi tirar o problema do coletor de lixo: lotes de 25 repositórios, um subprocesso por lote. O que o processo não devolve em vida, devolve ao morrer. O pico caiu para 894 MB, com o mesmo tempo total.
Entre repositórios, reconstrução total. As arestas que cruzam repositórios são refeitas do zero a cada execução, a partir dos fatos já gravados. Custa 3,5 segundos e torna a aresta órfã impossível por construção.
Um pacote, o mesmo banco
O extrator virou um pacote que lê código e decide arestas sem banco e sem ambiente. Um teste de fronteira falha se ele importar o driver do Neo4j ou ler uma variável de ambiente.
O banco continuou o mesmo. O valor do grafo de código está nas junções com o resto: o PR já chega ao ticket e ao time, a tela já existe no mapa do produto. Com dois bancos, essas junções sairiam do Cypher para o código da aplicação.
Limites
- O grafo descreve o branch padrão, não produção. Por isso a resposta carrega o SHA.
- Sem tipos, não há call graph.
DELEGATES_TOé uma exceção feita à mão para um padrão de injeção de dependência. - Indireção dinâmica escapa. Rota em constante, resolver montado por spread e closure em
DataLoadernão são lidos. Todos são contados. - A cobertura varia por linguagem. Python e Go entram com imports e declarações, ainda sem rotas HTTP.
O que eu levaria para outro projeto
- Comece pelo caminho, não pelo volume. Entramos com os quatro repositórios que formam painel → gateway → serviço e auditamos as arestas antes de abrir para os outros 171.
- Otimize precisão e conte cada descarte. Toda heurística recusada teria produzido arestas plausíveis e erradas.
- Trate o extrator como schema versionado. O que muda sem invalidar o cache produz um grafo que parece atual e não é.
- Reconstrua do zero onde for barato. É mais simples e correto por construção.
O grafo agora começa na tela que o cliente vê e termina na linha do controller que responde. Quando não conhece o caminho, ele diz onde parou.