Buscar código con el grafo de código

Esta guía te muestra cómo llevar un repo al grafo de código y luego usarlo para responder la pregunta que de verdad tienes antes de un refactor: ¿qué depende de esto?

El grafo de código es una base de datos de símbolos y aristas que se construye analizando con tree-sitter los checkouts que registraste. Sus herramientas están orientadas al agente: llegas 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 se delega a git ls-files --cached --others --exclude-standard, así que se respetan 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 todos los casos. Los archivos generados normalmente se confirman al repositorio, así que git por sí solo no los excluiría y cambian en cada ejecución de generación de código.

Indexa un repo

Registrar un checkout dispara RepoAdded, que inicia automáticamente el pipeline index_code correspondiente. Consulta Agregar repos a un espacio de trabajo.

Para volver a indexar manualmente:

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

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

Vale la pena conocer dos límites de concurrencia, porque explican una espera que parece un cuelgue:

El watcher 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 indexador mismo serializa dos ejecuciones del mismo checkout, de modo que el inicio de un pipeline y un barrido del watcher no puedan analizarlo dos veces.
Los árboles de trabajo que pertenecen a espacios inactivos (sin mensajes en la última semana) no se vigilan ni se indexan. Los checkouts vinculados siguen vigilados. Una decisión de omisión se vuelve a evaluar a los cinco minutos, así que un espacio que vuelve a estar activo se retoma.

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 provienen de list_repos. El argumento opcional mode es keyword, semantic o hybrid y su valor predeterminado es híbrido: BM25 sobre nombres, firmas y comentarios de documentación, combinado con similitud vectorial.

Cada resultado incluye el id, el nombre, el nombre calificado, el tipo, la ruta de archivo, las líneas de inicio y 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 conoces el nombre exacto, búscalo directamente en su lugar:

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

Rastrear llamadas

Ambas toman un symbol_id de un resultado de búsqueda, más un limit opcional (predeterminado 50):

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 dependencia inversa: todo lo que depende directa o transitivamente del símbolo a lo largo de las aristas calls, extends e implements (las importaciones, los mix-in y las referencias genéricas se guardan en el grafo, pero no se recorren aquí). depth es la cantidad máxima de saltos, entre 1 y 6, con un valor predeterminado de 2.

El resultado tiene tres campos:

root: el símbolo por el que preguntaste
impacted: el conjunto alcanzable, que incluye la raíz en la profundidad 0; cada elemento lleva su depth respecto de la raíz
edgeCount: cuántas aristas cruzó el recorrido, como un conteo en lugar de las aristas mismas

Ejecútala antes de renombrar algo o cambiar una firma, y dale al agente la lista de impactados como su alcance.

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 conteo staleOmitted junto con una nota que indica que el índice está desactualizado para esos símbolos.

Por eso tú y un agente pueden 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 único árbol de trabajo. La verificación falla de forma abierta: se prefiere una respuesta desactualizada a una vacía.

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

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

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

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

Ten en cuenta también que cualquier recompilación del binario del servidor vuelve a preparar las dylibs de las gramáticas y cambia sus mtimes, lo que invalida cada punto de control del índice y obliga a recorrer de nuevo por completo 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