Pesquisar código com o grafo de código

Este guia mostra como colocar um repositório no grafo de código e depois usá-lo para responder à pergunta que você realmente tem antes de uma refatoração: do que isso depende?

O grafo de código é um banco de dados de símbolos e arestas construído pela análise dos seus checkouts registrados com o tree-sitter. Suas ferramentas são voltadas ao agente — você as acessa pedindo a um agente.

Antes de começar

O grafo indexa Dart, JavaScript, TypeScript, TSX, PHP, Python, Rust, Zig, C, C++, Go, Java, Ruby, C#, Swift, Kotlin, R, Assembly, MATLAB e Ada. Arquivos em qualquer outra linguagem não são analisados, então não aparecem em search_code, code_symbol, code_callers, code_callees nem code_impact.

Mais dois fatores moldam o que é indexado:

• Em uma árvore de trabalho do git, a enumeração é delegada a git ls-files --cached --others --exclude-standard, então todo .gitignore, arquivo de ignore aninhado, .git/info/exclude e o arquivo global de exclusões é respeitado. É isso que mantém node_modules e a saída de build fora do grafo.
• Dart gerado é descartado de qualquer modo. Arquivos gerados costumam estar commitados, então só o git não os excluiria, e eles mudam a cada execução de geração de código.

Indexar um repositório

Registrar um checkout dispara RepoAdded, que inicia automaticamente o pipeline index_code para ele. Consulte Adicionar repos a um espaço de trabalho.

Para reindexar manualmente:

1. Abra Configurações → Espaço de trabalho → Repositórios.
2. Clique no botão Indexar código na linha do repositório.
3. Enquanto ela roda, o botão mostra os arquivos concluídos sobre o total, com um controle de cancelamento. Quando termina, ele se firma em um check com a contagem de símbolos.

O grafo é particionado por espaço de trabalho, repositório e checkout: o checkout vinculado é uma partição, e cada worktree de espaço tem a sua própria (com chave pelo id de repositório isolado).

Vale conhecer dois limitadores, porque eles explicam uma espera que parece um travamento:

• O observador de arquivos admite apenas uma execução de indexação por vez no host — um segundo checkout espera. O pipeline index_code é limitado separadamente a uma execução por espaço de trabalho, então dois repositórios no mesmo espaço de trabalho entram na fila; espaços de trabalho diferentes podem indexar em paralelo. O próprio indexador serializa duas execuções do mesmo checkout, de modo que o início de um pipeline e uma varredura do observador não possam analisá-lo duas vezes.
• Worktrees pertencentes a espaços inativos (sem mensagem na última semana) não são observados nem indexados. Checkouts vinculados continuam sendo observados. Uma decisão de pular é reavaliada após cinco minutos, então um espaço que volta a ficar ativo é retomado.

Uma gramática ausente derruba o servidor, não a busca

O tree-sitter e suas gramáticas são natives obrigatórios. Se faltar um, o cc_server se recusa a inicializar e informa a dylib ausente — o sintoma é um servidor que não inicia, nunca uma busca degradada. Prepare-os com scripts/natives/build_natives.sh e recompile o binário do servidor.

Encontrar um símbolo

Peça a um agente para pesquisar. A ferramenta é search_code e precisa tanto de um espaço de trabalho quanto de um repositório:

search_code(workspace_id: "...", repo_id: "...", query: "authentication middleware")

Os ids de repositório vêm de list_repos. O argumento opcional mode é keyword, semantic ou hybrid e assume hybrid por padrão — BM25 sobre nomes, assinaturas e comentários de documentação, combinado com similaridade vetorial.

Cada resultado carrega o id, o nome, o nome qualificado, o tipo, o caminho do arquivo, a linha inicial e a final do símbolo e sua assinatura, quando ele tem uma. O id é o identificador que você repassa a todas as outras ferramentas desta página.

Quando você sabe o nome exato, consulte-o diretamente em vez disso:

code_symbol(workspace_id: "...", repo_id: "...", name: "MyClass")

Rastrear chamadas

Ambas recebem um symbol_id de um resultado de busca, além de um limit opcional (padrão 50):

code_callers(workspace_id: "...", symbol_id: "...")
code_callees(workspace_id: "...", symbol_id: "...")

code_callers retorna os símbolos com uma aresta de entrada para este; code_callees retorna aqueles dos quais ele depende.

Verificar o que uma alteração quebraria

É para essa ferramenta que a página inteira existe:

code_impact(workspace_id: "...", symbol_id: "...", depth: 3)

Ela calcula o raio de dependência reversa: tudo o que depende direta ou transitivamente do símbolo pelas arestas calls, extends e implements (imports, mixes-in e referências genéricas são armazenados no grafo, mas não são percorridos aqui). depth é o número máximo de saltos, entre 1 e 6, com padrão 2.

O resultado tem três campos:

• root — o símbolo sobre o qual você perguntou
• impacted — o conjunto alcançável, incluindo a raiz em depth 0, cada um com seu depth a partir da raiz
• edgeCount — quantas arestas a travessia cruzou, como uma contagem em vez das próprias arestas

Execute-a antes de renomear ou alterar uma assinatura e dê ao agente a lista de impactados como escopo.

Os resultados são verificados contra a cópia de trabalho do próprio chamador

Para um chamador agente, o id do espaço é injetado automaticamente e os resultados são verificados contra a cópia de trabalho daquele espaço. Um símbolo cujo arquivo não existe mais na árvore do chamador é omitido, e a resposta traz uma contagem staleOmitted mais uma nota dizendo que o índice está desatualizado para esses símbolos.

É por isso que você e um agente podem obter respostas diferentes para a mesma consulta, e por que um agente em um espaço pode obter uma resposta diferente da de um agente em outro. Toda conversa em um espaço compartilha esse único worktree. A verificação falha de forma aberta: uma resposta desatualizada é preferível a uma vazia.

Peça a um agente para executar code_impact (ou review_studio.blastRadius) quando quiser o raio de impacto de uma alteração. Consulte Computação de revisão.

A busca semântica precisa do modelo de embeddings

Símbolos e fatos recebem embeddings no momento da escrita e somente quando o modelo de embeddings no dispositivo está instalado. Até lá, mode: "semantic" e a metade semântica do hybrid não têm com o que comparar, e a busca é efetivamente apenas por palavra-chave.

Instale o modelo em Configurações → Servidor → Diagnóstico e privacidade → Busca semântica antes de indexar. Os símbolos recebem um vetor quando seu arquivo é ingerido.

Observe também que qualquer recompilação do binário do servidor recopia as dylibs de gramática e altera seus mtimes, o que invalida todos os checkpoints de índice e força uma varredura completa de cada checkout na próxima execução. Ele recalcula os hashes, mas não reextrai os arquivos inalterados.

O que há no grafo

Tipos de símbolo: function, method, class, field, enum, constructor, getter, setter, typedef, extension, mixin, variable.

Tipos de aresta: calls, imports, extends, implements, mixes in, references.

As assinaturas canônicas dessas ferramentas estão em Ferramentas MCP.

Guias relacionados

• Adicionar repos a um espaço de trabalho
• Computação de revisão (coortes e eixos)
• Usar o servidor MCP

Conceitos relacionados

• Espaços de trabalho e isolamento