@hoilab/ada-cli 0.85.0 → 0.85.3

package/docs/modules-producto.md

@@ -0,0 +1,179 @@
+# Módulos — Producto
+
+Páginas de referencia de los módulos orientados a producto del fork Ada CLI (marketplace de plugins, registro de proveedores, memoria episódica, commits agénticos, discovery de runtimes, URIs internas, limpieza de código y consumo multi-cuenta). Audiencia: usuarios y agentes que no leen el código.
+
+## Marketplace de plugins — descubre, instala, diagnostica y configura plugins desde un catálogo
+
+Resuelve el problema de gestionar plugins de forma informada: saber qué existe (catálogo), instalarlo sin reinstalarlo dos veces, comprobar que una instalación está sana y activar/desactivar sus features.
+
+**Activa**: comandos `plugin marketplace list`, `plugin install|upgrade|uninstall <n>`, `plugin enable|disable <p> <f>`, `plugin doctor <p> [--fix]` (los hints de guardrails de `marketplace`, `upgrade`, `enable`, `disable`, `extensions` apuntan aquí). El catálogo vive en `~/.ada/marketplace.json`; un catálogo remoto se consulta cuando hay URL configurada (`ADA_MARKETPLACE_URL` u `opciones.urlRemota`) y sobreescribe entradas locales por nombre.
+
+**Garantiza**:
+- Catálogo con tres estados honestos: cargado / vacío / inaccesible (un catálogo roto es un estado, no un crash).
+- Instalación idempotente e informada: instalar lo ya instalado es un no-op declarado (`ya-instalado`), nunca una segunda instalación silenciosa; scope explícito user/project sobre el package-manager existente (npm/git/local, sin CRUD nuevo).
+- Features on/off por plugin persistidas en `~/.ada/plugin-features.json`, validadas contra lo declarado en el catálogo: no puedes activar una feature que el plugin no declara.
+- `plugin doctor`: package.json parseable, entry (`main`/`bin`) presente en disco, dependencias resueltas, features declaradas vs activas, conflictos de versión con el catálogo.
+- `--fix` solo aplica correcciones seguras y únicamente con confirmación explícita (`confirmado: true`).
+
+**No garantiza**:
+- No es destructivo ni con `--fix`: reparaciones fuera del conjunto seguro no se aplican.
+- El fetch remoto tiene timeout de 10 s y requiere URL configurada; sin ella solo hay catálogo local.
+- No valida el contenido del plugin más allá del doctor (no ejecuta auditoría de código).
+
+**Código**: `src/core/marketplace/` (`catalogo.ts`, `instalar.ts`, `doctor.ts`, `features.ts`, `index.ts` con el patrón de wiring documentado).
+
+**Test**: `test/marketplace.test.ts`.
+
+## Registro declarativo de proveedores — describir cada proveedor LLM como datos públicos de catálogo
+
+Resuelve el problema de añadir un proveedor LLM sin tocar código disperso: toda su descripción (familia de API, baseUrl por defecto, modelos con contexto y costes, mecanismo de auth, features) es UNA entrada declarativa en una tabla tipada.
+
+**Activa**: automático a nivel de tipos — la tabla `PROVIDERS` usa `satisfies Record<string, ProviderDefinition>`, así que cualquier proveedor nuevo incompleto o familia de API nueva sin soporte rompe la compilación. Se consulta por API (`resolverProveedor`, `listarProveedores`, `buscarPorModelo`) y sirve de puente para el discovery de runtimes (`resolverPorBaseUrl`).
+
+**Garantiza**:
+- Completitud compile-time: campos requeridos y uniones cerradas (`familia`, `tipo`) verificadas por el compilador, no por tests.
+- Resolución case-insensitive de ids con definición canónica devuelta; error útil (`ProveedorDesconocidoError`) que lista los conocidos y cómo añadir uno nuevo.
+- Búsqueda de modelos exacta, única y múltiple (p. ej. openrouter replicando catálogos ajenos).
+- Puente discovery→registry: endpoints descubiertos heredan familia/features de la tabla cuando su baseUrl casa (normalizando barra final y caso).
+
+**No garantiza**:
+- NUNCA contiene claves ni secretos: el auth es una referencia a variable de entorno, OAuth o none — jamás el valor.
+- Un endpoint local cuya baseUrl nadie declara NO es error: `resolverPorBaseUrl` devuelve undefined (es legítimo).
+- La comparación de modelos es exacta: alias o variantes de id no casan.
+
+**Código**: `src/core/proveedores-registry/` (`tipos.ts`, `definiciones.ts`, `resolver.ts`, `index.ts`).
+
+**Test**: `test/proveedores-registry.test.ts`.
+
+## Grafo episódico de memoria — recall que encuentra memorias conectadas aunque no compartan léxico
+
+Resuelve el techo del recall plano (ME1): este solo recupera memorias que comparten palabras con la consulta. El grafo añade un salto de expansión por afinidad entre memorias, recuperando las conectadas a los aciertos aunque no compartan ninguna palabra con ella.
+
+**Activa**: llamada a `recallConGrafo(almacen, consulta, k)` sobre el almacén híbrido de memoria; reúsa `recordar()` del almacén como semillas. Automático dentro del pipeline de recall del motor de memoria.
+
+**Garantiza**:
+- Aristas medidas con tres señales baratas y locales, sin NLP pesado: Jaccard de tokens (peso 0.5), entidades compartidas extraídas con regex simples (@menciones, rutas de fichero, nombres propios capitalizados; peso 0.3) y proximidad temporal con decaimiento exponencial (escala de una semana; peso 0.2).
+- Re-ranking determinista según el contrato ME5: `puntuacion × 0.7 + pesoAristaHaciaSeed × 0.3`.
+- Aristas bajo el umbral (0.05) no se crean: sin señal no hay arista.
+- Vecinos consultables top-k (`vecinosDe`), adyacencia ordenada por peso.
+
+**No garantiza**:
+- Construcción O(n²) en pares: pensado para n pequeño; no escala a corpus grandes sin particionar.
+- Solo UN salto de expansión desde las mejores semillas (~k/2): no hay búsqueda multi-salto ni recorrido completo del grafo.
+- La extracción de entidades es regex simple, no NLP: entidades mal capitalizadas o implícitas no generan señal.
+
+**Código**: `src/core/memoria/grafo.ts`.
+
+**Test**: `test/memoria-grafo.test.ts`.
+
+## Commit agéntico — mensajes generados conversando con herramientas sobre el diff real, con split por tema y CHANGELOG
+
+Resuelve el problema del mensaje de commit inventado: en lugar de una pasada ciega map-reduce, el modelo decide qué mirar (diff de un fichero concreto), ve el estilo real del repo y propone; la propuesta se valida contra el diff antes de aceptarse. Con `--split`, además separa el índice en commits coherentes por paquete/tema y alimenta los changelogs correspondientes.
+
+**Activa**: comando `ada-cli commit [--split] [--hacer] [--model <p/m>] [--detalle]`. Sin `--hacer` solo imprime la propuesta por stdout (canalizable: `ada-cli commit | git commit -F -`).
+
+**Garantiza**:
+- Lee SIEMPRE el índice (`git diff --cached`), nunca el árbol de trabajo: el mensaje describe exactamente lo que se va a commitear.
+- Validación estructurada contra el diff: todo fichero citado que no esté en el índice es un ERROR que se devuelve al modelo como recordatorio sintético (hasta 3×); titulares genéricos («varios cambios», «wip») detectados y rechazados.
+- Degradación honesta: si no hay propuesta válida tras los recordatorios, mensaje DETERMINISTA generado desde los datos reales del diff, marcado `usedFallback` — sabrás que salió sin el modelo, no con él.
+- `--split`: agrupado determinista y LOCAL (sin modelo) por paquete del monorepo o primer segmento; lockfiles huérfanos se asignan al grupo de su manifiesto más cercano (nunca un commit «chore» que no explica nada). Cada commit sale con su mensaje validado con las mismas garantías agénticas.
+- CHANGELOG Keep-a-Changelog por paquete: entradas nuevas bajo `## [Unreleased]` en su sección según tipo convencional, dedupe case-insensitive (regenerar no duplica líneas), destino = CHANGELOG.md más cercano subiendo desde los ficheros del grupo; si no existe ninguno se crea en el directorio común — las entradas no se tiran al changelog del vecino ni se callan.
+- En fallo (índice vacío o modelo caído): código de salida 1 y stdout VACÍO, para que nada falso se cuele encadenado a `git commit -F -`.
+
+**No garantiza**:
+- Nunca commitea por su cuenta sin `--hacer`.
+- Máximo 3 rondas de recordatorio; después cae al fallback determinista.
+- El agrupador por tema entiende monorepos `packages/<x>/` y primeros segmentos: esquemas de layout distintos no se agrupan tan fino.
+
+**Código**: `src/core/commits/` (`agentic.ts`, `split.ts`, `changelog.ts`, `diff.ts`, `git.ts`) + `src/cli/commit-command.ts`.
+
+**Test**: `test/commit-agentic.test.ts`, `test/changelog.test.ts`.
+
+## Discovery de runtimes locales/proxies — encontrar los modelos servidos en tu máquina o proxy sin configurar nada
+
+Resuelve el problema de descubrir qué modelos hay disponibles en runtimes locales y proxies compatibles (Ollama, LM Studio, LiteLLM, new-api/one-api, listas estilo OpenAI) sondeando sus endpoints HTTP conocidos y construyendo un catálogo unificado.
+
+**Activa**: llamada a `descubrirRuntimes({ extraBases?, authHeaders?, signal? })`. Sondea automáticamente las bases loopback por defecto (Ollama en `http://127.0.0.1:11434`, LM Studio en `http://127.0.0.1:1234`); bases remotas adicionales vía `extraBases`.
+
+**Garantiza**:
+- Cobertura por familia: Ollama (`/api/tags` + `/api/show` para num_ctx/capabilities), LM Studio nativo y v0 (`/v1/models`, `/api/v0/models`, contexto desde campo del endpoint o preset INI local en `~/.lmstudio`/`~/.cache/lm-studio`), openai-models-list enriquecido (`/v1/models` + `/v1/models/:id`), LiteLLM rich→fallback (`/model/info` si existe, si no `/v1/models`) y proxies new-api/one-api con routing por `supported_endpoint_types`.
+- Timeouts diferenciados: loopback 250 ms, remoto 10 s — un runtime muerto no cuelga el descubrimiento.
+- Dedup por URL normalizada: el mismo endpoint no aparece dos veces.
+- Catálogo por modelo (`modelosDisponibles`) anotado con el id del proveedor declarativo cuya baseUrl casa (puente con `proveedores-registry`).
+- Fetch inyectable y AbortSignal para tests y cancelación externa.
+
+**No garantiza**:
+- llama.cpp NO se duplica aquí: esa familia ya vive en `extensions/llama/` y está excluida del agregador deliberadamente.
+- Un runtime lento (>250 ms loopback) puede no aparecer: el timeout de sondeo es corto a propósito.
+- El contexto de modelo (`contextLength`) es opcional: si el endpoint y el preset INI no lo dan, no se inventa.
+
+**Código**: `src/core/descubrimiento/runtimes/` (`index.ts` agregador, `ollama.ts`, `lm-studio.ts`, `litellm.ts`, `tipos.ts`).
+
+**Test**: `test/runtimes-discovery.test.ts`.
+
+## URIs internas — 8 esquemas `esquema://…` accesibles desde read/edit sin tocar upstream
+
+Resuelve el problema de dar al modelo acceso uniforme a recursos internos (memoria, vault, reglas, auditoría, parches, limpieza, LSP, share) con un espacio de nombres propio: cualquier texto con `://` entra en ese espacio y nunca se interpreta como ruta de fichero.
+
+**Activa**: automático — las tools `read` y `edit` se envuelven con el router (`envolverReadConRouter`/`envolverEditConRouter`) y se reemplazan por inserción en el Map de tools de la sesión; el modelo ve la misma tool con la descripción ampliada con los esquemas disponibles. Extensible por registro: `registrar(esquema, handler)` añade o reemplaza handlers sin tocar el fichero del router.
+
+**Garantiza**:
+- Los 8 esquemas registrados por defecto: `memory://`, `vault://`, `rule://`, `audit://` (con dispatch real a memoria, bóveda, reglas y libro de auditoría) y `patch://`, `cleanse://`, `lsp://`, `share://` (fachada con validación y dispatch).
+- Parsing con frontera literal: `null` cuando el texto no tiene forma de URI (no aplica), error útil con la lista de esquemas disponibles cuando el esquema no está registrado.
+- Validación por esquema: `lsp://` exige consulta, `share://` exige id alfanumérico con guiones, ningún resto acepta caracteres de control.
+- Cutover limpio: el código nuevo vive en módulos Ada-owned; cero hunks en ficheros de upstream.
+
+**No garantiza**:
+- Los handlers de los 4 esquemas nuevos (`patch`, `cleanse`, `lsp`, `share`) son contratos de fachada del router (placeholder validado y despachado), no la implementación completa de cada slice: `patch://` no toca `core/parche/` (propiedad de D03).
+- `core/router-uris/` es un shim de re-export de `core/rutas/`: no hay dos routers, solo uno.
+
+**Código**: `src/core/rutas/` (`router.ts`, `envoltorio.ts`, `index.ts`); `src/core/router-uris/` (re-export); cableado en `src/core/urls-internas/lector.ts`.
+
+**Test**: `test/router-uris.test.ts`.
+
+## Cleanse — arregla en paralelo los diagnósticos que YA reportan los comprobadores de tu proyecto
+
+Resuelve el problema de pasar de «hay 40 problemas de lint/typecheck/test» a «están arreglados», lanzando un subagente por fichero con verificación real, sin inventarse comprobadores ni aceptar arreglos que no se demuestran.
+
+**Activa**: comando `ada-cli cleanse [--dry-run] [--fix] [--concurrency N] [--model <provider/model>]`. La detección es automática mirando lo que hay: scripts de package.json, tsconfig, biome/eslint, ruff, cargo clippy, go vet, gradle/maven (wrapper incluido).
+
+**Garantiza**:
+- Cero comprobadores inventados: `detectarComprobadores` documenta en `mirado` cada sitio comprobado aunque no encuentre nada — distingue «no he mirado» de «he mirado y no hay nada».
+- Streaming exactly-once (C06): cada diagnóstico se emite UNA sola vez aunque el checker reimprima la línea en varios flushes; el corte es en la última `\
+` con intervalo de 5 s para checkers parcialmente silenciosos.
+- Balanceo por peso (error=5, +2 sin línea, +1 sin regla, +1 sin sugerencia): los ficheros más rotos y menos accionables se reparan primero.
+- Ownership sticky por fichero: todos los diagnósticos tardíos de un fichero van al mismo worker; si llega tarde y el dueño vive, steering por IRC; si murió o el canal falla, reencola.
+- Verificación honesta del arreglo: tras cada arreglo se RE-EJECUTAN todos los comprobadores de alcance «fichero» (un arreglo de lint que rompe el typecheck del mismo fichero no pasa por limpio). Un arreglo se acepta solo si el diagnóstico original desapareció Y no apareció ninguno nuevo en ese fichero, comparando por firma (comprobador+regla+mensaje, inmune al desplazamiento de líneas). Si no se acepta, el fichero SE REVIERTE al contenido previo — rechazar de verdad, no solo decirlo.
+- Tablero vivo: TTY repinta filas por checker/grupo sin scroll; no-TTY/CI emite líneas `[start]/[done]/[fail]` estables.
+
+**No garantiza**:
+- Los comprobadores mutadores (clippy --fix, etc.) solo corren con `--fix`.
+- Diagnósticos de proyecto entero (test runners, sin `ruta`) forman su propio grupo: no se atribuyen a fichero alguno.
+- No ejecuta comprobadores que el proyecto no tenga configurados.
+
+**Código**: `src/core/limpieza/` (`reparacion.ts` orquestador, `comprobadores.ts`, `flujo.ts`, `peso.ts`, `pool.ts`, `tablero.ts`, `parseo.ts`, `tipos.ts`) + `src/cli/cleanse-command.ts`.
+
+**Test**: `test/cleanse-comprobadores.test.ts`, `test/cleanse-reparacion.test.ts`, `test/cleanse-sticky.test.ts`.
+
+## Usage multi-cuenta — quién gastó cuánto, con identidades redactadas y series temporales legibles
+
+Resuelve la pregunta org-decisiva cuando hay varias credenciales en juego: `aggregate.ts` dice cuánto se gastó; esto dice QUIÉN lo gastó, con serie temporal por día y máscaras estables que permiten seguir una cuenta entre ejecuciones sin revelar su identidad.
+
+**Activa**: comando `ada-cli usage` (panel multi-cuenta con sparklines y máscaras). Agrega los mismos JSONL de sesión que el resumen global; la cuota viva (lo que QUEDA) se pregunta al proveedor con la credencial ya guardada, cacheada unos minutos, para anthropic, openrouter, openai-codex, github-copilot y google-gemini.
+
+**Garantiza**:
+- Identidad de cuenta: `accountId` explícito del JSONL si viene; si no, huella de la API key usada — SHA-256 truncado a 16 hex con prefijo de proveedor (`proveedor#huella`) — la clave NUNCA viaja entera, ni en memoria ni en salida, y dos claves iguales en proveedores distintos no se funden en una cuenta.
+- Redacción keyed: cada identidad se sustituye por una máscara `AMIGABLE-XXXX` derivada con HMAC-SHA256 usando la clave per-install de secretos (persistida, 0600, jamás enviada a proveedor) — misma entrada produce siempre la misma máscara, entradas distintas producen máscaras distintas (charset base32 sin I/L/O/0/1 para no confundirlas a ojo), y de la máscara no se vuelve a la identidad ni por diccionario.
+- Filtros espejo del resumen global (directorios temporales fuera, filtro `desde`, solo respuestas del asistente): el total multi-cuenta CUADRA con el total general — dos paneles que no suman lo mismo es cómo empieza a mentir un panel.
+- Sparklines de bloques a ancho fijo: normaliza min→▁ max→█; serie plana → todo ▁ (nunca inventa pendiente); series largas reducidas por medias de cubo.
+- Cuota viva cacheada para no sumar una petición HTTP a cada turno; en la clave de caché solo los últimos caracteres del secreto.
+
+**No garantiza**:
+- No estima nada: suma lo que el proveedor cobró (`usage` de cada mensaje del asistente); donde no hay dato, no hay número.
+- Los tokens de caché van APARTE del total (mezclarlos enseñaría un gasto que no se corresponde con la factura: en DeepSeek un acierto cuesta ~1/31 de un fallo).
+- Si la clave de secretos no existe, NO se crea al redactar: cae a una clave derivada del agentDir (peor caso aceptado — instala normal usa siempre la de secretos).
+- Consultor de cuota solo para los 5 proveedores registrados; `ultimoUso` falta si ninguna línea del JSONL traía timestamp.
+
+**Código**: `src/core/usage/` (`aggregate.ts` global, `multi.ts` multi-cuenta + sparklines, `redaccion.ts` máscaras, `cuota/` consultores por proveedor) + `src/cli/usage-command.ts`.
+
+**Test**: `test/usage-aggregate.test.ts`, `test/usage-multi.test.ts`, `test/usage-cuota.test.ts`.

