@saulwade/swl-ses 2.3.0 → 2.4.1

package/scripts/lib/gate-hooks-requires.js

@@ -1,249 +1,249 @@
-'use strict';
-
-/**
- * gate-hooks-requires.js
- *
- * Gate de release: cruza los `require()` relativos de los hooks DISTRIBUIDOS
- * (`hooks/**` registrados en `manifiestos/modulos.json`) que apuntan a
- * `scripts/**`, y verifica que cada lib objetivo — incluidas sus dependencias
- * TRANSITIVAS — esté registrada en `modulos.json` y cubierta en todos los
- * perfiles que instalan el hook.
- *
- * Cierra la clase de bug del caso check-update (2026-06-12): el hook requería
- * `scripts/lib/npm-version.js` (que a su vez requería `paquetes-conocidos.js`),
- * ninguna estaba en módulo alguno, y el wrapper de settings.json traga
- * MODULE_NOT_FOUND → el hook murió en silencio en TODA instalación destino
- * desde su creación. Misma familia que `ejecutarGateBinImports` (bin/ vs
- * `package.json#files`), en el eje instalador→destino.
- *
- * Hallazgos (todos bloqueantes — un hook distribuido con dependencia rota es
- * un artefacto roto para el usuario del paquete):
- *   - `lib-inexistente`: el require apunta a un archivo que no existe en repo.
- *   - `no-registrada`:   la lib existe pero no está en ningún módulo.
- *   - `sin-cobertura`:   la lib está en módulo(s), pero algún perfil instala
- *                        el módulo del hook sin ningún módulo de la lib.
- *
- * Los hooks NO registrados en modulos.json se ignoran: no se distribuyen, su
- * require solo corre en el repo madre donde scripts/ existe completo.
- *
- * Funciones puras zero-deps + entrypoint CLI `--json`.
- */
-
-const fs = require('node:fs');
-const path = require('node:path');
-
-const RE_REQUIRE_RELATIVO = /require\(\s*['"](\.\.?\/[^'"]+)['"]\s*\)/g;
-const MAX_PROFUNDIDAD_TRANSITIVA = 10;
-
-/** Extrae las rutas de los require() relativos de un código fuente. */
-function extraerRequiresRelativos(codigo) {
-  const out = [];
-  let m;
-  RE_REQUIRE_RELATIVO.lastIndex = 0;
-  while ((m = RE_REQUIRE_RELATIVO.exec(codigo)) !== null) out.push(m[1]);
-  return out;
-}
-
-/**
- * Resuelve un require relativo desde un archivo (ruta repo-relativa posix) a
- * una ruta repo-relativa del objetivo, restringida a `scripts/`.
- * @returns {string|null} 'scripts/lib/x.js' o null si no cae en scripts/.
- */
-function resolverObjetivoScripts(archivoRel, requireRel, baseDir) {
-  const dir = path.posix.dirname(archivoRel.split(path.sep).join('/'));
-  let objetivo = path.posix.normalize(path.posix.join(dir, requireRel));
-  if (!objetivo.startsWith('scripts/')) return null;
-  // Resolución estilo Node: exacto → +.js → /index.js
-  const candidatos = objetivo.endsWith('.js')
-    ? [objetivo]
-    : [objetivo, objetivo + '.js', objetivo + '/index.js'];
-  for (const c of candidatos) {
-    if (fs.existsSync(path.join(baseDir, c))) return c;
-  }
-  // No existe: devolver el candidato .js canónico para reportar lib-inexistente.
-  return objetivo.endsWith('.js') ? objetivo : objetivo + '.js';
-}
-
-/**
- * Expande una lib de scripts/ a su cierre transitivo de requires relativos
- * que permanezcan dentro de scripts/.
- * @returns {string[]} rutas repo-relativas (incluye la lib raíz).
- */
-function expandirTransitivas(baseDir, libRel, _vistos, _prof = 0) {
-  const vistos = _vistos || new Set();
-  if (vistos.has(libRel) || _prof > MAX_PROFUNDIDAD_TRANSITIVA) return [...vistos];
-  vistos.add(libRel);
-  let codigo = null;
-  try {
-    codigo = fs.readFileSync(path.join(baseDir, libRel), 'utf8');
-  } catch {
-    return [...vistos]; // inexistente: se reporta como hallazgo aguas arriba
-  }
-  for (const req of extraerRequiresRelativos(codigo)) {
-    const objetivo = resolverObjetivoScripts(libRel, req, baseDir);
-    if (objetivo) expandirTransitivas(baseDir, objetivo, vistos, _prof + 1);
-  }
-  return [...vistos];
-}
-
-/** Mapa archivo repo-relativo → array de nombres de módulo que lo declaran. */
-function _mapaArchivoModulos(modulos) {
-  const mapa = new Map();
-  for (const [nombre, mod] of Object.entries(modulos)) {
-    for (const archivo of mod.archivos || []) {
-      if (!mapa.has(archivo)) mapa.set(archivo, []);
-      mapa.get(archivo).push(nombre);
-    }
-  }
-  return mapa;
-}
-
-/** Lista recursiva de archivos .js bajo hooks/ (repo-relativos posix). */
-function _listarHooks(baseDir) {
-  const out = [];
-  const raiz = path.join(baseDir, 'hooks');
-  function walk(dir, rel) {
-    let entradas;
-    try {
-      entradas = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const e of entradas) {
-      const r = rel ? `${rel}/${e.name}` : e.name;
-      if (e.isDirectory()) walk(path.join(dir, e.name), r);
-      else if (e.isFile() && e.name.endsWith('.js')) out.push(`hooks/${r}`);
-    }
-  }
-  walk(raiz, '');
-  return out;
-}
-
-/**
- * Evalúa los requires hooks→scripts contra modulos.json + perfiles.json.
- * @returns {{disponible:boolean, hooksDistribuidos?:number, dependencias?:Array,
- *            hallazgos?:Array, error?:string}}
- */
-function evaluarHooksRequires(baseDir = process.cwd(), opts = {}) {
-  let modulos, perfiles;
-  try {
-    modulos = (opts.modulos ||
-      JSON.parse(fs.readFileSync(path.join(baseDir, 'manifiestos', 'modulos.json'), 'utf8')).modulos);
-    const p = opts.perfiles ||
-      JSON.parse(fs.readFileSync(path.join(baseDir, 'manifiestos', 'perfiles.json'), 'utf8'));
-    perfiles = p.perfiles || p;
-  } catch (err) {
-    return { disponible: false, error: 'manifiestos ilegibles: ' + err.message };
-  }
-
-  const mapa = _mapaArchivoModulos(modulos);
-  const hooks = _listarHooks(baseDir).filter((h) => mapa.has(h)); // solo distribuidos
-
-  const dependencias = [];
-  const hallazgos = [];
-
-  for (const hook of hooks) {
-    let codigo;
-    try {
-      codigo = fs.readFileSync(path.join(baseDir, hook), 'utf8');
-    } catch {
-      continue;
-    }
-    const modulosHook = mapa.get(hook);
-
-    const objetivosDirectos = new Set();
-    for (const req of extraerRequiresRelativos(codigo)) {
-      const objetivo = resolverObjetivoScripts(hook, req, baseDir);
-      if (objetivo) objetivosDirectos.add(objetivo);
-    }
-
-    // Cierre transitivo de cada objetivo directo.
-    const objetivos = new Set();
-    for (const o of objetivosDirectos) {
-      for (const t of expandirTransitivas(baseDir, o)) objetivos.add(t);
-    }
-
-    for (const lib of [...objetivos].sort()) {
-      const existe = fs.existsSync(path.join(baseDir, lib));
-      const modulosLib = mapa.get(lib) || [];
-      const dep = { hook, lib, modulosHook, modulosLib, ok: true };
-
-      if (!existe) {
-        dep.ok = false;
-        hallazgos.push({
-          tipo: 'lib-inexistente',
-          hook,
-          lib,
-          detalle: `${hook} requiere ${lib} pero el archivo no existe en el repo`,
-        });
-      } else if (modulosLib.length === 0) {
-        dep.ok = false;
-        hallazgos.push({
-          tipo: 'no-registrada',
-          hook,
-          lib,
-          detalle:
-            `${hook} (módulo ${modulosHook.join(',')}) requiere ${lib} que NO está ` +
-            `en ningún módulo de modulos.json — el hook morirá en silencio en el destino`,
-        });
-      } else {
-        // Cobertura: todo perfil que instala el hook debe instalar la lib.
-        const perfilesSinLib = [];
-        for (const [nombrePerfil, perfil] of Object.entries(perfiles)) {
-          const mods = perfil.modulos || [];
-          const instalaHook = modulosHook.some((m) => mods.includes(m));
-          const instalaLib = modulosLib.some((m) => mods.includes(m));
-          if (instalaHook && !instalaLib) perfilesSinLib.push(nombrePerfil);
-        }
-        if (perfilesSinLib.length > 0) {
-          dep.ok = false;
-          dep.perfilesSinLib = perfilesSinLib;
-          hallazgos.push({
-            tipo: 'sin-cobertura',
-            hook,
-            lib,
-            detalle:
-              `${lib} (módulo ${modulosLib.join(',')}) no llega a los perfiles que ` +
-              `instalan ${hook}: ${perfilesSinLib.join(', ')}`,
-          });
-        }
-      }
-      dependencias.push(dep);
-    }
-  }
-
-  return {
-    disponible: true,
-    hooksDistribuidos: hooks.length,
-    dependencias,
-    hallazgos,
-  };
-}
-
-module.exports = {
-  evaluarHooksRequires,
-  extraerRequiresRelativos,
-  resolverObjetivoScripts,
-  expandirTransitivas,
-};
-
-// Entrypoint CLI: node scripts/lib/gate-hooks-requires.js [--json] [baseDir]
-if (!require.main || require.main === module) {
-  const args = process.argv.slice(2);
-  const json = args.includes('--json');
-  const baseDir = args.find((a) => !a.startsWith('--')) || process.cwd();
-  const r = evaluarHooksRequires(baseDir);
-
-  if (json) {
-    process.stdout.write(JSON.stringify(r, null, 2) + '\n');
-  } else if (!r.disponible) {
-    process.stdout.write(`Gate hooks-requires no disponible: ${r.error}\n`);
-  } else {
-    process.stdout.write(
-      `Hooks distribuidos analizados: ${r.hooksDistribuidos} | ` +
-      `dependencias hooks→scripts: ${r.dependencias.length} | hallazgos: ${r.hallazgos.length}\n`
-    );
-    for (const h of r.hallazgos) process.stdout.write(`  [${h.tipo}] ${h.detalle}\n`);
-  }
-  process.exit(r.disponible && r.hallazgos && r.hallazgos.length > 0 ? 1 : 0);
-}
+'use strict';
+
+/**
+ * gate-hooks-requires.js
+ *
+ * Gate de release: cruza los `require()` relativos de los hooks DISTRIBUIDOS
+ * (`hooks/**` registrados en `manifiestos/modulos.json`) que apuntan a
+ * `scripts/**`, y verifica que cada lib objetivo — incluidas sus dependencias
+ * TRANSITIVAS — esté registrada en `modulos.json` y cubierta en todos los
+ * perfiles que instalan el hook.
+ *
+ * Cierra la clase de bug del caso check-update (2026-06-12): el hook requería
+ * `scripts/lib/npm-version.js` (que a su vez requería `paquetes-conocidos.js`),
+ * ninguna estaba en módulo alguno, y el wrapper de settings.json traga
+ * MODULE_NOT_FOUND → el hook murió en silencio en TODA instalación destino
+ * desde su creación. Misma familia que `ejecutarGateBinImports` (bin/ vs
+ * `package.json#files`), en el eje instalador→destino.
+ *
+ * Hallazgos (todos bloqueantes — un hook distribuido con dependencia rota es
+ * un artefacto roto para el usuario del paquete):
+ *   - `lib-inexistente`: el require apunta a un archivo que no existe en repo.
+ *   - `no-registrada`:   la lib existe pero no está en ningún módulo.
+ *   - `sin-cobertura`:   la lib está en módulo(s), pero algún perfil instala
+ *                        el módulo del hook sin ningún módulo de la lib.
+ *
+ * Los hooks NO registrados en modulos.json se ignoran: no se distribuyen, su
+ * require solo corre en el repo madre donde scripts/ existe completo.
+ *
+ * Funciones puras zero-deps + entrypoint CLI `--json`.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const RE_REQUIRE_RELATIVO = /require\(\s*['"](\.\.?\/[^'"]+)['"]\s*\)/g;
+const MAX_PROFUNDIDAD_TRANSITIVA = 10;
+
+/** Extrae las rutas de los require() relativos de un código fuente. */
+function extraerRequiresRelativos(codigo) {
+  const out = [];
+  let m;
+  RE_REQUIRE_RELATIVO.lastIndex = 0;
+  while ((m = RE_REQUIRE_RELATIVO.exec(codigo)) !== null) out.push(m[1]);
+  return out;
+}
+
+/**
+ * Resuelve un require relativo desde un archivo (ruta repo-relativa posix) a
+ * una ruta repo-relativa del objetivo, restringida a `scripts/`.
+ * @returns {string|null} 'scripts/lib/x.js' o null si no cae en scripts/.
+ */
+function resolverObjetivoScripts(archivoRel, requireRel, baseDir) {
+  const dir = path.posix.dirname(archivoRel.split(path.sep).join('/'));
+  let objetivo = path.posix.normalize(path.posix.join(dir, requireRel));
+  if (!objetivo.startsWith('scripts/')) return null;
+  // Resolución estilo Node: exacto → +.js → /index.js
+  const candidatos = objetivo.endsWith('.js')
+    ? [objetivo]
+    : [objetivo, objetivo + '.js', objetivo + '/index.js'];
+  for (const c of candidatos) {
+    if (fs.existsSync(path.join(baseDir, c))) return c;
+  }
+  // No existe: devolver el candidato .js canónico para reportar lib-inexistente.
+  return objetivo.endsWith('.js') ? objetivo : objetivo + '.js';
+}
+
+/**
+ * Expande una lib de scripts/ a su cierre transitivo de requires relativos
+ * que permanezcan dentro de scripts/.
+ * @returns {string[]} rutas repo-relativas (incluye la lib raíz).
+ */
+function expandirTransitivas(baseDir, libRel, _vistos, _prof = 0) {
+  const vistos = _vistos || new Set();
+  if (vistos.has(libRel) || _prof > MAX_PROFUNDIDAD_TRANSITIVA) return [...vistos];
+  vistos.add(libRel);
+  let codigo = null;
+  try {
+    codigo = fs.readFileSync(path.join(baseDir, libRel), 'utf8');
+  } catch {
+    return [...vistos]; // inexistente: se reporta como hallazgo aguas arriba
+  }
+  for (const req of extraerRequiresRelativos(codigo)) {
+    const objetivo = resolverObjetivoScripts(libRel, req, baseDir);
+    if (objetivo) expandirTransitivas(baseDir, objetivo, vistos, _prof + 1);
+  }
+  return [...vistos];
+}
+
+/** Mapa archivo repo-relativo → array de nombres de módulo que lo declaran. */
+function _mapaArchivoModulos(modulos) {
+  const mapa = new Map();
+  for (const [nombre, mod] of Object.entries(modulos)) {
+    for (const archivo of mod.archivos || []) {
+      if (!mapa.has(archivo)) mapa.set(archivo, []);
+      mapa.get(archivo).push(nombre);
+    }
+  }
+  return mapa;
+}
+
+/** Lista recursiva de archivos .js bajo hooks/ (repo-relativos posix). */
+function _listarHooks(baseDir) {
+  const out = [];
+  const raiz = path.join(baseDir, 'hooks');
+  function walk(dir, rel) {
+    let entradas;
+    try {
+      entradas = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entradas) {
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) walk(path.join(dir, e.name), r);
+      else if (e.isFile() && e.name.endsWith('.js')) out.push(`hooks/${r}`);
+    }
+  }
+  walk(raiz, '');
+  return out;
+}
+
+/**
+ * Evalúa los requires hooks→scripts contra modulos.json + perfiles.json.
+ * @returns {{disponible:boolean, hooksDistribuidos?:number, dependencias?:Array,
+ *            hallazgos?:Array, error?:string}}
+ */
+function evaluarHooksRequires(baseDir = process.cwd(), opts = {}) {
+  let modulos, perfiles;
+  try {
+    modulos = (opts.modulos ||
+      JSON.parse(fs.readFileSync(path.join(baseDir, 'manifiestos', 'modulos.json'), 'utf8')).modulos);
+    const p = opts.perfiles ||
+      JSON.parse(fs.readFileSync(path.join(baseDir, 'manifiestos', 'perfiles.json'), 'utf8'));
+    perfiles = p.perfiles || p;
+  } catch (err) {
+    return { disponible: false, error: 'manifiestos ilegibles: ' + err.message };
+  }
+
+  const mapa = _mapaArchivoModulos(modulos);
+  const hooks = _listarHooks(baseDir).filter((h) => mapa.has(h)); // solo distribuidos
+
+  const dependencias = [];
+  const hallazgos = [];
+
+  for (const hook of hooks) {
+    let codigo;
+    try {
+      codigo = fs.readFileSync(path.join(baseDir, hook), 'utf8');
+    } catch {
+      continue;
+    }
+    const modulosHook = mapa.get(hook);
+
+    const objetivosDirectos = new Set();
+    for (const req of extraerRequiresRelativos(codigo)) {
+      const objetivo = resolverObjetivoScripts(hook, req, baseDir);
+      if (objetivo) objetivosDirectos.add(objetivo);
+    }
+
+    // Cierre transitivo de cada objetivo directo.
+    const objetivos = new Set();
+    for (const o of objetivosDirectos) {
+      for (const t of expandirTransitivas(baseDir, o)) objetivos.add(t);
+    }
+
+    for (const lib of [...objetivos].sort()) {
+      const existe = fs.existsSync(path.join(baseDir, lib));
+      const modulosLib = mapa.get(lib) || [];
+      const dep = { hook, lib, modulosHook, modulosLib, ok: true };
+
+      if (!existe) {
+        dep.ok = false;
+        hallazgos.push({
+          tipo: 'lib-inexistente',
+          hook,
+          lib,
+          detalle: `${hook} requiere ${lib} pero el archivo no existe en el repo`,
+        });
+      } else if (modulosLib.length === 0) {
+        dep.ok = false;
+        hallazgos.push({
+          tipo: 'no-registrada',
+          hook,
+          lib,
+          detalle:
+            `${hook} (módulo ${modulosHook.join(',')}) requiere ${lib} que NO está ` +
+            `en ningún módulo de modulos.json — el hook morirá en silencio en el destino`,
+        });
+      } else {
+        // Cobertura: todo perfil que instala el hook debe instalar la lib.
+        const perfilesSinLib = [];
+        for (const [nombrePerfil, perfil] of Object.entries(perfiles)) {
+          const mods = perfil.modulos || [];
+          const instalaHook = modulosHook.some((m) => mods.includes(m));
+          const instalaLib = modulosLib.some((m) => mods.includes(m));
+          if (instalaHook && !instalaLib) perfilesSinLib.push(nombrePerfil);
+        }
+        if (perfilesSinLib.length > 0) {
+          dep.ok = false;
+          dep.perfilesSinLib = perfilesSinLib;
+          hallazgos.push({
+            tipo: 'sin-cobertura',
+            hook,
+            lib,
+            detalle:
+              `${lib} (módulo ${modulosLib.join(',')}) no llega a los perfiles que ` +
+              `instalan ${hook}: ${perfilesSinLib.join(', ')}`,
+          });
+        }
+      }
+      dependencias.push(dep);
+    }
+  }
+
+  return {
+    disponible: true,
+    hooksDistribuidos: hooks.length,
+    dependencias,
+    hallazgos,
+  };
+}
+
+module.exports = {
+  evaluarHooksRequires,
+  extraerRequiresRelativos,
+  resolverObjetivoScripts,
+  expandirTransitivas,
+};
+
+// Entrypoint CLI: node scripts/lib/gate-hooks-requires.js [--json] [baseDir]
+if (!require.main || require.main === module) {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const baseDir = args.find((a) => !a.startsWith('--')) || process.cwd();
+  const r = evaluarHooksRequires(baseDir);
+
+  if (json) {
+    process.stdout.write(JSON.stringify(r, null, 2) + '\n');
+  } else if (!r.disponible) {
+    process.stdout.write(`Gate hooks-requires no disponible: ${r.error}\n`);
+  } else {
+    process.stdout.write(
+      `Hooks distribuidos analizados: ${r.hooksDistribuidos} | ` +
+      `dependencias hooks→scripts: ${r.dependencias.length} | hallazgos: ${r.hallazgos.length}\n`
+    );
+    for (const h of r.hallazgos) process.stdout.write(`  [${h.tipo}] ${h.detalle}\n`);
+  }
+  process.exit(r.disponible && r.hallazgos && r.hallazgos.length > 0 ? 1 : 0);
+}