@saulwade/swl-ses 2.2.4 → 2.3.1

package/hooks/spec-gate.js

@@ -1,211 +1,211 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * Hook: spec-gate.js  (Gate G0 — SDD)
- * Tipo: PreToolUse  (matcher: Write|Edit|MultiEdit)
- *
- * Detecta escrituras de CÓDIGO FUENTE sin fase activa con PLAN aprobado.
- * Implementa el gate G0 del flujo SPEC→PLAN→TEST→CODE→VERIFY (Revisión
- * Evolutiva 03 §5.2): "ningún Write/Edit a código fuente sin fase activa
- * con PLAN aprobado".
- *
- * Modo actual: WARN-ONLY (ADR-0034, decisión D-07 de 10-CONTEXTO.md).
- *   - Emite nudge `kind: spec-gate` a .planning/evolution/nudges.jsonl.
- *   - NUNCA exit 2. La promoción a blocking se decide vía ADR tras ~2
- *     semanas de calibración sin falsos positivos (patrón ADR-0027→0033).
- *
- * Concepto "fase activa": `.planning/locks/fase-activa.json`, escrito por
- * /swl:aprobar-plan al firmar un plan y eliminado por /swl:ejecutar-fase al
- * cerrar la fase. Formato:
- *   { numero, planPath, sha256, aprobadoEn, aprobadoPor }
- * El hook re-computa el SHA256 del plan referenciado y lo compara con el del
- * archivo de fase activa — verificación autocontenida (sin dependencia de
- * scripts/lib/, que puede no estar distribuido en proyectos destino).
- *
- * Zero-config: en proyectos sin `.planning/` el hook sale 0 sin ruido.
- * Opt-out: SWL_SPEC_GATE=0 desactiva completamente el hook.
- *
- * Modelo de amenaza (heredado de plan-lock.js): detecta omisión accidental
- * del ciclo GSD y mutación post-firma; NO resiste a un adversario con
- * escritura al repo (puede regenerar fase-activa.json).
- */
-
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-const RUTAS_EXCLUIDAS = [
-  '/temp/',
-  '/node_modules/',
-  '/respositorios-git/',
-  '/_userland/',
-  '/.planning/',
-  '/.claude/',
-];
-
-/**
- * Clasificador de código fuente. Reutiliza esArchivoFuente() de
- * calidad-pre-commit.js (misma definición que el gate G3) con fallback
- * defensivo si el módulo no está disponible en el destino.
- */
-function cargarClasificador() {
-  try {
-    const calidad = require(path.join(__dirname, 'calidad-pre-commit.js'));
-    if (typeof calidad.esArchivoFuente === 'function') return calidad.esArchivoFuente;
-  } catch (_) {
-    // Fallback mínimo: extensiones de código de los lenguajes soportados,
-    // excluyendo tests por sufijo/directorio.
-  }
-  return function esArchivoFuenteFallback(ruta) {
-    const normal = ruta.replace(/\\/g, '/');
-    if (/\.(test|spec)\.[jt]sx?$/.test(normal)) return false;
-    if (/(^|\/)(tests?|__tests__|spec)\//.test(normal)) return false;
-    if (/\.(md|json|ya?ml|toml|ini|cfg|conf|txt|svg|lock)$/i.test(normal)) return false;
-    return /\.(jsx?|tsx?|py|go|rs|java|kt|cs|rb|php|swift|c|cc|cpp|h|hpp)$/i.test(normal);
-  };
-}
-
-/**
- * Evalúa el estado de la fase activa del proyecto en `cwd`.
- * @returns {{ ok: boolean, motivo: string|null, numero?: number }}
- *   ok=true  → hay fase activa con plan íntegro (no advertir)
- *   ok=false → motivo describe por qué no hay cobertura de spec
- */
-function evaluarFaseActiva(cwd) {
-  const rutaFaseActiva = path.join(cwd, '.planning', 'locks', 'fase-activa.json');
-  if (!fs.existsSync(rutaFaseActiva)) {
-    return { ok: false, motivo: 'sin fase activa (no existe .planning/locks/fase-activa.json)' };
-  }
-
-  let faseActiva;
-  try {
-    faseActiva = JSON.parse(fs.readFileSync(rutaFaseActiva, 'utf-8'));
-  } catch (_) {
-    return { ok: false, motivo: 'fase-activa.json corrupto (JSON inválido)' };
-  }
-
-  if (!faseActiva || typeof faseActiva.planPath !== 'string' || typeof faseActiva.sha256 !== 'string') {
-    return { ok: false, motivo: 'fase-activa.json sin planPath/sha256' };
-  }
-
-  const planAbs = path.isAbsolute(faseActiva.planPath)
-    ? faseActiva.planPath
-    : path.join(cwd, faseActiva.planPath);
-
-  if (!fs.existsSync(planAbs)) {
-    return { ok: false, motivo: `el plan de la fase activa no existe (${faseActiva.planPath})` };
-  }
-
-  let hashActual;
-  try {
-    hashActual = crypto.createHash('sha256').update(fs.readFileSync(planAbs)).digest('hex');
-  } catch (_) {
-    return { ok: false, motivo: 'no se pudo leer el plan de la fase activa' };
-  }
-
-  if (hashActual !== faseActiva.sha256) {
-    return {
-      ok: false,
-      motivo: `el plan de la fase activa fue mutado tras la firma (${faseActiva.planPath})`,
-      numero: faseActiva.numero,
-    };
-  }
-
-  return { ok: true, motivo: null, numero: faseActiva.numero };
-}
-
-/**
- * Decide si la escritura amerita advertencia G0.
- * @returns {null | { motivo: string }}  null = silencio
- */
-function evaluarEscritura({ cwd, toolName, filePath, esArchivoFuente }) {
-  if (!toolName || !['Write', 'Edit', 'MultiEdit'].includes(toolName)) return null;
-  if (!filePath) return null;
-
-  // Zero-config: sin .planning/ no hay ciclo GSD que vigilar.
-  if (!fs.existsSync(path.join(cwd, '.planning'))) return null;
-
-  const normal = filePath.replace(/\\/g, '/');
-  if (RUTAS_EXCLUIDAS.some((ex) => normal.includes(ex))) return null;
-  if (!esArchivoFuente(normal)) return null;
-
-  const fase = evaluarFaseActiva(cwd);
-  if (fase.ok) return null;
-
-  return { motivo: fase.motivo };
-}
-
-function emitirNudge({ cwd, filePath, motivo }) {
-  const rutaRelativa = path.relative(cwd, filePath).replace(/\\/g, '/');
-  let emit;
-  try {
-    ({ emit } = require(path.join(__dirname, 'lib', 'nudge-tracker.js')));
-  } catch (_) {
-    return;
-  }
-  try {
-    emit({
-      kind: 'spec-gate',
-      target: rutaRelativa,
-      source: 'hooks/spec-gate.js',
-      message:
-        `Gate G0 (warn): escritura de código fuente ${rutaRelativa} ${motivo}. ` +
-        `El flujo SDD espera una fase activa con PLAN aprobado (/swl:aprobar-plan N) ` +
-        `antes de escribir código. Si es un fix trivial o exploración, ignora este aviso ` +
-        `— se usa para calibrar la promoción a blocking (ADR-0034). Opt-out: SWL_SPEC_GATE=0.`,
-      data: { archivo: rutaRelativa, motivo, gate: 'G0' },
-      mutation_category: 'optimize',
-      risk_level: 'low',
-    });
-  } catch (_) {
-    // La observabilidad nunca bloquea el trabajo productivo.
-  }
-}
-
-function main() {
-  if (process.env.SWL_SPEC_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);
-  }
-
-  const cwd = process.cwd();
-  const toolName = evento?.tool_name;
-  const filePath = evento?.tool_input?.file_path;
-
-  let resultado = null;
-  try {
-    resultado = evaluarEscritura({
-      cwd,
-      toolName,
-      filePath,
-      esArchivoFuente: cargarClasificador(),
-    });
-  } catch (_) {
-    process.exit(0);
-  }
-
-  if (resultado) {
-    emitirNudge({ cwd, filePath, motivo: resultado.motivo });
-  }
-
-  // WARN-ONLY (ADR-0034): jamás exit 2 en este modo.
-  process.exit(0);
-}
-
-if (require.main === module) {
-  main();
-}
-
-module.exports = { evaluarFaseActiva, evaluarEscritura, RUTAS_EXCLUIDAS };
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: spec-gate.js  (Gate G0 — SDD)
+ * Tipo: PreToolUse  (matcher: Write|Edit|MultiEdit)
+ *
+ * Detecta escrituras de CÓDIGO FUENTE sin fase activa con PLAN aprobado.
+ * Implementa el gate G0 del flujo SPEC→PLAN→TEST→CODE→VERIFY (Revisión
+ * Evolutiva 03 §5.2): "ningún Write/Edit a código fuente sin fase activa
+ * con PLAN aprobado".
+ *
+ * Modo actual: WARN-ONLY (ADR-0034, decisión D-07 de 10-CONTEXTO.md).
+ *   - Emite nudge `kind: spec-gate` a .planning/evolution/nudges.jsonl.
+ *   - NUNCA exit 2. La promoción a blocking se decide vía ADR tras ~2
+ *     semanas de calibración sin falsos positivos (patrón ADR-0027→0033).
+ *
+ * Concepto "fase activa": `.planning/locks/fase-activa.json`, escrito por
+ * /swl:aprobar-plan al firmar un plan y eliminado por /swl:ejecutar-fase al
+ * cerrar la fase. Formato:
+ *   { numero, planPath, sha256, aprobadoEn, aprobadoPor }
+ * El hook re-computa el SHA256 del plan referenciado y lo compara con el del
+ * archivo de fase activa — verificación autocontenida (sin dependencia de
+ * scripts/lib/, que puede no estar distribuido en proyectos destino).
+ *
+ * Zero-config: en proyectos sin `.planning/` el hook sale 0 sin ruido.
+ * Opt-out: SWL_SPEC_GATE=0 desactiva completamente el hook.
+ *
+ * Modelo de amenaza (heredado de plan-lock.js): detecta omisión accidental
+ * del ciclo GSD y mutación post-firma; NO resiste a un adversario con
+ * escritura al repo (puede regenerar fase-activa.json).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const RUTAS_EXCLUIDAS = [
+  '/temp/',
+  '/node_modules/',
+  '/respositorios-git/',
+  '/_userland/',
+  '/.planning/',
+  '/.claude/',
+];
+
+/**
+ * Clasificador de código fuente. Reutiliza esArchivoFuente() de
+ * calidad-pre-commit.js (misma definición que el gate G3) con fallback
+ * defensivo si el módulo no está disponible en el destino.
+ */
+function cargarClasificador() {
+  try {
+    const calidad = require(path.join(__dirname, 'calidad-pre-commit.js'));
+    if (typeof calidad.esArchivoFuente === 'function') return calidad.esArchivoFuente;
+  } catch (_) {
+    // Fallback mínimo: extensiones de código de los lenguajes soportados,
+    // excluyendo tests por sufijo/directorio.
+  }
+  return function esArchivoFuenteFallback(ruta) {
+    const normal = ruta.replace(/\\/g, '/');
+    if (/\.(test|spec)\.[jt]sx?$/.test(normal)) return false;
+    if (/(^|\/)(tests?|__tests__|spec)\//.test(normal)) return false;
+    if (/\.(md|json|ya?ml|toml|ini|cfg|conf|txt|svg|lock)$/i.test(normal)) return false;
+    return /\.(jsx?|tsx?|py|go|rs|java|kt|cs|rb|php|swift|c|cc|cpp|h|hpp)$/i.test(normal);
+  };
+}
+
+/**
+ * Evalúa el estado de la fase activa del proyecto en `cwd`.
+ * @returns {{ ok: boolean, motivo: string|null, numero?: number }}
+ *   ok=true  → hay fase activa con plan íntegro (no advertir)
+ *   ok=false → motivo describe por qué no hay cobertura de spec
+ */
+function evaluarFaseActiva(cwd) {
+  const rutaFaseActiva = path.join(cwd, '.planning', 'locks', 'fase-activa.json');
+  if (!fs.existsSync(rutaFaseActiva)) {
+    return { ok: false, motivo: 'sin fase activa (no existe .planning/locks/fase-activa.json)' };
+  }
+
+  let faseActiva;
+  try {
+    faseActiva = JSON.parse(fs.readFileSync(rutaFaseActiva, 'utf-8'));
+  } catch (_) {
+    return { ok: false, motivo: 'fase-activa.json corrupto (JSON inválido)' };
+  }
+
+  if (!faseActiva || typeof faseActiva.planPath !== 'string' || typeof faseActiva.sha256 !== 'string') {
+    return { ok: false, motivo: 'fase-activa.json sin planPath/sha256' };
+  }
+
+  const planAbs = path.isAbsolute(faseActiva.planPath)
+    ? faseActiva.planPath
+    : path.join(cwd, faseActiva.planPath);
+
+  if (!fs.existsSync(planAbs)) {
+    return { ok: false, motivo: `el plan de la fase activa no existe (${faseActiva.planPath})` };
+  }
+
+  let hashActual;
+  try {
+    hashActual = crypto.createHash('sha256').update(fs.readFileSync(planAbs)).digest('hex');
+  } catch (_) {
+    return { ok: false, motivo: 'no se pudo leer el plan de la fase activa' };
+  }
+
+  if (hashActual !== faseActiva.sha256) {
+    return {
+      ok: false,
+      motivo: `el plan de la fase activa fue mutado tras la firma (${faseActiva.planPath})`,
+      numero: faseActiva.numero,
+    };
+  }
+
+  return { ok: true, motivo: null, numero: faseActiva.numero };
+}
+
+/**
+ * Decide si la escritura amerita advertencia G0.
+ * @returns {null | { motivo: string }}  null = silencio
+ */
+function evaluarEscritura({ cwd, toolName, filePath, esArchivoFuente }) {
+  if (!toolName || !['Write', 'Edit', 'MultiEdit'].includes(toolName)) return null;
+  if (!filePath) return null;
+
+  // Zero-config: sin .planning/ no hay ciclo GSD que vigilar.
+  if (!fs.existsSync(path.join(cwd, '.planning'))) return null;
+
+  const normal = filePath.replace(/\\/g, '/');
+  if (RUTAS_EXCLUIDAS.some((ex) => normal.includes(ex))) return null;
+  if (!esArchivoFuente(normal)) return null;
+
+  const fase = evaluarFaseActiva(cwd);
+  if (fase.ok) return null;
+
+  return { motivo: fase.motivo };
+}
+
+function emitirNudge({ cwd, filePath, motivo }) {
+  const rutaRelativa = path.relative(cwd, filePath).replace(/\\/g, '/');
+  let emit;
+  try {
+    ({ emit } = require(path.join(__dirname, 'lib', 'nudge-tracker.js')));
+  } catch (_) {
+    return;
+  }
+  try {
+    emit({
+      kind: 'spec-gate',
+      target: rutaRelativa,
+      source: 'hooks/spec-gate.js',
+      message:
+        `Gate G0 (warn): escritura de código fuente ${rutaRelativa} ${motivo}. ` +
+        `El flujo SDD espera una fase activa con PLAN aprobado (/swl:aprobar-plan N) ` +
+        `antes de escribir código. Si es un fix trivial o exploración, ignora este aviso ` +
+        `— se usa para calibrar la promoción a blocking (ADR-0034). Opt-out: SWL_SPEC_GATE=0.`,
+      data: { archivo: rutaRelativa, motivo, gate: 'G0' },
+      mutation_category: 'optimize',
+      risk_level: 'low',
+    });
+  } catch (_) {
+    // La observabilidad nunca bloquea el trabajo productivo.
+  }
+}
+
+function main() {
+  if (process.env.SWL_SPEC_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);
+  }
+
+  const cwd = process.cwd();
+  const toolName = evento?.tool_name;
+  const filePath = evento?.tool_input?.file_path;
+
+  let resultado = null;
+  try {
+    resultado = evaluarEscritura({
+      cwd,
+      toolName,
+      filePath,
+      esArchivoFuente: cargarClasificador(),
+    });
+  } catch (_) {
+    process.exit(0);
+  }
+
+  if (resultado) {
+    emitirNudge({ cwd, filePath, motivo: resultado.motivo });
+  }
+
+  // WARN-ONLY (ADR-0034): jamás exit 2 en este modo.
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { evaluarFaseActiva, evaluarEscritura, RUTAS_EXCLUIDAS };