changebook 0.4.8 → 0.4.10

package/dist/guard.js

@@ -13,22 +13,69 @@
  *            deliberately does NOT block.
  */
 import * as fs from "node:fs";
-import * as path from "node:path";
 import { execFileSync } from "node:child_process";
-import { execFileAsync, gitPath } from "./git.js";
+import { execFileAsync, gitPath, projectNameFor } from "./git.js";
 import { feedWarningFor } from "./feed.js";
 /** Exit code that asks the pre-commit hook to abort the commit. */
 export const EXIT_BLOCK = 3;
 // A commit should never feel slow because of us: whatever the network hasn't
 // answered by then is treated as "no findings".
 const GUARD_TIMEOUT_MS = 3_500;
+/**
+ * Tope de greps para decidir a QUIEN se avisa (ver `guardFindings`, nota 3).
+ *
+ * Mas alto que el tope de refutaciones del hook (3) porque aqui el grep decide
+ * si el aviso SALE, no solo si se cae: quedarse corto devuelve al guardian al
+ * comportamiento contaminado que estamos arreglando. Y sigue siendo barato —
+ * ~30 ms cada uno sobre este repo, cacheados por simbolo — dentro de los 3,5 s.
+ */
+const MAX_GREPS_DE_DESTINO = 8;
 // Open alerts move at analysis speed (one per commit at most), so a short
 // cache makes rebases/amend streaks free without risking stale warnings.
 const CACHE_TTL_MS = 5 * 60_000;
 const MAX_ALERTS = 20;
