claude-git-hooks 1.5.5 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,93 @@ Todos los cambios notables en este proyecto se documentarán en este archivo.
 El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2025-11-04
+
+### Changed
+
+- 🔄 Renombrado marcador de exclusión de línea única: `// SKIP-ANALYSIS` → `// SKIP_ANALYSIS_LINE` para consistencia de nomenclatura
+- 🐛 Corregido bug crítico en orden de detección de patrones que impedía funcionamiento de `SKIP_ANALYSIS_BLOCK`
+
+### Known Issues
+
+- ⚠️ **SKIP_ANALYSIS marcado como EXPERIMENTAL/BROKEN**: Los marcadores de exclusión no funcionan correctamente porque el análisis se realiza sobre git diff en lugar del archivo completo. Marcadores agregados en commits anteriores no son detectados en cambios subsecuentes.
+
+### Migration Guide
+
+Si utilizabas `// SKIP-ANALYSIS` en tu código, reemplázalo por `// SKIP_ANALYSIS_LINE`:
+
+```java
+// Antes (deprecated):
+// SKIP-ANALYSIS
+private String legacyCode;
+
+// Ahora:
+// SKIP_ANALYSIS_LINE
+private String legacyCode;
+```
+
+El marcador de bloque `// SKIP_ANALYSIS_BLOCK` permanece sin cambios.
+
+## [2.0.1] - 2025-11-04
+
+### Fixed
+
+- 🔧 Compatibilidad completa en Windows: corregidos line endings CRLF, validación WSL, y comparación de versiones sin dependencia bash
+- 🔧 Operaciones de rutas utilizan módulo `path` nativo para mejor portabilidad multiplataforma
+
+## [2.0.0] - 2025-10-30
+
+### 🚀 BREAKING CHANGE: Migration from Bash to Node.js Hooks
+
+**Why this change?**
+The bash-based hooks created fundamental incompatibilities with Windows Git and IDE workflows (VSCode, IntelliJ), causing:
+- Git worktree path conflicts (Windows paths incompatible with WSL)
+- IDE commit failures when using Windows Git
+- Developers forced to use WSL terminal exclusively, abandoning IDE Git features
+
+### ✅ Advantages
+
+**Cross-Platform Native Support**
+- ✅ Works with Windows Git, WSL, and Bash
+- ✅ No more worktree path issues
+- ✅ Single codebase for all platforms
+
+**Dramatically Improved Maintainability**
+- ✅ JavaScript/Node.js: ~60-70% of developers proficient vs ~1-2% with bash/jq/sed/awk
+- ✅ Modern tooling: ESLint, Prettier, Jest testing framework
+- ✅ VS Code debugging support vs echo statements
+
+**Professional Development Practices**
+- ✅ Unit and integration testing with Jest
+- ✅ Type safety optional (TypeScript)
+- ✅ Consistent error handling patterns
+
+### ⚠️ Disadvantages
+
+- ⚠️ Initial migration effort
+- ⚠️ Startup performance: +40-90ms overhead (~1% of total execution time)
+
+### 🏆 Industry Success Cases
+
+**Node.js Git Hooks - Proven Track Record:**
+- **Husky**: 43k GitHub stars, 500+ contributors, 7M+ weekly npm downloads
+- **lint-staged**: 12k stars, 200+ contributors
+- **Commitizen**: 16k stars, industry standard
+- **simple-git-hooks**: Fast, minimal, 1M+ weekly downloads
+
+### Changed
+
+- 🔄 **Migrated from Bash to Node.js with ES6 modules** - Hooks now in `lib/hooks/*.js` with bash wrappers, removing jq/sed/awk dependencies
+- 🌐 **Cross-platform support enabled** - Works on Windows Git Bash, WSL, Linux, and macOS with automatic Claude detection
+- 🔧 **Platform compatibility** - CRLF-to-LF conversion during install, Windows path support (C:\ to /c/) in bash wrappers
+
+### Migration Guide
+
+Existing installations will continue working. To upgrade:
+1. Run `claude-hooks update` to get v2.0.0
+2. Run `claude-hooks install --force` to reinstall with Node.js hooks
+3. No configuration changes needed - works transparently
+
 ## [1.5.5] - 2025-10-29
 
 ### Added

package/README.md

@@ -2,14 +2,24 @@
 
 🚀 **Transforma tu flujo de desarrollo con IA**: análisis de código instantáneo, mensajes de commit automáticos y generación de PRs perfectas. Claude revisa tu código antes de cada commit, detecta issues críticos al estilo SonarQube, y genera toda la documentación que necesitas. ¿Lo mejor? Se ejecuta localmente sin contaminar tu CI/CD.
 
