ast-mcp-server 0.6.0 → 0.7.1

package/skills/structural-code-editing/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: structural-code-editing
 description: Leer, navegar y editar proyectos TypeScript/JavaScript mediante el resolver real del compilador y operaciones AST preparadas, revisadas y vinculadas por hash.
-version: "4.0.0"
+version: "4.1.0"
 author: "yail"
 license: "ISC"
 metadata:
@@ -38,16 +38,28 @@ La presencia de este skill no demuestra que el transporte MCP esté configurado.
 
 El setup falla cerrado ante un registro `ast` conflictivo. No eliminar ni reemplazar una configuración existente sin revisión explícita.
 
+## Runtime, soporte y errores
+
+El paquete requiere Node.js `>=22.5.0`. El target verificado para v0.7.1 es Linux x64 con Node.js 22.5.0 o la línea actual de Node.js 24 y el `mv` de GNU coreutils requerido por la publicación atómica de evidencia. Otras arquitecturas Linux, sistemas sin ese primitivo, macOS y Windows están sin verificar.
+
+El transporte soportado es stdio local bajo los permisos filesystem del usuario que invoca el proceso. No asumir autenticación HTTP, sandbox, aislamiento entre tenants ni una frontera segura para clientes remotos o no confiables.
+
+La persistencia del índice está deshabilitada por default. El modo `canary` requiere `AST_SYMBOL_INDEX_PERSISTENCE=canary` y un `AST_SYMBOL_INDEX_CACHE_ROOT` absoluto y aislado; `enabled` sigue sin publicarse y falla cerrado a memoria con `enabled_not_released`.
+
+Los errores públicos usan un vocabulario cerrado dentro de `{ "error": { "code", "message", "correlation_id" } }`, con `isError: true`. Conservar el `correlation_id` al reportar un fallo; no pedir ni exponer stacks, paths absolutos, source, cache, argumentos crudos, environment ni credenciales para diagnosticarlo.
+
 ## Flujo compacto de lectura
 
 1. `ast_list_files` para descubrir archivos. Paginar; no pedir todo un monorepo si alcanza con un filtro.
-2. `ast_explore` para una pregunta de lectura que combine descubrimiento y evidencia. Usar `summary` por defecto, `context` para source seleccionado y `full` para source más referencias.
-3. `ast_get_file` si ya se conoce el archivo y hace falta source exacto. Usar `offset`/`limit`; no cargar el archivo completo por defecto.
-4. `ast_search_symbols` si todavía no se conoce el archivo o el selector exacto.
-5. `ast_get_outline` para ver contratos sin cuerpos. No pedir `include_symbols` salvo que haga falta la metadata detallada.
-6. `ast_get_symbol_source` solo para las declaraciones cuya implementación haya que inspeccionar.
-7. `ast_find_references` antes de renames o cambios con impacto cross-file.
-8. `ast_get_diagnostics` para establecer y verificar el estado del proyecto.
+2. `ast_get_project_status` para comprobar compiler, freshness, watcher, index y operation queue antes de confiar en una lectura sensible.
+3. `ast_explore` para una pregunta de lectura que combine descubrimiento y evidencia. Usar `summary` por defecto, `context` para source seleccionado y `full` para source más referencias.
+4. `ast_get_file` si ya se conoce el archivo y hace falta source exacto. Usar `offset`/`limit`; no cargar el archivo completo por defecto.
+5. `ast_search_symbols` si todavía no se conoce el archivo o el selector exacto.
+6. `ast_get_outline` para ver contratos sin cuerpos. No pedir `include_symbols` salvo que haga falta la metadata detallada.
+7. `ast_get_symbol_source` solo para las declaraciones cuya implementación haya que inspeccionar.
+8. `ast_find_references` antes de renames o cambios con impacto cross-file.
+9. `ast_get_impact` para explorar impacto directo/transitivo con relaciones compiler-backed y límites explícitos.
+10. `ast_get_diagnostics` para establecer y verificar el estado del proyecto.
 
 `ast_search_symbols` devuelve por default hasta 20 records `summary` rankeados. Su campo `selector` es el valor que se pasa como `symbol_path` a la siguiente tool; pedir `detail: "selectors"` para routing puro o `detail: "full", limit: 100` para el perfil v0.4.0. `ast_find_references` devuelve `detail: "locations"` por default; expandir a `detail: "context"` únicamente cuando la línea fuente aporte evidencia necesaria.
 
