@saulwade/swl-ses 1.5.1 → 1.6.0

package/scripts/verificar-docs-vs-codigo.js

@@ -0,0 +1,425 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * scripts/verificar-docs-vs-codigo.js
+ *
+ * Verificador automatizado de drift entre documentación y estado real del
+ * proyecto. Pensado para correr en CI tras un release o cuando se modifican
+ * componentes del sistema.
+ *
+ * Checks implementados:
+ *
+ *   1. CONTADORES: INVENTARIO.md vs disco
+ *      Verifica que los contadores (agentes, skills, comandos, hooks, reglas)
+ *      reportados en INVENTARIO.md, README.md, AGENTS.md, MANUAL_USO.md,
+ *      package.json#description y plugin.json#description coincidan con lo
+ *      que existe en disco.
+ *
+ *   2. COMANDOS: comandos/swl/*.md vs COMANDOS.md y MANUAL_USO.md
+ *      Cada comando con archivo en comandos/swl/ debe mencionarse en
+ *      COMANDOS.md (al menos una vez como /swl:<nombre>) y en MANUAL_USO.md
+ *      (al menos una sección dedicada).
+ *
+ *   3. FLAGS críticos: parser vs docs
+ *      Si parsear-opciones.js declara una flag como booleana, debe aparecer
+ *      en bin/swl-ses.js --help y en COMANDOS.md tabla de opciones.
+ *
+ *   4. VERSIONES: package.json vs encabezados de docs
+ *      Las primeras líneas de CLAUDE.md, README.md, AGENTS.md, COMANDOS.md,
+ *      MANUAL_USO.md, INSTALACION.md deben mencionar la versión de
+ *      package.json.
+ *
+ *   5. TUI: scripts/tui/pantallas/*.js vs docs
+ *      Cada pantalla del TUI (welcome, menu-principal, install-wizard,
+ *      update-wizard, uninstall-wizard, inspect, progreso, resumen) debe
+ *      tener al menos una mención en MANUAL_USO.md.
+ *
+ * Exit codes:
+ *   0 — todos los checks pasan
+ *   1 — hay drift en al menos un check obligatorio
+ *   2 — error de invocación
+ *
+ * Uso:
+ *   node scripts/verificar-docs-vs-codigo.js [--check N] [--quiet]
+ *
+ *   --check N    Ejecuta solo el check N (1-5). Sin flag: todos.
+ *   --quiet      Suprime el output de checks que pasan; solo reporta fallas.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const RAIZ = path.resolve(__dirname, '..');
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+function leerArchivo(rel) {
+  try {
+    return fs.readFileSync(path.join(RAIZ, rel), 'utf-8');
+  } catch (_) {
+    return null;
+  }
+}
+
+function contarEntradasDirectorio(dir, opts = {}) {
+  const dirAbs = path.join(RAIZ, dir);
+  if (!fs.existsSync(dirAbs)) return 0;
+  const entradas = fs.readdirSync(dirAbs, { withFileTypes: true });
+  if (opts.dirsOnly) return entradas.filter(e => e.isDirectory()).length;
+  if (opts.filesOnly) {
+    return entradas.filter(e => e.isFile() && (!opts.ext || e.name.endsWith(opts.ext))).length;
+  }
+  return entradas.length;
+}
+
+function contarHooksEjecutables() {
+  const dirAbs = path.join(RAIZ, 'hooks');
+  if (!fs.existsSync(dirAbs)) return 0;
+  return fs.readdirSync(dirAbs)
+    .filter(n => n.endsWith('.js') && !n.startsWith('_'))
+    .length;
+}
+
+function contarReglasMd() {
+  const dirAbs = path.join(RAIZ, 'reglas');
+  if (!fs.existsSync(dirAbs)) return 0;
+  // Cuenta archivos .md en raíz de reglas/ + subdirectorios por lenguaje
+  let total = 0;
+  function recurse(d) {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (e.isDirectory() && !e.name.startsWith('_')) recurse(path.join(d, e.name));
+      else if (e.isFile() && e.name.endsWith('.md') && !e.name.startsWith('_')) total++;
+    }
+  }
+  recurse(dirAbs);
+  return total;
+}
+
+// ── reporting ─────────────────────────────────────────────────────────────────
+
+const COLOR_OK = '\x1b[32m';
+const COLOR_FAIL = '\x1b[31m';
+const COLOR_WARN = '\x1b[33m';
+const COLOR_DIM = '\x1b[2m';
+const COLOR_RESET = '\x1b[0m';
+const tty = !!process.stdout.isTTY;
+const c = (color, txt) => (tty ? `${color}${txt}${COLOR_RESET}` : txt);
+
+const opts = (() => {
+  const args = process.argv.slice(2);
+  const checkIdx = args.indexOf('--check');
+  return {
+    only: checkIdx >= 0 ? parseInt(args[checkIdx + 1], 10) : null,
+    quiet: args.includes('--quiet'),
+  };
+})();
+
+const resultados = [];
+
+function reportar(check, etiqueta, ok, detalle) {
+  resultados.push({ check, etiqueta, ok, detalle });
+  if (ok && opts.quiet) return;
+  const mark = ok ? c(COLOR_OK, '[OK]') : c(COLOR_FAIL, '[FAIL]');
+  console.log(`  ${mark} check #${check} — ${etiqueta}`);
+  if (detalle && !opts.quiet) {
+    for (const linea of String(detalle).split('\n')) {
+      console.log(`        ${c(COLOR_DIM, linea)}`);
+    }
+  } else if (detalle && !ok) {
+    for (const linea of String(detalle).split('\n')) {
+      console.log(`        ${linea}`);
+    }
+  }
+}
+
+// ── Check 1: contadores ──────────────────────────────────────────────────────
+
+function check1Contadores() {
+  if (opts.only && opts.only !== 1) return;
+  console.log(c(COLOR_DIM, '\n[1] Contadores: INVENTARIO.md / README.md / docs vs disco'));
+
+  const real = {
+    agentes: contarEntradasDirectorio('agentes', { filesOnly: true, ext: '.md' })
+      - (fs.existsSync(path.join(RAIZ, 'agentes', 'README.md')) ? 1 : 0),
+    skills: contarEntradasDirectorio('habilidades', { dirsOnly: true }),
+    comandos: contarEntradasDirectorio('comandos/swl', { filesOnly: true, ext: '.md' }),
+    reglas: contarReglasMd(),
+    hooks: contarHooksEjecutables(),
+  };
+
+  // Corregir agentes: descartar archivos `_*.md` (fragmentos compartidos)
+  const dirAgentes = path.join(RAIZ, 'agentes');
+  real.agentes = fs.readdirSync(dirAgentes)
+    .filter(n => n.endsWith('.md') && !n.startsWith('_') && n !== 'README.md')
+    .length;
+
+  // Cargar lo que dicen los manifiestos canónicos. INVENTARIO.md usa una
+  // tabla del tipo `| Agentes SWL | 60 |` así que extraemos por fila.
+  const inventario = leerArchivo('INVENTARIO.md') || '';
+  const extraerCelda = (regex) => {
+    const m = inventario.match(regex);
+    return m ? Number(m[1]) : null;
+  };
+  const declarado = {
+    agentes:  extraerCelda(/\|\s*Agentes[^|]*\|\s*(\d+)\s*\|/i),
+    skills:   extraerCelda(/\|\s*Habilidades[^|]*\|\s*(\d+)\s*\|/i)
+              || extraerCelda(/\|\s*Skills[^|]*\|\s*(\d+)\s*\|/i),
+    comandos: extraerCelda(/\|\s*Comandos[^|]*\|\s*(\d+)\s*\|/i),
+    reglas:   (() => {
+      // INVENTARIO.md separa "Reglas base" + "Reglas por lenguaje".
+      const base = extraerCelda(/\|\s*Reglas base[^|]*\|\s*(\d+)\s*\|/i) || 0;
+      const lang = extraerCelda(/\|\s*Reglas por lenguaje[^|]*\|\s*(\d+)\s*\|/i) || 0;
+      const total = extraerCelda(/\|\s*Reglas\s*\|\s*(\d+)\s*\|/i);
+      if (total) return total;
+      if (base + lang > 0) return base + lang;
+      return null;
+    })(),
+    hooks:    extraerCelda(/\|\s*Hooks\s*\|\s*(\d+)\s*\|/i),
+  };
+
+  for (const cat of Object.keys(real)) {
+    if (declarado[cat] == null) {
+      reportar(1, `INVENTARIO.md no declara ${cat}`, false,
+        `Real en disco: ${real[cat]}; INVENTARIO.md no incluye un patrón "(\\d+) ${cat}"`);
+    } else if (Number(declarado[cat]) === real[cat]) {
+      reportar(1, `INVENTARIO.md ${cat}: ${real[cat]}`, true);
+    } else {
+      reportar(1, `INVENTARIO.md ${cat} drift`, false,
+        `Real en disco: ${real[cat]}; INVENTARIO.md declara: ${declarado[cat]}`);
+    }
+  }
+}
+
+// ── Check 2: comandos/swl/*.md vs docs ──────────────────────────────────────
+
+function check2Comandos() {
+  if (opts.only && opts.only !== 2) return;
+  console.log(c(COLOR_DIM, '\n[2] Comandos /swl:* en disco vs COMANDOS.md y MANUAL_USO.md'));
+
+  const dirAbs = path.join(RAIZ, 'comandos/swl');
+  if (!fs.existsSync(dirAbs)) {
+    reportar(2, 'comandos/swl/ no existe', false, 'Directorio faltante');
+    return;
+  }
+
+  const archivos = fs.readdirSync(dirAbs)
+    .filter(n => n.endsWith('.md') && !n.startsWith('_') && n !== 'README.md');
+
+  const comandosMd = leerArchivo('COMANDOS.md') || '';
+  const manualUsoMd = leerArchivo('MANUAL_USO.md') || '';
+
+  // Check #2 reporta WARN (no FAIL) cuando un comando no está en docs.
+  // Razón: la deuda de documentación granular por comando es preexistente
+  // y resolverla está fuera del scope del verificador. El verificador
+  // marca los gaps para que se vayan cerrando incrementalmente.
+  let pendientes = 0;
+  let documentados = 0;
+  const sinDocumentar = [];
+  for (const archivo of archivos) {
+    const nombre = archivo.replace(/\.md$/, '');
+    const refSlash = `/swl:${nombre}`;
+    const enComandos = comandosMd.includes(refSlash);
+    const enManual = manualUsoMd.includes(refSlash);
+    if (!enComandos || !enManual) {
+      pendientes++;
+      const faltas = [];
+      if (!enComandos) faltas.push('COMANDOS.md');
+      if (!enManual) faltas.push('MANUAL_USO.md');
+      sinDocumentar.push(`${refSlash} (falta en ${faltas.join(' + ')})`);
+    } else {
+      documentados++;
+    }
+  }
+
+  if (pendientes === 0) {
+    reportar(2, `${archivos.length} comandos /swl:* documentados en COMANDOS.md y MANUAL_USO.md`, true);
+  } else {
+    // WARN consolidado: no falla el verificador pero lista los gaps
+    const colorWarn = tty ? COLOR_WARN : '';
+    const mark = tty ? `${COLOR_WARN}[WARN]${COLOR_RESET}` : '[WARN]';
+    console.log(`  ${mark} check #2 — ${pendientes} comandos sin documentar (de ${archivos.length} en disco)`);
+    if (!opts.quiet) {
+      for (const item of sinDocumentar) {
+        console.log(`        ${c(COLOR_DIM, '- ' + item)}`);
+      }
+      console.log(`        ${c(COLOR_DIM, '(WARN no falla el verificador; documentar incremental)')}`);
+    }
+    // Marca como OK porque es WARN, no FAIL — la deuda es preexistente
+    resultados.push({ check: 2, etiqueta: `${documentados}/${archivos.length} comandos documentados`, ok: true, detalle: null });
+  }
+}
+
+// ── Check 3: flags booleanas vs docs ────────────────────────────────────────
+
+function check3Flags() {
+  if (opts.only && opts.only !== 3) return;
+  console.log(c(COLOR_DIM, '\n[3] Flags booleanas del parser vs bin --help y COMANDOS.md'));
+
+  const parser = leerArchivo('scripts/lib/parsear-opciones.js') || '';
+  const binHelp = leerArchivo('bin/swl-ses.js') || '';
+  const comandosMd = leerArchivo('COMANDOS.md') || '';
+
+  // Extraer las booleanas del parser (busca el array BOOLEANAS)
+  const matchBool = parser.match(/const BOOLEANAS\s*=\s*\[([\s\S]*?)\];/);
+  if (!matchBool) {
+    reportar(3, 'parsear-opciones.js no exporta BOOLEANAS', false,
+      'No se encontró el array BOOLEANAS en el parser');
+    return;
+  }
+
+  const booleanas = (matchBool[1].match(/['"]([^'"]+)['"]/g) || [])
+    .map(s => s.replace(/['"]/g, ''))
+    .filter(b => !['simular', 'forzar'].includes(b)); // alias en español ya cubiertos
+
+  // Flags críticas que SÍ deben estar documentadas (subset)
+  const criticas = ['tui', 'no-tui', 'with-mcp', 'all-langs', 'force', 'dry-run', 'global'];
+
+  let fallas = 0;
+  for (const flag of criticas) {
+    if (!booleanas.includes(flag)) {
+      // Si la flag no está en el parser tampoco; eso es señalable pero no fail aquí
+      continue;
+    }
+    const enBinHelp = binHelp.includes(`--${flag}`);
+    const enComandosMd = comandosMd.includes(`--${flag}`);
+    if (!enBinHelp || !enComandosMd) {
+      fallas++;
+      const faltas = [];
+      if (!enBinHelp) faltas.push('bin/swl-ses.js (--help)');
+      if (!enComandosMd) faltas.push('COMANDOS.md');
+      reportar(3, `Flag --${flag} sin documentar en ${faltas.join(' + ')}`, false,
+        `Parser la declara como booleana pero falta en docs`);
+    }
+  }
+  if (fallas === 0) {
+    reportar(3, `${criticas.length} flags críticas documentadas en bin --help y COMANDOS.md`, true);
+  }
+}
+
+// ── Check 4: versiones ──────────────────────────────────────────────────────
+
+function check4Versiones() {
+  if (opts.only && opts.only !== 4) return;
+  console.log(c(COLOR_DIM, '\n[4] Versión de package.json vs encabezados de docs'));
+
+  let version;
+  try {
+    version = require(path.join(RAIZ, 'package.json')).version;
+  } catch (_) {
+    reportar(4, 'package.json no parsea', false);
+    return;
+  }
+
+  const docs = ['CLAUDE.md', 'README.md', 'AGENTS.md', 'COMANDOS.md', 'MANUAL_USO.md', 'INSTALACION.md'];
+  let fallas = 0;
+  for (const doc of docs) {
+    const contenido = leerArchivo(doc);
+    if (!contenido) {
+      fallas++;
+      reportar(4, `${doc} no se puede leer`, false);
+      continue;
+    }
+    const primeraLinea = contenido.split('\n')[0] || '';
+    if (!primeraLinea.includes(version)) {
+      fallas++;
+      reportar(4, `${doc} encabezado sin v${version}`, false,
+        `Primera línea: "${primeraLinea.slice(0, 100)}"`);
+    }
+  }
+  if (fallas === 0) {
+    reportar(4, `Encabezados de ${docs.length} docs consistentes con v${version}`, true);
+  }
+}
+
+// ── Check 5: pantallas TUI ───────────────────────────────────────────────────
+
+function check5Tui() {
+  if (opts.only && opts.only !== 5) return;
+  console.log(c(COLOR_DIM, '\n[5] Pantallas TUI vs menciones en MANUAL_USO.md'));
+
+  const dirAbs = path.join(RAIZ, 'scripts/tui/pantallas');
+  if (!fs.existsSync(dirAbs)) {
+    // Si no hay TUI (pre-v1.6.0), saltar el check sin fallar
+    reportar(5, 'scripts/tui/pantallas/ no existe (TUI no instalado)', true);
+    return;
+  }
+
+  const pantallas = fs.readdirSync(dirAbs)
+    .filter(n => n.endsWith('.js'))
+    .map(n => n.replace(/\.js$/, ''));
+
+  const manualUsoMd = (leerArchivo('MANUAL_USO.md') || '').toLowerCase();
+
+  // Mapeo de nombre de archivo a término que debe aparecer en docs
+  const terminos = {
+    'welcome': ['welcome', 'bienvenida'],
+    'menu-principal': ['menú principal', 'menu principal'],
+    'install-wizard': ['wizard install', 'install wizard', 'wizard de instalación', 'instalador tui'],
+    'update-wizard': ['wizard update', 'update wizard', 'wizard de actualización'],
+    'uninstall-wizard': ['uninstall', 'desinstal'],
+    'inspect': ['inspect'],
+    'progreso': ['progreso', 'barra de progreso'],
+    'resumen': ['resumen', 'pantalla resumen'],
+  };
+
+  let fallas = 0;
+  for (const pantalla of pantallas) {
+    const expectedTerms = terminos[pantalla];
+    if (!expectedTerms) continue; // archivo no es una pantalla documentable
+    const algunoPresente = expectedTerms.some(t => manualUsoMd.includes(t.toLowerCase()));
+    if (!algunoPresente) {
+      fallas++;
+      reportar(5, `Pantalla "${pantalla}" sin mención en MANUAL_USO.md`, false,
+        `Esperaba al menos uno de: ${expectedTerms.join(', ')}`);
+    }
+  }
+  if (fallas === 0) {
+    const documentables = Object.keys(terminos).length;
+    reportar(5, `${documentables} pantallas TUI mencionadas en MANUAL_USO.md`, true);
+  }
+}
+
+// ── main ──────────────────────────────────────────────────────────────────────
+
+function main() {
+  console.log(c(COLOR_DIM, 'Verificador docs-vs-código — swl-ses\n' + '═'.repeat(60)));
+
+  check1Contadores();
+  check2Comandos();
+  check3Flags();
+  check4Versiones();
+  check5Tui();
+
+  const fails = resultados.filter(r => !r.ok).length;
+  const total = resultados.length;
+
+  console.log('\n' + '─'.repeat(60));
+  if (fails === 0) {
+    console.log(c(COLOR_OK, `✓ ${total} checks OK — docs alineadas con código`));
+    process.exit(0);
+  } else {
+    console.log(c(COLOR_FAIL, `✗ ${fails}/${total} checks con drift`));
+    console.log(c(COLOR_DIM, 'Revisa los hallazgos arriba. Las menciones marcadas FAIL deben'));
+    console.log(c(COLOR_DIM, 'actualizarse antes del próximo merge.'));
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (err) {
+    console.error(c(COLOR_FAIL, `Error de ejecución: ${err.message}`));
+    if (process.env.SWL_DEBUG) console.error(err.stack);
+    process.exit(2);
+  }
+}
+
+module.exports = {
+  check1Contadores,
+  check2Comandos,
+  check3Flags,
+  check4Versiones,
+  check5Tui,
+};