package/docs/modules-seguridad.md

@@ -0,0 +1,158 @@
+# Seguridad — secretos, cifrado, parches, revisión y privacidad
+
+Los ocho módulos de este grupo defienden tres cosas: que los secretos no lleguen al proveedor, que lo que se escribe a disco no filtre datos protegidos, y que las operaciones destructivas (editar, aplicar parches, publicar revisiones) fallen de forma comprobable en vez de corromper en silencio.
+
+## Secretos keyed reversibles (C01) — evita que tus API keys y tokens salgan hacia el modelo/proveedor, sin romper los edits exactos del agente.
+
+**Activa**: lanzando con la extensión `ada-cli -e packages/coding-agent/src/core/secretos/extension.ts` (dos ganchos ya emitidos por el runner, coste cero contra el presupuesto de sincronización con upstream). Migrar a builtin está previsto pero hoy requiere el flag `-e`.
+
+**Garantiza**:
+- Los mensajes salientes se ofuscan con placeholders `$$NOMBRE_AMIGABLE_HASH$$` keyed (SHA-256 HMAC con clave por instalación): los bytes del secreto nunca llegan al proveedor.
+- Es un punto fijo: re-ofuscar cada turno no altera el output ni rompe los prefijos de prompt-cache.
+- Antes de ejecutar una herramienta, `deobfuscateToolArguments` restaura los placeholders sobre el input, así los edits exact-match siguen casando con los bytes reales del disco (issue #6968).
+- Tokens con forma de credencial (GitHub/GitLab/OpenAI/Anthropic: `ghp_`, `glpat-`, `sk-proj-`, `sk-ant-`, …) se detectan sin entropy-gate: un falso positivo solo sobre-ofusca y el round-trip es lossless.
+- La clave vive en `$XDG_STATE_HOME/ada/secret-placeholder.key` (fallback `~/.ada/agent/`), creada con flag `wx` mode 0600 anti-carrera; nunca pasa por argv ni se registra, y el propio obfuscador la auto-redacta del output visible.
+- Para display local, los placeholders que el modelo eco-ea se restauran (`deobfuscateSessionContext`).
+- Los placeholders llevan ~62 bits de entropía para que secretos distintos no colisionen aunque cambie el conjunto configurado entre sesiones.
+
+**No garantiza**:
+- No es builtin: sin el flag `-e` no hay ofuscación.
+- Coincidencias más cortas de 8 caracteres (`MIN_OBFUSCATE_SECRET_LEN`) no van detrás de placeholder reversible, para no tapar palabras pequeñas.
+- No es gestión de credenciales ni cifrado en reposo: solo evita la salida hacia el proveedor.
+
+**Código**: `src/core/secretos/` (`extension.ts` cableado, `index.ts`, `obfuscator.ts`, `message-transform.ts`, `placeholder.ts`, `placeholder-scan.ts`, `replacement.ts`, `regex.ts`)
+
+**Test**: `test/secretos-keyed.test.ts`
+
+## Share cifrado E2E — exporta/comparte una sesión sin que el paquete (ni quien lo intercepte) pueda leerla; primero se tapa, después se cifra.
+
+**Activa**: automático donde se usa: el exportador es un módulo puro que solo escribe si le das fichero destino, y su primitiva de sellado AES-256-GCM se reutiliza en las salas de colaboración (`colaboracion/rele`).
+
+**Garantiza**:
+- El orden ES la feature (hallazgo D10 de la auditoría omp): la redacción previa reutiliza el punto único `taparAntesDeEscribir` (identificadores + art. 9 del RGPD), no un detector propio.
+- Cifrado AES-256-GCM con clave derivada por scrypt (resistente a tablas precalculadas si la clave humana es débil). Formato `[MAGIC "ADASHR1"][sal 16B][iv 12B][ct+tag]`; la sal va en el paquete porque no es secreta.
+- La clave (256 bits aleatorios, base64url) nunca se serializa dentro del paquete ni en disco junto a él: va al receptor por canal aparte.
+- Tres estados honestos: `exportado` (hay contenido superviviente sellado), `vacio` (la sesión no tenía texto) y `todo-tapado` (había texto y la redacción lo eliminó todo) — no exporta un bloque opaco inútil.
+- Techo del paquete: 1 MiB. Errores distinguibles: `PaqueteNoReconocido` (formato) vs `ClaveIncorrecta` (GCM falla: clave equivocada o paquete alterado).
+- Sin red: no hace fetch, no abre sockets, no sube nada a ninguna parte.
+
+**No garantiza**:
+- Quien tenga la clave lee todo lo que sobrevivió a la redacción: la confidencialidad frente al receptor depende del canal aparte por el que viajes la clave.
+- No transporta el paquete: moverlo es cosa de la persona.
+
+**Código**: `src/core/share/cifrado.ts`, `src/core/share/exportar.ts`
+
+**Test**: `test/share-cifrado.test.ts`
+
+## apply_patch nativo — aplica los patches wire (`*** Begin Patch … *** End Patch`) que emiten los proveedores entrenados, rechazando con `conflict://` si el fichero divergió.
+
+**Activa**: automático: `core/registro.ts` (importado por `core/ada.ts`, sin tocar upstream) registra la tool nativa `apply_patch` y envuelve la tool `edit` para delegar directamente al parser/aplicador nativo cuando los argumentos traen `patch`.
+
+**Garantiza**:
+- Anclaje por contexto: cada hunk valida su contenido esperado contra el fichero; si divergió, falla con `conflict://<ruta>#<hashEsperado>-><hashActual>` SIN tocar disco.
+- Escritura atómica con verificación byte a byte post-escritura.
+- Soporta Add / Update / Delete / Move-to y hunks `@@ -a,b +c,d @@`; los hunks se aplican de abajo hacia arriba para no desplazar índices.
+- Los ficheros con cabecera binaria se rechazan (sniffer).
+- Normalización LF para comparar, preservando la terminación original fuera del patch.
+
+**No garantiza**:
+- NO es un wrapper fuzzy: no adivina posiciones; si el contexto no casa exacto, conflicto.
+
+**Código**: `src/core/parche/parser.ts`, `src/core/parche/aplicar.ts`, `src/core/parche/registro.ts`; tool expuesta en `src/core/tools/apply_patch.ts`
+
+**Test**: `test/apply-patch.test.ts`
+
+## Auto-reparación de hunks — recupera una edición fallida cuyo bloque de contexto existe pero desplazado, en vez de perder un turno.
+
+**Activa**: automática: cuando una edición falla porque el hunk no aplica donde se esperaba, se intenta la reparación antes de devolver el error.
+
+**Garantiza**:
+- Solo repara con un «par simétrico» válido: las mismas líneas de `oldText` aparecen contiguas y ÚNICAS en el contenido actual (0 apariciones = contenido distinto; >1 = ambiguo; en ambos casos no se repara).
+- Validación sintáctica posterior con la regla de `edicion/parseo.ts`: solo se acusa a la edición si la preimagen parseaba; un fichero ya roto antes no bloquea.
+- Tree-sitter es opcional y nunca lanza: si el parser o la gramática del lenguaje no están instalados, devuelve «no sé, no bloqueo». Es dependencia realmente opcional.
+
+**No garantiza**:
+- No repara contenido divergiendo (el bloque ya no es ese) ni posiciones ambiguas: elegir por el modelo es peor que rechazar.
+- Sin gramáticas tree-sitter instaladas, esa capa estructural no añade ninguna prueba.
+
+**Código**: `src/core/reparacion/index.ts`, `src/core/reparacion/reparar-hunk.ts`
+
+**Test**: `test/reparacion-hunk.test.ts`
+
+## Revisión de código (dispositions + procedencia + SARIF firmado) — convierte «pídele al modelo que revise» en un proceso de seguridad: hallazgos anclados, decisiones humanas trazables e informes que GitHub ingiere.
+
+**Activa**: comando `ada-cli review` sobre tu diff; añade `--sarif` para publicar en el pipeline de Code Scanning.
+
+**Garantiza**:
+- **Anclaje**: un hallazgo cuya evidencia no aparece literalmente (texto normalizado) en las líneas AÑADIDAS del diff se descarta, por convincente que sea. Sobre un diff limpio, un revisor honesto devuelve cero.
+- Hallazgos con evidencia OBLIGATORIA y huella estable (regla + ruta + evidencia, deliberadamente sin número de línea): mover el fichero no lo convierte en hallazgo nuevo.
+- **Dispositions**: `aceptado-riesgo` y `falso-positivo` suprimen solo con quién, cuándo y justificación; `corregido` NO suprime — si el hallazgo reaparece, cuenta como regresión nueva; `pendiente` no decide nada.
+- **Procedencia encadenada**: cada scan registra herramienta, versión, commit analizado, timestamp y pin del ruleset, con hash SHA-256 encadenado al registro anterior (como el libro de auditoría); `verificarProcedencia` recomputa toda la cadena y detecta cualquier manipulación o edición manual a medias.
+- **SARIF 2.1.0** válido para GitHub Code Scanning / Azure DevOps: toda regla citada en `results` está declarada en `driver.rules` y `originalUriBaseIds` fija la raíz del repositorio. Vale para cualquier revisión, no solo el escáner.
+- **Publicación firmada**: HMAC-SHA256 sobre los bytes EXACTOS del documento, firma en `.sig` aparte (el SARIF sigue siendo ingerible tal cual), verificación con `timingSafeEqual` y validación de forma previa (Buffer.from hex trunca en silencio).
+
+**No garantiza**:
+- La calidad de los hallazgos sigue siendo la del modelo: el anclaje garantiza que lo publicado existe, no que sea cierto.
+- La firma es simétrica: verificar exige la misma clave que firmó.
+- Una disposition sin persona/fecha/motivo no es auditoría — el formato te la exige, pero no puede impedir que alguien justifique mal.
+
+**Código**: `src/core/revision/` (`hallazgo.ts`, `revisor.ts`, `dispositions.ts`, `procedencia.ts`, `sarif.ts`, `publicar.ts`); CLI en `src/cli/review-command.ts`
+
+**Test**: `test/sarif.test.ts`, `test/revision-dispositions.test.ts` (incluye procedencia encadenada y publicación firmada)
+
+## Hooks TypeScript in-process (B05) — reflejos programáticos sobre cada llamada a herramienta, con objetos tipados y capacidad de reescritura bajo re-aprobación obligatoria.
+
+**Activa**: registrando hooks como ficheros `.ts` que exportan `{matcher?, onToolCall}`; se compilan al vuelo con jiti (sin caché de módulos: editar el `.ts` surte efecto sin reiniciar). Complementa, no sustituye, los hooks de shell de `core/hooks/`.
+
+**Garantiza**:
+- Tres veredictos: `permitir`, `rechazar`, `reescribir`. El `matcher` es una regex contra `toolName`; ausente casa con todo; inválida NO casa y no revienta (misma semántica que `planificarHooks`).
+- Fail-closed por defecto: un hook colgado o que revienta queda aislado por timeout (10 s por defecto) y cierra el paso según `failClosed` (por defecto, cerrar).
+- Orden determinista (hooks ordenados por origen); el primer veredicto que bloquea gana. El runner nunca lanza: un módulo dinámico no puede tumbar el turno.
+- Invariante «approve one thing, run another»: una reescritura NUNCA sale lista para aplicar. Si `effectiveParams` difiere del input recibido, el resultado lleva `requiereAprobacion: true` y el consumidor está obligado a re-aprobar SOBRE LOS PARÁMETROS EFECTIVOS antes de ejecutar nada. No existe camino que devuelva `effectiveParams` sin esa marca.
+
+**No garantiza**:
+- No reemplaza los hooks de shell: es la variante in-process con tipado y reescritura.
+- El runner no re-aprueba él mismo: delega la re-aprobación en el consumidor (es un contrato documentado, no automático).
+
+**Código**: `src/core/hooks-ts/tipos.ts` (contrato puro), `cargador.ts` (jiti), `runner.ts` (agregación), `index.ts`
+
+**Test**: `test/hooks-ts.test.ts`
+
+## Privacidad art. 9/10 RGPD — impide que categorías especiales de datos (salud, sindicación, origen étnico, religión, política, vida sexual, biometría, genética; condenas del art. 10) se escriban EN CLARO en auditoría, diario o export.
+
+**Activa**: automático: todo lo que toca disco pasa por el punto único `taparAntesDeEscribir` — el libro de auditoría (`audit/libro.ts`), el diario de ediciones y la exportación cifrada (`share/`). No hay que acordarse de llamar a las dos pasadas: el módulo las compone.
+
+**Garantiza**:
+- Dos pasadas compuestas: identificadores (`redactSensitive`) + barrido específico de categorías especiales art. 9/10, que NO depende del nivel elegido (el art. 9 es una prohibición legal, no una preferencia).
+- Los IDENTIFICADORES se validan, no se reconocen por forma: DNI/NIE por letra de control (módulo 23), IBAN y número de la Seguridad Social por módulo 97 — esto elimina el falso positivo medido del escáner anterior (un UUID con fragmento con forma de NSS).
+- El VOCABULARIO ambiguo exige CO-OCURRENCIA con un marcador de persona dentro de una ventana de 60 caracteres («su diagnóstico» dispara; «diagnóstico» en un log de compilador, no).
+- Si el texto no se puede analizar (`TextoNoAnalizable`: no es cadena o es absurdamente largo), se tapa el TEXTO ENTERO con marca y motivo visible — nunca se escribe en claro algo que nadie ha mirado, y quien audite distingue un campo tapado por precaución de uno tapado por hallazgo.
+
+**No garantiza**:
+- No entiende negación ni hipótesis («no está de baja por depresión» dispara igual): deliberado — en detección de fugas el falso negativo se paga más caro.
+- No cubre `fingerprint`/«huella digital» como biometría (en este repo son huellas de certificado/fichero); sí cubre «huella dactilar».
+- La matrícula española no tiene dígito de control: única forma sin validar de las cinco (compensada exigiendo el alfabeto real de placas).
+
+**Código**: `src/core/privacidad/categorias-especiales.ts` (detección), `src/core/privacidad/tapar.ts` (composición)
+
+**Test**: `test/pii-categorias-especiales.test.ts`, `test/tapar-articulo-9.test.ts`
+
+## Edición robusta — recupera ediciones que hoy se pierden por una errata del modelo, una ruta a medias o un notebook, sin convertir la recuperación en corrupción.
+
+**Activa**: automático dentro de la tool de edición (`tools/edit-diff.ts`) y del observador de ediciones; la edición de notebooks está expuesta por la API de `core/ada.ts`.
+
+**Garantiza**:
+- **Bloques con errata (`parecido.ts`)**: el modelo cita contexto y lo retipea mal; se casa por parecido (Levenshtein) con tres puertas — umbral alto 0,92 de similitud media por línea, dominancia clara del mejor candidato sobre el segundo, y las líneas CITADAS se escriben del FICHERO, no del modelo (solo las líneas donde `oldText` y `newText` difieren son propuesta del modelo). A diferencia de omp, no persiste las erratas del contexto citado.
+- **Rutas difusas (`rutas-difusas.ts`)**: el modelo dijo `edit.ts` y quiso decir `src/core/tools/edit.ts`; resuelve por sufijo ÚNICO de ruta en el workspace. La ruta exacta gana siempre; 0 o 2+ coincidencias es error con candidatos (`ErrorRutaAmbigua`, hasta 10 listados). Excluye `node_modules`, `.git`, `dist`, etc.
+- **Notebooks (`ipynb.ts`)**: edición por celdas sobre el JSON parseado; re-serialización estable (orden de claves original, indentación 1 como Jupyter — el diff solo muestra la celda tocada) y validación por re-parseo ANTES de escribir: nunca escribe JSON roto. Sin dependencias nuevas.
+- **Diario de ediciones (`diario.ts`)**: JSONL diario con `{ruta, antes, despues, resultado}` de cada edición, materia prima para medir si el auto-arreglo mejora de verdad. Ambos lados pasan por `taparAntesDeEscribir` (no por `redactSensitive`, que no cubre el art. 9). Nunca lanza: un fallo del diario no tumba la edición que registra.
+
+**No garantiza**:
+- Erratas por debajo del umbral de similitud o sin candidato dominante se rechazan: no adivina.
+- La búsqueda difusa es por sufijo EXACTO, no por parecido de nombre: `edit.tss` no resuelve a `edit.ts` (eso es terreno de la recuperación de erratas de `reparacion.ts`, en otro plano).
+- El wiring de `.ipynb` en `tools/edit.ts` queda pendiente (hunks upstream vivos): la API ya está expuesta, el despacho es una línea cuando toque.
+- El diario no es el libro de sesión: nadie audita su cadena, por eso mismo todo lo que escribe va tapado.
+
+**Código**: `src/core/edicion/parecido.ts`, `rutas-difusas.ts`, `ipynb.ts`, `diario.ts`, `observador.ts`, `reparacion.ts`
+
+**Test**: `test/edicion-robustez.test.ts`, `test/diario-de-ediciones.test.ts`, `test/reparacion-de-ediciones.test.ts`, `test/cleanse-reparacion.test.ts`

package/package.json

@@ -1,115 +1,115 @@
 {
-	"name": "@hoilab/ada-cli",
-	"version": "0.85.0",
-	"description": "Ada CLI - coding agent CLI (rebranded fork of pi.dev) with read, bash, edit, write tools and session management",
-	"type": "module",
-	"piConfig": {
-		"name": "ada-cli",
-		"configDir": ".ada"
-	},
-	"bin": {
-		"ada-cli": "dist/cli.js"
-	},
-	"main": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		},
-		"./rpc-entry": {
-			"import": "./dist/rpc-entry.js"
-		},
-		"./client": {
-			"types": "./dist/client/index.d.ts",
-			"import": "./dist/client/index.js"
-		},
-		"./usage-cuota": {
-			"types": "./dist/core/usage/cuota/index.d.ts",
-			"import": "./dist/core/usage/cuota/index.js"
-		}
-	},
-	"files": [
-		"dist",
-		"docs",
-		"examples",
-		"containerization.md",
-		"CHANGELOG.md",
-		"npm-shrinkwrap.json"
-	],
-	"scripts": {
-		"clean": "shx rm -rf dist",
-		"build": "tsgo -p tsconfig.build.json && shx chmod +x dist/cli.js dist/rpc-entry.js && npm run copy-assets",
-		"build:binary": "npm --prefix ../tui run build && npm --prefix ../telemetry run build && npm --prefix ../ai run build && npm --prefix ../agent run build && npm --prefix ../protocol run build && npm --prefix ../client run build && npm run build && bun build --compile --no-compile-autoload-bunfig ./dist/bun/cli.js ./src/utils/image-resize-worker.ts --outfile dist/ada-cli && npm run copy-binary-assets",
-		"copy-assets": "shx mkdir -p dist/modes/interactive/theme && shx cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && shx mkdir -p dist/modes/interactive/assets && shx cp src/modes/interactive/assets/*.png dist/modes/interactive/assets/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/ && shx mkdir -p dist/skills && shx cp -r skills/* dist/skills/ && shx mkdir -p dist/core/computer/motor/platform/macos && shx cp src/core/computer/motor/platform/macos/*.mjs dist/core/computer/motor/platform/macos/ && shx mkdir -p dist/core/prompts && shx cp src/core/prompts/*.md dist/core/prompts/",
-		"copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx cp CHANGELOG.md dist/ && shx mkdir -p dist/theme && shx cp src/modes/interactive/theme/*.json dist/theme/ && shx mkdir -p dist/assets && shx cp src/modes/interactive/assets/*.png dist/assets/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && shx cp ../../node_modules/@silvia-odwyer/photon-node/photon_rs_bg.wasm dist/",
-		"test": "vitest --run",
-		"shrinkwrap": "node ../../scripts/generate-coding-agent-shrinkwrap.mjs",
-		"prepublishOnly": "npm run clean && npm run build && npm run shrinkwrap"
-	},
-	"dependencies": {
-		"@agentclientprotocol/sdk": "1.3.0",
-		"@earendil-works/pi-agent-core": "^0.84.2",
-		"@earendil-works/pi-ai": "^0.84.2",
-		"@earendil-works/pi-client": "^0.84.2",
-		"@earendil-works/pi-protocol": "^0.84.2",
-		"@earendil-works/pi-server": "^0.84.2",
-		"@earendil-works/pi-tui": "^0.84.2",
-		"@silvia-odwyer/photon-node": "0.3.4",
-		"chalk": "5.6.2",
-		"cross-spawn": "7.0.6",
-		"diff": "8.0.4",
-		"glob": "13.0.6",
-		"grok-mermaid": "0.2.2",
-		"highlight.js": "10.7.3",
-		"hosted-git-info": "9.0.3",
-		"ignore": "7.0.5",
-		"jiti": "2.7.0",
-		"minimatch": "10.2.5",
-		"proper-lockfile": "4.1.2",
-		"semver": "7.8.0",
-		"typebox": "1.3.7",
-		"typescript": "5.9.3",
-		"undici": "8.9.0",
-		"yaml": "2.9.0"
-	},
-	"overrides": {
-		"protobufjs": "7.6.5",
-		"rimraf": "6.1.2",
-		"gaxios": {
-			"rimraf": "6.1.2"
-		}
-	},
-	"optionalDependencies": {
-		"@mariozechner/clipboard": "0.3.9"
-	},
-	"devDependencies": {
-		"@types/cross-spawn": "6.0.6",
-		"@types/diff": "7.0.2",
-		"@types/hosted-git-info": "3.0.5",
-		"@types/ms": "2.1.0",
-		"@types/node": "24.12.4",
-		"@types/proper-lockfile": "4.1.4",
-		"@types/semver": "7.7.1",
-		"shx": "0.4.0",
-		"vitest": "4.1.9"
-	},
-	"keywords": [
-		"coding-agent",
-		"ai",
-		"llm",
-		"cli",
-		"tui",
-		"agent"
-	],
-	"author": "Mario Zechner",
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/earendil-works/pi.git",
-		"directory": "packages/coding-agent"
-	},
-	"engines": {
-		"node": ">=22.19.0"
-	}
+  "name": "@hoilab/ada-cli",
+  "version": "0.85.3",
+  "description": "Ada CLI - coding agent CLI (rebranded fork of pi.dev) with read, bash, edit, write tools and session management",
+  "type": "module",
+  "piConfig": {
+    "name": "ada-cli",
+    "configDir": ".ada"
+  },
+  "bin": {
+    "ada-cli": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./rpc-entry": {
+      "import": "./dist/rpc-entry.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./usage-cuota": {
+      "types": "./dist/core/usage/cuota/index.d.ts",
+      "import": "./dist/core/usage/cuota/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "containerization.md",
+    "CHANGELOG.md",
+    "npm-shrinkwrap.json"
+  ],
+  "scripts": {
+    "clean": "shx rm -rf dist",
+    "build": "tsc -p tsconfig.build.json && shx chmod +x dist/cli.js dist/rpc-entry.js && npm run copy-assets",
+    "build:binary": "npm --prefix ../tui run build && npm --prefix ../telemetry run build && npm --prefix ../ai run build && npm --prefix ../agent run build && npm --prefix ../protocol run build && npm --prefix ../client run build && npm run build && bun build --compile --no-compile-autoload-bunfig ./dist/bun/cli.js ./src/utils/image-resize-worker.ts --outfile dist/ada-cli && npm run copy-binary-assets",
+    "copy-assets": "shx mkdir -p dist/modes/interactive/theme && shx cp src/modes/interactive/theme/*.json dist/modes/interactive/theme/ && shx mkdir -p dist/modes/interactive/assets && shx cp src/modes/interactive/assets/*.png dist/modes/interactive/assets/ && shx mkdir -p dist/core/export-html/vendor && shx cp src/core/export-html/template.html src/core/export-html/template.css src/core/export-html/template.js dist/core/export-html/ && shx cp src/core/export-html/vendor/*.js dist/core/export-html/vendor/ && shx mkdir -p dist/skills && shx cp -r skills/* dist/skills/ && shx mkdir -p dist/core/computer/motor/platform/macos && shx cp src/core/computer/motor/platform/macos/*.mjs dist/core/computer/motor/platform/macos/ && shx mkdir -p dist/core/prompts && shx cp src/core/prompts/*.md dist/core/prompts/",
+    "copy-binary-assets": "shx cp package.json dist/ && shx cp README.md dist/ && shx cp CHANGELOG.md dist/ && shx mkdir -p dist/theme && shx cp src/modes/interactive/theme/*.json dist/theme/ && shx mkdir -p dist/assets && shx cp src/modes/interactive/assets/*.png dist/assets/ && shx mkdir -p dist/export-html/vendor && shx cp src/core/export-html/template.html dist/export-html/ && shx cp src/core/export-html/vendor/*.js dist/export-html/vendor/ && shx cp -r docs dist/ && shx cp -r examples dist/ && shx cp ../../node_modules/@silvia-odwyer/photon-node/photon_rs_bg.wasm dist/",
+    "test": "vitest --run",
+    "shrinkwrap": "node ../../scripts/generate-coding-agent-shrinkwrap.mjs",
+    "prepublishOnly": "npm run clean && npm run build && npm run shrinkwrap"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.3.0",
+    "@earendil-works/pi-agent-core": "^0.84.3",
+    "@earendil-works/pi-ai": "^0.84.3",
+    "@earendil-works/pi-client": "^0.84.3",
+    "@earendil-works/pi-protocol": "^0.84.3",
+    "@earendil-works/pi-server": "^0.84.3",
+    "@earendil-works/pi-tui": "^0.84.3",
+    "@silvia-odwyer/photon-node": "0.3.4",
+    "chalk": "5.6.2",
+    "cross-spawn": "7.0.6",
+    "diff": "8.0.4",
+    "glob": "13.0.6",
+    "grok-mermaid": "0.2.2",
+    "highlight.js": "10.7.3",
+    "hosted-git-info": "9.0.3",
+    "ignore": "7.0.5",
+    "jiti": "2.7.0",
+    "minimatch": "10.2.5",
+    "proper-lockfile": "4.1.2",
+    "semver": "7.8.0",
+    "typebox": "1.3.7",
+    "typescript": "5.9.3",
+    "undici": "8.9.0",
+    "yaml": "2.9.0"
+  },
+  "overrides": {
+    "protobufjs": "7.6.5",
+    "rimraf": "6.1.2",
+    "gaxios": {
+      "rimraf": "6.1.2"
+    }
+  },
+  "optionalDependencies": {
+    "@mariozechner/clipboard": "0.3.9"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "6.0.6",
+    "@types/diff": "7.0.2",
+    "@types/hosted-git-info": "3.0.5",
+    "@types/ms": "2.1.0",
+    "@types/node": "24.12.4",
+    "@types/proper-lockfile": "4.1.4",
+    "@types/semver": "7.7.1",
+    "shx": "0.4.0",
+    "vitest": "4.1.9"
+  },
+  "keywords": [
+    "coding-agent",
+    "ai",
+    "llm",
+    "cli",
+    "tui",
+    "agent"
+  ],
+  "author": "Mario Zechner",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/earendil-works/pi.git",
+    "directory": "packages/coding-agent"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
 }