+## ✨ Novedad v2.0.0 - Ahora Cross-Platform
+
+**¡Nueva arquitectura!** Migración completa a Node.js con ES6 modules para soporte más universal:
+- ✅ **Windows** - Git en Bash y Powershell
+- ✅ **WSL** - Subsistema de Linux
+- ✅ **Linux** - Funcionamiento nativo
+- ✅ **Worktrees** - Compatible con git worktrees en cualquier entorno
+- ✅ **IDEs** - Compatible con git manager de IntelliJ and VSCode -> mensaje de commit "auto" committea (y pushea si se quiere) con mensaje automático. Si el commit tiene problemas, se bloquea.
+
 ## 🎯 Características principales
 
 - 🔍 **Análisis de código pre-commit**: Detecta issues críticos antes de que lleguen al repo
-- 💬 **Mensajes de commit automáticos**: Escribe "auto" y Claude genera el mensaje perfecto
+- 💬 **Mensajes de commit automáticos**: Escribe "auto" y Claude genera el mensaje
 - 📋 **Generación de PRs**: Título, descripción y tests sugeridos con un solo comando
-- 🎨 **Modo SonarQube**: Métricas de calidad y Quality Gate integrados
-- 🚫 **Skip inteligente**: Excluye código legacy con comentarios SKIP-ANALYSIS
+- ⚠️ **Skip inteligente** (EXPERIMENTAL/BROKEN): Exclusión de código con comentarios SKIP_ANALYSIS - no funciona correctamente con git diff
+- 🕵️‍♂️ **Paralelización**: Análisis asincrónico de archivos con sub agentes
 - 🔄 **Auto-actualización**: Se mantiene actualizado automáticamente
+- 🌍 **Cross-platform**: Windows, WSL, macOS, Linux sin configuración especial
 
 ## 📋 CHEATSHEET
 
@@ -31,15 +41,15 @@ claude-hooks install --force --skip-auth
 
 ### 📦 Instalación y Gestión
 
