Grafo de código

Cuatro consultas sobre el índice propio del taller: preciso en Go, heurístico en el resto, con una confianza por arista.

Qué es#

Cuatro preguntas que el índice sabe responder, cada una con su herramienta de agente y su comando humano.

Pregunta Herramienta MCP Comando humano Responde con
Muéstrame el cuerpo de esta función code_snippet orch symbols snippet <name> {symbol, start_line, end_line, body, file_bytes}
¿Quién la llama y a quién llama? trace_path orch symbols trace <name> {root, nodes, edges}, una confianza por arista
¿Qué rompe este cambio? impact orch symbols impact [path...] {paths, touched, callers, edges}
¿Cómo se ve este repositorio? architecture orch symbols arch {dirs, edges} por directorio

trace_path acepta un direction opcional (callers, callees o both) y una depth de 1 a 5, con 2 por defecto. impact sin argumentos lee el diff del árbol de trabajo; dale paths[] o un git_range para preguntar por otra cosa. code_snippet devuelve a lo sumo max_lines líneas, 120 por defecto.

Por qué existe#

Leer un archivo entero para encontrar una función es el hábito más caro que tiene un agente. Un snippet por rango de líneas cuesta una fracción, y un grafo de llamadas responde "¿quién más usa esto?" en un solo viaje en lugar de una docena de greps. orch ya parsea cada archivo que indexa, así que el grafo es un subproducto y no una segunda herramienta que instalar y mantener sincronizada.

Preciso en Go, heurístico en el resto#

Cada arista lleva una confidence, y ese número es la parte honesta:

Confianza Cómo se resolvió la arista
1.0 El resolvedor de Go acertó un import, o el propio archivo
0.7 El resolvedor de Go acertó un tipo receptor
0.4 El tokenizador genérico acertó un Name( suelto contra la tabla de símbolos del mismo lenguaje

Así que Go es preciso y los otros veintiocho lenguajes langspec son heurísticos: una arista 0.4 es una llamada plausible, no probada. Un nombre que no resuelve a ningún símbolo indexado se descarta en vez de guardarse, así que un recorrido nunca cae en una arista colgante.

  fuente Go ----> resolvedor go/ast ---> aristas en 1.0 / 0.7
  otros leng. --> regex langspec     ---> símbolos, luego aristas del tokenizador en 0.4
                     |
                     v
              tabla symbol_refs  --> trace_path / impact / architecture

Qué no ve#

El índice ve símbolos con firma: funciones, tipos, métodos, clases. Es ciego a constantes, nombres de tabla, banderas de esquema y cualquier nombre que viva dentro de una cadena. Para eso, grep sigue siendo la herramienta correcta. Un resultado vacío es una respuesta real, no una falla: significa que no hay coincidencia, así que puedes crear la cosa localmente — pero no inventes un duplicado de un nombre que ya sabes que es compartido.

Cómo se relaciona con el resto#

  • El índice es el mismo que llena la ley del código compartido: alcance shared para símbolos etiquetados, local para todo lo demás. La búsqueda responde solo shared; el grafo lee ambos.
  • code_snippet y trace_path registran los bytes que devolvieron frente al tamaño del archivo que reemplazaron. Esos totales salen como un bloque graph en orch usage, libre de contenido.

Aquí no hay nada que ejecutar#

El grafo se consulta, no se construye: registrar e indexar una carpeta lo llena. orch index shared vuelve a escanear las rutas compartidas registradas, y orch inventory contrasta esas carpetas con lo que el índice realmente tiene.