package/dist/core/commit/diff.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../../src/core/commit/diff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC9B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,yEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,KAAK,EAAE,OAAO,CAAC;CACf;AASD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7C;AAgBD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQrD;AAuCD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CAehE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE,CAM9E;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,SAAS,GAAG,MAAM,CAGrE","sourcesContent":["/**\n * Trocea un diff unificado por fichero y mide cuánta SUSTANCIA hay en cada uno.\n *\n * El motivo de que esto exista aparte del modelo: en un diff de 25 ficheros lo\n * normal es que 24 sean ruido —un import movido, el lockfile, el número de\n * versión— y uno solo contenga el cambio de verdad. Si los 25 resúmenes entran\n * al reduce con el mismo peso y en orden alfabético, el mensaje que sale es\n * «actualiza varios ficheros»: literalmente cierto y completamente inútil.\n *\n * Ordenar por sustancia ANTES de llamar al modelo es lo que hace que la primera\n * puerta se pueda comprobar sin red: sobre un diff preparado donde solo un\n * fichero cambia algo, ese fichero tiene que salir el primero.\n */\n\n/** Un fichero del diff, ya separado del resto. */\nexport interface TrozoDeFichero {\n\t/** Ruta destino (o la de origen si el fichero se borra). */\n\truta: string;\n\t/** El diff de ESE fichero, cabecera incluida. */\n\tdiff: string;\n\t/** Líneas añadidas/borradas que dicen algo. Ver `puntuarSustancia`. */\n\tsustancia: number;\n\t/** Ficheros generados que nadie escribe a mano: lockfiles, minificados, dist. */\n\truido: boolean;\n}\n\n/**\n * Ficheros que se regeneran solos. Resumirlos con el modelo es pagar por leer\n * 4.000 líneas de hashes para acabar escribiendo «se actualizó el lockfile».\n */\nconst RUTAS_DE_RUIDO =\n\t/(^|\\/)(package-lock\\.json|npm-shrinkwrap\\.json|pnpm-lock\\.yaml|yarn\\.lock|bun\\.lockb?|Cargo\\.lock|go\\.sum|composer\\.lock|Gemfile\\.lock|poetry\\.lock|uv\\.lock)$|(^|\\/)(dist|build|vendor|node_modules)\\/|\\.min\\.(js|css)$|\\.(snap|lock)$/;\n\nexport function esRuido(ruta: string): boolean {\n\treturn RUTAS_DE_RUIDO.test(ruta);\n}\n\n/**\n * Líneas que cambian sin cambiar nada: en blanco, imports movidos, cierres de\n * bloque sueltos. Se excluyen del recuento porque son justo lo que un\n * reordenado masivo genera a puñados, y sin excluirlas 24 ficheros con un\n * import tocado le ganan por goleada al único que trae la función nueva.\n */\nfunction esLineaTrivial(cuerpo: string): boolean {\n\tconst t = cuerpo.trim();\n\tif (t === \"\") return true;\n\tif (/^(import|export\\s+\\*|export\\s+\\{|from|require|use|using|#include|package)\\b/.test(t)) return true;\n\tif (/^[{}()[\\];,]+$/.test(t)) return true;\n\treturn false;\n}\n\n/**\n * Cuántas líneas con contenido cambia este trozo.\n *\n * No pretende ser una métrica de complejidad: solo tiene que separar «aquí pasa\n * algo» de «aquí se movió una coma», que es la única decisión que toma.\n */\nexport function puntuarSustancia(diff: string): number {\n\tlet n = 0;\n\tfor (const linea of diff.split(\"\\n\")) {\n\t\tif (linea.startsWith(\"+++\") || linea.startsWith(\"---\")) continue;\n\t\tif (linea[0] !== \"+\" && linea[0] !== \"-\") continue;\n\t\tif (!esLineaTrivial(linea.slice(1))) n++;\n\t}\n\treturn n;\n}\n\n/**\n * La ruta que toca enseñar: la de destino, salvo que el fichero se borre.\n *\n * El `\\t?$` no es defensa contra un caso raro: es el formato NORMAL de git en\n * cuanto la ruta lleva un espacio. `git diff` termina las líneas `---`/`+++`\n * con un TABULADOR cuando el nombre tiene espacios, para que se pueda saber\n * dónde acaba:\n *\n *     --- a/mi app/package-lock.json\\t\n *     +++ b/mi app/package-lock.json\\t\n *\n * Sin quitarlo, la ruta se queda en `mi app/package-lock.json\\t` y `esRuido`\n * —que casa con `$`— deja de reconocerlo. Medido ejecutando `ada-cli commit\n * --detalle` por la ruta real sobre un índice con `mi app/package-lock.json`\n * (200 dependencias) y `mi app/codigo.ts`:\n *\n *     • mi app/package-lock.json<TAB> (802): ...\n *     • mi app/codigo.ts<TAB> (2): ...\n *\n * El lockfile con el punto (·) de generado convertido en bala (•): se le gastó\n * una llamada al modelo con 12.000 caracteres de hashes Y, por sus 802 líneas,\n * se ordenó DELANTE del único fichero con código. O sea, el ruido llegando el\n * primero al reduce, que es exactamente lo que este módulo existe para impedir.\n *\n * No lo cazó nadie porque el corpus de pruebas eran diffs escritos a mano, y a\n * mano nadie escribe el tabulador que pone git.\n */\nfunction rutaDelTrozo(diff: string): string {\n\tconst destino = diff.match(/^\\+\\+\\+ b\\/(.+?)\\t?$/m);\n\tif (destino && destino[1] !== \"/dev/null\") return destino[1];\n\tconst origen = diff.match(/^--- a\\/(.+?)\\t?$/m);\n\tif (origen && origen[1] !== \"/dev/null\") return origen[1];\n\t// Renombrados y cambios de modo no traen `---`/`+++`; la cabecera sí.\n\tconst cabecera = diff.match(/^diff --git a\\/(.+?) b\\/(.+)$/m);\n\treturn cabecera ? cabecera[2] : \"(desconocido)\";\n}\n\n/**\n * Parte `git diff` en un trozo por fichero.\n *\n * Devuelve `[]` solo cuando el diff está vacío de verdad. Quien llama tiene que\n * distinguir eso de «no he podido leer el diff»; aquí no se puede inventar esa\n * diferencia, así que la entrada vacía se devuelve vacía y el CLI decide.\n */\nexport function trocearPorFichero(diff: string): TrozoDeFichero[] {\n\tconst trozos: TrozoDeFichero[] = [];\n\t// El separador es la cabecera de git. Se parte con lookahead para no perderla.\n\tfor (const bruto of diff.split(/^(?=diff --git )/m)) {\n\t\tconst texto = bruto.trimEnd();\n\t\tif (!texto.startsWith(\"diff --git \")) continue;\n\t\tconst ruta = rutaDelTrozo(texto);\n\t\ttrozos.push({\n\t\t\truta,\n\t\t\tdiff: texto,\n\t\t\tsustancia: puntuarSustancia(texto),\n\t\t\truido: esRuido(ruta),\n\t\t});\n\t}\n\treturn trozos;\n}\n\n/**\n * De más sustancia a menos; el ruido siempre al final.\n *\n * Empate deshecho por ruta para que dos ejecuciones sobre el mismo diff den el\n * mismo orden: un mensaje de commit que cambia según el humor del `sort` no se\n * puede depurar.\n */\nexport function ordenarPorSustancia(trozos: TrozoDeFichero[]): TrozoDeFichero[] {\n\treturn [...trozos].sort((a, b) => {\n\t\tif (a.ruido !== b.ruido) return a.ruido ? 1 : -1;\n\t\tif (a.sustancia !== b.sustancia) return b.sustancia - a.sustancia;\n\t\treturn a.ruta.localeCompare(b.ruta);\n\t});\n}\n\n/**\n * Recorta un trozo para que quepa en la llamada de map.\n *\n * Se recorta por el final y se dice que se ha recortado: un resumen hecho sobre\n * medio fichero sin avisar es un resumen que miente sobre su cobertura.\n */\nexport function recortar(diff: string, maxCaracteres = 12_000): string {\n\tif (diff.length <= maxCaracteres) return diff;\n\treturn `${diff.slice(0, maxCaracteres)}\\n[...recortado: el fichero cambia ${diff.length} caracteres y solo se han leído los primeros ${maxCaracteres}]`;\n}\n"]}