changebook 0.4.10 → 0.6.0

package/dist/guard.js

@@ -14,8 +14,10 @@
  */
 import * as fs from "node:fs";
 import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { execFileAsync, gitPath, projectNameFor } from "./git.js";
 import { feedWarningFor } from "./feed.js";
+import { avisoDeRamaPara } from "./rama.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
@@ -308,7 +310,11 @@ export function dondeApareceElSimbolo(alert, buscarFicheros) {
  */
 export function guardFindings(staged, alerts, filesByModule, refutado, ficherosDelSimbolo) {
     const stagedSet = new Set(staged);
-    const seen = new Set();
+    // Map y no Set: al colapsar dos avisos con el mismo (modulo, texto) hay que
+    // QUEDARSE con los dos ids, no descartar el segundo. Se sirve una linea —dos
+    // frases identicas no dejan actuar distinto— pero se registran las dos
+    // alertas, que es lo que permitira atribuir el veredicto a la que toca.
+    const porClave = new Map();
     const findings = [];
     for (const alert of alerts) {
         const module = (alert.module ?? "").trim();
@@ -332,10 +338,22 @@ export function guardFindings(staged, alerts, filesByModule, refutado, ficherosD
         if (refutado?.(alert))
             continue;
         const key = module + "\u0000" + plain;
-        if (seen.has(key))
+        const id = alert.id ?? null;
+        const ya = porClave.get(key);
+        if (ya) {
+            // El aviso ya se sirve; lo unico que queda por recoger es su identidad.
+            if (id && !ya.alertIds.includes(id))
+                ya.alertIds.push(id);
             continue;
-        seen.add(key);
-        findings.push({ module, plain, staged: touched });
+        }
+        const finding = {
+            module,
+            plain,
+            staged: touched,
+            alertIds: id ? [id] : [],
+        };
+        porClave.set(key, finding);
+        findings.push(finding);
     }
     return findings;
 }
@@ -403,6 +421,16 @@ function grepDelRepo(dir, simbolo, modo) {
             // aviso de tipo "esto sigue usandose" encontraria su propia cita y no
             // podria refutarse jamas. Lo cazo el test, no el diseno.
             ":!*.md",
+            // Y tampoco en el resto de la PROSA, por la misma razon exacta. El
+            // 2026-07-30, usando el producto sobre si mismo, un aviso sobre
+            // `reason` se sirvio diciendo «still appears in privacidad.html,
+            // terminos.html» — la comprobacion encontro la PALABRA en dos paginas
+            // legales y la presento como si hablara del codigo. Un simbolo en un
+            // parrafo no es una referencia: es una coincidencia de idioma.
+            ":!*.html",
+            ":!*.txt",
+            ":!*.csv",
+            ":!*.svg",
             // Con comodín a propósito: un pathspec sin comodín ("docs/") hace
             // abortar a git grep si la carpeta no existe — en cualquier repo de
             // usuario sin docs/ el buscador devolvía null y la refutación moría
@@ -417,6 +445,23 @@ function grepDelRepo(dir, simbolo, modo) {
         return code === 1 ? "" : null;
     }
 }
+/**
+ * LA VERSIÓN DE LA FORMA DE LA CACHÉ. Súbela cuando cambie QUÉ se guarda —las
+ * columnas del select, un campo del que dependa una decisión—, no cuando cambie
+ * el código de alrededor.
+ *
+ * El caso concreto que la trae: el commit anterior añadió `evidence_scope` al
+ * select de las alertas. Sin versión, la caché escrita por el binario de antes
+ * se deserializa sin error y el guardián decide sobre ella cinco minutos más,
+ * con el ámbito ausente — o sea, sin refutar nada. Y no hay forma de notarlo: la
+ * caché vieja no está rota, solo incompleta, así que el guardián se calla en vez
+ * de fallar. Mismo modo de fallo que la caché de `{project_id: null}` que costó
+ * cinco minutos de silencio el 2026-07-26.
+ *
+ * Empieza en 1: una caché SIN `v` es anterior al versionado y se descarta
+ * siempre.
+ */
+const GUARD_CACHE_V = 1;
 export async function stagedFiles(dir) {
     // -z: NUL-separated, and crucially git does NOT octal-quote non-ASCII paths
     // (default quotepath would emit "m\303\263dulo.ts", which never matches the
@@ -425,12 +470,25 @@ export async function stagedFiles(dir) {
     const { stdout } = await execFileAsync("git", ["diff", "--cached", "--name-only", "-z"], { cwd: dir, encoding: "utf8" });
     return stdout.split("\0").filter(Boolean);
 }
+/**
+ * ¿Se puede decidir sobre esta caché? De esta forma Y fresca.
+ *
+ * Otra forma → se trata como si no hubiera caché: se vuelve a consultar. El
+ * guardián ya sabe hacer eso (es el camino en frío), así que descartar no añade
+ * ningún modo de fallo nuevo. Pura y exportada porque lo que evita —decidir
+ * sobre campos que no están— no se ve desde fuera: la caché vieja no está rota.
+ */
+export function cacheDelGuardianServible(cache, ahora) {
+    if (!cache)
+        return false;
+    if (cache.v !== GUARD_CACHE_V)
+        return false;
+    return ahora - cache.fetched_at <= CACHE_TTL_MS;
+}
 function loadCache(file) {
     try {
         const cache = JSON.parse(fs.readFileSync(file, "utf8"));
-        if (Date.now() - cache.fetched_at > CACHE_TTL_MS)
-            return null;
-        return cache;
+        return cacheDelGuardianServible(cache, Date.now()) ? cache : null;
     }
     catch {
         return null;
@@ -461,7 +519,17 @@ async function fetchSignals(db, dir, env) {
     let filesByModule = new Map();
     const projectId = projects[0]?.id ?? null;
     if (projectId) {
-        alerts = await db.rest(`regression_alerts?select=module,plain,created_at,evidence_symbol,evidence_expect,files&project_id=eq.${projectId}&resolved_at=is.null&order=created_at.desc&limit=${MAX_ALERTS}`);
+        alerts = await db.rest(
+        // `evidence_scope` NO es opcional aquí, por mucho que el tipo lo sea: sin
+        // él, `alcanceDelRepo` devuelve "sin_declarar" para TODA alerta y la
+        // refutación de `avisoRefutado` no descarta nada nunca. El campo se
+        // escribe en la base desde el 2026-07-26 y ningún cliente lo pedía; el
+        // comentario de `avisoRefutado` decía que esa rama "disparó 0 veces en
+        // producción", y disparó cero porque el dato no llegaba, no porque el gate
+        // fuera barato. Lo vigila `test/alcanceLlegaAlCliente.test.ts`, que lee
+        // ESTA línea: un test de comportamiento no lo caza, porque los stubs
+        // inyectan el campo a mano.
+        `regression_alerts?select=id,module,plain,created_at,evidence_symbol,evidence_expect,evidence_scope,evidence_line,files&project_id=eq.${projectId}&resolved_at=is.null&order=created_at.desc&limit=${MAX_ALERTS}`);
         const modules = [
             ...new Set(alerts.map((a) => (a.module ?? "").trim()).filter(Boolean)),
         ];
@@ -472,6 +540,7 @@ async function fetchSignals(db, dir, env) {
     }
     if (cacheFile) {
         const cache = {
+            v: GUARD_CACHE_V,
             fetched_at: Date.now(),
             project_id: projectId,
             alerts,
@@ -536,6 +605,71 @@ export function findingsMessage(findings, block) {
         : "\nReview or dismiss the alert in your atlas: changebook open\n");
     return lines.join("\n");
 }
+/** Tope de rutas por fila: un registro no puede crecer sin limite por un commit gigante. */
+const MAX_FICHEROS_EN_LA_ENTREGA = 50;
+/**
+ * EL NUCLEO, sin la forma del guardian.
+ *
+ * Existe porque hay DOS canales que sirven avisos —el guardian en el commit y el
+ * hook antes de editar— y el libro tiene que registrar lo mismo en los dos. Si
+ * cada uno armara su fila, el tope de ficheros o el dedup de ids podrian
+ * divergir y "en total" empezaria a significar dos cosas distintas segun el
+ * canal. Un criterio, un sitio.
+ *
+ * `message` es lo que de verdad se sirvio, no un resumen: el hash ata la fila al
+ * texto exacto que se imprimio, y eso es lo que impide reescribir el consejo a
+ * posteriori para que parezca que acerto.
+ */
+export function entregaDe(input) {
+    if (input.message.trim().length === 0)
+        return null;
+    const alertIds = [
+        ...new Set(input.alertIds.filter((id) => typeof id === "string" && id.length > 0)),
+    ];
+    return {
+        advice_hash: input.hash(input.message),
+        alert_ids: alertIds,
+        advice_files: [...new Set(input.files)].slice(0, MAX_FICHEROS_EN_LA_ENTREGA),
+        head_sha: input.headSha,
+    };
+}
+export function entregaDeAviso(findings, message, headSha, hash) {
+    if (findings.length === 0)
+        return null;
+    return entregaDe({
+        // flatMap y no map: un finding puede venir de varias alertas colapsadas por
+        // texto (ver GuardFinding.alertIds). El Set de `entregaDe` quita ademas el
+        // mismo aviso servido por dos rutas, que es otra cosa.
+        alertIds: findings.flatMap((f) => f.alertIds),
+        files: findings.flatMap((f) => f.staged),
+        message,
+        headSha,
+        hash,
+    });
+}
+/** sha256 en hex. Aparte para que `entregaDeAviso` se pueda probar sin crypto. */
+export function hashDelTexto(texto) {
+    return createHash("sha256").update(texto, "utf8").digest("hex");
+}
+/**
+ * El commit en el que esta el repo. `null` si no se puede saber — y ese null se
+ * guarda tal cual: un ancla inventada es peor que ninguna. Repo recien creado
+ * sin commits incluido, que es el caso que devuelve error de verdad.
+ */
+export function headShaDe(dir) {
+    try {
+        const salida = execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd: dir,
+            encoding: "utf8",
+            timeout: 1_000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return /^[0-9a-f]{7,40}$/.test(salida) ? salida : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Returns the process exit code. Everything that can go wrong resolves to 0
  * (pass): the guard informs, it does not gatekeep — except when the user
@@ -553,6 +687,13 @@ export async function runGuard(db, dir, env = process.env) {
     const pulse = await feedWarningFor(dir);
     if (pulse)
         console.error(pulse);
+    // ANTES del corte por credenciales a proposito: que tu rama vaya a revertir el
+    // trabajo de otro es un hecho de git, no del atlas. Quien no tenga sesion —o
+    // no tenga cuenta— tambien merece enterarse. Ver rama.ts para el porque de la
+    // señal (solapamiento, no "vas atrasado").
+    const rama = await avisoDeRamaPara(dir);
+    if (rama)
+        console.error(rama);
     if (!db.hasCredentials())
         return 0;
     let staged;
@@ -635,6 +776,9 @@ export async function runGuard(db, dir, env = process.env) {
                 tool: "guard_precommit",
                 source: "guard",
                 chars_served: message.length,
+                // El libro de entregas. Solo viaja cuando de verdad se avisó: una
+                // corrida limpia sigue siendo una fila normal, purgable como siempre.
+                ...(entregaDeAviso(findings, message, headShaDe(dir), hashDelTexto) ?? {}),
             })
                 .catch(() => { }),
             new Promise((resolve) => {