@saulwade/swl-ses 2.6.0 → 2.8.0

package/scripts/lib/clasificar-directorio.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * clasificar-directorio.js — Clasifica un directorio de trabajo para que el
+ * instalador y `doctor` decidan si deben anclar `.planning/` ahí.
+ *
+ * Bug de origen (2026-07-15): instalador/doctor trataban `process.cwd()` como
+ * proyecto sin distinguir el HOME del usuario (ubicación de una instalación
+ * GLOBAL, NO un proyecto) de un proyecto de desarrollo real. Correr
+ * `install --global` o `doctor` desde el HOME sembraba `~/.planning/`
+ * (backups del install, scaffold de marcadores, telemetría mal dirigida).
+ *
+ * Categorías:
+ *   - 'home'     : cwd === os.homedir(). Ubicación de install global; NUNCA un proyecto.
+ *   - 'proyecto' : proyecto de desarrollo real (.git, stack detectado, o `.planning/`
+ *                  con marcadores de proyecto).
+ *   - 'nuevo'    : directorio vacío o casi vacío (candidato a inicializar un proyecto).
+ *   - 'otro'     : con contenido pero sin señales de proyecto (no scaffoldear a ciegas).
+ *
+ * Uso interno del instalador/doctor (no viaja a destinos): puede requerir otras
+ * libs de `scripts/lib` y `hooks/lib`. Zero-deps npm.
+ *
+ * @module scripts/lib/clasificar-directorio
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { detectarStack } = require('./detectar-stack');
+const { tienePlanningReal } = require('../../hooks/lib/raiz-proyecto');
+
+// Entradas que NO cuentan como "contenido" al decidir si un dir está vacío
+// (metadatos del SO / control de versiones que pueden existir en un dir "nuevo").
+const IGNORAR_AL_MEDIR_VACIO = new Set(['.git', '.DS_Store', 'Thumbs.db', 'desktop.ini']);
+
+/**
+ * ¿El directorio es el HOME del usuario? (comparación canónica por realpath
+ * para tolerar el nombre corto 8.3 de Windows — misma razón que raiz-proyecto).
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function esHome(dir) {
+  const canon = (p) => { try { return fs.realpathSync.native(p); } catch (_) { return path.resolve(p); } };
+  return canon(dir) === canon(os.homedir());
+}
+
+/**
+ * ¿El directorio es un proyecto de desarrollo real? Señal: repo git, stack de
+ * lenguaje detectado, o `.planning/` con marcadores de proyecto.
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function esProyectoDesarrollo(dir) {
+  try {
+    if (fs.existsSync(path.join(dir, '.git'))) return true;
+  } catch (_) { /* seguir */ }
+  if (tienePlanningReal(dir)) return true;
+  try {
+    if (detectarStack(dir).size > 0) return true;
+  } catch (_) { /* seguir */ }
+  return false;
+}
+
+/**
+ * ¿El directorio está vacío o casi vacío (solo metadatos del SO/git)?
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function estaVacio(dir) {
+  let entradas;
+  try {
+    entradas = fs.readdirSync(dir);
+  } catch (_) {
+    return false; // no legible → no lo tratamos como vacío
+  }
+  return entradas.filter((e) => !IGNORAR_AL_MEDIR_VACIO.has(e)).length === 0;
+}
+
+/**
+ * Clasifica el directorio de trabajo.
+ * @param {string} [cwd] - Directorio (default: process.cwd()).
+ * @returns {'home'|'proyecto'|'nuevo'|'otro'}
+ */
+function clasificarDirectorio(cwd) {
+  const dir = path.resolve(cwd || process.cwd());
+  if (esHome(dir)) return 'home';
+  if (esProyectoDesarrollo(dir)) return 'proyecto';
+  if (estaVacio(dir)) return 'nuevo';
+  return 'otro';
+}
+
+module.exports = { clasificarDirectorio, esHome, esProyectoDesarrollo, estaVacio };

package/scripts/lib/contadores-inventario.js

