@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/lib/detector-reglas-duplicadas.js

@@ -1,220 +1,220 @@
-'use strict';
-
-/**
- * scripts/lib/detector-reglas-duplicadas.js
- *
- * Detecta inline en CLAUDE.md de proyecto contenido que duplica reglas
- * globales de ~/.claude/rules/. Consume el catálogo declarativo en
- * scripts/lib/reglas-globales-conocidas.json.
- *
- * Lógica:
- *   - Cada entrada del catálogo lista patrones regex. Si ≥ min_matches
- *     patrones aciertan en el contenido del CLAUDE.md, se marca como
- *     duplicación.
- *   - Reporta línea aproximada del primer match para que el refactor
- *     pueda señalarla.
- *   - Severidad fija WARN (no bloquea). La idea es nudge, no bloqueo.
- *
- * NO emite efectos secundarios — función pura input → output.
- *
- * Public API:
- *   cargarCatalogo(rutaJson?) → catálogo parseado
- *   detectarDuplicaciones(contenido, catalogo?, opciones?) → resultado
- *
- * El módulo es zero-dependency (solo fs/path standard).
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const RUTA_CATALOGO_DEFAULT = path.join(__dirname, 'reglas-globales-conocidas.json');
-
-function cargarCatalogo(rutaJson = RUTA_CATALOGO_DEFAULT) {
-  if (!fs.existsSync(rutaJson)) {
-    throw new Error(`Catálogo no encontrado: ${rutaJson}`);
-  }
-  const raw = fs.readFileSync(rutaJson, 'utf8');
-  return JSON.parse(raw);
-}
-
-/**
- * Detecta duplicaciones de reglas globales en un CLAUDE.md.
- *
- * @param {string} contenido - Contenido completo del CLAUDE.md
- * @param {object} [catalogo] - Catálogo (default: cargar desde JSON)
- * @param {object} [opciones]
- * @param {boolean} [opciones.skipUserLevel=true] - No evaluar user-level
- * @param {boolean} [opciones.esUserLevel=false] - True si rutaClaudeMd está bajo ~/.claude/
- * @returns {object} { duplicaciones: [...], total_reglas_evaluadas: N, evaluado: bool }
- */
-function detectarDuplicaciones(contenido, catalogo = null, opciones = {}) {
-  const skipUserLevel = opciones.skipUserLevel !== false;
-  const esUserLevel = opciones.esUserLevel === true;
-
-  if (skipUserLevel && esUserLevel) {
-    return {
-      evaluado: false,
-      razon: 'user-level — no evaluado (ver configuracion.ignore_si_user_level)',
-      duplicaciones: [],
-      total_reglas_evaluadas: 0,
-    };
-  }
-
-  if (!catalogo) catalogo = cargarCatalogo();
-
-  const minLineas = catalogo.configuracion?.min_lineas_archivo ?? 20;
-  const lineasContenido = contenido.split('\n');
-
-  if (lineasContenido.length < minLineas) {
-    return {
-      evaluado: false,
-      razon: `archivo < ${minLineas} LOC — no acumula duplicaciones`,
-      duplicaciones: [],
-      total_reglas_evaluadas: 0,
-    };
-  }
-
-  const duplicaciones = [];
-
-  for (const regla of catalogo.reglas) {
-    const matches = encontrarMatches(contenido, regla.patrones);
-    const minMatches = regla.min_matches || 1;
-
-    if (matches.length >= minMatches) {
-      // Encontrar línea aproximada del primer match
-      const lineaAprox = encontrarLineaDePrimerMatch(lineasContenido, regla.patrones);
-
-      // Si el match está cerca (±3 líneas) de una referencia consciente
-      // a la regla global (`<nombre-de-regla>.md` o `@reglas/.../<regla>.md`
-      // o `@~/.claude/rules/<regla>`), NO es duplicación — es referencia legítima.
-      if (esReferenciaConsciente(lineasContenido, lineaAprox, regla.regla_global)) {
-        continue;
-      }
-
-      duplicaciones.push({
-        id: regla.id,
-        regla_global: regla.regla_global,
-        seccion_canonica: regla.seccion_canonica,
-        referencia_canonica: regla.referencia_canonica,
-        descripcion: regla.descripcion,
-        patrones_matcheados: matches.length,
-        min_matches_requeridos: minMatches,
-        linea_aproximada: lineaAprox,
-        remediacion: regla.remediacion_sugerida,
-        severidad: catalogo.configuracion?.severidad_default || 'WARN',
-      });
-    }
-  }
-
-  return {
-    evaluado: true,
-    duplicaciones,
-    total_reglas_evaluadas: catalogo.reglas.length,
-  };
-}
-
-/**
- * Cuenta cuántos patrones (de una lista) tienen al menos 1 match en el contenido.
- * No cuenta matches múltiples del mismo patrón — solo presencia/ausencia.
- */
-function encontrarMatches(contenido, patronesStr) {
-  let count = 0;
-  for (const patronStr of patronesStr) {
-    try {
-      const re = new RegExp(patronStr, 'im');
-      if (re.test(contenido)) count++;
-    } catch (e) {
-      // Patrón regex inválido — saltar silenciosamente. El catálogo es de confianza
-      // pero queremos resiliencia ante typos.
-      continue;
-    }
-  }
-  return new Array(count); // length usable por caller
-}
-
-/**
- * True si la regla global está referenciada conscientemente cerca del match,
- * en cuyo caso NO es duplicación sino mención legítima.
- *
- * "Referencia consciente" = ventana ±3 líneas alrededor del match contiene
- * el nombre del archivo de la regla global (ej. "git-coauthor.md",
- * "@~/.claude/rules/brevedad-output.md", "@reglas/...").
- *
- * Esto evita marcar como duplicación bloques que:
- *  - Citan la regla global explícitamente como referencia
- *  - Documentan override con justificación
- *  - Listan las reglas obligatorias en una tabla con descripción corta
- */
-function esReferenciaConsciente(lineas, lineaAprox, reglaGlobalArchivo) {
-  if (!lineaAprox || !reglaGlobalArchivo) return false;
-  // Ventana estrecha: línea exacta + adyacentes inmediatas (±1).
-  // Si el nombre del archivo de regla aparece en esa ventana, el bloque
-  // ya está nombrando explícitamente la regla → referencia consciente,
-  // no duplicación. Si está más lejos, probablemente es bloque inline
-  // que re-deriva la regla aunque la haya citado al principio.
-  const start = Math.max(0, lineaAprox - 2);
-  const end = Math.min(lineas.length, lineaAprox + 1);
-  const ventana = lineas.slice(start, end).join('\n');
-  // Buscar `<archivo>.md` literal en cualquier formato (`@~/.claude/rules/X.md`,
-  // `@reglas/X.md`, `<código>X.md</código>`, link markdown)
-  const re = new RegExp(escapeRegex(reglaGlobalArchivo), 'i');
-  return re.test(ventana);
-}
-
-function escapeRegex(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-/**
- * Devuelve el número de línea (1-based) del primer match encontrado entre
- * todos los patrones. Si no hay match (no debería pasar si llegamos aquí),
- * devuelve null.
- */
-function encontrarLineaDePrimerMatch(lineas, patronesStr) {
-  for (let i = 0; i < lineas.length; i++) {
-    for (const patronStr of patronesStr) {
-      try {
-        const re = new RegExp(patronStr, 'i');
-        if (re.test(lineas[i])) {
-          return i + 1;
-        }
-      } catch (e) {
-        continue;
-      }
-    }
-  }
-  return null;
-}
-
-/**
- * Construye sugerencia de refactor para una duplicación.
- * Output: bloque de texto listo para impresión por /swl:claudemd refactor.
- */
-function construirSugerenciaRefactor(duplicacion) {
-  const partes = [];
-  partes.push(`### Duplicación detectada: ${duplicacion.id}`);
-  partes.push('');
-  partes.push(`**Regla global existente**: \`~/.claude/rules/${duplicacion.regla_global}\``);
-  partes.push(`**Sección canónica**: ${duplicacion.seccion_canonica}`);
-  if (duplicacion.linea_aproximada) {
-    partes.push(`**Línea aproximada en CLAUDE.md**: ${duplicacion.linea_aproximada}`);
-  }
-  partes.push('');
-  partes.push('**Remediación sugerida**:');
-  partes.push(duplicacion.remediacion);
-  partes.push('');
-  partes.push('**Reemplazo canónico** (si se necesita mencionarla):');
-  partes.push('```markdown');
-  partes.push(`Ver ${duplicacion.referencia_canonica}.`);
-  partes.push('```');
-  return partes.join('\n');
-}
-
-module.exports = {
-  cargarCatalogo,
-  detectarDuplicaciones,
-  construirSugerenciaRefactor,
-  // exports privados para tests:
-  _encontrarLineaDePrimerMatch: encontrarLineaDePrimerMatch,
-  RUTA_CATALOGO_DEFAULT,
-};
+'use strict';
+
+/**
+ * scripts/lib/detector-reglas-duplicadas.js
+ *
+ * Detecta inline en CLAUDE.md de proyecto contenido que duplica reglas
+ * globales de ~/.claude/rules/. Consume el catálogo declarativo en
+ * scripts/lib/reglas-globales-conocidas.json.
+ *
+ * Lógica:
+ *   - Cada entrada del catálogo lista patrones regex. Si ≥ min_matches
+ *     patrones aciertan en el contenido del CLAUDE.md, se marca como
+ *     duplicación.
+ *   - Reporta línea aproximada del primer match para que el refactor
+ *     pueda señalarla.
+ *   - Severidad fija WARN (no bloquea). La idea es nudge, no bloqueo.
+ *
+ * NO emite efectos secundarios — función pura input → output.
+ *
+ * Public API:
+ *   cargarCatalogo(rutaJson?) → catálogo parseado
+ *   detectarDuplicaciones(contenido, catalogo?, opciones?) → resultado
+ *
+ * El módulo es zero-dependency (solo fs/path standard).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const RUTA_CATALOGO_DEFAULT = path.join(__dirname, 'reglas-globales-conocidas.json');
+
+function cargarCatalogo(rutaJson = RUTA_CATALOGO_DEFAULT) {
+  if (!fs.existsSync(rutaJson)) {
+    throw new Error(`Catálogo no encontrado: ${rutaJson}`);
+  }
+  const raw = fs.readFileSync(rutaJson, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Detecta duplicaciones de reglas globales en un CLAUDE.md.
+ *
+ * @param {string} contenido - Contenido completo del CLAUDE.md
+ * @param {object} [catalogo] - Catálogo (default: cargar desde JSON)
+ * @param {object} [opciones]
+ * @param {boolean} [opciones.skipUserLevel=true] - No evaluar user-level
+ * @param {boolean} [opciones.esUserLevel=false] - True si rutaClaudeMd está bajo ~/.claude/
+ * @returns {object} { duplicaciones: [...], total_reglas_evaluadas: N, evaluado: bool }
+ */
+function detectarDuplicaciones(contenido, catalogo = null, opciones = {}) {
+  const skipUserLevel = opciones.skipUserLevel !== false;
+  const esUserLevel = opciones.esUserLevel === true;
+
+  if (skipUserLevel && esUserLevel) {
+    return {
+      evaluado: false,
+      razon: 'user-level — no evaluado (ver configuracion.ignore_si_user_level)',
+      duplicaciones: [],
+      total_reglas_evaluadas: 0,
+    };
+  }
+
+  if (!catalogo) catalogo = cargarCatalogo();
+
+  const minLineas = catalogo.configuracion?.min_lineas_archivo ?? 20;
+  const lineasContenido = contenido.split('\n');
+
+  if (lineasContenido.length < minLineas) {
+    return {
+      evaluado: false,
+      razon: `archivo < ${minLineas} LOC — no acumula duplicaciones`,
+      duplicaciones: [],
+      total_reglas_evaluadas: 0,
+    };
+  }
+
+  const duplicaciones = [];
+
+  for (const regla of catalogo.reglas) {
+    const matches = encontrarMatches(contenido, regla.patrones);
+    const minMatches = regla.min_matches || 1;
+
+    if (matches.length >= minMatches) {
+      // Encontrar línea aproximada del primer match
+      const lineaAprox = encontrarLineaDePrimerMatch(lineasContenido, regla.patrones);
+
+      // Si el match está cerca (±3 líneas) de una referencia consciente
+      // a la regla global (`<nombre-de-regla>.md` o `@reglas/.../<regla>.md`
+      // o `@~/.claude/rules/<regla>`), NO es duplicación — es referencia legítima.
+      if (esReferenciaConsciente(lineasContenido, lineaAprox, regla.regla_global)) {
+        continue;
+      }
+
+      duplicaciones.push({
+        id: regla.id,
+        regla_global: regla.regla_global,
+        seccion_canonica: regla.seccion_canonica,
+        referencia_canonica: regla.referencia_canonica,
+        descripcion: regla.descripcion,
+        patrones_matcheados: matches.length,
+        min_matches_requeridos: minMatches,
+        linea_aproximada: lineaAprox,
+        remediacion: regla.remediacion_sugerida,
+        severidad: catalogo.configuracion?.severidad_default || 'WARN',
+      });
+    }
+  }
+
+  return {
+    evaluado: true,
+    duplicaciones,
+    total_reglas_evaluadas: catalogo.reglas.length,
+  };
+}
+
+/**
+ * Cuenta cuántos patrones (de una lista) tienen al menos 1 match en el contenido.
+ * No cuenta matches múltiples del mismo patrón — solo presencia/ausencia.
+ */
+function encontrarMatches(contenido, patronesStr) {
+  let count = 0;
+  for (const patronStr of patronesStr) {
+    try {
+      const re = new RegExp(patronStr, 'im');
+      if (re.test(contenido)) count++;
+    } catch (e) {
+      // Patrón regex inválido — saltar silenciosamente. El catálogo es de confianza
+      // pero queremos resiliencia ante typos.
+      continue;
+    }
+  }
+  return new Array(count); // length usable por caller
+}
+
+/**
+ * True si la regla global está referenciada conscientemente cerca del match,
+ * en cuyo caso NO es duplicación sino mención legítima.
+ *
+ * "Referencia consciente" = ventana ±3 líneas alrededor del match contiene
+ * el nombre del archivo de la regla global (ej. "git-coauthor.md",
+ * "@~/.claude/rules/brevedad-output.md", "@reglas/...").
+ *
+ * Esto evita marcar como duplicación bloques que:
+ *  - Citan la regla global explícitamente como referencia
+ *  - Documentan override con justificación
+ *  - Listan las reglas obligatorias en una tabla con descripción corta
+ */
+function esReferenciaConsciente(lineas, lineaAprox, reglaGlobalArchivo) {
+  if (!lineaAprox || !reglaGlobalArchivo) return false;
+  // Ventana estrecha: línea exacta + adyacentes inmediatas (±1).
+  // Si el nombre del archivo de regla aparece en esa ventana, el bloque
+  // ya está nombrando explícitamente la regla → referencia consciente,
+  // no duplicación. Si está más lejos, probablemente es bloque inline
+  // que re-deriva la regla aunque la haya citado al principio.
+  const start = Math.max(0, lineaAprox - 2);
+  const end = Math.min(lineas.length, lineaAprox + 1);
+  const ventana = lineas.slice(start, end).join('\n');
+  // Buscar `<archivo>.md` literal en cualquier formato (`@~/.claude/rules/X.md`,
+  // `@reglas/X.md`, `<código>X.md</código>`, link markdown)
+  const re = new RegExp(escapeRegex(reglaGlobalArchivo), 'i');
+  return re.test(ventana);
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Devuelve el número de línea (1-based) del primer match encontrado entre
+ * todos los patrones. Si no hay match (no debería pasar si llegamos aquí),
+ * devuelve null.
+ */
+function encontrarLineaDePrimerMatch(lineas, patronesStr) {
+  for (let i = 0; i < lineas.length; i++) {
+    for (const patronStr of patronesStr) {
+      try {
+        const re = new RegExp(patronStr, 'i');
+        if (re.test(lineas[i])) {
+          return i + 1;
+        }
+      } catch (e) {
+        continue;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Construye sugerencia de refactor para una duplicación.
+ * Output: bloque de texto listo para impresión por /swl:claudemd refactor.
+ */
+function construirSugerenciaRefactor(duplicacion) {
+  const partes = [];
+  partes.push(`### Duplicación detectada: ${duplicacion.id}`);
+  partes.push('');
+  partes.push(`**Regla global existente**: \`~/.claude/rules/${duplicacion.regla_global}\``);
+  partes.push(`**Sección canónica**: ${duplicacion.seccion_canonica}`);
+  if (duplicacion.linea_aproximada) {
+    partes.push(`**Línea aproximada en CLAUDE.md**: ${duplicacion.linea_aproximada}`);
+  }
+  partes.push('');
+  partes.push('**Remediación sugerida**:');
+  partes.push(duplicacion.remediacion);
+  partes.push('');
+  partes.push('**Reemplazo canónico** (si se necesita mencionarla):');
+  partes.push('```markdown');
+  partes.push(`Ver ${duplicacion.referencia_canonica}.`);
+  partes.push('```');
+  return partes.join('\n');
+}
+
+module.exports = {
+  cargarCatalogo,
+  detectarDuplicaciones,
+  construirSugerenciaRefactor,
+  // exports privados para tests:
+  _encontrarLineaDePrimerMatch: encontrarLineaDePrimerMatch,
+  RUTA_CATALOGO_DEFAULT,
+};