@saulwade/swl-ses 1.9.0 → 2.1.0

package/scripts/verificar-trazabilidad.js

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * verificar-trazabilidad.js — Valida la cadena REQ→T→commit→test de una fase (G4).
+ *
+ * Uso:
+ *   node scripts/verificar-trazabilidad.js --fase=10 [--solo-plan] [--json]
+ *
+ * Fuentes:
+ *   - REQ-NN:  `.planning/fases/NN-CONTEXTO.md` § Criterios de aceptación
+ *              (definiciones `**REQ-NN**:` o `REQ-NN:`; los marcados RETIRADO
+ *              se excluyen del universo exigible)
+ *   - T-NN:    `.planning/fases/NN-PLAN.md` — campo `**Verifica REQ**: ...`
+ *              por tarea `### T-NN:`
+ *   - Commits: `git log` — footer `Refs: REQ-NN[, REQ-MM]`
+ *   - Tests:   archivos de test versionados (git ls-files + clasificador de
+ *              calidad-pre-commit) con marker `verifica: REQ-NN`
+ *
+ * Exit codes:
+ *   0 — cadena completa, o CONTEXTO legacy sin REQ-IDs (gracia, con nota)
+ *   1 — huérfanos detectados (REQ sin tarea / sin commit / sin test)
+ *   2 — error de invocación o parseo (fase inexistente, args inválidos)
+ *
+ * `--solo-plan`: valida únicamente la matriz REQ×T (lo usa /swl:aprobar-plan,
+ * donde commits y tests aún no existen).
+ *
+ * Zero-deps. Espejo estructural de verificar-release.js (gates + exit codes).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const LIMITE_COMMITS = 300;
+
+// ─── Parseo de fuentes ──────────────────────────────────────────────────────
+
+/**
+ * Extrae definiciones REQ-NN del CONTEXTO.
+ * Método de verificación por REQ (patrón requirements engineering):
+ *   - default `test` — exige test con marker `verifica: REQ-NN`
+ *   - `(verificación: inspección)` en el criterio — satisfecho por prosa/docs/grep;
+ *     exige tarea y commit, pero NO test automatizado.
+ * @returns {{activos: string[], retirados: string[], metodo: Object<string,string>}}
+ */
+function extraerReqs(contextoTexto) {
+  const activos = new Set();
+  const retirados = new Set();
+  const metodo = {};
+  // Definición: línea con `**REQ-NN**:` o `REQ-NN:` (con bullet opcional).
+  // El criterio puede continuar en líneas siguientes indentadas — se capturan
+  // hasta la próxima definición para detectar la anotación de método.
+  // REQ-NN (legacy) o REQ-NN-MM (namespaceado por fase, DT-IDS-NAMESPACE).
+  // El grupo `(?:-\d{1,3})?` es greedy: en `REQ-12-01` captura el ID completo,
+  // nunca el prefijo `REQ-12` truncado.
+  const re = /^\s*(?:[-*]\s*)?\*{0,2}(REQ-\d{1,3}(?:-\d{1,3})?)\*{0,2}\s*:([\s\S]*?)(?=^\s*(?:[-*]\s*)?\*{0,2}REQ-\d|^#|\n\n|$(?![\s\S]))/gm;
+  let m;
+  while ((m = re.exec(contextoTexto)) !== null) {
+    const cuerpo = m[2];
+    if (/RETIRADO/i.test(cuerpo)) {
+      retirados.add(m[1]);
+      continue;
+    }
+    activos.add(m[1]);
+    metodo[m[1]] = /verificaci[oó]n:\s*inspecci[oó]n/i.test(cuerpo) ? 'inspeccion' : 'test';
+  }
+  return { activos: [...activos], retirados: [...retirados], metodo };
+}
+
+/** Extrae mapa tarea→REQs del PLAN. @returns {Map<string, string[]>} */
+function extraerMatrizPlan(planTexto) {
+  const tareas = new Map();
+  let tareaActual = null;
+  for (const linea of planTexto.split('\n')) {
+    const t = linea.match(/^#{2,4}\s*(T-\d{1,3})\s*:/);
+    if (t) {
+      tareaActual = t[1];
+      if (!tareas.has(tareaActual)) tareas.set(tareaActual, []);
+      continue;
+    }
+    // Solo la línea-campo cuenta (`- **Verifica REQ**: ...` al inicio, bullet
+    // opcional). Una descripción que cite `**Verifica REQ**:` en prosa NO debe
+    // contaminar la matriz ni ocultar huérfanos (ancla `^` obligatoria).
+    if (tareaActual && /^\s*(?:[-*]\s*)?\*\*Verifica REQ\*\*\s*:/i.test(linea)) {
+      const reqs = linea.match(/REQ-\d{1,3}(?:-\d{1,3})?/g) || [];
+      tareas.get(tareaActual).push(...reqs);
+    }
+  }
+  return tareas;
+}
+
+/** Commits con footer `Refs: REQ-NN`. @returns {Map<string, string[]>} REQ → hashes cortos */
+function extraerCommitsConRefs(cwd) {
+  const porReq = new Map();
+  let salida;
+  try {
+    salida = execFileSync(
+      'git',
+      ['log', `-${LIMITE_COMMITS}`, '--format=%h%x00%B%x01'],
+      { cwd, encoding: 'utf8', timeout: 10000 }
+    );
+  } catch (_) {
+    return porReq; // sin repo git o sin commits — el reporte lo refleja como gap
+  }
+  for (const bloque of salida.split('\x01')) {
+    const [hash, cuerpo] = bloque.split('\x00');
+    if (!hash || !cuerpo) continue;
+    const refs = cuerpo.match(/^Refs:\s*(.+)$/m);
+    if (!refs) continue;
+    for (const req of refs[1].match(/REQ-\d{1,3}(?:-\d{1,3})?/g) || []) {
+      if (!porReq.has(req)) porReq.set(req, []);
+      porReq.get(req).push(hash.trim());
+    }
+  }
+  return porReq;
+}
+
+/** Tests con marker `verifica: REQ-NN`. @returns {Map<string, string[]>} REQ → archivos */
+function extraerTestsConMarker(cwd) {
+  const porReq = new Map();
+  let esArchivoTest;
+  try {
+    ({ esArchivoTest } = require(path.join(__dirname, '..', 'hooks', 'calidad-pre-commit.js')));
+  } catch (_) {
+    esArchivoTest = (r) => /\.(test|spec)\.[jt]sx?$/.test(r) || /test_.*\.py$/.test(r);
+  }
+
+  let archivos = [];
+  try {
+    archivos = execFileSync('git', ['ls-files'], { cwd, encoding: 'utf8', timeout: 10000 })
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean)
+      .filter(esArchivoTest);
+  } catch (_) {
+    return porReq;
+  }
+
+  for (const archivo of archivos) {
+    let contenido;
+    try {
+      contenido = fs.readFileSync(path.join(cwd, archivo), 'utf-8');
+    } catch (_) {
+      continue;
+    }
+    for (const m of contenido.matchAll(/verifica:\s*(REQ-\d{1,3}(?:-\d{1,3})?)/g)) {
+      const req = m[1];
+      if (!porReq.has(req)) porReq.set(req, []);
+      if (!porReq.get(req).includes(archivo)) porReq.get(req).push(archivo);
+    }
+  }
+  return porReq;
+}
+
+// ─── Validación ─────────────────────────────────────────────────────────────
+
+function validarFase({ cwd, fase, soloPlan }) {
+  const nn = String(Number(fase)).padStart(2, '0');
+  const contextoPath = path.join(cwd, '.planning', 'fases', `${nn}-CONTEXTO.md`);
+  if (!fs.existsSync(contextoPath)) {
+    return { error: `No existe ${path.relative(cwd, contextoPath)}`, exit: 2 };
+  }
+
+  const { activos, retirados, metodo } = extraerReqs(fs.readFileSync(contextoPath, 'utf-8'));
+  if (activos.length === 0) {
+    return {
+      fase: nn,
+      legacy: true,
+      nota: 'CONTEXTO sin REQ-IDs — trazabilidad no exigible (gracia legacy, fases pre-10)',
+      exit: 0,
+    };
+  }
+
+  const planPath = path.join(cwd, '.planning', 'fases', `${nn}-PLAN.md`);
+  const matrizTareas = fs.existsSync(planPath)
+    ? extraerMatrizPlan(fs.readFileSync(planPath, 'utf-8'))
+    : new Map();
+
+  const reqATareas = new Map(activos.map((r) => [r, []]));
+  const tareasSinReq = [];
+  for (const [tarea, reqs] of matrizTareas) {
+    if (reqs.length === 0) tareasSinReq.push(tarea);
+    for (const req of reqs) {
+      if (reqATareas.has(req)) reqATareas.get(req).push(tarea);
+    }
+  }
+
+  const commits = soloPlan ? new Map() : extraerCommitsConRefs(cwd);
+  const tests = soloPlan ? new Map() : extraerTestsConMarker(cwd);
+
+  const validaciones = {
+    req_sin_tarea: activos.filter((r) => (reqATareas.get(r) || []).length === 0),
+    req_sin_commit: soloPlan ? [] : activos.filter((r) => !(commits.get(r) || []).length),
+    req_sin_test: soloPlan
+      ? []
+      : activos.filter((r) => metodo[r] === 'test' && !(tests.get(r) || []).length),
+    tarea_sin_req: tareasSinReq, // informativo, no rompe
+  };
+
+  const trazabilidad = {};
+  for (const req of activos) {
+    trazabilidad[req] = {
+      metodo: metodo[req],
+      tareas: reqATareas.get(req) || [],
+      commits: commits.get(req) || [],
+      tests: tests.get(req) || [],
+    };
+  }
+
+  const huerfanos =
+    validaciones.req_sin_tarea.length +
+    validaciones.req_sin_commit.length +
+    validaciones.req_sin_test.length;
+
+  return {
+    fase: nn,
+    legacy: false,
+    soloPlan: Boolean(soloPlan),
+    reqs: activos,
+    retirados,
+    trazabilidad,
+    validaciones,
+    exit: huerfanos > 0 ? 1 : 0,
+  };
+}
+
+// ─── Reporte ────────────────────────────────────────────────────────────────
+
+function imprimirReporte(r) {
+  if (r.error) {
+    console.error(`ERROR: ${r.error}`);
+    return;
+  }
+  if (r.legacy) {
+    console.log(`Fase ${r.fase}: ${r.nota}. Exit 0.`);
+    return;
+  }
+  console.log(`Trazabilidad REQ→T→commit→test — Fase ${r.fase}${r.soloPlan ? ' (--solo-plan: matriz REQ×T)' : ''}`);
+  console.log('');
+  for (const req of r.reqs) {
+    const t = r.trazabilidad[req];
+    const partes = [`tareas: ${t.tareas.join(', ') || '—'}`];
+    if (!r.soloPlan) {
+      partes.push(`commits: ${t.commits.join(', ') || '—'}`);
+      partes.push(t.metodo === 'inspeccion' ? 'verificación: inspección' : `tests: ${t.tests.join(', ') || '—'}`);
+    }
+    console.log(`  ${req} → ${partes.join(' | ')}`);
+  }
+  if (r.retirados.length) console.log(`  Retirados (no exigibles): ${r.retirados.join(', ')}`);
+  console.log('');
+
+  const v = r.validaciones;
+  const gaps = [];
+  if (v.req_sin_tarea.length) gaps.push(`REQ sin tarea: ${v.req_sin_tarea.join(', ')}`);
+  if (v.req_sin_commit.length) gaps.push(`REQ sin commit (footer Refs:): ${v.req_sin_commit.join(', ')}`);
+  if (v.req_sin_test.length) gaps.push(`REQ sin test (marker verifica:): ${v.req_sin_test.join(', ')}`);
+
+  if (gaps.length) {
+    console.log('HUÉRFANOS DETECTADOS:');
+    for (const g of gaps) console.log(`  ✗ ${g}`);
+  } else {
+    console.log('✓ Cadena de trazabilidad completa: 0 huérfanos.');
+  }
+  if (v.tarea_sin_req.length) {
+    console.log(`  (info) Tareas sin REQ declarado: ${v.tarea_sin_req.join(', ')} — válido para infraestructura/refactor`);
+  }
+}
+
+// ─── CLI ────────────────────────────────────────────────────────────────────
+
+function main() {
+  const args = process.argv.slice(2);
+  const faseArg = args.find((a) => a.startsWith('--fase='));
+  if (!faseArg || !/^\d+$/.test(faseArg.split('=')[1] || '')) {
+    console.error('Uso: node scripts/verificar-trazabilidad.js --fase=N [--solo-plan] [--json]');
+    process.exit(2);
+  }
+
+  const resultado = validarFase({
+    cwd: process.cwd(),
+    fase: faseArg.split('=')[1],
+    soloPlan: args.includes('--solo-plan'),
+  });
+
+  if (args.includes('--json')) {
+    console.log(JSON.stringify(resultado, null, 2));
+  } else {
+    imprimirReporte(resultado);
+  }
+  process.exit(resultado.exit);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { extraerReqs, extraerMatrizPlan, extraerCommitsConRefs, extraerTestsConMarker, validarFase };