@saulwade/swl-ses 1.0.0

package/hooks/calidad-pre-commit.js

@@ -0,0 +1,929 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: calidad-pre-commit.js
+ * Tipo: PreToolUse  (aplica a: Bash — comandos git commit)
+ *
+ * Verifica calidad mínima del código staged ANTES de que Claude Code
+ * ejecute un `git commit`. Si detecta violaciones, bloquea el commit
+ * y lista los problemas encontrados con archivo y número de línea.
+ *
+ * Verificaciones por tipo de archivo:
+ *
+ *   Todos los archivos:
+ *     - Sin credenciales hardcodeadas (password=, secret=, api_key=, token=)
+ *     - Sin archivos > 1 MB siendo commiteados
+ *     - Sin pendientes (TO-DO) sin referencia a ticket/issue
+ *
+ *   Archivos .py / .ts / .js:
+ *     - Sin console.log() de debug (.ts / .js)
+ *     - Sin print() de debug (.py) — excluye print dentro de if __name__
+ *
+ *   Archivos .py:
+ *     - Funciones públicas deben tener type hints en parámetros y retorno
+ *
+ *   Archivos de producción multi-lenguaje (excluyen test/spec):
+ *     - .java  → Sin System.out.println/printf/print
+ *     - .go    → Sin fmt.Println/Printf/Print
+ *     - .rs    → Sin println!/print!/eprintln!/eprint!
+ *     - .cs    → Sin Console.WriteLine/Write/Error.WriteLine
+ *     - .kt/.kts → Sin println()
+ *     - .php   → Sin var_dump/dd/dump/print_r/die
+ *     - .swift → Sin print()
+ *
+ * Resultado:
+ *   - Violaciones encontradas → razón en stdout + exit code 2 (block)
+ *   - Sin violaciones         → sin output, proceso termina naturalmente
+ *   - Error interno           → sin output (nunca bloquear por fallo del hook)
+ *
+ * NOTA: Este hook aplica solo cuando el comando Bash contiene "git commit".
+ * Para hooks de git nativos (.git/hooks/pre-commit), usar un script shell
+ * que llame a este archivo directamente.
+ */
+
+const fs          = require('fs');
+const path        = require('path');
+const { execSync } = require('child_process');
+
+const { normalizeForDetection } = require('./lib/normalize-input');
+
+// ---------------------------------------------------------------------------
+// Constantes de configuración
+// ---------------------------------------------------------------------------
+
+/** Tamaño máximo permitido por archivo a commitear (en bytes). */
+const LIMITE_TAMANO_BYTES = 1024 * 1024; // 1 MB
+
+/**
+ * Patrones de credenciales hardcodeadas.
+ * Se evalúan línea por línea en todos los archivos de texto.
+ */
+const PATRONES_CREDENCIALES = [
+  {
+    nombre: 'password hardcodeado',
+    // password = "valor", password: "valor" — no captura placeholders vacíos
+    patron: /\bpassword\s*[=:]\s*["'][^"'\s]{4,}["']/i,
+  },
+  {
+    nombre: 'secret hardcodeado',
+    patron: /\bsecret\s*[=:]\s*["'][^"'\s]{4,}["']/i,
+  },
+  {
+    nombre: 'api_key hardcodeada',
+    patron: /\bapi_key\s*[=:]\s*["'][^"'\s]{4,}["']/i,
+  },
+  {
+    nombre: 'token hardcodeado',
+    // "token" como variable independiente, no como parte de otra palabra
+    patron: /\btoken\s*[=:]\s*["'][^"'\s]{8,}["']/i,
+  },
+];
+
+/**
+ * Marcadores que indican que un valor es un placeholder y no una credencial real.
+ * Si la línea contiene alguno de estos, se omite la alerta de credencial.
+ */
+const MARCADORES_PLACEHOLDER_CREDENCIAL = [
+  'YOUR_',
+  'your_',
+  '<YOUR',
+  'PLACEHOLDER',
+  'placeholder',
+  'example',
+  'fake_',
+  'dummy_',
+  'xxxxxxxx',
+  'os.environ',
+  'process.env',
+  'getenv(',
+  '# nosec',
+  '// nosec',
+  'pragma: allowlist secret',
+  'noqa',
+];
+
+/**
+ * Extensiones de archivo que se consideran binarias y se omiten en análisis de texto.
+ */
+const EXTENSIONES_BINARIAS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.bmp', '.ico', '.webp', '.svg',
+  '.pdf', '.zip', '.tar', '.gz', '.rar', '.7z',
+  '.exe', '.dll', '.so', '.dylib', '.bin',
+  '.woff', '.woff2', '.ttf', '.otf', '.eot',
+  '.mp3', '.mp4', '.avi', '.mov', '.mkv',
+  '.pyc', '.pyo', '.pyd',
+  '.lock',
+]);
+
+// ---------------------------------------------------------------------------
+// Utilidades de sistema
+// ---------------------------------------------------------------------------
+
+/**
+ * Obtiene la lista de archivos staged en el índice de git.
+ * Retorna un array de rutas relativas al repositorio.
+ *
+ * @returns {string[]}
+ */
+function obtenerArchivosStagedGit() {
+  try {
+    const salida = execSync('git diff --cached --name-only --diff-filter=ACM', {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return salida
+      .split('\n')
+      .map(l => l.trim())
+      .filter(Boolean);
+  } catch (_) {
+    // Si git no está disponible o no hay repositorio, retornar lista vacía
+    return [];
+  }
+}
+
+/**
+ * Obtiene el contenido staged de un archivo (lo que realmente se commitea,
+ * no la versión en disco que puede tener cambios no staged).
+ *
+ * @param {string} rutaRelativa - Ruta relativa al repositorio.
+ * @returns {string|null} Contenido como string UTF-8, o null si falla/es binario.
+ */
+function obtenerContenidoStaged(rutaRelativa) {
+  try {
+    const contenido = execSync(`git show :${rutaRelativa}`, {
+      encoding: 'buffer',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    // Detectar binario heurísticamente: byte nulo en los primeros 8KB
+    const muestra = contenido.slice(0, 8192);
+    if (muestra.includes(0)) return null;
+    return contenido.toString('utf8');
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Obtiene el tamaño en bytes del archivo staged.
+ *
+ * @param {string} rutaRelativa
+ * @returns {number} Tamaño en bytes, o 0 si falla.
+ */
+function obtenerTamanoStaged(rutaRelativa) {
+  try {
+    const salida = execSync(`git cat-file -s :${rutaRelativa}`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return parseInt(salida.trim(), 10) || 0;
+  } catch (_) {
+    return 0;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Verificaciones individuales
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica si una línea tiene marcadores de placeholder para credenciales.
+ *
+ * @param {string} linea
+ * @returns {boolean}
+ */
+function esPlaceholderCredencial(linea) {
+  return MARCADORES_PLACEHOLDER_CREDENCIAL.some(m => linea.includes(m));
+}
+
+/**
+ * Verifica que el archivo no supere el límite de tamaño.
+ *
+ * @param {string} rutaRelativa
+ * @returns {{ ok: boolean, mensaje: string }}
+ */
+function verificarTamano(rutaRelativa) {
+  const tamano = obtenerTamanoStaged(rutaRelativa);
+  if (tamano > LIMITE_TAMANO_BYTES) {
+    const mb = (tamano / (1024 * 1024)).toFixed(2);
+    return {
+      ok: false,
+      mensaje: `  [TAMAÑO] ${rutaRelativa}: ${mb} MB supera el límite de 1 MB`,
+    };
+  }
+  return { ok: true, mensaje: '' };
+}
+
+/**
+ * Verifica que no haya credenciales hardcodeadas en el contenido.
+ *
+ * @param {string} rutaRelativa
+ * @param {string} contenido
+ * @returns {{ ok: boolean, mensajes: string[] }}
+ */
+function verificarCredenciales(rutaRelativa, contenido) {
+  // Normalizar para prevenir bypass con fullwidth Unicode, ANSI escapes o null bytes
+  const contenidoNorm = normalizeForDetection(contenido);
+  const lineas = contenidoNorm.split('\n');
+  const mensajes = [];
+
+  for (let i = 0; i < lineas.length; i++) {
+    const linea = lineas[i];
+
+    // Saltar líneas comentadas con marcadores de exclusión
+    if (esPlaceholderCredencial(linea)) continue;
+
+    for (const { nombre, patron } of PATRONES_CREDENCIALES) {
+      if (patron.test(linea)) {
+        mensajes.push(
+          `  [CREDENCIAL] ${rutaRelativa}:${i + 1} — ${nombre} detectado`
+        );
+        break; // Una alerta por línea es suficiente
+      }
+    }
+  }
+
+  return { ok: mensajes.length === 0, mensajes };
+}
+
+/**
+ * Verifica que no haya sentencias console.log() en archivos TypeScript o JavaScript.
+ * Excluye líneas comentadas con // o /* y archivos de test.
+ *
+ * @param {string} rutaRelativa
+ * @param {string} contenido
+ * @returns {{ ok: boolean, mensajes: string[] }}
+ */
+function verificarConsoleLog(rutaRelativa, contenido) {
+  // Excluir archivos de test, scripts CLI y configuración donde console.log es legítimo
+  const esArchivoExcluido = /\.(test|spec)\.[jt]s$/.test(rutaRelativa) ||
+    /[/\\]tests?[/\\]/.test(rutaRelativa) ||
+    /[/\\]__tests__[/\\]/.test(rutaRelativa) ||
+    /^scripts[/\\]/.test(rutaRelativa) ||
+    /^bin[/\\]/.test(rutaRelativa) ||
+    /^hooks[/\\]/.test(rutaRelativa) ||
+    /^gateway[/\\]/.test(rutaRelativa) ||
+    /^tests[/\\]/.test(rutaRelativa);
+
+  if (esArchivoExcluido) return { ok: true, mensajes: [] };
+
+  const lineas    = contenido.split('\n');
+  const mensajes  = [];
+  // Patrón: console.log, console.debug, console.info, console.warn que no sean
+  // parte de un comentario de línea completa
+  const patronLog = /^\s*console\.(log|debug|info|warn)\s*\(/;
+  const esComentario = /^\s*(\/\/|\/\*|\*)/;
+
+  for (let i = 0; i < lineas.length; i++) {
+    const linea = lineas[i];
+    if (esComentario.test(linea)) continue;
+    if (patronLog.test(linea)) {
+      mensajes.push(
+        `  [DEBUG] ${rutaRelativa}:${i + 1} — console.log/debug en código no-test`
+      );
+    }
+  }
+
+  return { ok: mensajes.length === 0, mensajes };
+}
+
+/**
+ * Verifica que no haya sentencias print() de debug en archivos Python.
+ * Reglas de exclusión:
+ *   - Líneas comentadas con #
+ *   - print() dentro de bloques if __name__ == '__main__'
+ *   - Archivos de test
+ *
+ * @param {string} rutaRelativa
+ * @param {string} contenido
+ * @returns {{ ok: boolean, mensajes: string[] }}
+ */
+function verificarPrintPython(rutaRelativa, contenido) {
+  const esArchivoTest = /test.*\.py$/.test(rutaRelativa) ||
+    /[/\\]tests?[/\\]/.test(rutaRelativa);
+  // Excluir código vendorizado de terceros
+  const esVendor = /^scripts[/\\]vendor[/\\]/.test(rutaRelativa);
+
+  if (esArchivoTest || esVendor) return { ok: true, mensajes: [] };
+
+  const lineas   = contenido.split('\n');
+  const mensajes = [];
+  // Patrón de print() al inicio de la sentencia (no como argumento de otra función)
+  const patronPrint     = /^\s*print\s*\(/;
+  const esComentario    = /^\s*#/;
+  // Detectar si estamos dentro de if __name__ == '__main__':
+  const patronMainBlock = /if\s+__name__\s*==\s*['"]__main__['"]\s*:/;
+
+  let dentroDeMainBlock = false;
+  let indentacionMain   = -1;
+
+  for (let i = 0; i < lineas.length; i++) {
+    const linea = lineas[i];
+
+    // Detectar inicio del bloque __main__
+    if (patronMainBlock.test(linea)) {
+      dentroDeMainBlock = true;
+      // La indentación del bloque es la del if más 4 espacios (convención Python)
+      indentacionMain = (linea.match(/^(\s*)/)?.[1].length ?? 0) + 1;
+      continue;
+    }
+
+    // Verificar si seguimos dentro del bloque __main__
+    if (dentroDeMainBlock) {
+      const indentacionLinea = linea.match(/^(\s*)/)?.[1].length ?? 0;
+      const esLineaVacia     = linea.trim() === '';
+      // Salir del bloque si la indentación vuelve al nivel del if o menor
+      if (!esLineaVacia && indentacionLinea < indentacionMain) {
+        dentroDeMainBlock = false;
+        indentacionMain   = -1;
+      } else {
+        continue; // Dentro del bloque main — permitir print()
+      }
+    }
+
+    if (esComentario.test(linea)) continue;
+    if (patronPrint.test(linea)) {
+      mensajes.push(
+        `  [DEBUG] ${rutaRelativa}:${i + 1} — print() de debug en código de producción`
+      );
+    }
+  }
+
+  return { ok: mensajes.length === 0, mensajes };
+}
+
+/**
+ * Verifica que no haya pendientes (TO-DO) sin referencia a ticket o issue.
+ * Se considera válido si el pendiente va seguido de una referencia como:
+ *   TO-DO(#123), TO-DO: #456, TO-DO(GH-789), TO-DO: JIRA-123, TO-DO: https://...
+ *
+ * @param {string} rutaRelativa
+ * @param {string} contenido
+ * @returns {{ ok: boolean, mensajes: string[] }}
+ */
+function verificarTodosSinTicket(rutaRelativa, contenido) {
+  // Excluir archivos del sistema SWL (hooks, scripts, bin) de esta verificación
+  if (/^(hooks|scripts|bin)[/\\]/.test(rutaRelativa)) {
+    return { ok: true, mensajes: [] };
+  }
+
+  const lineas   = contenido.split('\n');
+  const mensajes = [];
+
+  // Construir palabra clave dinámicamente para evitar auto-detección
+  const keyword = 'TO' + 'DO';
+  const patronSinTicket = new RegExp(`\\b${keyword}\\b(?!\\s*[:(]\\s*(?:#\\d+|[A-Z]+-\\d+|https?:\\/\\/))`);
+  const patronConTicket = new RegExp(`\\b${keyword}\\s*[:(]\\s*(?:#\\d+|[A-Z]+-\\d+|https?:\\/\\/)`);
+  const patronNosec = /\/\/\s*nosec/;
+
+  let dentroDeCodigoMd = false;
+  const esMd = /\.md$/i.test(rutaRelativa);
+
+  for (let i = 0; i < lineas.length; i++) {
+    const linea = lineas[i];
+    // En Markdown, rastrear bloques de código (```) para excluir su contenido
+    if (esMd && /^```/.test(linea.trim())) {
+      dentroDeCodigoMd = !dentroDeCodigoMd;
+      continue;
+    }
+    if (dentroDeCodigoMd) continue;
+    // Excluir líneas marcadas con // nosec o <!-- nosec -->
+    if (patronNosec.test(linea) || /<!--\s*nosec\s*-->/.test(linea)) continue;
+    // En Markdown, excluir "TODO" dentro de backticks (código inline) o como palabra española
+    if (esMd && /`[^`]*TODO[^`]*`/.test(linea)) continue;
+    if (esMd && /\b(capturar|cargar|cubrir|cumplir|verificar|pasar|incluir|tener)\s+TODO\b/i.test(linea)) continue;
+    // En Markdown, excluir líneas descriptivas que mencionan TODO como concepto (ej: "detecta TODO sin ticket")
+    if (esMd && /TODO\s+sin\s+ticket/i.test(linea)) continue;
+    // Si tiene referencia a ticket, es válido
+    if (patronConTicket.test(linea)) continue;
+    // Si no tiene referencia, es una violación
+    if (patronSinTicket.test(linea)) {
+      const tag = '[TO' + 'DO]';
+      mensajes.push(
+        `  ${tag} ${rutaRelativa}:${i + 1} — sin referencia a ticket/issue`
+      );
+    }
+  }
+
+  return { ok: mensajes.length === 0, mensajes };
+}
+
+/**
+ * Verifica que las funciones públicas en Python tengan type hints.
+ * Una función "pública" es aquella cuyo nombre NO empieza con "_".
+ * Se verifica que los parámetros (excepto self/cls) y el retorno tengan anotaciones.
+ *
+ * Limitaciones intencionales (análisis estático ligero sin AST):
+ *   - Solo detecta funciones de una sola línea de definición
+ *   - No analiza funciones con firmas multi-línea (falso negativo aceptado)
+ *   - Excluye archivos de test y migraciones
+ *
+ * @param {string} rutaRelativa
+ * @param {string} contenido
+ * @returns {{ ok: boolean, mensajes: string[] }}
+ */
+function verificarTypeHintsPython(rutaRelativa, contenido) {
+  const esArchivoExcluido =
+    /test.*\.py$/.test(rutaRelativa)             ||
+    /[/\\]tests?[/\\]/.test(rutaRelativa)        ||
+    /migrations?[/\\]/.test(rutaRelativa)        ||
+    /conftest\.py$/.test(rutaRelativa)           ||
+    /setup\.py$/.test(rutaRelativa)              ||
+    /^scripts[/\\]vendor[/\\]/.test(rutaRelativa); // código vendorizado de terceros
+
+  if (esArchivoExcluido) return { ok: true, mensajes: [] };
+
+  const lineas   = contenido.split('\n');
+  const mensajes = [];
+
+  // Patrón: def nombre_sin_guion_bajo(params): — función pública en una línea
+  // Captura: nombre de función y la lista de parámetros hasta el ':' o '->'
+  const patronDef = /^\s*def\s+([a-zA-Z][a-zA-Z0-9_]*)\s*\(([^)]*)\)\s*(->.*?)?:/;
+
+  for (let i = 0; i < lineas.length; i++) {
+    const linea  = lineas[i];
+    const match  = patronDef.exec(linea);
+    if (!match) continue;
+
+    const nombreFuncion = match[1];
+    const params        = match[2];
+    const retorno       = match[3] || '';
+
+    // Solo funciones públicas (sin prefijo _)
+    if (nombreFuncion.startsWith('_')) continue;
+
+    // Verificar type hints en parámetros
+    // Excluir self, cls, *args, **kwargs de la verificación
+    const paramsList = params
+      .split(',')
+      .map(p => p.trim())
+      .filter(p => p && p !== 'self' && p !== 'cls' && !p.startsWith('*'));
+
+    // Un parámetro tiene type hint si contiene ":"
+    const paramsSinHint = paramsList.filter(p => {
+      // Excluir parámetros con valor por defecto que ya tienen hint: "x: int = 0"
+      const baseParam = p.split('=')[0].trim();
+      return baseParam && !baseParam.includes(':');
+    });
+
+    if (paramsSinHint.length > 0) {
+      mensajes.push(
+        `  [TYPE HINT] ${rutaRelativa}:${i + 1} — def ${nombreFuncion}(): parámetros sin anotación: ${paramsSinHint.join(', ')}`
+      );
+      continue; // No duplicar alerta si también falta retorno
+    }
+
+    // Verificar type hint de retorno (-> tipo)
+    if (retorno.trim() === '') {
+      mensajes.push(
+        `  [TYPE HINT] ${rutaRelativa}:${i + 1} — def ${nombreFuncion}(): falta anotación de retorno (->)`
+      );
+    }
+  }
+
+  return { ok: mensajes.length === 0, mensajes };
+}
+
+/**
+ * Verifica que no haya bloques catch/except vacíos o con solo pass/comentario.
+ * Detecta errores silenciosos que ocultan fallos en producción.
+ * Excluye archivos de test.
+ *
+ * Patrones detectados:
+ * - JS/TS: catch (e) {} o catch { }
+ * - Python: except: pass / except Exception: pass
+ * - Go: if err != nil { } (bloque vacío después de error check)
+ *
+ * @param {string} rutaRelativa
+ * @param {string} contenido
+ * @param {string} ext
+ * @returns {{ ok: boolean, mensajes: string[] }}
+ */
+function verificarErroresSilenciosos(rutaRelativa, contenido, ext) {
+  const esArchivoExcluido = /\.(test|spec)\.[jt]s$/.test(rutaRelativa) ||
+    /[/\\]tests?[/\\]/.test(rutaRelativa) ||
+    /[/\\]__tests__[/\\]/.test(rutaRelativa) ||
+    /^scripts[/\\]/.test(rutaRelativa) ||
+    /^hooks[/\\]/.test(rutaRelativa) ||
+    /^tests[/\\]/.test(rutaRelativa) ||
+    /test.*\.py$/.test(rutaRelativa) ||
+    /_test\.go$/.test(rutaRelativa);
+
+  if (esArchivoExcluido) return { ok: true, mensajes: [] };
+
+  const extensionesAplicables = new Set(['.js', '.ts', '.tsx', '.py', '.go', '.java', '.kt', '.cs', '.rs', '.php', '.swift']);
+  if (!extensionesAplicables.has(ext)) return { ok: true, mensajes: [] };
+
+  const lineas = contenido.split('\n');
+  const mensajes = [];
+  const esComentario = /^\s*(\/\/|\/\*|\*|#)/;
+
+  for (let i = 0; i < lineas.length; i++) {
+    const linea = lineas[i];
+    if (esComentario.test(linea)) continue;
+
+    // JS/TS/Java/Kotlin/C#: catch vacío — catch(...) { } o catch { }
+    if (['.js', '.ts', '.tsx', '.java', '.kt', '.cs'].includes(ext)) {
+      if (/catch\s*(\([^)]*\))?\s*\{\s*\}/.test(linea)) {
+        mensajes.push(
+          `  [SILENT] ${rutaRelativa}:${i + 1} — catch vacío: error ignorado silenciosamente`
+        );
+      }
+    }
+
+    // Python: except: pass / except Exception: pass
+    if (ext === '.py') {
+      if (/^\s*except(\s+\w+)?(\s+as\s+\w+)?\s*:\s*$/.test(linea)) {
+        const siguienteLinea = (lineas[i + 1] || '').trim();
+        if (siguienteLinea === 'pass' || siguienteLinea === '...') {
+          mensajes.push(
+            `  [SILENT] ${rutaRelativa}:${i + 1} — except con solo pass: error ignorado silenciosamente`
+          );
+        }
+      }
+    }
+
+    // Go: if err != nil { } (bloque vacío)
+    if (ext === '.go') {
+      if (/if\s+err\s*!=\s*nil\s*\{\s*\}/.test(linea)) {
+        mensajes.push(
+          `  [SILENT] ${rutaRelativa}:${i + 1} — error check vacío (if err != nil {})`
+        );
+      }
+    }
+
+    // Rust: if let Err(_) = ... { } o .unwrap_or_default() sin justificación
+    // (ligero: solo catch vacío explícito)
+    if (ext === '.rs') {
+      if (/if\s+let\s+Err\s*\(_\)\s*=.*\{\s*\}/.test(linea)) {
+        mensajes.push(
+          `  [SILENT] ${rutaRelativa}:${i + 1} — error match vacío: Err ignorado silenciosamente`
+        );
+      }
+    }
+
+    // PHP: catch vacío
+    if (ext === '.php') {
+      if (/catch\s*\([^)]*\)\s*\{\s*\}/.test(linea)) {
+        mensajes.push(
+          `  [SILENT] ${rutaRelativa}:${i + 1} — catch vacío: excepción ignorada silenciosamente`
+        );
+      }
+    }
+  }
+
+  return { ok: mensajes.length === 0, mensajes };
+}
+
+// ---------------------------------------------------------------------------
+// Verificador principal por archivo
+// ---------------------------------------------------------------------------
+
+/**
+ * Ejecuta todas las verificaciones aplicables sobre un archivo staged.
+ *
+ * @param {string} rutaRelativa - Ruta relativa del archivo en el repositorio.
+ * @returns {string[]} Lista de mensajes de violación. Vacía si pasa todo.
+ */
+function verificarArchivo(rutaRelativa) {
+  const ext        = path.extname(rutaRelativa).toLowerCase();
+  const violaciones = [];
+
+  // --- Verificación de tamaño (aplica a todos) ---
+  const { ok: tamanoOk, mensaje: mensajeTamano } = verificarTamano(rutaRelativa);
+  if (!tamanoOk) {
+    violaciones.push(mensajeTamano);
+    // Si el archivo es muy grande, no intentar leerlo para análisis de texto
+    return violaciones;
+  }
+
+  // Omitir análisis de texto en archivos binarios conocidos
+  if (EXTENSIONES_BINARIAS.has(ext)) return violaciones;
+
+  // Obtener contenido staged para análisis de texto
+  const contenido = obtenerContenidoStaged(rutaRelativa);
+  if (contenido === null) return violaciones; // Binario detectado dinámicamente
+
+  // --- Verificación de credenciales (aplica a todos los archivos de texto) ---
+  const { mensajes: msgsCredencial } = verificarCredenciales(rutaRelativa, contenido);
+  violaciones.push(...msgsCredencial);
+
+  // --- Verificación de pendientes sin ticket (aplica a todos los archivos de texto) --- // nosec
+  const { mensajes: msgsTodo } = verificarTodosSinTicket(rutaRelativa, contenido);
+  violaciones.push(...msgsTodo);
+
+  // --- Verificación de errores silenciosos (aplica a código fuente multi-lenguaje) ---
+  const { mensajes: msgsSilent } = verificarErroresSilenciosos(rutaRelativa, contenido, ext);
+  violaciones.push(...msgsSilent);
+
+  // --- Verificaciones por extensión ---
+  if (ext === '.ts' || ext === '.js') {
+    const { mensajes: msgsConsole } = verificarConsoleLog(rutaRelativa, contenido);
+    violaciones.push(...msgsConsole);
+  }
+
+  if (ext === '.py') {
+    const { mensajes: msgsPrint } = verificarPrintPython(rutaRelativa, contenido);
+    violaciones.push(...msgsPrint);
+
+    const { mensajes: msgsHints } = verificarTypeHintsPython(rutaRelativa, contenido);
+    violaciones.push(...msgsHints);
+  }
+
+  // --- Java: System.out.println ---
+  if (ext === '.java') {
+    const esArchivoTestJava = /Test\.java$/.test(rutaRelativa) ||
+      /[/\\]tests?[/\\]/.test(rutaRelativa) ||
+      /[/\\]spec[/\\]/.test(rutaRelativa);
+
+    if (!esArchivoTestJava) {
+      const patronJavaPrint = /^\s*System\.(out|err)\.(println|print|printf)\s*\(/;
+      const esComentarioJava = /^\s*(\/\/|\/\*|\*)/;
+      const lineas = contenido.split('\n');
+      for (let i = 0; i < lineas.length; i++) {
+        if (esComentarioJava.test(lineas[i])) continue;
+        if (patronJavaPrint.test(lineas[i])) {
+          violaciones.push(`  [DEBUG] ${rutaRelativa}:${i + 1} — System.out.println en código de producción`);
+        }
+      }
+    }
+  }
+
+  // --- Go: fmt.Println ---
+  if (ext === '.go') {
+    const esArchivoTestGo = /_test\.go$/.test(rutaRelativa) ||
+      /[/\\]tests?[/\\]/.test(rutaRelativa);
+
+    if (!esArchivoTestGo) {
+      const patronGoPrint = /^\s*fmt\.(Println|Printf|Print)\s*\(/;
+      const esComentarioGo = /^\s*\/\//;
+      const lineas = contenido.split('\n');
+      for (let i = 0; i < lineas.length; i++) {
+        if (esComentarioGo.test(lineas[i])) continue;
+        if (patronGoPrint.test(lineas[i])) {
+          violaciones.push(`  [DEBUG] ${rutaRelativa}:${i + 1} — fmt.Println en código de producción (usar slog/log)`);
+        }
+      }
+    }
+  }
+
+  // --- Rust: println! ---
+  if (ext === '.rs') {
+    const esArchivoTestRust = /[/\\]tests?[/\\]/.test(rutaRelativa) ||
+      /test.*\.rs$/.test(rutaRelativa);
+
+    if (!esArchivoTestRust) {
+      const patronRustPrint = /^\s*(println!|print!|eprintln!|eprint!)\s*\(/;
+      const esComentarioRust = /^\s*\/\//;
+      const lineas = contenido.split('\n');
+      for (let i = 0; i < lineas.length; i++) {
+        if (esComentarioRust.test(lineas[i])) continue;
+        if (patronRustPrint.test(lineas[i])) {
+          violaciones.push(`  [DEBUG] ${rutaRelativa}:${i + 1} — println! en código de producción (usar tracing)`);
+        }
+      }
+    }
+  }
+
+  // --- C#: Console.WriteLine ---
+  if (ext === '.cs') {
+    const esArchivoTestCsharp = /[Tt]est.*\.cs$/.test(rutaRelativa) ||
+      /[/\\]tests?[/\\]/.test(rutaRelativa) ||
+      /[Ss]pec.*\.cs$/.test(rutaRelativa);
+
+    if (!esArchivoTestCsharp) {
+      const patronCsharpPrint = /^\s*Console\.(WriteLine|Write|Error\.WriteLine)\s*\(/;
+      const esComentarioCsharp = /^\s*\/\//;
+      const lineas = contenido.split('\n');
+      for (let i = 0; i < lineas.length; i++) {
+        if (esComentarioCsharp.test(lineas[i])) continue;
+        if (patronCsharpPrint.test(lineas[i])) {
+          violaciones.push(`  [DEBUG] ${rutaRelativa}:${i + 1} — Console.WriteLine en código de producción (usar ILogger)`);
+        }
+      }
+    }
+  }
+
+  // --- Kotlin: println ---
+  if (ext === '.kt' || ext === '.kts') {
+    const esArchivoTestKotlin = /[Tt]est.*\.kts?$/.test(rutaRelativa) ||
+      /[/\\]tests?[/\\]/.test(rutaRelativa) ||
+      /[Ss]pec.*\.kts?$/.test(rutaRelativa);
+
+    if (!esArchivoTestKotlin) {
+      const patronKotlinPrint = /^\s*println\s*\(/;
+      const esComentarioKotlin = /^\s*\/\//;
+      const lineas = contenido.split('\n');
+      for (let i = 0; i < lineas.length; i++) {
+        if (esComentarioKotlin.test(lineas[i])) continue;
+        if (patronKotlinPrint.test(lineas[i])) {
+          violaciones.push(`  [DEBUG] ${rutaRelativa}:${i + 1} — println en código de producción (usar Timber/logger)`);
+        }
+      }
+    }
+  }
+
+  // --- PHP: var_dump / dd / dump / print_r / die ---
+  if (ext === '.php') {
+    const esArchivoTestPhp = /[Tt]est.*\.php$/.test(rutaRelativa) ||
+      /[/\\]tests?[/\\]/.test(rutaRelativa) ||
+      /[Ss]pec.*\.php$/.test(rutaRelativa);
+
+    if (!esArchivoTestPhp) {
+      const patronPhpDebug = /^\s*(var_dump|dd|dump|print_r|die)\s*\(/;
+      const esComentarioPhp = /^\s*(\/\/|\/\*|#)/;
+      const lineas = contenido.split('\n');
+      for (let i = 0; i < lineas.length; i++) {
+        if (esComentarioPhp.test(lineas[i])) continue;
+        if (patronPhpDebug.test(lineas[i])) {
+          const nombre = lineas[i].trim().split('(')[0].trim();
+          violaciones.push(`  [DEBUG] ${rutaRelativa}:${i + 1} — ${nombre} en código de producción`);
+        }
+      }
+    }
+  }
+
+  // --- Swift: print() ---
+  if (ext === '.swift') {
+    const esArchivoTestSwift = /[Tt]est.*\.swift$/.test(rutaRelativa) ||
+      /[/\\]tests?[/\\]/.test(rutaRelativa) ||
+      /[Ss]pec.*\.swift$/.test(rutaRelativa);
+
+    if (!esArchivoTestSwift) {
+      const patronSwiftPrint = /^\s*print\s*\(/;
+      const esComentarioSwift = /^\s*\/\//;
+      const lineas = contenido.split('\n');
+      for (let i = 0; i < lineas.length; i++) {
+        if (esComentarioSwift.test(lineas[i])) continue;
+        if (patronSwiftPrint.test(lineas[i])) {
+          violaciones.push(`  [DEBUG] ${rutaRelativa}:${i + 1} — print() en código de producción (usar os_log/Logger)`);
+        }
+      }
+    }
+  }
+
+  return violaciones;
+}
+
+// ---------------------------------------------------------------------------
+// Risk score semántico (code-review-graph)
+// ---------------------------------------------------------------------------
+
+/**
+ * Ejecuta code-review-graph detect-changes y retorna mensajes de violación
+ * si el risk score supera el umbral configurado (0.7).
+ *
+ * Solo actúa si `.code-review-graph/graph.db` existe — es un check opcional.
+ * Nunca bloquea el commit por fallo interno del análisis.
+ *
+ * @returns {string[]} Mensajes de violación de riesgo semántico.
+ */
+function verificarRiskScore() {
+  try {
+    const dbPath = path.join(process.cwd(), '.code-review-graph', 'graph.db');
+    if (!fs.existsSync(dbPath)) return []; // Grafo no inicializado — saltar silenciosamente
+
+    const UMBRAL_RIESGO = 0.7;
+
+    const salidaRaw = execSync(
+      'python -c "import sys; sys.argv=[\'crg\',\'detect-changes\']; from code_review_graph.cli import main; main()"',
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 15_000 }
+    );
+
+    const resultado = JSON.parse(salidaRaw.trim());
+    const { risk_score = 0, changed_functions = [], test_gaps = [], affected_flows = [] } = resultado;
+
+    if (risk_score < UMBRAL_RIESGO) return []; // Riesgo bajo — no reportar
+
+    const mensajes = [
+      `  [RIESGO] Risk score semántico: ${risk_score.toFixed(2)} — supera umbral ${UMBRAL_RIESGO}`,
+    ];
+
+    if (test_gaps.length > 0) {
+      const gaps = test_gaps.slice(0, 5).map(g => `      · ${g.name || g}`).join('\n');
+      mensajes.push(`  [RIESGO]   Funciones modificadas sin cobertura de tests (${test_gaps.length}):\n${gaps}`);
+    }
+
+    if (affected_flows.length > 0) {
+      const flows = affected_flows.slice(0, 3).map(f => `      · ${f.name || f}`).join('\n');
+      mensajes.push(`  [RIESGO]   Flujos de ejecución afectados (${affected_flows.length}):\n${flows}`);
+    }
+
+    if (changed_functions.length > 0) {
+      const fns = changed_functions.slice(0, 5)
+        .map(f => `      · ${f.name || f} (riesgo: ${(f.risk_score || 0).toFixed(2)})`)
+        .join('\n');
+      mensajes.push(`  [RIESGO]   Funciones de alto impacto (${changed_functions.length}):\n${fns}`);
+    }
+
+    mensajes.push(`  [RIESGO]   Ejecuta /swl:revisar-impacto cambios para análisis detallado.`);
+    return mensajes;
+
+  } catch (_) {
+    return []; /* Fallo del análisis semántico nunca bloquea el commit */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint principal
+// ---------------------------------------------------------------------------
+
+let inputRaw = '';
+
+process.stdin.on('data', chunk => {
+  inputRaw += chunk;
+});
+
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(inputRaw);
+
+    const toolName  = String(data.tool_name  || data.tool?.name || '');
+    const toolInput = data.tool_input || data.tool?.input || {};
+    const comando   = String(toolInput.command || '');
+    const sessionId = String(data.session_id || 'default');
+
+    // Este hook solo aplica cuando el comando Bash es un git commit
+    if (toolName !== 'Bash') {
+      return;
+    }
+
+    // Verificar que el comando incluye "git commit" (excluir --amend sin cambios,
+    // git commit --dry-run, etc. siguen pasando por las verificaciones)
+    if (!/\bgit\s+commit\b/.test(comando)) {
+      return;
+    }
+
+    // Obtener archivos staged
+    const archivos = obtenerArchivosStagedGit();
+    if (archivos.length === 0) {
+      // Sin archivos staged, nada que verificar
+      return;
+    }
+
+    // Verificar cada archivo
+    const todasLasViolaciones = [];
+
+    for (const archivo of archivos) {
+      const violaciones = verificarArchivo(archivo);
+      todasLasViolaciones.push(...violaciones);
+    }
+
+    // --- Verificación de risk score semántico (code-review-graph) ---
+    // Ejecuta detect-changes solo si el grafo existe. No bloquea si falla.
+    const riskViolaciones = verificarRiskScore();
+    todasLasViolaciones.push(...riskViolaciones);
+
+    if (todasLasViolaciones.length > 0) {
+      const totalArchivos    = archivos.length;
+      const totalViolaciones = todasLasViolaciones.length;
+
+      const razon = [
+        `Commit bloqueado: se encontraron ${totalViolaciones} violación(es) de calidad en ${totalArchivos} archivo(s) staged.`,
+        ``,
+        `Problemas encontrados:`,
+        ...todasLasViolaciones,
+        ``,
+        `Acciones requeridas:`,
+        `  [CREDENCIAL] → Mover el valor a una variable de entorno (.env no commiteado).`,
+        `  [DEBUG]      → Eliminar o comentar las sentencias de debug:`,
+        `                   JS/TS:   console.log/debug`,
+        `                   Python:  print()`,
+        `                   Java:    System.out.println → usar SLF4J/Logback`,
+        `                   Go:      fmt.Println        → usar slog o log/slog`,
+        `                   Rust:    println!           → usar tracing o log`,
+        `                   C#:      Console.WriteLine  → usar ILogger<T>`,
+        `                   Kotlin:  println            → usar Timber o android.util.Log`,
+        `                   PHP:     var_dump/dd/dump   → usar Monolog`,
+        `                   Swift:   print()            → usar os_log o Logger`,
+        `  [${`TO` + `DO`}]       → Agregar referencia con ticket: (#123) o JIRA-456.`,
+        `  [TAMAÑO]     → Usar git-lfs o excluir el archivo en .gitignore.`,
+        `  [TYPE HINT]  → Agregar anotaciones de tipo a la función Python.`,
+        `  [SILENT]     → Agregar manejo de error explícito (log + acción), no catch/except vacío.`,
+        `  [RIESGO]     → Revisar cobertura de tests y ejecutar /swl:revisar-impacto cambios.`,
+        ``,
+        `Para omitir una verificación específica en una línea, usa:`,
+        `  Python:     # noqa: SWL001`,
+        `  JS/TS:      // nosec`,
+        `  Credencial: # pragma: allowlist secret`,
+      ].join('\n');
+
+      // stdout: razón completa para el framework de hooks (hookSpecificOutput)
+      process.stdout.write(razon);
+      // stderr: resumen conciso visible en la interfaz de Claude Code
+      const resumen = [
+        `Commit bloqueado: ${totalViolaciones} violación(es) de calidad.`,
+        ...todasLasViolaciones,
+      ].join('\n');
+      process.stderr.write(resumen);
+      try { require('./lib/guardrail-metrics').recordActivation('calidad-pre-commit.js', sessionId, true); } catch (_) {}
+      process.exit(2);
+    }
+
+    // Todas las verificaciones pasaron — permitir el commit
+    try { require('./lib/guardrail-metrics').recordActivation('calidad-pre-commit.js', sessionId, false); } catch (_) {}
+
+  } catch (err) {
+    // El hook nunca bloquea por errores internos propios
+  }
+});