raphael cunhaSOFTWARE, PEOPLE & IDEAS

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

Um fio terracota sai de um quadro com uma tela simples, passa pelos ilhoses de três caixas de fichas, preso por alfinetes, e termina numa caixa de correio verde, com uma lupa sobre a mesa

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.

Ilustração conceitual. Três repositórios, três pontas soltas: quem liga uma à outra é a pessoa, de memória.

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.

Diagrama com nomes fictícios. As setas mostram o sentido da leitura, da tela ao endpoint. Só uma é tracejada: a chamada HTTP, a única que o grafo infere em vez de ler.
  1. 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.
  2. IMPORTS: do componente até o arquivo da operação GraphQL, em até três saltos.
  3. USES_OPERATION: a operação escrita em gql`…` liga ao campo do gateway, pelo tipo raiz e pelo nome. O parse é do graphql-js.
  4. RESOLVES_FIELD: pela chave exata no mapa de resolvers. Conferido contra o schema que o próprio gateway gera: 252 campos de 252.
  5. 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 faz this.get(…). 245 de 252 campos têm cadeia completa.
  6. 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 {}.
  7. 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:

tiercondição
exatomesmos segmentos, sem parâmetro
parametroo {} da chamada só cai onde a rota tem path variable
prefixouma ú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 mudouo que é refeito
nenhum pushnada, nem chamada de rede
mesmo SHA no branch padrãonada (um git ls-remote)
o blob de um arquivoo arquivo, e os IMPORTS do repositório
a versão do extratoro repositório inteiro
execução anterior interrompidao 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.

Ilustração conceitual. O clone completo trazia o caixote inteiro; o clone parcial e esparso traz só as fichas que o extrator lê.

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 DataLoader nã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.