@@ -1,217 +1,217 @@
-'use strict';
-
-/**
- * contadores-inventario.js
- *
- * Funciones puras zero-deps para validar consistencia entre los contadores
- * de inventario (agentes, skills, comandos, hooks, reglas) declarados en
- * `INVENTARIO.md` (fuente de verdad regenerada por
- * `scripts/generar-inventario.js`) y los contadores citados en los demás
- * documentos canónicos del repositorio.
- *
- * Motivado por el drift recurrente detectado el 2026-04-29: MAPEO_SKILLS_AGENTES.md
- * decía "153 skills" cuando la realidad eran 150; COMPACTACION.md reportaba
- * "147 skills, 40 comandos, 31 hooks". El hook `verificar-release.js` valida
- * versión pero no contadores. Este módulo cierra ese hueco.
- *
- * Cobertura intencional:
- *   - Patrón resumen "X agentes, Y skills, Z comandos, W reglas, V hooks"
- *     (separadores `,` o `+` o `y`) — valida los 5 números a la vez.
- *   - Patrón "X agentes + Y habilidades + Z comandos + W reglas + V hooks"
- *     común en tablas de perfiles `completo`.
- *   - Patrón "Total de agentes: X" / "Total de skills: X" en MAPEO.
- *
- * Cobertura intencionalmente excluida (falsos positivos clásicos):
- *   - "los 17 skills de Anthropic" (skills externos)
- *   - "8 lenguajes × 5 reglas" (multiplicación)
- *   - perfiles parciales "2 hooks", "6 hooks" (no son totales)
- *   - notas históricas "estimé 28 hooks visualmente y propagué el error"
- *   - referencias a versiones pasadas en MAPEO ("136 skills tras release X")
- *   - filas de tabla histórica con SemVer + fecha ("| 5.4.0 | 2026-04-10 | 57 agentes...")
- *
- * Estas se ignoran porque el patrón resumen es el único que tiene los 5
- * componentes alineados; las menciones aisladas de un solo número se dejan
- * para una auditoría aparte (no bloqueante).
- */
-
-const COMPONENTES = ['agentes', 'skills', 'comandos', 'hooks', 'reglas'];
-
-/**
- * Parsea la sección "## Resumen" de INVENTARIO.md y retorna un mapa con
- * los contadores reales del sistema.
- *
- * Espera tabla del tipo:
- *   ## Resumen
- *   | Componente | Cantidad |
- *   |-----------|----------|
- *   | Agentes SWL | 59 |
- *   | Habilidades | 150 |
- *   | Comandos | 41 |
- *   | Reglas base | 20 |
- *   | Reglas por lenguaje | 40 |
- *   | Hooks | 36 |
- *
- * Retorna `{ agentes, skills, comandos, hooks, reglas }`.
- * `skills` y `habilidades` se mapean al mismo número.
- * `reglas` = base + por_lenguaje.
- */
-function parsearInventario(rawMd) {
-  const lineas = rawMd.split(/\r?\n/);
-  const resumen = {};
-  let enResumen = false;
-  for (const linea of lineas) {
-    if (/^##\s+Resumen\s*$/.test(linea)) { enResumen = true; continue; }
-    if (enResumen && /^##\s+/.test(linea)) break;
-    if (!enResumen) continue;
-    const m = linea.match(/^\|\s*([^|]+?)\s*\|\s*(\d+)\s*\|/);
-    if (m) resumen[m[1].trim()] = parseInt(m[2], 10);
-  }
-
-  const reglasBase = resumen['Reglas base'] || 0;
-  const reglasLeng = resumen['Reglas por lenguaje'] || 0;
-
-  return {
-    agentes: resumen['Agentes SWL'] || 0,
-    skills: resumen['Habilidades'] || 0,
-    comandos: resumen['Comandos'] || 0,
-    hooks: resumen['Hooks'] || 0,
-    reglas: reglasBase + reglasLeng,
-  };
-}
-
-/**
- * Detecta el patrón resumen en una línea y retorna los números encontrados.
- * Soporta separadores `,`, `+` y `y`. Tolera el orden canónico
- * agentes → skills/habilidades → comandos → reglas → hooks.
- *
- * Ejemplos que matchean:
- *   "59 agentes, 150 skills, 41 comandos, 60 reglas, 36 hooks"
- *   "59 agentes + 150 habilidades + 41 comandos + 60 reglas + 36 hooks"
- *   "59 agentes, 150 skills, 41 comandos, 60 reglas y 36 hooks"
- *   "Frontmatter: 59 agentes + 150 skills + 41 comandos verificados"
- *     (los 3 primeros se validan; los 2 últimos faltan → no full match,
- *      se devuelve match parcial con flags)
- *
- * Retorna `null` si no encuentra al menos `agentes` y un segundo componente.
- */
-function extraerResumenDeLinea(linea) {
-  // Patrón principal: 5 componentes en orden
-  const re5 = /(\d{1,4})\s+agentes?[\s,+y]+\s*(\d{1,4})\s+(?:skills|habilidades)[\s,+y]+\s*(\d{1,4})\s+comandos[\s,+y]+\s*(\d{1,4})\s+reglas[\s,+y]+\s*(\d{1,4})\s+hooks/i;
-  const m5 = linea.match(re5);
-  if (m5) {
-    return {
-      tipo: 'resumen5',
-      texto: m5[0],
-      agentes: parseInt(m5[1], 10),
-      skills: parseInt(m5[2], 10),
-      comandos: parseInt(m5[3], 10),
-      reglas: parseInt(m5[4], 10),
-      hooks: parseInt(m5[5], 10),
-    };
-  }
-
-  // Patrón parcial: 3 componentes (agentes, skills/habilidades, comandos)
-  const re3 = /(\d{1,4})\s+agentes?[\s,+y]+\s*(\d{1,4})\s+(?:skills|habilidades)[\s,+y]+\s*(\d{1,4})\s+comandos/i;
-  const m3 = linea.match(re3);
-  if (m3) {
-    return {
-      tipo: 'resumen3',
-      texto: m3[0],
-      agentes: parseInt(m3[1], 10),
-      skills: parseInt(m3[2], 10),
-      comandos: parseInt(m3[3], 10),
-    };
-  }
-
-  return null;
-}
-
-/**
- * Decide si una línea debe ignorarse por ser obviamente histórica
- * (fila de changelog/timeline con versión SemVer + fecha en formato tabla).
- */
-function esLineaHistorica(linea) {
-  // Tabla con versión SemVer + fecha ISO: "| 5.4.0 | 2026-04-10 | ..."
-  if (/^\s*\|\s*\d+\.\d+\.\d+\s*\|\s*\d{4}-\d{2}-\d{2}/.test(linea)) return true;
-  // "Baseline:" suele ser nota histórica
-  if (/\bBaseline\s*:/i.test(linea)) return true;
-  // "antes de v|previa a|tras release N" sugiere historia
-  if (/\b(?:antes de v|previa a|tras release|en v\d+\.\d+)\b/i.test(linea)) return true;
-  // Línea entre comillas dobles (cita textual de un patrón documentado): "22 hooks"
-  if (/"\s*\d+\s+(?:agentes|skills|habilidades|comandos|hooks|reglas)\s*"/i.test(linea)) return true;
-  return false;
-}
-
-/**
- * Valida un archivo contra los contadores reales.
- * Solo flagea las líneas que contienen patrón resumen identificable.
- *
- * Retorna { ok, lineas_revisadas, discrepancias: [{linea, encontrado, esperado, tipo, contexto}] }
- */
-function validarArchivo(rawMd, contadoresReales) {
-  const lineas = rawMd.split(/\r?\n/);
-  const discrepancias = [];
-  let lineasRevisadas = 0;
-
-  for (let i = 0; i < lineas.length; i++) {
-    if (esLineaHistorica(lineas[i])) continue;
-    const r = extraerResumenDeLinea(lineas[i]);
-    if (!r) continue;
-    lineasRevisadas++;
-
-    const campos = r.tipo === 'resumen5'
-      ? COMPONENTES
-      : ['agentes', 'skills', 'comandos'];
-
-    for (const campo of campos) {
-      if (r[campo] !== contadoresReales[campo]) {
-        discrepancias.push({
-          linea: i + 1,
-          campo,
-          encontrado: r[campo],
-          esperado: contadoresReales[campo],
-          tipo: r.tipo,
-          contexto: lineas[i].trim().slice(0, 110),
-        });
-      }
-    }
-  }
-
-  // Patrón nominal: "**Total de agentes**: N", "**Total de skills**: N"
-  const reTotal = /\*?\*?Total\s+de\s+(agentes|skills|habilidades|comandos|hooks|reglas)\*?\*?\s*:\s*(\d{1,4})/gi;
-  for (let i = 0; i < lineas.length; i++) {
-    if (esLineaHistorica(lineas[i])) continue;
-    let m;
-    reTotal.lastIndex = 0;
-    while ((m = reTotal.exec(lineas[i])) !== null) {
-      const palabra = m[1].toLowerCase();
-      const campo = palabra === 'habilidades' ? 'skills' : palabra;
-      const num = parseInt(m[2], 10);
-      lineasRevisadas++;
-      if (num !== contadoresReales[campo]) {
-        discrepancias.push({
-          linea: i + 1,
-          campo,
-          encontrado: num,
-          esperado: contadoresReales[campo],
-          tipo: 'total_nominal',
-          contexto: lineas[i].trim().slice(0, 110),
-        });
-      }
-    }
-  }
-
-  return {
-    ok: discrepancias.length === 0,
-    lineas_revisadas: lineasRevisadas,
-    discrepancias,
-  };
-}
-
-module.exports = {
-  COMPONENTES,
-  parsearInventario,
-  extraerResumenDeLinea,
-  esLineaHistorica,
-  validarArchivo,
-};
+'use strict';
+
+/**
+ * contadores-inventario.js
+ *
+ * Funciones puras zero-deps para validar consistencia entre los contadores
+ * de inventario (agentes, skills, comandos, hooks, reglas) declarados en
+ * `INVENTARIO.md` (fuente de verdad regenerada por
+ * `scripts/generar-inventario.js`) y los contadores citados en los demás
+ * documentos canónicos del repositorio.
+ *
+ * Motivado por el drift recurrente detectado el 2026-04-29: MAPEO_SKILLS_AGENTES.md
+ * decía "153 skills" cuando la realidad eran 150; COMPACTACION.md reportaba
+ * "147 skills, 40 comandos, 31 hooks". El hook `verificar-release.js` valida
+ * versión pero no contadores. Este módulo cierra ese hueco.
+ *
+ * Cobertura intencional:
+ *   - Patrón resumen "X agentes, Y skills, Z comandos, W reglas, V hooks"
+ *     (separadores `,` o `+` o `y`) — valida los 5 números a la vez.
+ *   - Patrón "X agentes + Y habilidades + Z comandos + W reglas + V hooks"
+ *     común en tablas de perfiles `completo`.
+ *   - Patrón "Total de agentes: X" / "Total de skills: X" en MAPEO.
+ *
+ * Cobertura intencionalmente excluida (falsos positivos clásicos):
+ *   - "los 17 skills de Anthropic" (skills externos)
+ *   - "8 lenguajes × 5 reglas" (multiplicación)
+ *   - perfiles parciales "2 hooks", "6 hooks" (no son totales)
+ *   - notas históricas "estimé 28 hooks visualmente y propagué el error"
+ *   - referencias a versiones pasadas en MAPEO ("136 skills tras release X")
+ *   - filas de tabla histórica con SemVer + fecha ("| 5.4.0 | 2026-04-10 | 57 agentes...")
+ *
+ * Estas se ignoran porque el patrón resumen es el único que tiene los 5
+ * componentes alineados; las menciones aisladas de un solo número se dejan
+ * para una auditoría aparte (no bloqueante).
+ */
+
+const COMPONENTES = ['agentes', 'skills', 'comandos', 'hooks', 'reglas'];
+
+/**
+ * Parsea la sección "## Resumen" de INVENTARIO.md y retorna un mapa con
+ * los contadores reales del sistema.
+ *
+ * Espera tabla del tipo:
+ *   ## Resumen
+ *   | Componente | Cantidad |
+ *   |-----------|----------|
+ *   | Agentes SWL | 59 |
+ *   | Habilidades | 150 |
+ *   | Comandos | 41 |
+ *   | Reglas base | 20 |
+ *   | Reglas por lenguaje | 40 |
+ *   | Hooks | 36 |
+ *
+ * Retorna `{ agentes, skills, comandos, hooks, reglas }`.
+ * `skills` y `habilidades` se mapean al mismo número.
+ * `reglas` = base + por_lenguaje.
+ */
+function parsearInventario(rawMd) {
+  const lineas = rawMd.split(/\r?\n/);
+  const resumen = {};
+  let enResumen = false;
+  for (const linea of lineas) {
+    if (/^##\s+Resumen\s*$/.test(linea)) { enResumen = true; continue; }
+    if (enResumen && /^##\s+/.test(linea)) break;
+    if (!enResumen) continue;
+    const m = linea.match(/^\|\s*([^|]+?)\s*\|\s*(\d+)\s*\|/);
+    if (m) resumen[m[1].trim()] = parseInt(m[2], 10);
+  }
+
+  const reglasBase = resumen['Reglas base'] || 0;
+  const reglasLeng = resumen['Reglas por lenguaje'] || 0;
+
+  return {
+    agentes: resumen['Agentes SWL'] || 0,
+    skills: resumen['Habilidades'] || 0,
+    comandos: resumen['Comandos'] || 0,
+    hooks: resumen['Hooks'] || 0,
+    reglas: reglasBase + reglasLeng,
+  };
+}
+
+/**
+ * Detecta el patrón resumen en una línea y retorna los números encontrados.
+ * Soporta separadores `,`, `+` y `y`. Tolera el orden canónico
+ * agentes → skills/habilidades → comandos → reglas → hooks.
+ *
+ * Ejemplos que matchean:
+ *   "59 agentes, 150 skills, 41 comandos, 60 reglas, 36 hooks"
+ *   "59 agentes + 150 habilidades + 41 comandos + 60 reglas + 36 hooks"
+ *   "59 agentes, 150 skills, 41 comandos, 60 reglas y 36 hooks"
+ *   "Frontmatter: 59 agentes + 150 skills + 41 comandos verificados"
+ *     (los 3 primeros se validan; los 2 últimos faltan → no full match,
+ *      se devuelve match parcial con flags)
+ *
+ * Retorna `null` si no encuentra al menos `agentes` y un segundo componente.
+ */
+function extraerResumenDeLinea(linea) {
+  // Patrón principal: 5 componentes en orden
+  const re5 = /(\d{1,4})\s+agentes?[\s,+y]+\s*(\d{1,4})\s+(?:skills|habilidades)[\s,+y]+\s*(\d{1,4})\s+comandos[\s,+y]+\s*(\d{1,4})\s+reglas[\s,+y]+\s*(\d{1,4})\s+hooks/i;
+  const m5 = linea.match(re5);
+  if (m5) {
+    return {
+      tipo: 'resumen5',
+      texto: m5[0],
+      agentes: parseInt(m5[1], 10),
+      skills: parseInt(m5[2], 10),
+      comandos: parseInt(m5[3], 10),
+      reglas: parseInt(m5[4], 10),
+      hooks: parseInt(m5[5], 10),
+    };
+  }
+
+  // Patrón parcial: 3 componentes (agentes, skills/habilidades, comandos)
+  const re3 = /(\d{1,4})\s+agentes?[\s,+y]+\s*(\d{1,4})\s+(?:skills|habilidades)[\s,+y]+\s*(\d{1,4})\s+comandos/i;
+  const m3 = linea.match(re3);
+  if (m3) {
+    return {
+      tipo: 'resumen3',
+      texto: m3[0],
+      agentes: parseInt(m3[1], 10),
+      skills: parseInt(m3[2], 10),
+      comandos: parseInt(m3[3], 10),
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Decide si una línea debe ignorarse por ser obviamente histórica
+ * (fila de changelog/timeline con versión SemVer + fecha en formato tabla).
+ */
+function esLineaHistorica(linea) {
+  // Tabla con versión SemVer + fecha ISO: "| 5.4.0 | 2026-04-10 | ..."
+  if (/^\s*\|\s*\d+\.\d+\.\d+\s*\|\s*\d{4}-\d{2}-\d{2}/.test(linea)) return true;
+  // "Baseline:" suele ser nota histórica
+  if (/\bBaseline\s*:/i.test(linea)) return true;
+  // "antes de v|previa a|tras release N" sugiere historia
+  if (/\b(?:antes de v|previa a|tras release|en v\d+\.\d+)\b/i.test(linea)) return true;
+  // Línea entre comillas dobles (cita textual de un patrón documentado): "22 hooks"
+  if (/"\s*\d+\s+(?:agentes|skills|habilidades|comandos|hooks|reglas)\s*"/i.test(linea)) return true;
+  return false;
+}
+
+/**
+ * Valida un archivo contra los contadores reales.
+ * Solo flagea las líneas que contienen patrón resumen identificable.
+ *
+ * Retorna { ok, lineas_revisadas, discrepancias: [{linea, encontrado, esperado, tipo, contexto}] }
+ */
+function validarArchivo(rawMd, contadoresReales) {
+  const lineas = rawMd.split(/\r?\n/);
+  const discrepancias = [];
+  let lineasRevisadas = 0;
+
+  for (let i = 0; i < lineas.length; i++) {
+    if (esLineaHistorica(lineas[i])) continue;
+    const r = extraerResumenDeLinea(lineas[i]);
+    if (!r) continue;
+    lineasRevisadas++;
+
+    const campos = r.tipo === 'resumen5'
+      ? COMPONENTES
+      : ['agentes', 'skills', 'comandos'];
+
+    for (const campo of campos) {
+      if (r[campo] !== contadoresReales[campo]) {
+        discrepancias.push({
+          linea: i + 1,
+          campo,
+          encontrado: r[campo],
+          esperado: contadoresReales[campo],
+          tipo: r.tipo,
+          contexto: lineas[i].trim().slice(0, 110),
+        });
+      }
+    }
+  }
+
+  // Patrón nominal: "**Total de agentes**: N", "**Total de skills**: N"
+  const reTotal = /\*?\*?Total\s+de\s+(agentes|skills|habilidades|comandos|hooks|reglas)\*?\*?\s*:\s*(\d{1,4})/gi;
+  for (let i = 0; i < lineas.length; i++) {
+    if (esLineaHistorica(lineas[i])) continue;
+    let m;
+    reTotal.lastIndex = 0;
+    while ((m = reTotal.exec(lineas[i])) !== null) {
+      const palabra = m[1].toLowerCase();
+      const campo = palabra === 'habilidades' ? 'skills' : palabra;
+      const num = parseInt(m[2], 10);
+      lineasRevisadas++;
+      if (num !== contadoresReales[campo]) {
+        discrepancias.push({
+          linea: i + 1,
+          campo,
+          encontrado: num,
+          esperado: contadoresReales[campo],
+          tipo: 'total_nominal',
+          contexto: lineas[i].trim().slice(0, 110),
+        });
+      }
+    }
+  }
+
+  return {
+    ok: discrepancias.length === 0,
+    lineas_revisadas: lineasRevisadas,
+    discrepancias,
+  };
+}
+
+module.exports = {
+  COMPONENTES,
+  parsearInventario,
+  extraerResumenDeLinea,
+  esLineaHistorica,
+  validarArchivo,
+};