+/**
+ * ¿Puede el REPO contestar la afirmacion de este aviso?
+ *
+ * Es la pregunta que faltaba, y la respuesta decide si el grep significa algo.
+ * Medido el 2026-07-26 sobre las 28 alertas con evidencia de AppAtlas: seis se
+ * descartaban en silencio porque su simbolo aparecia en el repo, y dos de ellas
+ * eran las UNICAS del registro que predijeron un incidente real —el desfase de
+ * esquema del 22 de julio, tres dias sin persistir alertas— porque hablaban de
+ * algo ausente en la BASE DE DATOS DE PRODUCCION. El simbolo estaba en el repo,
+ * claro: era el nombre del fichero de migracion.
+ *
+ * Una migracion presente en el repo NO prueba que su DDL haya corrido. Eso no se
+ * arregla con mejores greps; se arregla no haciendo el grep.
+ */
+export function alcanceDelRepo(alert) {
+    const scope = (alert.evidence_scope ?? "").trim();
+    if (scope === "repo")
+        return "si";
+    if (scope === "prod_db" || scope === "deployed")
+        return "no";
+    // Las 99 historicas y cualquier aviso donde el modelo lo omita. No se infiere
+    // del texto: adivinar el ambito es exactamente lo que rompio esto.
+    return "sin_declarar";
+}
+/**
+ * La frase para un aviso que el repo NO puede contestar. Es informacion, no
+ * ruido: le dice al agente donde SI habria que mirar, que en los dos casos
+ * medidos era "comprueba si la migracion corrio en produccion".
+ */
+export function dondeComprobarlo(alert) {
+    const scope = (alert.evidence_scope ?? "").trim();
+    if (scope === "prod_db") {
+        return "this claim is about the PRODUCTION DATABASE, not the repo — a migration file existing here does not mean its DDL ran";
+    }
+    if (scope === "deployed") {
+        return "this claim is about what is DEPLOYED right now, not the repo — check the deployed version, not the source";
+    }
+    return null;
+}
 /**
  * Same slug the backend derives from the project name (analysis.ts slugify):
- * the CLI sends `path.basename(cwd)` as projectName and the server slugifies
+ * the CLI sends `projectNameFor(cwd)` as projectName and the server slugifies
  * it, so reproducing that transform is how the guard finds its project row.
  */
 export function slugifyProject(value) {
@@ -82,19 +129,60 @@ function alertFiles(alert) {
 /**
  * ¿Se contradice el aviso con el codigo que hay delante?
  *
- * Devuelve `true` SOLO cuando la evidencia lo tumba de forma inequivoca. Sin
+ * Devuelve `true` SOLO cuando la evidencia lo tumba de forma INEQUIVOCA. Sin
  * evidencia, con el simbolo vacio o si la busqueda falla, devuelve `false`: la
  * duda deja pasar el aviso. Un guardian que se calla por un error de disco es
  * peor que uno ruidoso — misma leccion que el limitador que fallaba abierto y
  * nadie noto en nueve dias.
  *
+ * ── 2026-07-26: LA RAMA "absent" NO ERA INEQUIVOCA Y SE QUITO ───────────────
+ *
+ * Decia: expect 'absent' + el simbolo aparece => refutado ("si aparece, ya esta
+ * hecho"). Medido sobre las 28 alertas con evidencia de AppAtlas:
+ *
+ *     expect 'present' y el simbolo ya no esta -> descartar     0 veces
+ *     expect 'absent'  y el simbolo aparece    -> descartar     6 veces
+ *
+ * O sea que el 100% de los descartes venia de esa rama, y la solida no disparaba
+ * NUNCA. Y las seis eran de las mejores del registro:
+ *
+ *   · `alert_evidence` (22 jul): "esto deja regression_warnings vacio hasta que
+ *     se aplique la migracion en produccion". SE CUMPLIO: tres dias sin
+ *     persistir alertas.
+ *   · `admin_install_metrics` (25 jul): el MISMO fallo otra vez, citando el
+ *     precedente del 22. Una de las 5 alertas que alguien juzgo y arreglo.
+ *
+ * POR QUE FALLABA: "el simbolo aparece" significa dos cosas OPUESTAS — que el
+ * reemplazo se revirtio (el aviso ya no aplica) o que queda una referencia
+ * obsoleta (el aviso CUMPLIENDOSE). Y en esas seis, peor: hablaban de algo que
+ * falta en la BASE DE DATOS DE PRODUCCION, mientras el grep mira el REPO. El
+ * simbolo esta en el repo, claro que esta: es el nombre del fichero de
+ * migracion. Se buscaba en un sitio una afirmacion que era sobre otro.
+ *
+ * El caso que lo paga: cuando `vite.config.ts` todavia importaba `noscriptFor`,
+ * la alerta que lo nombraba se "refutaba" por aqui. Ese dia el build se rompio
+ * por eso exactamente.
+ *
+ * QUE SE HACE AHORA con ese caso: no se descarta, se SIRVE diciendo donde
+ * aparece el simbolo (ver `dondeApareceElSimbolo`). Nombrar el sitio es util en
+ * las dos lecturas y falso en ninguna, mientras que descartar es catastrofico en
+ * una de las dos. Es la misma regla de siempre —la duda deja pasar el aviso—
+ * aplicada donde no se estaba aplicando.
+ *
  * `buscar` devuelve cuantas veces aparece el simbolo, o null si no se pudo
  * mirar.
  */
 export function avisoRefutado(alert, buscar) {
     const simbolo = (alert.evidence_symbol ?? "").trim();
     const espera = alert.evidence_expect;
-    if (!simbolo || (espera !== "present" && espera !== "absent"))
+    // Solo 'present' puede refutarse con un grep del repo. 'absent' es ambiguo
+    // (ver arriba) y se resuelve sirviendo las rutas, no descartando.
+    if (!simbolo || espera !== "present")
+        return false;
+    // Y solo si la afirmacion es SOBRE el repo. Un 'sin_declarar' tampoco refuta:
+    // gatearlo no cuesta nada medido —esta rama disparo 0 veces en produccion— y
+    // quita el riesgo de tirar una alerta de produccion por buscar donde no era.
+    if (alcanceDelRepo(alert) !== "si")
         return false;
     let apariciones;
     try {
@@ -108,10 +196,77 @@ export function avisoRefutado(alert, buscar) {
     // "present": el aviso vive de que el simbolo siga ahi. Si ya no esta, el
     // conflicto que describia no puede darse — es el caso de las 3 alertas del
     // renombrado latestFilesByModule -> moduleFilesUnion: cero referencias.
-    if (espera === "present")
-        return apariciones === 0;
-    // "absent": el aviso vive de que algo FALTE. Si aparece, ya esta hecho.
-    return apariciones > 0;
+    return apariciones === 0;
+}
+/**
+ * Una linea por TEXTO: si dos avisos abiertos dicen lo mismo, se sirve uno.
+ *
+ * El dedup de creacion distingue por (simbolo, expectativa) a proposito — "tiene
+ * que seguir" y "tiene que desaparecer" son afirmaciones opuestas y colapsarlas
+ * escondería una regresion real. Pero eso es la IDENTIDAD, no la PANTALLA.
+ *
+ * Visto en produccion el 2026-07-27, servido al agente:
+ *
+ *   ⚠ OPEN ALERT: La funcion noscriptFor fue reemplazada por crawlerBodyFor...
+ *   ⚠ OPEN ALERT: La funcion noscriptFor fue reemplazada por crawlerBodyFor...
+ *     → CHECKED NOW: ...
+ *
+ * Dos alertas de verdad distintas (una 'present', otra 'absent') con el MISMO
+ * texto, porque la expectativa no se muestra. Para quien lo lee es una
+ * repeticion, y un avisador que repite se ignora igual que uno que se equivoca.
+ * No se puede actuar distinto sobre dos frases identicas.
+ *
+ * `informativo` decide cual sobrevive: se prefiere el que trae la linea de
+ * comprobacion (donde aparece el simbolo, o donde habria que mirarlo), porque es
+ * el unico que añade algo. Empate: el primero, y el orden de entrada se respeta.
+ */
+export function unoPorTexto(items, texto, informativo) {
+    const mejor = new Map();
+    for (const it of items) {
+        const clave = texto(it).trim();
+        if (!clave)
+            continue;
+        const actual = mejor.get(clave);
+        if (!actual || (!informativo(actual) && informativo(it))) {
+            mejor.set(clave, it);
+        }
+    }
+    return [...mejor.values()];
+}
+/**
+ * Donde aparece el simbolo de un aviso 'absent', para poder CONTESTAR el
+ * condicional en vez de vigilarlo.
+ *
+ * Es la otra mitad del cambio de arriba. El aviso de `noscriptFor` decia
+ * "actualiza cualquier referencia interna a noscriptFor ... SI LOS HUBIERA", y
+ * la respuesta era un grep. El 56% de los textos lleva un condicional asi
+ * ("si los hubiera", "podria", "sugiriendo"): en vez de prohibir la redaccion
+ * —que es tratar el sintoma— se resuelve la condicion y se dice el hecho.
+ *
+ * Devuelve null cuando no hay nada que añadir: otro `expect`, sin simbolo, la
+ * busqueda fallo, o el simbolo no aparece (y entonces el aviso se sirve tal
+ * cual, que es lo que ya hacia).
+ */
+export function dondeApareceElSimbolo(alert, buscarFicheros) {
+    const simbolo = (alert.evidence_symbol ?? "").trim();
+    if (!simbolo || alert.evidence_expect !== "absent")
+        return null;
+    // Con 'prod_db' o 'deployed' no se busca: decir "sigue apareciendo en X" sobre
+    // una afirmacion que no era del repo es afirmar algo falso con cara de hecho
+    // comprobado, que es peor que callarse. Para esos va `dondeComprobarlo`.
+    // 'sin_declarar' SI localiza: es aditivo y no puede perder un aviso.
+    if (alcanceDelRepo(alert) === "no")
+        return null;
+    let ficheros;
+    try {
+        ficheros = buscarFicheros(simbolo);
+    }
+    catch {
+        return null;
+    }
+    if (!ficheros || ficheros.length === 0)
+        return null;
+    return ficheros;
 }
 /**
  * Open alerts × staged files → warnings, deduped by (module, message).
@@ -126,8 +281,32 @@ export function avisoRefutado(alert, buscar) {
  *
  * 2. SI SIGUE EN PIE. `refutado` lo decide quien llama, que es quien tiene el
  *    arbol de trabajo. De 7 avisos abiertos, 4 se caian con un grep.
+ *
+ * 3. DONDE VIVE EL SIMBOLO manda sobre la lista del aviso (2026-07-27), y esto
+ *    nace de medir el guardian en 62 corridas reales. Aviso 2 veces; una en el
+ *    clavo y otra falso positivo:
+ *
+ *      La alerta era sobre `noscriptFor` en PUBLICACION (seoRoutes.ts,
+ *      publish.yml) y salto al preparar `tools/bench-orientacion.mjs` — el arnes
+ *      del benchmark, que no tiene nada que ver con noscriptFor.
+ *
+ *    La causa: la lista `files` de un aviso son LOS FICHEROS DEL DIFF QUE LO
+ *    LEVANTO, no los ficheros donde vive el simbolo. Medido sobre las 27 alertas
+ *    con lista: **10 (37%) no nombran ni un fichero donde su simbolo este**. Y
+ *    los peores contaminadores son los que se tocan a todas horas —
+ *    `_shared/analysis.ts` sale en 5 listas, `bench-orientacion.mjs` en 4 —, o
+ *    sea que cada vez que los editas arrastras avisos ajenos.
+ *
+ *    Con `ficherosDelSimbolo` se pregunta donde esta el simbolo DE VERDAD. Es la
+ *    misma pieza que sirve para contestar el condicional (`ficherosEnRepo`), aqui
+ *    para decidir a quien se avisa.
+ *
+ *    ORDEN DE PREFERENCIA, y cada escalon es un fallo-abierto del siguiente:
+ *      donde vive el simbolo  >  lista del aviso  >  ficheros del modulo
+ *    Si el grep falla o no encuentra nada se cae a la lista de siempre, asi que
+ *    un fallo de disco no puede volver mudo al guardian.
  */
-export function guardFindings(staged, alerts, filesByModule, refutado) {
+export function guardFindings(staged, alerts, filesByModule, refutado, ficherosDelSimbolo) {
     const stagedSet = new Set(staged);
     const seen = new Set();
     const findings = [];
@@ -136,10 +315,15 @@ export function guardFindings(staged, alerts, filesByModule, refutado) {
         const plain = (alert.plain ?? "").trim();
         if (!module || !plain)
             continue;
-        // Las rutas del aviso mandan sobre las del modulo: dicen de QUE va, no solo
-        // a que cajon pertenece.
+        // Donde vive el simbolo manda sobre la lista del aviso, y la lista del aviso
+        // sobre el modulo: de mas preciso a menos. Ver la nota 3 de arriba.
+        const porSimbolo = ficherosDelSimbolo?.(alert) ?? null;
         const propias = alertFiles(alert);
-        const ambito = propias.length > 0 ? propias : (filesByModule.get(module) ?? []);
+        const ambito = porSimbolo && porSimbolo.length > 0
+            ? porSimbolo
+            : propias.length > 0
+                ? propias
+                : (filesByModule.get(module) ?? []);
         const touched = ambito.filter((f) => stagedSet.has(f));
         if (touched.length === 0)
             continue;
@@ -167,13 +351,50 @@ export function guardFindings(staged, alerts, filesByModule, refutado) {
  * `.` sueltos lo convertirian en otra expresion regular.
  */
 export function contarEnRepo(dir, simbolo) {
+    const out = grepDelRepo(dir, simbolo, "--count");
+    if (out === null)
+        return null;
+    // Una linea "fichero:N" por fichero con coincidencias.
+    return out
+        .split("\n")
+        .filter(Boolean)
+        .reduce((n, l) => n + (Number(l.slice(l.lastIndexOf(":") + 1)) || 0), 0);
+}
+/**
+ * En QUE ficheros aparece el simbolo. Mismo grep, mismos pathspecs, distinta
+ * pregunta: `contarEnRepo` sirve para refutar y este para CONTESTAR (ver
+ * `dondeApareceElSimbolo`).
+ *
+ * Comparten `grepDelRepo` a proposito y no por ahorrar lineas: si divergieran
+ * los pathspecs, uno podria decir "no aparece" y el otro "aparece en X" sobre el
+ * mismo simbolo, y no habria forma de saber cual miente.
+ */
+export function ficherosEnRepo(dir, simbolo) {
+    const out = grepDelRepo(dir, simbolo, "--files-with-matches");
+    if (out === null)
+        return null;
+    return out.split("\n").filter(Boolean).slice(0, MAX_FICHEROS_SERVIDOS);
+}
+/** Tope de rutas que se nombran en un aviso: la lista es una pista, no un informe. */
+const MAX_FICHEROS_SERVIDOS = 4;
+/**
+ * El grep compartido. `modo` es `--count` o `--files-with-matches`.
+ *
+ * `git grep` y no un recorrido propio: respeta .gitignore, no entra en
+ * node_modules y esta escrito en C. Sobre este repo tarda ~30 ms, asi que cabe
+ * de sobra en el presupuesto de 3,5 s del guardian.
+ *
+ * `--fixed-strings` es obligatorio: el simbolo viene de un modelo y un `$` o un
+ * `.` sueltos lo convertirian en otra expresion regular.
+ */
+function grepDelRepo(dir, simbolo, modo) {
     if (!/^[A-Za-z_$][\w$.]{1,118}$/.test(simbolo))
         return null;
     try {
-        const out = execFileSync("git", [
+        return execFileSync("git", [
             "grep",
             "--fixed-strings",
-            "--count",
+            modo,
             "--",
             simbolo,
             // Se busca en CODIGO, nunca en prosa. Sin esto el mecanismo nace
@@ -188,17 +409,12 @@ export function contarEnRepo(dir, simbolo) {
             // en silencio. Lo cazó el fixture hermético del test (2026-07-21).
             ":!docs/**",
         ], { cwd: dir, encoding: "utf8", timeout: 2_000, maxBuffer: 4 * 1024 * 1024 });
-        // Una linea "fichero:N" por fichero con coincidencias.
-        return out
-            .split("\n")
-            .filter(Boolean)
-            .reduce((n, l) => n + (Number(l.slice(l.lastIndexOf(":") + 1)) || 0), 0);
     }
     catch (e) {
         // git grep sale con 1 cuando NO hay coincidencias: eso es un cero real, no
         // un fallo. Cualquier otro codigo si es "no he podido mirar".
         const code = e.status;
-        return code === 1 ? 0 : null;
+        return code === 1 ? "" : null;
     }
 }
 export async function stagedFiles(dir) {
@@ -233,7 +449,7 @@ async function fetchSignals(db, dir, env) {
     }
     // Same project the analyze/hook pipeline reports to: CHANGEBOOK_PROJECT
     // wins, otherwise the directory name, matched by server-side slug first.
-    const candidate = env.CHANGEBOOK_PROJECT?.trim() || path.basename(path.resolve(dir));
+    const candidate = projectNameFor(dir, env);
     const slug = slugifyProject(candidate);
     let projects = slug
         ? await db.rest(`projects?select=id&slug=eq.${encodeURIComponent(slug)}&limit=1`)
@@ -367,7 +583,35 @@ export async function runGuard(db, dir, env = process.env) {
         await logRun(dir, `timeout after ${GUARD_TIMEOUT_MS}ms — passing`);
         return 0;
     }
-    const findings = guardFindings(staged, signals.alerts, signals.filesByModule, (alert) => avisoRefutado(alert, (simbolo) => contarEnRepo(dir, simbolo)));
+    // Presupuesto de greps para decidir A QUIEN se avisa. `contarEnRepo` y
+    // `ficherosEnRepo` son execFileSync, o sea que BLOQUEAN el bucle de eventos y
+    // el techo de GUARD_TIMEOUT_MS no puede desalojarlos — un Promise.race no gana
+    // a una llamada sincrona. Con muchas alertas abiertas esto se comeria el
+    // presupuesto del commit a ~30 ms por grep. Pasado el tope se cae a la lista
+    // del aviso, que es el comportamiento de siempre.
+    //
+    // Se cachea por simbolo porque varias alertas comparten el mismo (noscriptFor
+    // salio 3 veces): sin esto se pagaria el mismo grep tres veces.
+    let grepsRestantes = MAX_GREPS_DE_DESTINO;
+    const cacheSimbolo = new Map();
+    const ficherosDelSimbolo = (alert) => {
+        const simbolo = (alert.evidence_symbol ?? "").trim();
+        if (!simbolo)
+            return null;
+        // Misma puerta que la refutacion: en 'prod_db' o 'deployed' el repo no dice
+        // donde vive la afirmacion, asi que apuntar con el grep seria apuntar mal.
+        if (alcanceDelRepo(alert) === "no")
+            return null;
+        if (cacheSimbolo.has(simbolo))
+            return cacheSimbolo.get(simbolo) ?? null;
+        if (grepsRestantes <= 0)
+            return null;
+        grepsRestantes -= 1;
+        const encontrados = ficherosEnRepo(dir, simbolo);
+        cacheSimbolo.set(simbolo, encontrados);
+        return encontrados;
+    };
+    const findings = guardFindings(staged, signals.alerts, signals.filesByModule, (alert) => avisoRefutado(alert, (simbolo) => contarEnRepo(dir, simbolo)), ficherosDelSimbolo);
     const block = mode === "block";
     const message = findingsMessage(findings, block);
     // La consulta del guardián también es una consulta del atlas (QA