@saulwade/swl-ses 2.3.0 → 2.4.1

package/hooks/tdd-gate.js

@@ -1,241 +1,242 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * Hook: tdd-gate.js  (Gate G2 — TDD con evidencia RED)
- * Tipo: PreToolUse  (matcher: Bash)
- *
- * Ante un `git commit` de feature (código fuente + tests en el diff staged),
- * verifica que exista evidencia de ciclo RED en la telemetría de loops
- * (`iteraciones.tsv` dentro de `.planning/loops/tdd-…`, escrita por
- * ejecutar-fase / tdd-workflow). Cierra F-TDD-6 de la Revisión Evolutiva 03:
- * "TDD declarativo sin evidencia — el RED no deja rastro".
- *
- * Modo actual: WARN-ONLY (ADR-0035, decisión D-07 de 10-CONTEXTO.md).
- *   - Emite nudge `kind: tdd-red-evidence`; NUNCA exit 2 en este modo.
- *
- * Alcance deliberado (sin doble nudge ni falsos dominios):
- *   - Solo aplica con FASE ACTIVA (`.planning/locks/fase-activa.json`) — el
- *     enforcement TDD es parte del ciclo GSD, no de commits sueltos.
- *   - Solo cuando el diff staged toca fuente Y tests: el caso "fuente sin
- *     tests" es dominio del gate G3 (calidad-pre-commit) y ya tiene nudge.
- *   - Respeta el opt-out declarado del CONTEXTO (`**TDD**: off — razón: ...`).
- *   - Prefijos exentos: docs:/chore:/style: (mismos que G3).
- *
- * Evidencia RED válida: corrida `tdd-*` cuya `iteraciones.tsv` fue modificada
- * dentro de la ventana (default 24h, `SWL_TDD_GATE_VENTANA_H`) con una fila
- * de estado `baseline` con métrica > 0, o cuya descripción contenga "RED".
- *
- * Opt-out: SWL_TDD_GATE=0 desactiva completamente el hook.
- */
-
-const fs = require('fs');
-const path = require('path');
-const { execFileSync } = require('child_process');
-
-const VENTANA_HORAS_DEFAULT = 24;
-
-/** ¿El comando es un git commit? (ignora git status/log/diff y comandos no-git) */
-function esGitCommit(comando) {
-  if (typeof comando !== 'string') return false;
-  // Cinturón: un comando legítimo de commit no excede unos KB. Acotar evita
-  // costo lineal patológico del regex ante input gigante (hardening, no ReDoS).
-  if (comando.length > 10000) return false;
-  return /\bgit\b[^|&;]*\bcommit\b/.test(comando);
-}
-
-/** Lee el numero de fase activa y verifica el opt-out del CONTEXTO. */
-function estadoTddDeFaseActiva(cwd) {
-  const rutaFaseActiva = path.join(cwd, '.planning', 'locks', 'fase-activa.json');
-  if (!fs.existsSync(rutaFaseActiva)) return { aplica: false, motivo: 'sin-fase-activa' };
-
-  let faseActiva;
-  try {
-    faseActiva = JSON.parse(fs.readFileSync(rutaFaseActiva, 'utf-8'));
-  } catch (_) {
-    return { aplica: false, motivo: 'fase-activa-corrupta' };
-  }
-
-  const numero = Number(faseActiva?.numero);
-  if (!Number.isFinite(numero)) return { aplica: false, motivo: 'fase-activa-sin-numero' };
-
-  const nn = String(numero).padStart(2, '0');
-  const contextoPath = path.join(cwd, '.planning', 'fases', `${nn}-CONTEXTO.md`);
-  if (fs.existsSync(contextoPath)) {
-    try {
-      const contexto = fs.readFileSync(contextoPath, 'utf-8');
-      if (/\*\*TDD\*\*:\s*off/i.test(contexto)) {
-        return { aplica: false, motivo: 'tdd-off-declarado' };
-      }
-    } catch (_) {
-      // CONTEXTO ilegible: asumir TDD on (default)
-    }
-  }
-  return { aplica: true, numero: nn };
-}
-
-/** Archivos staged del repo en cwd (lista vacía si no es repo o falla git). */
-function archivosStaged(cwd) {
-  try {
-    const out = execFileSync('git', ['diff', '--cached', '--name-only'], {
-      cwd,
-      encoding: 'utf8',
-      timeout: 5000,
-    });
-    return out.split('\n').map((l) => l.trim()).filter(Boolean);
-  } catch (_) {
-    return [];
-  }
-}
-
-/**
- * Busca evidencia RED en `.planning/loops/tdd-*` dentro de la ventana.
- * @returns {boolean}
- */
-function hayEvidenciaRed(cwd, ventanaHoras = VENTANA_HORAS_DEFAULT) {
-  const loopsDir = path.join(cwd, '.planning', 'loops');
-  if (!fs.existsSync(loopsDir)) return false;
-
-  let corridas;
-  try {
-    corridas = fs.readdirSync(loopsDir).filter((d) => d.startsWith('tdd-'));
-  } catch (_) {
-    return false;
-  }
-
-  const limite = Date.now() - ventanaHoras * 3600 * 1000;
-
-  for (const corrida of corridas) {
-    const tsvPath = path.join(loopsDir, corrida, 'iteraciones.tsv');
-    let stat;
-    try {
-      stat = fs.statSync(tsvPath);
-    } catch (_) {
-      continue;
-    }
-    if (stat.mtimeMs < limite) continue;
-
-    let contenido;
-    try {
-      contenido = fs.readFileSync(tsvPath, 'utf-8');
-    } catch (_) {
-      continue;
-    }
-
-    for (const linea of contenido.split('\n')) {
-      if (linea.startsWith('#') || linea.startsWith('iteracion')) continue;
-      const cols = linea.split('\t');
-      if (cols.length < 6) continue;
-      const metrica = Number(cols[2]);
-      const estado = (cols[4] || '').trim();
-      const descripcion = cols[5] || '';
-      if ((estado === 'baseline' && metrica > 0) || /\bRED\b/.test(descripcion)) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
-
-/**
- * Decide si el commit amerita advertencia G2.
- * @returns {null | { fuentes: string[], tests: string[] }}
- */
-function evaluarCommit({ cwd, comando, helpers }) {
-  if (!esGitCommit(comando)) return null;
-
-  const mensaje = helpers.extraerMensajeCommit(comando);
-  if (helpers.esPrefijoExentoDeTests(mensaje)) return null;
-
-  const fase = estadoTddDeFaseActiva(cwd);
-  if (!fase.aplica) return null;
-
-  const staged = archivosStaged(cwd);
-  const fuentes = staged.filter(helpers.esArchivoFuente);
-  const tests = staged.filter(helpers.esArchivoTest);
-  // Solo el caso feature-con-tests: "fuente sin tests" es dominio de G3.
-  if (fuentes.length === 0 || tests.length === 0) return null;
-
-  const ventana = Number(process.env.SWL_TDD_GATE_VENTANA_H) || VENTANA_HORAS_DEFAULT;
-  if (hayEvidenciaRed(cwd, ventana)) return null;
-
-  return { fuentes, tests };
-}
-
-function emitirNudge({ cwd, hallazgo }) {
-  let emit;
-  try {
-    ({ emit } = require(path.join(__dirname, 'lib', 'nudge-tracker.js')));
-  } catch (_) {
-    return;
-  }
-  try {
-    const muestra = hallazgo.tests.slice(0, 2).join(', ');
-    emit({
-      kind: 'tdd-red-evidence',
-      target: hallazgo.tests[0],
-      source: 'hooks/tdd-gate.js',
-      message:
-        `Gate G2 (warn): commit de feature con tests (${muestra}) sin evidencia de ciclo ` +
-        `RED en .planning/loops/tdd-*/ — el TDD exige registrar el test fallando ANTES de ` +
-        `implementar (Skill("tdd-workflow") § Evidencia RED en telemetría). Este aviso ` +
-        `calibra la promoción a blocking (ADR-0035). Opt-out: SWL_TDD_GATE=0 o ` +
-        `'**TDD**: off — razón: ...' en el CONTEXTO de la fase.`,
-      data: { fuentes: hallazgo.fuentes, tests: hallazgo.tests, gate: 'G2' },
-      mutation_category: 'optimize',
-      risk_level: 'low',
-    });
-  } catch (_) {
-    // La observabilidad nunca bloquea el trabajo productivo.
-  }
-}
-
-function main() {
-  if (process.env.SWL_TDD_GATE === '0') process.exit(0);
-
-  let hookInput = '';
-  try {
-    hookInput = fs.readFileSync(0, 'utf-8');
-  } catch (_) {
-    process.exit(0);
-  }
-
-  let evento;
-  try {
-    evento = JSON.parse(hookInput);
-  } catch (_) {
-    process.exit(0);
-  }
-
-  if (evento?.tool_name !== 'Bash') process.exit(0);
-  const comando = evento?.tool_input?.command;
-  const cwd = process.cwd();
-
-  // Zero-config: sin .planning/ no hay ciclo GSD que vigilar.
-  if (!fs.existsSync(path.join(cwd, '.planning'))) process.exit(0);
-
-  let helpers;
-  try {
-    helpers = require(path.join(__dirname, 'calidad-pre-commit.js'));
-  } catch (_) {
-    process.exit(0);
-  }
-
-  let hallazgo = null;
-  try {
-    hallazgo = evaluarCommit({ cwd, comando, helpers });
-  } catch (_) {
-    process.exit(0);
-  }
-
-  if (hallazgo) emitirNudge({ cwd, hallazgo });
-
-  // WARN-ONLY (ADR-0035): jamás exit 2 en este modo.
-  process.exit(0);
-}
-
-if (require.main === module) {
-  main();
-}
-
-module.exports = { esGitCommit, estadoTddDeFaseActiva, hayEvidenciaRed, evaluarCommit };
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: tdd-gate.js  (Gate G2 — TDD con evidencia RED)
+ * Tipo: PreToolUse  (matcher: Bash)
+ *
+ * Ante un `git commit` de feature (código fuente + tests en el diff staged),
+ * verifica que exista evidencia de ciclo RED en la telemetría de loops
+ * (`iteraciones.tsv` dentro de `.planning/loops/tdd-…`, escrita por
+ * ejecutar-fase / tdd-workflow). Cierra F-TDD-6 de la Revisión Evolutiva 03:
+ * "TDD declarativo sin evidencia — el RED no deja rastro".
+ *
+ * Modo actual: WARN-ONLY (ADR-0035, decisión D-07 de 10-CONTEXTO.md).
+ *   - Emite nudge `kind: tdd-red-evidence`; NUNCA exit 2 en este modo.
+ *
+ * Alcance deliberado (sin doble nudge ni falsos dominios):
+ *   - Solo aplica con FASE ACTIVA (`.planning/locks/fase-activa.json`) — el
+ *     enforcement TDD es parte del ciclo GSD, no de commits sueltos.
+ *   - Solo cuando el diff staged toca fuente Y tests: el caso "fuente sin
+ *     tests" es dominio del gate G3 (calidad-pre-commit) y ya tiene nudge.
+ *   - Respeta el opt-out declarado del CONTEXTO (`**TDD**: off — razón: ...`).
+ *   - Prefijos exentos: docs:/chore:/style: (mismos que G3).
+ *
+ * Evidencia RED válida: corrida `tdd-*` cuya `iteraciones.tsv` fue modificada
+ * dentro de la ventana (default 24h, `SWL_TDD_GATE_VENTANA_H`) con una fila
+ * de estado `baseline` con métrica > 0, o cuya descripción contenga "RED".
+ *
+ * Opt-out: SWL_TDD_GATE=0 desactiva completamente el hook.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const VENTANA_HORAS_DEFAULT = 24;
+
+/** ¿El comando es un git commit? (ignora git status/log/diff y comandos no-git) */
+function esGitCommit(comando) {
+  if (typeof comando !== 'string') return false;
+  // Cinturón: un comando legítimo de commit no excede unos KB. Acotar evita
+  // costo lineal patológico del regex ante input gigante (hardening, no ReDoS).
+  if (comando.length > 10000) return false;
+  return /\bgit\b[^|&;]*\bcommit\b/.test(comando);
+}
+
+/** Lee el numero de fase activa y verifica el opt-out del CONTEXTO. */
+function estadoTddDeFaseActiva(cwd) {
+  const rutaFaseActiva = path.join(cwd, '.planning', 'locks', 'fase-activa.json');
+  if (!fs.existsSync(rutaFaseActiva)) return { aplica: false, motivo: 'sin-fase-activa' };
+
+  let faseActiva;
+  try {
+    faseActiva = JSON.parse(fs.readFileSync(rutaFaseActiva, 'utf-8'));
+  } catch (_) {
+    return { aplica: false, motivo: 'fase-activa-corrupta' };
+  }
+
+  const numero = Number(faseActiva?.numero);
+  if (!Number.isFinite(numero)) return { aplica: false, motivo: 'fase-activa-sin-numero' };
+
+  const nn = String(numero).padStart(2, '0');
+  const contextoPath = path.join(cwd, '.planning', 'fases', `${nn}-CONTEXTO.md`);
+  if (fs.existsSync(contextoPath)) {
+    try {
+      const contexto = fs.readFileSync(contextoPath, 'utf-8');
+      if (/\*\*TDD\*\*:\s*off/i.test(contexto)) {
+        return { aplica: false, motivo: 'tdd-off-declarado' };
+      }
+    } catch (_) {
+      // CONTEXTO ilegible: asumir TDD on (default)
+    }
+  }
+  return { aplica: true, numero: nn };
+}
+
+/** Archivos staged del repo en cwd (lista vacía si no es repo o falla git). */
+function archivosStaged(cwd) {
+  try {
+    const out = execFileSync('git', ['diff', '--cached', '--name-only'], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    return out.split('\n').map((l) => l.trim()).filter(Boolean);
+  } catch (_) {
+    return [];
+  }
+}
+
+/**
+ * Busca evidencia RED en `.planning/loops/tdd-*` dentro de la ventana.
+ * @returns {boolean}
+ */
+function hayEvidenciaRed(cwd, ventanaHoras = VENTANA_HORAS_DEFAULT) {
+  const loopsDir = path.join(cwd, '.planning', 'loops');
+  if (!fs.existsSync(loopsDir)) return false;
+
+  let corridas;
+  try {
+    corridas = fs.readdirSync(loopsDir).filter((d) => d.startsWith('tdd-'));
+  } catch (_) {
+    return false;
+  }
+
+  const limite = Date.now() - ventanaHoras * 3600 * 1000;
+
+  for (const corrida of corridas) {
+    const tsvPath = path.join(loopsDir, corrida, 'iteraciones.tsv');
+    let stat;
+    try {
+      stat = fs.statSync(tsvPath);
+    } catch (_) {
+      continue;
+    }
+    if (stat.mtimeMs < limite) continue;
+
+    let contenido;
+    try {
+      contenido = fs.readFileSync(tsvPath, 'utf-8');
+    } catch (_) {
+      continue;
+    }
+
+    for (const linea of contenido.split('\n')) {
+      if (linea.startsWith('#') || linea.startsWith('iteracion')) continue;
+      const cols = linea.split('\t');
+      if (cols.length < 6) continue;
+      const metrica = Number(cols[2]);
+      const estado = (cols[4] || '').trim();
+      const descripcion = cols[5] || '';
+      if ((estado === 'baseline' && metrica > 0) || /\bRED\b/.test(descripcion)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Decide si el commit amerita advertencia G2.
+ * @returns {null | { fuentes: string[], tests: string[] }}
+ */
+function evaluarCommit({ cwd, comando, helpers }) {
+  if (!esGitCommit(comando)) return null;
+
+  const mensaje = helpers.extraerMensajeCommit(comando);
+  if (helpers.esPrefijoExentoDeTests(mensaje)) return null;
+
+  const fase = estadoTddDeFaseActiva(cwd);
+  if (!fase.aplica) return null;
+
+  const staged = archivosStaged(cwd);
+  const fuentes = staged.filter(helpers.esArchivoFuente);
+  const tests = staged.filter(helpers.esArchivoTest);
+  // Solo el caso feature-con-tests: "fuente sin tests" es dominio de G3.
+  if (fuentes.length === 0 || tests.length === 0) return null;
+
+  const ventana = Number(process.env.SWL_TDD_GATE_VENTANA_H) || VENTANA_HORAS_DEFAULT;
+  if (hayEvidenciaRed(cwd, ventana)) return null;
+
+  return { fuentes, tests };
+}
+
+function emitirNudge({ cwd, hallazgo }) {
+  let emit;
+  try {
+    ({ emit } = require(path.join(__dirname, 'lib', 'nudge-tracker.js')));
+  } catch (_) {
+    return;
+  }
+  try {
+    const muestra = hallazgo.tests.slice(0, 2).join(', ');
+    emit({
+      kind: 'tdd-red-evidence',
+      target: hallazgo.tests[0],
+      source: 'hooks/tdd-gate.js',
+      message:
+        `Gate G2 (warn): commit de feature con tests (${muestra}) sin evidencia de ciclo ` +
+        `RED en .planning/loops/tdd-*/ — el TDD exige registrar el test fallando ANTES de ` +
+        `implementar (Skill("tdd-workflow") § Evidencia RED en telemetría). Este aviso ` +
+        `calibra la promoción a blocking (ADR-0035). Opt-out: SWL_TDD_GATE=0 o ` +
+        `'**TDD**: off — razón: ...' en el CONTEXTO de la fase.`,
+      data: { fuentes: hallazgo.fuentes, tests: hallazgo.tests, gate: 'G2' },
+      mutation_category: 'optimize',
+      risk_level: 'low',
+    });
+  } catch (_) {
+    // La observabilidad nunca bloquea el trabajo productivo.
+  }
+}
+
+function main() {
+  if (process.env.SWL_TDD_GATE === '0') process.exit(0);
+
+  let hookInput = '';
+  try {
+    hookInput = fs.readFileSync(0, 'utf-8');
+  } catch (_) {
+    process.exit(0);
+  }
+
+  let evento;
+  try {
+    evento = JSON.parse(hookInput);
+  } catch (_) {
+    process.exit(0);
+  }
+
+  if (evento?.tool_name !== 'Bash') process.exit(0);
+  const comando = evento?.tool_input?.command;
+  const cwd = process.cwd();
+
+  // Zero-config: sin .planning/ no hay ciclo GSD que vigilar.
+  if (!fs.existsSync(path.join(cwd, '.planning'))) process.exit(0);
+
+  let helpers;
+  try {
+    helpers = require(path.join(__dirname, 'calidad-pre-commit.js'));
+  } catch (_) {
+    process.exit(0);
+  }
+
+  let hallazgo = null;
+  try {
+    hallazgo = evaluarCommit({ cwd, comando, helpers });
+  } catch (_) {
+    process.exit(0);
+  }
+
+  if (hallazgo) emitirNudge({ cwd, hallazgo });
+
+  // WARN-ONLY (ADR-0035): jamás exit 2 en este modo.
+  process.exit(0);
+}
+
+// Entrypoint directo o wrapper `node -e "require(...)"` (require.main undefined).
+if (!require.main || require.main === module) {
+  main();
+}
+
+module.exports = { esGitCommit, estadoTddDeFaseActiva, hayEvidenciaRed, evaluarCommit };