swl-ses 3.3.2

package/hooks/calidad-pre-commit.js

@@ -0,0 +1,578 @@
+#!/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 TODO 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
+ *
+ * Resultado:
+ *   - Violaciones encontradas → exit 2, JSON {result:"block", reason:"..."} en stdout
+ *   - Sin violaciones         → exit 0, sin output
+ *   - Error interno           → exit 0 (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');
+
+// ---------------------------------------------------------------------------
+// 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 (err) {
+    // Si git no está disponible o no hay repositorio, retornar lista vacía
+    process.stderr.write(`[calidad-pre-commit] No se pudieron obtener archivos staged: ${err.message}\n`);
+    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) {
+  const lineas = contenido.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 y configuración donde console.log es legítimo
+  const esArchivoTest = /\.(test|spec)\.[jt]s$/.test(rutaRelativa) ||
+    /[/\\]tests?[/\\]/.test(rutaRelativa) ||
+    /[/\\]__tests__[/\\]/.test(rutaRelativa);
+
+  if (esArchivoTest) 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);
+
+  if (esArchivoTest) 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 TODO sin referencia a ticket o issue.
+ * Se considera válido si el TODO va seguido de una referencia como:
+ *   TODO(#123), TODO: #456, TODO(GH-789), TODO: JIRA-123, TODO: https://...
+ *
+ * @param {string} rutaRelativa
+ * @param {string} contenido
+ * @returns {{ ok: boolean, mensajes: string[] }}
+ */
+function verificarTodosSinTicket(rutaRelativa, contenido) {
+  const lineas   = contenido.split('\n');
+  const mensajes = [];
+
+  // Patrón que captura TODO sin referencia explícita
+  // Referencias válidas: #123, GH-123, JIRA-123, http...
+  const patronTodoSinTicket = /\bTODO\b(?!\s*[:(]\s*(?:#\d+|[A-Z]+-\d+|https?:\/\/))/i;
+  // Patrón de TODO con referencia (para excluir falsos positivos)
+  const patronTodoConTicket = /\bTODO\s*[:(]\s*(?:#\d+|[A-Z]+-\d+|https?:\/\/)/i;
+
+  for (let i = 0; i < lineas.length; i++) {
+    const linea = lineas[i];
+    // Si tiene TODO con ticket, es válido
+    if (patronTodoConTicket.test(linea)) continue;
+    // Si tiene TODO sin ticket, es una violación
+    if (patronTodoSinTicket.test(linea)) {
+      mensajes.push(
+        `  [TODO] ${rutaRelativa}:${i + 1} — TODO 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);
+
+  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 };
+}
+
+// ---------------------------------------------------------------------------
+// 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 TODO sin ticket (aplica a todos los archivos de texto) ---
+  const { mensajes: msgsTodo } = verificarTodosSinTicket(rutaRelativa, contenido);
+  violaciones.push(...msgsTodo);
+
+  // --- 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);
+  }
+
+  return violaciones;
+}
+
+// ---------------------------------------------------------------------------
+// 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 || '');
+
+    // Este hook solo aplica cuando el comando Bash es un git commit
+    if (toolName !== 'Bash') {
+      process.exit(0);
+    }
+
+    // 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)) {
+      process.exit(0);
+    }
+
+    // Obtener archivos staged
+    const archivos = obtenerArchivosStagedGit();
+    if (archivos.length === 0) {
+      // Sin archivos staged, nada que verificar
+      process.exit(0);
+    }
+
+    // Verificar cada archivo
+    const todasLasViolaciones = [];
+
+    for (const archivo of archivos) {
+      const violaciones = verificarArchivo(archivo);
+      todasLasViolaciones.push(...violaciones);
+    }
+
+    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.`,
+        `  [TODO]       → Agregar referencia: TODO(#123) o TODO: JIRA-456.`,
+        `  [TAMAÑO]     → Usar git-lfs o excluir el archivo en .gitignore.`,
+        `  [TYPE HINT]  → Agregar anotaciones de tipo a la función Python.`,
+        ``,
+        `Para omitir una verificación específica en una línea, usa:`,
+        `  Python:     # noqa: SWL001`,
+        `  JS/TS:      // nosec`,
+        `  Credencial: # pragma: allowlist secret`,
+      ].join('\n');
+
+      process.stdout.write(JSON.stringify({ result: 'block', reason: razon }));
+      process.exit(2);
+    }
+
+    // Todas las verificaciones pasaron — permitir el commit
+    process.exit(0);
+
+  } catch (err) {
+    // El hook nunca bloquea por errores internos propios
+    process.stderr.write(`[calidad-pre-commit] Error interno: ${err.message}\n`);
+    process.exit(0);
+  }
+});