Saltar a contenido

Las páginas sin traducir se abren en inglés y se indican como inglés.

Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.

El shim de grep

El shim de grep es un wrapper de grep/rg que añade a la línea de cada coincidencia la función que la contiene, obtenida del índice de código; requiere Node 18 o posterior, un token de visor y un repositorio en el índice de código. Está pensado para agentes que solo usan grep de shell, o que se ejecutan donde los hooks no funcionan (claude --bare omite el desvío de código del plugin de Claude Code). El agente, su prompt y su harness no cambian.

$ grep -rn "getSettingsRef().max_threads" src/Processors
src/Processors/QueryPlan/ReadFromMergeTree.cpp:1466:    ... max_threads ...   ⟵ DB::ReadFromMergeTree::selectRangesToRead
src/Processors/Executors/PipelineExecutor.cpp:298:      ... max_threads ...   ⟵ DB::PipelineExecutor::initializeExecution
loom: 2/2 hits scoped to their enclosing function via code.enclosing, index at c7a9fe7c9f, 180 ms

Instalación

export PATH=/path/to/loom/integrations/grep-shim/bin:$PATH
export LOOM_BASE_URL=https://loom.example.com   # or ~/.loom/config.json {url, token}
export LOOM_API_KEY=<viewer token>              # or ~/.loom/token
export LOOM_CODE_NAMESPACE=code-myrepo
export LOOM_AGENT=pr-analyst                    # optional: names the caller in the ledger

which grep debe apuntar al shim. Ejecuta el agente dentro del checkout que indexa el espacio de nombres: las rutas se hacen relativas a git rev-parse --show-toplevel. Una discrepancia de rama se manifiesta como coincidencias sin resolver, no como coincidencias erróneas.

El shim ejecuta el primer grep o rg de PATH que no sea él mismo (LOOM_GREP_REAL y LOOM_RG_REAL fuerzan una ruta).

Garantías

  • Cada byte que imprime la herramienta real se imprime, en orden. El único cambio es un sufijo opcional ⟵ <qualified name> en las líneas de coincidencia cuya función contenedora conoce el índice, y un resumen de una línea en stderr.
  • Se conserva el código de salida (grep: 0 con coincidencias, 1 sin coincidencias, 2 error).
  • Se anotan dos formatos: path:line:text (varios operandos, -r sobre un directorio, -H) y line:text de exactamente un archivo como operando (grep -n pattern file.cpp, el formato al que se acomoda un agente cuando ya conoce el archivo; la ruta es el operando, así que -h no supone problema ahí). Todo lo demás pasa sin tocar: sin -n, -l, -L, -c, -o, -z, -Z, -b, -q, --color=always (rg: -N, --json, --files, -0), stdin, o varios archivos con -h.
  • Un límite estricto de latencia. LOOM_GREP_SHIM_TIMEOUT_MS (por defecto 2500). Cualquier error, un timeout, un token ausente o más de 8 MB de salida (LOOM_GREP_SHIM_MAX_BYTES) imprime la salida sin modificar.
  • Carga acotada en el servidor. Una llamada a code.enclosing por cada 200 coincidencias distintas, con un máximo de 5 en paralelo; se anotan 1,000 coincidencias y el resto se imprime sin anotar.

El bloque del grafo de dependencias

LOOM_GREP_SHIM_GRAPH=on (por defecto off) añade un bloque después de la salida real: [Related from loom dependency graph], y luego una línea por cada función contenedora con su módulo, hasta LOOM_GREP_SHIM_GRAPH_K (5) llamadores, llamados y pruebas, y una nota (lower bound: …) cuando el grafo está incompleto. Cortar desde la línea de encabezado devuelve los bytes reales. El bloque usa la misma llamada a code.enclosing, el mismo timeout y las mismas reglas de fallo abierto; se omite si hay más de LOOM_GREP_SHIM_GRAPH_MAX_ANCHORS (20) funciones o cuando la salida se transmitió en streaming (más de 8 MB).

Interruptores

Variable Por defecto Efecto
LOOM_GREP_SHIM on off convierte el shim en un simple pass-through
LOOM_GREP_SHIM_QUIET sin definir defínelo para suprimir la línea de resumen en stderr
LOOM_GREP_SHIM_TIMEOUT_MS 2500 el límite de latencia
LOOM_GREP_SHIM_MAX_BYTES 8 MB la salida que supere esto pasa sin modificar
LOOM_GREP_SHIM_GRAPH off on añade el bloque del grafo de dependencias
LOOM_GREP_SHIM_GRAPH_K 5 vecinos por función (1–20)
LOOM_GREP_SHIM_GRAPH_MAX_ANCHORS 20 número de funciones a partir del cual se omite el bloque
LOOM_CODE_NAMESPACE, LOOM_AGENT el espacio de nombres de código; el nombre del agente que llama (por defecto grep-shim)
LOOM_CONFIG_FILE, LOOM_API_KEY_FILE ~/.loom/config.json, ~/.loom/token de dónde se leen la URL, el espacio de nombres y el token cuando el entorno no los define

Del lado del servidor: code.enclosing

El shim es un cliente ligero sobre una sola operación. code.enclosing (POST /v1/code.enclosing, visor) recibe locations: ["src/F.cpp:12", …] (hasta 200) y devuelve un resultado por ubicación en el orden de entrada, con symbol == "" cuando la línea está en el ámbito del archivo o la ruta no está indexada. Cada fila resuelta incluye symbol_id.

  • include_body: true (con token_budget, por defecto 4000) coloca en la fila el cuerpo completo de cada función contenedora, obtenido una vez por función distinta y rellenado en orden de primera aparición hasta agotar el presupuesto; el resto incluyen un next listo para pegar (code.symbol(symbol_id=…)). El shim lo deja desactivado.
  • neighbours: true (con neighbour_k, por defecto 5) devuelve los datos del bloque del grafo: una entrada por cada función contenedora distinta (como máximo 20; anchors_capped cuando se resolvieron más) con callers, callees (se prefiere el nivel del compilador; se descartan los símbolos fuera del repositorio y las suposiciones del parser con confianza inferior a 0.8), tests, module y el envelope epistemic / causes.

code.symbol también acepta name: "src/F.cpp:12" para una sola ubicación, y el SDK de Python expone agent.code.enclosing([...], include_body=True). Consulta las operaciones del índice de código.

Límites

  • Solo código integrado. El índice conoce la rama que indexa; una coincidencia en una edición sin commit se resuelve contra la versión indexada del archivo, o no se resuelve en absoluto.
  • Mejor esfuerzo. Ante cualquier imprevisto se imprime la salida sin modificar; una línea sin anotar no significa que grep haya fallado.
  • Las mismas búsquedas. El agente sigue usando grep. Un agente que pueda llamar a herramientas MCP debería usar code.search, code.callers y code.impact directamente.

Relacionado