-⚠️ **IMPORTANTE**: Todo debe ejecutarse desde consola WSL/Ubuntu (no PowerShell ni CMD). Ver [Configuración Previa](#-configuración-previa-importante) antes de comenzar.
+✨ **v2.0.0+**: Funciona terminales WSL y Bash.
 
 Se debe instalar el paquete globalmente, para luego gestionarlo localmente en cada repositorio.
 
 ```bash
-# En consola WSL/Ubuntu - Instalar globalmente
+# Instalar globalmente (desde cualquier terminal)
 npm install -g claude-git-hooks
 
-# Luego en cada proyecto (también desde WSL/Ubuntu)
+# Luego en cada proyecto
 cd /tu/proyecto
 claude-hooks install
 
@@ -75,10 +85,13 @@ git commit --no-verify -m "hotfix: corrección urgente"
 git commit --amend
 ```
 
-### 🚫 Exclusión de Código del Análisis
+### ⚠️ Exclusión de Código del Análisis (EXPERIMENTAL/BROKEN)
 
 ```java
-// SKIP-ANALYSIS
+// NOTA: Este feature NO funciona correctamente
+// Los marcadores no son detectados si fueron agregados en commits anteriores
+
+// SKIP_ANALYSIS_LINE
 private String legacyCode = "no analizar siguiente línea";
 
 // SKIP_ANALYSIS_BLOCK
@@ -174,25 +187,50 @@ git commit -m "feat: implement multiple features"
 
 **Best for:** Large commits (3+ files), refactoring tasks, feature branches
 
+### 🎨 Personalización y Customización
+
+**Archivos clave para modificar:**
+- `.claude/CLAUDE_PRE_COMMIT_SONAR.md` - Criterios (backend/frontend/data/db)
+- `.claude/CLAUDE_ANALYSIS_PROMPT_SONAR.md` - Template del prompt
+- `lib/hooks/pre-commit.js` - CONFIG object (extensiones, límites, umbrales)
+
+**Subagents (v1.5.5+)** - Para commits multi-archivo (3+), reduce análisis 60-70%:
+```bash
+export CLAUDE_USE_SUBAGENTS=true      # Activar paralelo
+export CLAUDE_SUBAGENT_MODEL=haiku    # haiku/sonnet/opus
+export CLAUDE_SUBAGENT_BATCH_SIZE=3   # Archivos simultáneos
+```
+
+**Ejemplo:**
+```bash
+vim .claude/CLAUDE_PRE_COMMIT_SONAR.md  # Agregar reglas API REST/Spring Boot
+```
+
 ## 🔧 Configuración Previa Importante
 
-### Credenciales Git en WSL
+### Requisitos del Sistema
+
+✨ **v2.0.0+**: Los hooks funcionan en cualquier terminal donde tengas:
+
+- **Node.js** >= 16.9.0
+- **Git** configurado
+- **Claude CLI** instalado y autenticado
 
-Debes configurar tus credenciales de git nuevamente en WSL:
+### Credenciales Git
+
+Si es tu primera vez configurando git en esta terminal, configura tus credenciales:
 
 ```bash
-# En WSL
 git config --global user.name "Tu Nombre"
 git config --global user.email "tu.email@ejemplo.com"
 
-# Si usas AWS CodeCommit o similar, reconfigura las credenciales
+# Si usas credential helper (opcional)
 git config --global credential.helper store
-# O configura tu credential helper específico
 ```
 
 ## 🚀 Instalación
 
-**IMPORTANTE**: Claude CLI corre en WSL, por lo que toda la instalación y uso de git debe hacerse desde la terminal WSL.
+✨ **v2.0.0+**: Instalación cross-platform. Funciona en PowerShell, CMD, WSL, macOS Terminal, Linux shell.
 
 ```bash
 # Instalar el paquete globalmente
@@ -203,15 +241,18 @@ cd tu-proyecto
 claude-hooks install
 ```
 
-El comando `claude-hooks install` ahora incluye:
+El comando `claude-hooks install` incluye:
 
-- ✅ Verificación completa de dependencias del sistema
-- ✅ Instalación automática de paquetes faltantes (jq, curl)
-- ✅ Configuración de Git (line endings WSL/Windows)
+- ✅ Verificación completa de dependencias del sistema (Node.js, Git, Claude CLI)
 - ✅ Verificación de autenticación Claude con entretenimiento (omitible con `--skip-auth`)
-- ✅ Instalación de hooks y archivos de pautas
+- ✅ Instalación de hooks con arquitectura bash wrapper + Node.js
+- ✅ Instalación de archivos de pautas y templates
 - ✅ Actualización automática de .gitignore con archivos de Claude
 
+**Nuevo en v2.0.0 - Soporte Cross-Platform:**
+
+Auto-detecta plataforma, convierte CRLF→LF en install, busca Claude en WSL (Windows), instala bash wrappers que convierten rutas C:\ a /c/
+
 **Opciones de instalación:**
 
 - `--force`: Reinstala aunque los hooks ya existan
@@ -255,7 +296,7 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
 
 ### Hook pre-commit (Análisis de código)
 
-1. **Intercepta cada intento de commit** (en WSL)
+1. **Intercepta cada intento de commit**
 2. **Extrae y filtra archivos modificados**:
    - Solo analiza: Java, XML, properties, yml, yaml
    - Omite archivos mayores a 100KB
@@ -309,21 +350,19 @@ Si no existe un `.gitignore`, se creará uno nuevo. Si ya existe, las entradas s
 - **Modo debug**: `DEBUG=1 git commit` guarda respuestas en `debug-claude-response.json`
 - **Análisis de PR**: Nuevo comando `analyze-diff` para generar información de Pull Requests
 - **Validación de dependencias**: Verifica que Claude CLI esté autenticado antes de ejecutar
-- **Exclusión de código del análisis con SKIP-ANALYSIS**: Puedes excluir código específico del análisis usando comentarios `// SKIP-ANALYSIS`:
+- **⚠️ Exclusión de código del análisis (EXPERIMENTAL/BROKEN)**: Los marcadores `// SKIP_ANALYSIS_LINE` y `// SKIP_ANALYSIS_BLOCK` no funcionan correctamente. El hook analiza git diff en lugar del archivo completo, por lo que marcadores agregados en commits anteriores no son detectados en cambios subsecuentes.
 
 ```java
-// Excluir una sola línea
-// SKIP-ANALYSIS
-@Autowired private LegacyService legacyService;  // Esta línea no será analizada
+// NOTA: Este feature actualmente NO funciona de forma confiable
+// SKIP_ANALYSIS_LINE
+@Autowired private LegacyService legacyService;
 
-// Excluir un bloque de código
-// SKIP-ANALYSIS_BLOCK
+// SKIP_ANALYSIS_BLOCK
 @Deprecated
 public void methodWithKnownIssues() {
-    // Código legacy que no queremos que sea analizado
-    System.out.println("Debug temporal");
+    System.out.println("Legacy code");
 }
-// SKIP-ANALYSIS_BLOCK
+// SKIP_ANALYSIS_BLOCK
 ```
 
 ### Desactivar/Activar hooks
@@ -351,17 +390,17 @@ claude-hooks status
 
 ### Scripts
 
-En el archivo `pre-commit`:
+✨ **v2.0.0+**: Configuración en archivos Node.js dentro de `lib/hooks/`.
+
+En `lib/hooks/pre-commit.js`:
 
 - **`MAX_FILE_SIZE`**: Tamaño máximo de archivo a analizar (default: 100KB)
 - **`MAX_FILES`**: Número máximo de archivos por commit (default: 10)
-- **`CLAUDE_CLI`**: Comando de Claude CLI (default: "claude")
-- **`GUIDELINES_FILE`**: Archivo de pautas (default: ".claude/CLAUDE_PRE_COMMIT_SONAR.md")
+- **`ALLOWED_EXTENSIONS`**: Extensiones permitidas (default: .java, .xml, .properties, .yml, .yaml)
 
-En el archivo `prepare-commit-msg`:
+En `lib/hooks/prepare-commit-msg.js`:
 
 - **`MAX_FILE_SIZE`**: Tamaño máximo para incluir diff completo (default: 100KB)
-- **`CLAUDE_CLI`**: Comando de Claude CLI (default: "claude")
 
 ### Pautas de Evaluación
 
@@ -386,27 +425,42 @@ No hay... esto es la perfección hecha código.
 
 ### Estructura del Proyecto
 
+✨ **v2.0.0+**: Nueva arquitectura modular con ES6 modules.
+
 ```
 claude-git-hooks/
 ├── bin/
-│   └── claude-hooks                          # CLI principal con verificación completa
+│   └── claude-hooks                          # CLI principal (ES6 modules)
+├── lib/                                      # 🆕 Código Node.js modular
+│   ├── hooks/
+│   │   ├── pre-commit.js                     # Hook de análisis (Node.js)
+│   │   └── prepare-commit-msg.js             # Hook de mensajes (Node.js)
+│   └── utils/
+│       ├── logger.js                         # Sistema de logging centralizado
+│       ├── git-operations.js                 # Operaciones git abstractas
+│       ├── file-operations.js                # I/O con filtro SKIP_ANALYSIS_LINE
+│       ├── claude-client.js                  # Cliente Claude CLI
+│       ├── prompt-builder.js                 # Constructor de prompts
+│       └── resolution-prompt.js              # Generador de resolution prompts
 ├── templates/
-│   ├── pre-commit                            # Hook de análisis de código
-│   ├── prepare-commit-msg                    # Hook de generación de mensajes
+│   ├── pre-commit                            # Bash wrapper (llama a lib/hooks/pre-commit.js)
+│   ├── prepare-commit-msg                    # Bash wrapper (llama a lib/hooks/prepare-commit-msg.js)
 │   ├── check-version.sh                      # Script de verificación de versión
-│   ├── CLAUDE_PRE_COMMIT_SONAR.md            # Pautas SonarQube para pre commit
+│   ├── CLAUDE_PRE_COMMIT_SONAR.md            # Pautas SonarQube
 │   ├── CLAUDE_ANALYSIS_PROMPT_SONAR.md       # Template de prompt para análisis
 │   └── CLAUDE_RESOLUTION_PROMPT.md           # Template para resolución de issues
+├── test/                                     # 🆕 Tests unitarios con Jest
+│   └── unit/
+│       └── logger.test.js                    # Tests del logger
 ├── .claude/                                  # Directorio de configuración local (gitignore)
 │   └── settings.local.json                   # Configuración local del usuario
-├── package.json                              # Configuración NPM
+├── jest.config.js                            # 🆕 Configuración Jest para ES6
+├── .eslintrc.json                            # 🆕 Configuración ESLint
+├── .prettierrc.json                          # 🆕 Configuración Prettier
+├── package.json                              # Configuración NPM (type: "module")
 ├── package-lock.json                         # Lock file de NPM
 ├── README.md                                 # Este archivo
-├── README-NPM.md                             # Documentación para publicación NPM
 ├── CHANGELOG.md                              # Historial de versiones
-├── PUBLISH.md                                # Guía de publicación
-├── CLAUDE_PRE_COMMIT_SONAR.md                # Pautas de evaluación (legacy)
-├── pre-commit                                # Hook principal (legacy)
 └── .gitignore                                # Archivos ignorados por git
 ```
 
@@ -432,10 +486,12 @@ claude-hooks install
 
 #### 1. Modificar Hooks
 
-Los hooks están en `templates/`:
+✨ **v2.0.0+**: La lógica de los hooks está en `lib/hooks/`:
 
-- `templates/pre-commit` - Lógica de análisis de código
-- `templates/prepare-commit-msg` - Lógica de generación de mensajes
+- `lib/hooks/pre-commit.js` - Lógica de análisis de código (Node.js ES6)
+- `lib/hooks/prepare-commit-msg.js` - Lógica de generación de mensajes (Node.js ES6)
+- `templates/pre-commit` - Bash wrapper que llama al script Node.js
+- `templates/prepare-commit-msg` - Bash wrapper que llama al script Node.js
 
 #### 2. Probar Localmente