Buscar código con el grafo de código

Esta guía te muestra cómo meter un repo en el grafo de código y luego usarlo para responder a la pregunta que de verdad te haces antes de refactorizar: ¿de qué depende esto?

El grafo de código es una base de datos de símbolos y aristas que se construye analizando tus checkouts registrados con tree-sitter. Sus herramientas están orientadas al agente: se accede a ellas pidiéndoselo a un agente.

Antes de empezar

El grafo indexa Dart, JavaScript, TypeScript, TSX, PHP, Python, Rust, Zig, C, C++, Go, Java, Ruby, C#, Swift, Kotlin, R, Assembly, MATLAB y Ada. Los archivos de cualquier otro lenguaje no se analizan, así que no aparecen en search_code, code_symbol, code_callers, code_callees ni code_impact.

Hay dos cosas más que determinan qué se indexa:

En un árbol de trabajo de git, la enumeración recae en git ls-files --cached --others --exclude-standard, así que se tienen en cuenta todos los .gitignore, los archivos de exclusión anidados, .git/info/exclude y el archivo global de exclusiones. Eso es lo que mantiene node_modules y la salida de compilación fuera del grafo.
El Dart generado se descarta en cualquier caso. Los archivos generados suelen estar confirmados en el repositorio, así que git por sí solo no los excluiría y cambian en cada ejecución de generación de código.

Indexar un repo

Registrar un checkout dispara RepoAdded, que arranca automáticamente el pipeline index_code para él. Consulta Añadir repos a un espacio de trabajo.

Para volver a indexar a mano:

Abre Ajustes → Espacio de trabajo → Repositorios.
Haz clic en el botón Indexar código de la fila del repo.
Mientras se ejecuta, el botón muestra los archivos hechos sobre el total, con un control para cancelar. Cuando termina, se queda como una marca de verificación con el recuento de símbolos.

El grafo se particiona por espacio de trabajo, repo y checkout: el checkout vinculado es una partición, y cada worktree de espacio tiene la suya (con el id de su repo aislado como clave).

Hay dos limitadores que conviene conocer, porque explican una espera que parece un cuelgue:

El vigilante de archivos solo admite una ejecución de indexación a la vez en el host: un segundo checkout espera. El pipeline index_code tiene además un tope de una ejecución por espacio de trabajo, así que dos repos del mismo espacio de trabajo se ponen en cola; distintos espacios de trabajo pueden indexar en paralelo. El propio indexador serializa dos ejecuciones del mismo checkout, para que el arranque de un pipeline y un barrido del vigilante no lo analicen dos veces.
Los worktrees que pertenecen a espacios inactivos (ningún mensaje en la última semana) ni se vigilan ni se indexan. Los checkouts vinculados se siguen vigilando. Una decisión de omitir se vuelve a comprobar a los cinco minutos, así que un espacio que vuelve a estar activo acaba entrando.

Encontrar un símbolo

Pídele a un agente que busque. La herramienta es search_code y necesita tanto un espacio de trabajo como un repo:

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

Los ids de repo vienen de list_repos. El argumento opcional mode es keyword, semantic o hybrid y por defecto es hybrid: BM25 sobre nombres, firmas y comentarios de documentación, fusionado con similitud vectorial.

Cada resultado incluye el id, el nombre, el nombre cualificado, el tipo, la ruta del archivo, las líneas de inicio y de fin del símbolo y su firma cuando la tiene. El id es el identificador que le pasas a todas las demás herramientas de esta página.

Cuando conozcas el nombre exacto, búscalo directamente en lugar de eso:

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

Rastrear llamadas

Ambas toman un symbol_id de un resultado de búsqueda, además de un limit opcional (50 por defecto):

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

code_callers devuelve los símbolos con una arista entrante hacia este; code_callees devuelve aquellos de los que depende.

Comprobar qué rompería un cambio

Esta es la herramienta por la que existe toda la página:

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

Calcula el radio de dependencias inversas: todo lo que depende del símbolo, de forma directa o transitiva, por aristas calls, extends e implements (las importaciones, los mixes in y las referencias genéricas se guardan en el grafo, pero aquí no se recorren). depth es el número máximo de saltos, entre 1 y 6, y por defecto es 2.

El resultado tiene tres campos:

root — el símbolo por el que preguntaste
impacted — el conjunto alcanzable, incluida la raíz en la profundidad 0, y cada elemento con su depth desde la raíz
edgeCount — cuántas aristas cruzó el recorrido, como recuento en lugar de las aristas en sí

Ejecútala antes de renombrar algo o de cambiar una firma y dale al agente la lista de afectados como ámbito de su trabajo.

Los resultados se comprueban contra la copia de trabajo de quien llama

Cuando quien llama es un agente, el id del espacio se inyecta automáticamente y los resultados se verifican contra la copia de trabajo de ese espacio. Un símbolo cuyo archivo ya no existe en el árbol de quien llama se omite, y la respuesta incluye un recuento staleOmitted más una nota que dice que el índice está obsoleto para esos símbolos.

Por eso tú y un agente podéis obtener respuestas distintas a la misma consulta, y por eso un agente de un espacio puede obtener una respuesta distinta de la de un agente de otro. Todas las conversaciones de un espacio comparten ese mismo worktree. La verificación falla en abierto: se prefiere una respuesta obsoleta a una vacía.

Pídele a un agente que ejecute code_impact (o review_studio.blastRadius) cuando quieras conocer el radio de impacto de un cambio. Consulta Cómputo de revisión.

La búsqueda semántica necesita el modelo de embeddings

Los símbolos y los hechos se convierten en embeddings en el momento de escribirlos, y solo si está instalado el modelo de embeddings en el dispositivo. Hasta entonces, mode: "semantic" y la mitad semántica de hybrid no tienen con qué comparar, y la búsqueda es en la práctica solo por palabras clave.

Instala el modelo en Ajustes → Servidor → Diagnóstico y privacidad → Búsqueda semántica antes de indexar. Los símbolos obtienen un vector cuando se ingiere su archivo.

Fíjate también en que cualquier recompilación del binario del servidor vuelve a preparar las dylibs de las gramáticas y cambia sus mtimes, lo que invalida todos los puntos de control del índice y obliga a un recorrido completo de cada checkout en la siguiente ejecución. Vuelve a calcular los hashes, pero no vuelve a extraer los archivos sin cambios.

Qué hay en el grafo

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

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

Las firmas canónicas de estas herramientas están en Herramientas MCP.

Guías relacionadas

Conceptos relacionados

Espacios de trabajo y aislamiento