@saulwade/swl-ses 1.4.1 → 1.5.0

package/scripts/derivar-feature-list.js

@@ -0,0 +1,489 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * derivar-feature-list.js — Sub-fase 5 (Opción B desde análisis cc-sdd)
+ *
+ * Genera `.planning/feature-list.json` como **state machine machine-readable**
+ * derivado del Markdown libre de `.planning/HOJA-RUTA.md` y los PLAN.md/
+ * RESUMEN.md de cada fase en `.planning/fases/`.
+ *
+ * El HOJA-RUTA.md es la fuente de verdad human-friendly; este script produce
+ * una proyección JSON consumible por:
+ *   - `/swl:dashboard` (vista de progreso de fases)
+ *   - `/swl:metricas` (cálculo de velocity, lead time, completitud)
+ *   - Hooks de observabilidad
+ *   - Auditoría externa programática
+ *
+ * NO reemplaza HOJA-RUTA.md. Si entran en conflicto, HOJA-RUTA.md gana —
+ * este JSON es una derivación cache, regenerable.
+ *
+ * Inspirado en `feature_list.json` de harness-sdd-main, adaptado al modelo
+ * por-fase de swl-ses (no por-feature).
+ *
+ * Uso:
+ *   node scripts/derivar-feature-list.js
+ *   node scripts/derivar-feature-list.js --out custom/path.json
+ *   node scripts/derivar-feature-list.js --check       # exit 1 si JSON está stale
+ *   node scripts/derivar-feature-list.js --verbose
+ *
+ * Exit codes:
+ *   0  OK / generado / sincronizado
+ *   1  HOJA-RUTA.md ausente o .planning/ no inicializado
+ *   2  --check detectó drift entre HOJA-RUTA.md y feature-list.json
+ *   3  Error de parsing
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const CWD = process.cwd();
+const PLANNING_DIR = path.join(CWD, '.planning');
+const HOJA_RUTA = path.join(PLANNING_DIR, 'HOJA-RUTA.md');
+const FASES_DIR = path.join(PLANNING_DIR, 'fases');
+const DEFAULT_OUT = path.join(PLANNING_DIR, 'feature-list.json');
+
+const ESTADOS_VALIDOS = new Set([
+  'pendiente',
+  'en_progreso',
+  'spec_listo',
+  'completado',
+  'bloqueado',
+]);
+
+// ─── Parsing del HOJA-RUTA.md ────────────────────────────────────────────────
+
+/**
+ * Extrae fases del HOJA-RUTA.md.
+ *
+ * Reconoce dos formatos:
+ *
+ *  1. Tabla resumen al inicio:
+ *     | Fase | Nombre | Objetivo | Duración estimada | Estado |
+ *     | 1 | Bootstrap | ... | 2 semanas | Completado |
+ *
+ *  2. Secciones detalladas:
+ *     ## Fase N: Nombre
+ *     **Objetivo**: ...
+ *     **Estado**: Pendiente | En progreso | Completado
+ *     **Fecha inicio**: YYYY-MM-DD
+ *     **Fecha fin real**: YYYY-MM-DD
+ *
+ * Si solo existe la tabla, se usa esa. Si existen ambos, las secciones
+ * detalladas ganan (más metadata).
+ */
+function parsearHojaRuta(contenido) {
+  const fases = new Map(); // numero → fase
+
+  // Parsear tabla resumen
+  parsearTablaResumen(contenido, fases);
+
+  // Parsear secciones detalladas (sobreescriben con más detalle)
+  parsearSecciones(contenido, fases);
+
+  return Array.from(fases.values()).sort((a, b) => a.numero - b.numero);
+}
+
+function parsearTablaResumen(contenido, fases) {
+  // Detecta tabla cuyo encabezado contiene "Fase" o "Phase" + "Nombre" + "Estado"
+  const lineas = contenido.split('\n');
+  let enTabla = false;
+  let idxFase = -1;
+  let idxNombre = -1;
+  let idxObjetivo = -1;
+  let idxEstado = -1;
+
+  for (const linea of lineas) {
+    const trim = linea.trim();
+    if (!trim.startsWith('|')) {
+      if (enTabla && trim === '') enTabla = false;
+      continue;
+    }
+
+    const celdas = trim.split('|').map(c => c.trim()).filter(c => c !== '');
+
+    // Detectar header
+    if (idxFase === -1) {
+      const lowered = celdas.map(c => c.toLowerCase());
+      const fa = lowered.findIndex(c => c === 'fase' || c === 'phase' || c === '#');
+      const no = lowered.findIndex(c => c === 'nombre' || c === 'name');
+      const ob = lowered.findIndex(c => c === 'objetivo' || c === 'objective');
+      const es = lowered.findIndex(c => c === 'estado' || c === 'status');
+      if (fa !== -1 && no !== -1 && es !== -1) {
+        idxFase = fa;
+        idxNombre = no;
+        idxObjetivo = ob;
+        idxEstado = es;
+        enTabla = true;
+      }
+      continue;
+    }
+
+    // Línea separadora (|---|---|)
+    if (celdas.every(c => /^-+$/.test(c.replace(/:/g, '')))) continue;
+
+    if (!enTabla) continue;
+
+    const numStr = celdas[idxFase];
+    const numero = parseInt(numStr, 10);
+    if (!Number.isFinite(numero)) continue;
+
+    fases.set(numero, {
+      numero,
+      nombre: celdas[idxNombre] || `Fase ${numero}`,
+      objetivo: idxObjetivo !== -1 ? (celdas[idxObjetivo] || null) : null,
+      estado: normalizarEstado(celdas[idxEstado]),
+      estado_raw: celdas[idxEstado],
+      fecha_inicio: null,
+      fecha_fin_estimada: null,
+      fecha_fin_real: null,
+      entregables: [],
+      criterios_verificacion: [],
+      fuente: 'tabla-resumen',
+    });
+  }
+}
+
+function parsearSecciones(contenido, fases) {
+  // ## Fase N: Nombre  o  ## Fase N — Nombre
+  const reFase = /^##\s+Fase\s+(\d+)\s*[:\-—–]\s*(.+?)$/gm;
+  const matches = [...contenido.matchAll(reFase)];
+
+  for (let i = 0; i < matches.length; i++) {
+    const m = matches[i];
+    const numero = parseInt(m[1], 10);
+    const nombre = m[2].trim();
+    const inicio = m.index + m[0].length;
+    const fin = i + 1 < matches.length ? matches[i + 1].index : contenido.length;
+    const seccion = contenido.slice(inicio, fin);
+
+    const existente = fases.get(numero) || {
+      numero,
+      nombre,
+      objetivo: null,
+      estado: 'pendiente',
+      estado_raw: 'Pendiente',
+      fecha_inicio: null,
+      fecha_fin_estimada: null,
+      fecha_fin_real: null,
+      entregables: [],
+      criterios_verificacion: [],
+      fuente: 'seccion-detallada',
+    };
+
+    existente.nombre = nombre || existente.nombre;
+    existente.fuente = 'seccion-detallada';
+
+    const objetivo = extraerCampo(seccion, 'Objetivo');
+    if (objetivo) existente.objetivo = objetivo;
+
+    const estadoRaw = extraerCampo(seccion, 'Estado');
+    if (estadoRaw) {
+      existente.estado = normalizarEstado(estadoRaw);
+      existente.estado_raw = estadoRaw;
+    }
+
+    const fIni = extraerCampo(seccion, 'Fecha inicio');
+    if (fIni && esFecha(fIni)) existente.fecha_inicio = fIni;
+
+    const fFinEst = extraerCampo(seccion, 'Fecha fin estimada');
+    if (fFinEst && esFecha(fFinEst)) existente.fecha_fin_estimada = fFinEst;
+
+    const fFinReal = extraerCampo(seccion, 'Fecha fin real');
+    if (fFinReal && esFecha(fFinReal)) existente.fecha_fin_real = fFinReal;
+
+    // Entregables (subtabla)
+    existente.entregables = parsearTablaEntregables(seccion);
+
+    // Criterios de verificación (checklist)
+    existente.criterios_verificacion = parsearChecklistCriterios(seccion);
+
+    fases.set(numero, existente);
+  }
+}
+
+function extraerCampo(seccion, etiqueta) {
+  const re = new RegExp(`^\\s*[\\*\\-]?\\s*\\*\\*${etiqueta}\\*\\*\\s*:\\s*(.+?)$`, 'mi');
+  const m = seccion.match(re);
+  if (!m) return null;
+  const valor = m[1].trim();
+  if (valor === '—' || valor === '-' || valor === '' || valor.toLowerCase().startsWith('[')) {
+    return null;
+  }
+  return valor;
+}
+
+function parsearTablaEntregables(seccion) {
+  const lineas = seccion.split('\n');
+  const entregables = [];
+  let enTabla = false;
+  let idxNum = -1, idxNombre = -1, idxDesc = -1, idxReqs = -1, idxEstado = -1;
+
+  for (const linea of lineas) {
+    const trim = linea.trim();
+    if (!trim.startsWith('|')) {
+      if (enTabla && trim === '') {
+        enTabla = false;
+        idxNum = -1;
+      }
+      continue;
+    }
+    const celdas = trim.split('|').map(c => c.trim()).filter(c => c !== '');
+
+    if (idxNum === -1) {
+      const low = celdas.map(c => c.toLowerCase());
+      const n = low.findIndex(c => c === '#' || c === 'id');
+      const no = low.findIndex(c => c === 'entregable' || c === 'nombre');
+      const de = low.findIndex(c => c === 'descripción' || c === 'descripcion');
+      const re = low.findIndex(c => c.includes('requisitos') || c.includes('cubiertos'));
+      const es = low.findIndex(c => c === 'estado');
+      if (n !== -1 && no !== -1 && es !== -1) {
+        idxNum = n; idxNombre = no; idxDesc = de; idxReqs = re; idxEstado = es;
+        enTabla = true;
+      }
+      continue;
+    }
+
+    if (celdas.every(c => /^-+$/.test(c.replace(/:/g, '')))) continue;
+    if (!enTabla) continue;
+
+    const numEntregable = celdas[idxNum];
+    if (!numEntregable) continue;
+
+    entregables.push({
+      id: numEntregable,
+      nombre: celdas[idxNombre] || null,
+      descripcion: idxDesc !== -1 ? (celdas[idxDesc] || null) : null,
+      requisitos: idxReqs !== -1
+        ? (celdas[idxReqs] || '').split(',').map(s => s.trim()).filter(Boolean)
+        : [],
+      estado: normalizarEstado(celdas[idxEstado]),
+    });
+  }
+
+  return entregables;
+}
+
+function parsearChecklistCriterios(seccion) {
+  // Captura solo el bloque "Criterios de verificación" si existe
+  const idx = seccion.toLowerCase().indexOf('criterios de verificación');
+  if (idx === -1) return [];
+  const subseccion = seccion.slice(idx);
+  // Cortar en la siguiente sub-sección o el final
+  const finIdx = subseccion.search(/\n###?\s+/m);
+  const recorte = finIdx === -1 ? subseccion : subseccion.slice(0, finIdx);
+
+  const criterios = [];
+  const re = /^\s*-\s*\[(x| )\]\s+(.+?)$/gim;
+  let m;
+  while ((m = re.exec(recorte)) !== null) {
+    criterios.push({
+      cumplido: m[1].toLowerCase() === 'x',
+      descripcion: m[2].trim(),
+    });
+  }
+  return criterios;
+}
+
+function normalizarEstado(estadoRaw) {
+  if (!estadoRaw) return 'pendiente';
+  const lower = estadoRaw.toLowerCase().trim();
+
+  if (lower.includes('complet')) return 'completado';
+  if (lower.includes('done') || lower.includes('hecho')) return 'completado';
+  if (lower.includes('progreso') || lower.includes('progress') || lower.includes('curso')) {
+    return 'en_progreso';
+  }
+  if (lower.includes('spec') && lower.includes('listo')) return 'spec_listo';
+  if (lower.includes('bloque') || lower.includes('block')) return 'bloqueado';
+  if (lower.includes('pendiente') || lower.includes('pending')) return 'pendiente';
+
+  return 'pendiente'; // default conservador
+}
+
+function esFecha(s) {
+  return /^\d{4}-\d{2}-\d{2}/.test(s);
+}
+
+// ─── Enriquecimiento desde .planning/fases/ ──────────────────────────────────
+
+/**
+ * Para cada fase, intenta enriquecer con info de:
+ *   .planning/fases/0N-PLAN.md     → existe + estado
+ *   .planning/fases/0N-RESUMEN.md  → completada
+ *   .planning/fases/0N-CONTEXTO.md → discutida
+ */
+function enriquecerDesdeFases(fases, opciones = {}) {
+  // CWD dinámico — recalcula al llamar, no al require, para que los tests con
+  // process.chdir() funcionen sin requerir reload del módulo.
+  const cwd = opciones.cwd || process.cwd();
+  const fasesDir = path.join(cwd, '.planning', 'fases');
+  if (!fs.existsSync(fasesDir)) return fases;
+
+  const archivos = fs.readdirSync(fasesDir);
+
+  for (const fase of fases) {
+    const num = fase.numero.toString().padStart(2, '0');
+
+    fase.artefactos = {
+      contexto_md: archivos.includes(`${num}-CONTEXTO.md`)
+        ? `.planning/fases/${num}-CONTEXTO.md` : null,
+      plan_md: archivos.includes(`${num}-PLAN.md`)
+        ? `.planning/fases/${num}-PLAN.md` : null,
+      resumen_md: archivos.includes(`${num}-RESUMEN.md`)
+        ? `.planning/fases/${num}-RESUMEN.md` : null,
+    };
+
+    // Si tiene PLAN.md, intentar leer su frontmatter `estado:` para refinar
+    if (fase.artefactos.plan_md) {
+      const planPath = path.join(cwd, fase.artefactos.plan_md);
+      try {
+        const planContent = fs.readFileSync(planPath, 'utf-8');
+        const frontMatch = planContent.match(/^---\s*\n([\s\S]*?)\n---/);
+        if (frontMatch) {
+          const fm = frontMatch[1];
+          const estadoPlan = (fm.match(/^estado:\s*(.+)$/m) || [])[1];
+          if (estadoPlan) {
+            const estadoPlanLow = estadoPlan.trim().toLowerCase();
+            fase.plan_estado = estadoPlanLow;
+            // Si el PLAN está aprobado pero el roadmap dice "pendiente",
+            // refinar a "en_progreso" porque ya pasó la planeación.
+            if (estadoPlanLow === 'aprobado' && fase.estado === 'pendiente') {
+              fase.estado = 'en_progreso';
+            }
+          }
+        }
+      } catch { /* no bloquear si el PLAN tiene formato no esperado */ }
+    }
+
+    // Si tiene RESUMEN.md, asumir completada (a menos que HOJA-RUTA diga otra cosa explícita)
+    if (fase.artefactos.resumen_md && fase.estado !== 'bloqueado') {
+      fase.estado = 'completado';
+    }
+  }
+
+  return fases;
+}
+
+// ─── Generación del JSON canónico ────────────────────────────────────────────
+
+function generarFeatureList(fases) {
+  const ahora = new Date().toISOString();
+  const totales = {
+    fases: fases.length,
+    completadas: fases.filter(f => f.estado === 'completado').length,
+    en_progreso: fases.filter(f => f.estado === 'en_progreso').length,
+    pendientes: fases.filter(f => f.estado === 'pendiente').length,
+    bloqueadas: fases.filter(f => f.estado === 'bloqueado').length,
+    spec_listas: fases.filter(f => f.estado === 'spec_listo').length,
+  };
+
+  return {
+    schema: 'swl-feature-list/v1',
+    generado_en: ahora,
+    fuente: '.planning/HOJA-RUTA.md',
+    nota: 'Derivado automáticamente. HOJA-RUTA.md es la fuente de verdad. Regenerar con `node scripts/derivar-feature-list.js`.',
+    totales,
+    fases,
+  };
+}
+
+// ─── Comparación para --check ────────────────────────────────────────────────
+
+function compararConDisco(generado, rutaOut) {
+  if (!fs.existsSync(rutaOut)) {
+    return { iguales: false, razon: `${rutaOut} no existe` };
+  }
+  let actual;
+  try {
+    actual = JSON.parse(fs.readFileSync(rutaOut, 'utf-8'));
+  } catch (err) {
+    return { iguales: false, razon: `JSON existente está corrupto: ${err.message}` };
+  }
+
+  // Comparar ignorando `generado_en` (timestamp cambia siempre)
+  const a = { ...generado, generado_en: '_' };
+  const b = { ...actual, generado_en: '_' };
+
+  const aStr = JSON.stringify(a);
+  const bStr = JSON.stringify(b);
+
+  if (aStr === bStr) return { iguales: true };
+  return {
+    iguales: false,
+    razon: 'Contenido difiere. Regenerar con `node scripts/derivar-feature-list.js`.',
+  };
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+function parsearArgs(argv) {
+  const args = { out: DEFAULT_OUT, check: false, verbose: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--check' || a === '-c') args.check = true;
+    else if (a === '--verbose' || a === '-v') args.verbose = true;
+    else if (a === '--out' || a === '-o') args.out = argv[++i];
+    else if (a === '--help' || a === '-h') {
+      console.log('Uso: derivar-feature-list.js [--out <path>] [--check] [--verbose]');
+      process.exit(0);
+    }
+  }
+  return args;
+}
+
+function main() {
+  const args = parsearArgs(process.argv);
+
+  if (!fs.existsSync(HOJA_RUTA)) {
+    console.error('[derivar-feature-list] .planning/HOJA-RUTA.md no encontrado.');
+    console.error('  Inicializa con `/swl:nuevo-proyecto` o `/swl:adoptar-proyecto` primero.');
+    process.exit(1);
+  }
+
+  const contenido = fs.readFileSync(HOJA_RUTA, 'utf-8');
+  let fases;
+  try {
+    fases = parsearHojaRuta(contenido);
+    fases = enriquecerDesdeFases(fases);
+  } catch (err) {
+    console.error(`[derivar-feature-list] Error de parsing: ${err.message}`);
+    process.exit(3);
+  }
+
+  if (fases.length === 0 && args.verbose) {
+    console.log('[derivar-feature-list] No se detectaron fases en HOJA-RUTA.md.');
+    console.log('  El JSON se genera vacío (válido para proyectos recién inicializados).');
+  }
+
+  const generado = generarFeatureList(fases);
+
+  if (args.check) {
+    const cmp = compararConDisco(generado, args.out);
+    if (cmp.iguales) {
+      if (args.verbose) console.log(`[derivar-feature-list] OK — ${args.out} está sincronizado.`);
+      process.exit(0);
+    }
+    console.error(`[derivar-feature-list] DRIFT: ${cmp.razon}`);
+    process.exit(2);
+  }
+
+  fs.writeFileSync(args.out, JSON.stringify(generado, null, 2), 'utf-8');
+  if (args.verbose) {
+    console.log(`[derivar-feature-list] Generado ${args.out}`);
+    console.log(`  ${generado.totales.fases} fases | ${generado.totales.completadas} completadas | ${generado.totales.en_progreso} en progreso | ${generado.totales.pendientes} pendientes`);
+  } else {
+    console.log(`[derivar-feature-list] ${args.out} actualizado (${generado.totales.fases} fases)`);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  parsearHojaRuta,
+  enriquecerDesdeFases,
+  generarFeatureList,
+  normalizarEstado,
+};