@saulwade/swl-ses 2.2.4 → 2.3.1

package/scripts/lib/expandir-targets.js

@@ -1,71 +1,71 @@
-'use strict';
-
-/**
- * Expansión de --target (CSV) y --all-runtimes para multi-target install.
- *
- * ADR-0019 Sub-fase 2.5.
- *
- * Extraído de bin/swl-ses.js para permitir tests unitarios. NUNCA debe tener
- * side effects fuera de logging — solo manipula la lista de strings.
- *
- * @module scripts/lib/expandir-targets
- */
-
-const { listarRuntimesInstalables, RUNTIMES } = require('./detectar-runtime');
-
-/**
- * Expande las opciones del CLI a un array de target IDs.
- *
- * Reglas:
- *  - `all_runtimes` tiene prioridad sobre `target`. Si ambos vienen, se loggea
- *    aviso (vía `logger.warn`) y se usa `all_runtimes`.
- *  - `target='a,b,c'` → ['a','b','c'].
- *  - `target='claude'` → ['claude'].
- *  - Sin nada → ['claude'] (default histórico, backward-compat).
- *  - Duplicados se deduplican preservando el primer orden.
- *  - Targets desconocidos se omiten con aviso (logger.warn).
- *
- * @param {object} opciones - Objeto con `target` (string|undefined) y `all_runtimes` (bool).
- * @param {object} [logger] - Sustituible para tests. Default console.
- * @returns {{ targets: string[], omitidos: string[], errores: string[] }}
- */
-function expandirTargets(opciones, logger) {
-  const log = logger || console;
-  const omitidos = [];
-  const errores = [];
-
-  let candidatos;
-  if (opciones.all_runtimes) {
-    if (opciones.target && typeof opciones.target === 'string') {
-      log.warn && log.warn('[expandir-targets] --all-runtimes tiene prioridad sobre --target; se ignora --target.');
-    }
-    candidatos = listarRuntimesInstalables();
-  } else if (typeof opciones.target === 'string' && opciones.target.includes(',')) {
-    candidatos = opciones.target.split(',').map(s => s.trim()).filter(Boolean);
-  } else if (typeof opciones.target === 'string' && opciones.target.length > 0) {
-    candidatos = [opciones.target.trim()];
-  } else {
-    candidatos = ['claude']; // backward-compat
-  }
-
-  const visto = new Set();
-  const targets = [];
-  for (const t of candidatos) {
-    if (visto.has(t)) continue;
-    visto.add(t);
-    if (!RUNTIMES[t]) {
-      log.warn && log.warn(`[expandir-targets] Target desconocido omitido: "${t}". Disponibles: ${Object.keys(RUNTIMES).join(', ')}`);
-      omitidos.push(t);
-      continue;
-    }
-    targets.push(t);
-  }
-
-  if (targets.length === 0) {
-    errores.push('Ningún target válido tras expansión.');
-  }
-
-  return { targets, omitidos, errores };
-}
-
-module.exports = { expandirTargets };
+'use strict';
+
+/**
+ * Expansión de --target (CSV) y --all-runtimes para multi-target install.
+ *
+ * ADR-0019 Sub-fase 2.5.
+ *
+ * Extraído de bin/swl-ses.js para permitir tests unitarios. NUNCA debe tener
+ * side effects fuera de logging — solo manipula la lista de strings.
+ *
+ * @module scripts/lib/expandir-targets
+ */
+
+const { listarRuntimesInstalables, RUNTIMES } = require('./detectar-runtime');
+
+/**
+ * Expande las opciones del CLI a un array de target IDs.
+ *
+ * Reglas:
+ *  - `all_runtimes` tiene prioridad sobre `target`. Si ambos vienen, se loggea
+ *    aviso (vía `logger.warn`) y se usa `all_runtimes`.
+ *  - `target='a,b,c'` → ['a','b','c'].
+ *  - `target='claude'` → ['claude'].
+ *  - Sin nada → ['claude'] (default histórico, backward-compat).
+ *  - Duplicados se deduplican preservando el primer orden.
+ *  - Targets desconocidos se omiten con aviso (logger.warn).
+ *
+ * @param {object} opciones - Objeto con `target` (string|undefined) y `all_runtimes` (bool).
+ * @param {object} [logger] - Sustituible para tests. Default console.
+ * @returns {{ targets: string[], omitidos: string[], errores: string[] }}
+ */
+function expandirTargets(opciones, logger) {
+  const log = logger || console;
+  const omitidos = [];
+  const errores = [];
+
+  let candidatos;
+  if (opciones.all_runtimes) {
+    if (opciones.target && typeof opciones.target === 'string') {
+      log.warn && log.warn('[expandir-targets] --all-runtimes tiene prioridad sobre --target; se ignora --target.');
+    }
+    candidatos = listarRuntimesInstalables();
+  } else if (typeof opciones.target === 'string' && opciones.target.includes(',')) {
+    candidatos = opciones.target.split(',').map(s => s.trim()).filter(Boolean);
+  } else if (typeof opciones.target === 'string' && opciones.target.length > 0) {
+    candidatos = [opciones.target.trim()];
+  } else {
+    candidatos = ['claude']; // backward-compat
+  }
+
+  const visto = new Set();
+  const targets = [];
+  for (const t of candidatos) {
+    if (visto.has(t)) continue;
+    visto.add(t);
+    if (!RUNTIMES[t]) {
+      log.warn && log.warn(`[expandir-targets] Target desconocido omitido: "${t}". Disponibles: ${Object.keys(RUNTIMES).join(', ')}`);
+      omitidos.push(t);
+      continue;
+    }
+    targets.push(t);
+  }
+
+  if (targets.length === 0) {
+    errores.push('Ningún target válido tras expansión.');
+  }
+
+  return { targets, omitidos, errores };
+}
+
+module.exports = { expandirTargets };

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);
+}