@@ -57,13 +69,28 @@ El setup falla cerrado ante un registro `ast` conflictivo. No eliminar ni reempl
 
 `ast_explore` es read-only y no prepara ni aplica operaciones. Sus selectors son directamente reutilizables por las tools primitivas y de mutación. La respuesta declara `freshness`, `completeness`, `truncation`, `unresolved` y `budget`; si el límite de bytes impide incluir todo el contexto, el resultado queda marcado como incompleto.
 
+## Modelo de confianza y freshness
+
+No tratar toda salida como evidencia equivalente. Cuando una relación expone metadata de trust:
+
+- `provenance: "compiler"` + `confidence: "exact"` + `resolution: "resolved"` + `freshness.state: "fresh"` es la única combinación que puede llevar `compiler_authoritative: true`.
+- `provenance: "syntax"` describe estructura AST sin resolución semántica; sirve para navegación, no para afirmar que dos símbolos están conectados.
+- `provenance: "heuristic"` describe una sugerencia por convención o nombre; nunca autoriza una mutación ni un candidato de test compiler-backed.
+- El índice es una aceleración derivada y no una autoridad. Validar cualquier selector contra el compilador; si el índice está stale, falta o no coincide, usar el fallback compiler-backed o fallar cerrado.
+
+`fresh` significa que la evidencia coincide con el snapshot sincronizado. `pending`, `rebuilding`, `stale` y `degraded` no deben presentarse como evidencia actual. Las respuestas preservan `causes` (`source_change`, `config_change`, `index_failure`, `watcher_failure`, `compiler_rebuild`) y `checked_at`. `ast_get_impact` rechaza relaciones que no estén fresh; `ast_explore` conserva `completeness`, `unresolved`, `budget` y `truncation` para que una lectura parcial no parezca un negativo.
+
+El resolver interno de candidatos de tests solo acepta impacto fresh y exacto, devuelve evidencia de relación directa o transitiva con IDs bounded y no ejecuta tests. Si la relación es stale, está truncada, es ambigua o solo heurística, no genera candidatos.
+
+Todos los reads son bounded. Respetar `limit`, `reference_limit`, `max_bytes`, y en impacto `max_depth`, `max_nodes` y `max_edges`; revisar siempre `budget` y `truncation` antes de razonar sobre ausencia. Los límites de batch son independientes y también deben mantenerse explícitos.
+
 Los clientes pueden prefijar los nombres publicados (`ast_*`) según su convención MCP; elegir por el nombre base y el schema, no adivinar el prefijo.
 
 ## Formato de resultado para el modelo
 
-`ast_search_symbols`, `ast_find_references` y `ast_get_diagnostics` aceptan `output_format: "toon"`. Usarlo cuando la respuesta vaya directo al modelo y se espere una colección uniforme con varios registros. Omitirlo, o usar `json`, para automatización que dependa del objeto canónico.
+`ast_search_symbols`, `ast_find_references`, `ast_get_impact` y `ast_get_diagnostics` aceptan `output_format: "toon"`. Usarlo cuando la respuesta vaya directo al modelo y se espere una colección uniforme con varios registros. Omitirlo, o usar `json`, para automatización que dependa del objeto canónico.
 
-En MCP, TOON llega como un único envelope estructurado `{ "format": "toon", "data": "..." }`; `data` contiene el documento TOON lossless. No hay una copia JSON completa en paralelo. Las tres tools validan primero el valor canónico con Zod, pero no publican un `outputSchema` MCP único porque tienen dos representaciones de éxito.
+En MCP, TOON llega como un único envelope estructurado `{ "format": "toon", "data": "..." }`; `data` contiene el documento TOON lossless. No hay una copia JSON completa en paralelo. Las cuatro tools validan primero el valor canónico con Zod, pero no publican un `outputSchema` MCP único porque tienen dos representaciones de éxito.
 
 No pedir TOON para `ast_list_files`, outlines, source, previews ni mutaciones: los benchmarks muestran que el envelope empeora esas formas pequeñas, multiline o diff-heavy. Para un pipeline read-only conocido, se puede compactar únicamente el resultado final con: