@saulwade/swl-ses 2.0.0 → 2.1.0

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

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

package/scripts/lib/gate-licencias.js

@@ -0,0 +1,212 @@
+'use strict';
+
+/**
+ * gate-licencias.js — Clasificación de licencias del árbol runtime (Fase 14, ADR-0038).
+ *
+ * Gate de cadena de suministro: detecta licencias copyleft contaminantes en las
+ * dependencias de producción antes de un release. Zero-dependencies — lee
+ * `package-lock.json` (v3) y clasifica cada dependencia prod contra listas SPDX.
+ *
+ * Modo de uso en /swl:release: WARN-ONLY (D-14-02). Reporta hallazgos pero NUNCA
+ * bloquea el release en v1 — la promoción a blocking exigiría calibración + ADR
+ * posterior (mismo patrón que los gates G0/G2/G3).
+ *
+ * Clasificación de expresiones SPDX:
+ *   - OR  → el consumidor ELIGE un término → clasifica por el MEJOR (menos restrictivo).
+ *   - AND → ambos términos APLICAN → clasifica por el PEOR (más restrictivo).
+ *
+ * Severidad (de menor a mayor restricción): permisiva < débil < fuerte; "desconocida"
+ * es categoría propia (metadata ausente o no catalogada), no un error.
+ *
+ * Origen: Fase 14 — cadena de suministro en release (P4, ADR-0038).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Listas SPDX (normalizadas a mayúsculas). El matching es por PREFIJO de la
+// familia para tolerar variantes `-only` / `-or-later` (ej. GPL-3.0-or-later).
+const FAMILIAS_FUERTES = ['GPL', 'AGPL', 'SSPL', 'OSL', 'EUPL', 'CDDL'];
+const FAMILIAS_DEBILES = ['LGPL', 'MPL', 'EPL', 'CPL', 'MS-RL'];
+const PERMISIVAS = new Set([
+  'MIT', 'ISC', 'APACHE-2.0', 'APACHE 2.0', 'BSD', 'BSD-2-CLAUSE', 'BSD-3-CLAUSE',
+  '0BSD', 'UNLICENSE', 'CC0-1.0', 'WTFPL', 'BLUEOAK-1.0.0', 'ZLIB', 'PYTHON-2.0',
+  'APACHE-2.0 WITH LLVM-EXCEPTION',
+]);
+
+// Orden de severidad para resolver expresiones OR/AND. NOTA: `desconocida: 0`
+// NO es un grado ordinal de copyleft — es categoría especial. En `clasificarExprOr`
+// las "desconocidas" se filtran ANTES del reduce cuando hay algún término
+// catalogado, por lo que su valor 0 nunca contamina la elección del mejor/peor.
+const SEVERIDAD = { desconocida: 0, permisiva: 1, debil: 2, fuerte: 3 };
+
+// Cota de profundidad de recursión para licencias anidadas (array de arrays);
+// un package.json malicioso con anidamiento profundo no debe tumbar la auditoría.
+const MAX_PROFUNDIDAD_LICENCIA = 10;
+
+/**
+ * Normaliza un identificador de licencia simple (sin operadores) a su clasificación.
+ * @param {string} idRaw
+ * @returns {'fuerte'|'debil'|'permisiva'|'desconocida'}
+ */
+function clasificarSimple(idRaw) {
+  if (typeof idRaw !== 'string') return 'desconocida';
+  const id = idRaw.trim().toUpperCase().replace(/^\(/, '').replace(/\)$/, '').trim();
+  if (!id) return 'desconocida';
+  // Familias copyleft por prefijo (cubre -ONLY / -OR-LATER / versiones).
+  for (const fam of FAMILIAS_FUERTES) {
+    if (id === fam || id.startsWith(fam + '-') || id.startsWith(fam + ' ')) return 'fuerte';
+  }
+  for (const fam of FAMILIAS_DEBILES) {
+    if (id === fam || id.startsWith(fam + '-') || id.startsWith(fam + ' ')) return 'debil';
+  }
+  if (PERMISIVAS.has(id)) return 'permisiva';
+  return 'desconocida';
+}
+
+/**
+ * Clasifica una licencia npm: string SPDX (con OR/AND), objeto legacy {type},
+ * arreglo legacy de objetos, o ausente.
+ *
+ * @param {string|object|Array|undefined|null} valor
+ * @param {number} [_depth=0]  profundidad interna de recursión (cota anti-DoS)
+ * @returns {'fuerte'|'debil'|'permisiva'|'desconocida'}
+ */
+function clasificarLicencia(valor, _depth = 0) {
+  if (valor == null) return 'desconocida';
+  if (_depth > MAX_PROFUNDIDAD_LICENCIA) return 'desconocida'; // anidamiento abusivo
+
+  // Objeto legacy { type: 'MIT' }
+  if (typeof valor === 'object' && !Array.isArray(valor)) {
+    return clasificarLicencia(valor.type, _depth + 1);
+  }
+  // Arreglo legacy [{ type }] → tratar como OR (el consumidor elige)
+  if (Array.isArray(valor)) {
+    const cls = valor.map((v) => clasificarLicencia(v && v.type ? v.type : v, _depth + 1));
+    return cls.reduce((mejor, c) => (SEVERIDAD[c] < SEVERIDAD[mejor] ? c : mejor), 'fuerte');
+  }
+  if (typeof valor !== 'string') return 'desconocida';
+
+  const expr = valor.trim();
+  if (!expr) return 'desconocida';
+
+  // Expresión AND: ambas aplican → el PEOR término manda.
+  if (/\bAND\b/i.test(expr)) {
+    const partes = expr.replace(/[()]/g, ' ').split(/\bAND\b/i).map((s) => s.trim()).filter(Boolean);
+    return partes
+      .map((p) => clasificarExprOr(p))
+      .reduce((peor, c) => (SEVERIDAD[c] > SEVERIDAD[peor] ? c : peor), 'desconocida');
+  }
+  return clasificarExprOr(expr);
+}
+
+/**
+ * Resuelve una expresión que puede contener OR (el MEJOR término manda) o un
+ * identificador simple.
+ * @param {string} expr
+ * @returns {'fuerte'|'debil'|'permisiva'|'desconocida'}
+ */
+function clasificarExprOr(expr) {
+  if (/\bOR\b/i.test(expr)) {
+    const partes = expr.replace(/[()]/g, ' ').split(/\bOR\b/i).map((s) => s.trim()).filter(Boolean);
+    // mejor = menor severidad, pero ignorando "desconocida" si hay algo catalogado
+    const clasifs = partes.map((p) => clasificarSimple(p));
+    const catalogadas = clasifs.filter((c) => c !== 'desconocida');
+    const pool = catalogadas.length ? catalogadas : clasifs;
+    return pool.reduce((mejor, c) => (SEVERIDAD[c] < SEVERIDAD[mejor] ? c : mejor), 'fuerte');
+  }
+  return clasificarSimple(expr);
+}
+
+/**
+ * Resuelve la licencia de un paquete: primero el campo del lockfile, con fallback
+ * al package.json instalado en node_modules/<ruta>.
+ *
+ * @param {string} baseDir
+ * @param {string} rutaNodeModules  clave del lockfile, ej. "node_modules/foo"
+ * @param {object} entradaLock
+ * @returns {string|object|undefined}
+ */
+function resolverLicencia(baseDir, rutaNodeModules, entradaLock) {
+  if (entradaLock && entradaLock.license != null) return entradaLock.license;
+  if (entradaLock && entradaLock.licenses != null) return entradaLock.licenses; // legacy array
+  // Fallback: leer el package.json instalado.
+  try {
+    const pkgPath = path.join(baseDir, rutaNodeModules, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg.license != null ? pkg.license : pkg.licenses;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Evalúa las licencias del árbol de producción a partir de package-lock.json.
+ * Excluye entradas marcadas `dev: true` y la raíz "".
+ *
+ * @param {string} baseDir  raíz del proyecto (contiene package-lock.json)
+ * @returns {{hallazgos: Array<{paquete:string, version:string, licencia:string, clasificacion:string}>, resumen: {fuerte:number, debil:number, permisiva:number, desconocida:number}}}
+ */
+function evaluarLicencias(baseDir) {
+  const resumen = { fuerte: 0, debil: 0, permisiva: 0, desconocida: 0 };
+  const hallazgos = [];
+
+  const lockPath = path.join(baseDir, 'package-lock.json');
+  let lock;
+  try {
+    lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+  } catch (err) {
+    // Sin lockfile (ENOENT) → resultado vacío, no es error. Pero un lockfile
+    // corrupto (SyntaxError) o sin permisos (EACCES) SÍ se propaga: enmascararlo
+    // como "sin deps copyleft" daría un falso OK. El caller (verificar-release)
+    // lo captura y reporta como gate "no disponible".
+    if (err.code === 'ENOENT') return { hallazgos, resumen };
+    throw err;
+  }
+
+  const packages = lock.packages || {};
+  for (const [ruta, entrada] of Object.entries(packages)) {
+    if (!ruta || !ruta.startsWith('node_modules/')) continue; // raíz "" y workspaces fuera
+    if (entrada && entrada.dev) continue; // solo árbol prod
+    const licValor = resolverLicencia(baseDir, ruta, entrada);
+    const clasificacion = clasificarLicencia(licValor);
+    const licenciaStr = typeof licValor === 'string'
+      ? licValor
+      : (licValor && licValor.type) ? licValor.type
+      : (licValor == null ? '(ninguna)' : JSON.stringify(licValor));
+    hallazgos.push({
+      paquete: ruta.replace(/^node_modules\//, '').replace(/\/node_modules\//g, ' > '),
+      version: (entrada && entrada.version) || '?',
+      licencia: licenciaStr,
+      clasificacion,
+    });
+    resumen[clasificacion]++;
+  }
+
+  return { hallazgos, resumen };
+}
+
+// --- CLI ---------------------------------------------------------------------
+
+if (require.main === module) {
+  const res = evaluarLicencias(process.cwd());
+  console.log('Gate de licencias (árbol prod):');
+  console.log(`  permisiva: ${res.resumen.permisiva} | débil: ${res.resumen.debil} | fuerte: ${res.resumen.fuerte} | desconocida: ${res.resumen.desconocida}`);
+  const alertas = res.hallazgos.filter((h) => h.clasificacion !== 'permisiva');
+  if (alertas.length) {
+    console.log('\nHallazgos no permisivos (WARN — no bloquea el release):');
+    for (const h of alertas) {
+      console.log(`  [${h.clasificacion.toUpperCase()}] ${h.paquete}@${h.version} — ${h.licencia}`);
+    }
+  } else {
+    console.log('  Todas las dependencias de producción son permisivas.');
+  }
+}
+
+module.exports = {
+  clasificarLicencia,
+  evaluarLicencias,
+  resolverLicencia,
+  FAMILIAS_FUERTES,
+  FAMILIAS_DEBILES,
+};