@saulwade/swl-ses 1.6.7 → 1.7.0

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

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

package/scripts/lib/reglas-globales-conocidas.json

@@ -0,0 +1,112 @@
+{
+  "$schema-version": "1.0.0",
+  "description": "Catálogo de reglas globales ~/.claude/rules/ que NO deben duplicarse inline en CLAUDE.md de proyectos. Consumido por scripts/lib/detector-reglas-duplicadas.js y por scripts/auditar-claudemd.js dimensión 'duplicacion-reglas-globales'. Cada entrada lista: nombre canónico, archivo origen, sección canónica para referenciar, patrones de detección (regex), y reemplazo sugerido.",
+  "version": "1.0.0",
+  "actualizado": "2026-05-22",
+  "reglas": [
+    {
+      "id": "idioma-espanol-mexico",
+      "regla_global": "brevedad-output.md",
+      "seccion_canonica": "Idioma obligatorio: español de México",
+      "referencia_canonica": "@~/.claude/rules/brevedad-output.md § Idioma obligatorio",
+      "descripcion": "Idioma obligatorio español de México en todo contenido generado. Ya cubierto globalmente.",
+      "patrones": [
+        "\\bespañol\\s+de\\s+M[ée]xico\\b",
+        "\\bidioma\\s+obligatorio\\b",
+        "\\bacentuaci[oó]n\\s+correcta\\b",
+        "\\bgram[aá]tica\\s+normativa\\b",
+        "\\bevitar\\s+anglicismos\\b",
+        "^\\s*#+\\s*Language\\s*$",
+        "\\bdomain\\s+terms\\b.*\\bin\\s+\\*?\\*?Spanish\\*?\\*?",
+        "\\bmensajes?\\s+de\\s+commit.*siempre\\s+en\\s+español\\b"
+      ],
+      "min_matches": 2,
+      "scope": "project-level",
+      "remediacion_sugerida": "Eliminar el bloque local de idioma. La regla global `~/.claude/rules/brevedad-output.md` (cargada en cada sesión SWL) ya lo cubre. Si el proyecto tiene matices propios (ej: identificadores técnicos en inglés), conservar SOLO esos matices con frase corta: \"Convenciones locales: identificadores técnicos en inglés (rutas, comandos)\"."
+    },
+    {
+      "id": "brevedad-sin-aiisms",
+      "regla_global": "brevedad-output.md",
+      "seccion_canonica": "Brevedad y eficiencia de output",
+      "referencia_canonica": "@~/.claude/rules/brevedad-output.md § Brevedad y eficiencia de output",
+      "descripcion": "Brevedad, sin preámbulos de cortesía ni cierres. Ya cubierto globalmente.",
+      "patrones": [
+        "\\bsin\\s+pre[aá]mbulos\\s+de\\s+cortes[ií]a\\b",
+        "\\bnunca\\s+iniciar\\s+con\\s+[\"']?claro",
+        "\\bnunca\\s+terminar\\s+con\\s+[\"']?espero",
+        "\\bno\\s+iniciar\\s+respuestas?\\s+con\\b.*\\bcortes[ií]a"
+      ],
+      "min_matches": 1,
+      "scope": "project-level",
+      "remediacion_sugerida": "Eliminar el bloque local de brevedad. La regla global ya cubre el contrato. Si el proyecto tiene matices (formato específico de revisiones, etc.) conservar solo esos."
+    },
+    {
+      "id": "git-sin-coautores",
+      "regla_global": "git-coauthor.md",
+      "seccion_canonica": "Sin co-autores en commits",
+      "referencia_canonica": "@~/.claude/rules/git-coauthor.md",
+      "descripcion": "Los commits NO deben incluir Co-Authored-By de Claude/IA. Ya cubierto globalmente.",
+      "patrones": [
+        "\\bSin\\s+co-?autores\\s+en\\s+commits\\b",
+        "\\bNO\\s+incluir\\s+Co-Authored-By\\b",
+        "\\bnunca\\s+incluir\\s+[\"']?Co-Authored-By:\\s+Claude",
+        "\\bsin\\s+atribuci[oó]n\\s+a\\s+Claude\\b"
+      ],
+      "min_matches": 1,
+      "scope": "project-level",
+      "remediacion_sugerida": "Eliminar el bloque local. La regla global `~/.claude/rules/git-coauthor.md` aplica a todos los proyectos del usuario."
+    },
+    {
+      "id": "arreglar-al-detectar",
+      "regla_global": "arreglar-al-detectar.md",
+      "seccion_canonica": "Detectar → Informar → Arreglar en mismo turno",
+      "referencia_canonica": "@~/.claude/rules/arreglar-al-detectar.md",
+      "descripcion": "Patrón detectar-informar-arreglar en mismo turno. Ya cubierto globalmente.",
+      "patrones": [
+        "\\bdetectar\\s*[→\\-]\\s*informar\\s*[→\\-]\\s*arreglar\\b",
+        "\\bno\\s+dejar\\s+pendientes\\b.*\\barreglar\\s+en\\s+(el\\s+)?mismo\\s+turno",
+        "\\barreglar\\s+en\\s+mismo\\s+turno\\b"
+      ],
+      "min_matches": 1,
+      "scope": "project-level",
+      "remediacion_sugerida": "Eliminar el bloque local. La regla global cubre el principio. Si el proyecto tiene excepciones específicas (fix urgente con incidente activo), documentarlas como excepción local sin re-derivar el principio."
+    },
+    {
+      "id": "debatir-antes-de-aceptar",
+      "regla_global": "debatir-antes-de-aceptar.md",
+      "seccion_canonica": "Debatir antes de aceptar decisiones que chocan con reglas",
+      "referencia_canonica": "@~/.claude/rules/debatir-antes-de-aceptar.md",
+      "descripcion": "Debatir decisiones del usuario que chocan con reglas documentadas. Ya cubierto globalmente.",
+      "patrones": [
+        "\\bdebatir\\s+antes\\s+de\\s+aceptar\\b",
+        "\\bnunca\\s+la\\s+aceptes\\s+por\\s+reflejo\\b",
+        "\\bcita\\s+concreta\\s*\\+\\s*riesgo\\s+observable\\s*\\+\\s*alternativa\\b"
+      ],
+      "min_matches": 1,
+      "scope": "project-level",
+      "remediacion_sugerida": "Eliminar el bloque local. La regla global aplica."
+    },
+    {
+      "id": "usar-context7",
+      "regla_global": "usar-context7.md",
+      "seccion_canonica": "Consultar Context7 antes de generar código con dependencias externas",
+      "referencia_canonica": "@~/.claude/rules/usar-context7.md",
+      "descripcion": "Consultar Context7 antes de agregar/usar librerías externas. Ya cubierto globalmente.",
+      "patrones": [
+        "\\bconsultar\\s+Context7\\s+antes\\b",
+        "\\bantes\\s+de\\s+agregar\\s+dependencia\\b.*\\bverificar\\b",
+        "\\bContext7\\s+obligatorio\\b"
+      ],
+      "min_matches": 1,
+      "scope": "project-level",
+      "remediacion_sugerida": "Eliminar el bloque local. La regla global aplica."
+    }
+  ],
+  "configuracion": {
+    "severidad_default": "WARN",
+    "scope_default": "project-level",
+    "ignore_si_user_level": true,
+    "min_lineas_archivo": 20,
+    "comentario": "Solo evaluar archivos >=20 LOC (CLAUDE.md mínimos no acumulan duplicaciones). User-level (~/.claude/CLAUDE.md) NO se evalúa contra este detector porque ahí sí puede declarar preferencias personales."
+  }
+}