claude-git-hooks/README.md

Git hooks con Claude CLI para análisis de código y generación automática de mensajes de commit

# Pre-commit Hook con Claude CLI

Este directorio contiene un pre-commit hook que utiliza Claude CLI para revisar automáticamente el código antes de cada commit.

## 📁 Archivos en este Directorio

- **`README.md`** - Esta documentación
- **`pre-commit`** - Hook principal para análisis de código (con auto-actualización)
- **`prepare-commit-msg`** - Hook para generar mensajes de commit automáticos
- **`.gitattributes`** - Configuración para mantener line endings correctos
- **`CLAUDE_PRE_COMMIT.md`** - Pautas de evaluación formato estándar
- **`CLAUDE_PRE_COMMIT_SONAR.md`** - Pautas de evaluación formato SonarQube

## 🔧 Configuración Previa Importante

### 1. Armonización de Line Endings (EOL)

Debido a que Claude CLI corre en WSL y el desarrollo puede hacerse en Windows, es crucial configurar correctamente los line endings para evitar que los archivos de hooks se corrompan:

```bash
# IMPORTANTE: Usar la misma configuración en WSL y Windows
# Recomendación: usar 'input' en ambos entornos

# En WSL
git config core.autocrlf input

# En PowerShell/Windows
git config core.autocrlf input

# Verificar configuración actual
git config --local core.autocrlf
git config --global core.autocrlf
```

**⚠️ ADVERTENCIA**: Si tienes `core.autocrlf = true` en local e `input` en global, esto puede causar que los archivos de los hooks se vacíen. Asegúrate de que ambas configuraciones sean consistentes.

### 2. Credenciales Git en WSL

Debes configurar tus credenciales de git nuevamente en WSL:

```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
git config --global credential.helper store
# O configura tu credential helper específico
```

## 🚀 Instalación

### Paquete NPM Global (Recomendado)

**IMPORTANTE**: Claude CLI corre en WSL, por lo que toda la instalación y uso de git debe hacerse desde la terminal WSL.

```bash
# Instalar el paquete globalmente
npm install -g claude-git-hooks

# En cualquier repositorio, instalar los hooks
cd tu-proyecto
claude-hooks install
```

El comando `claude-hooks install` ahora 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 de autenticación Claude con entretenimiento
- ✅ Instalación de hooks y archivos de pautas

#### Añadir como Dependencia de Desarrollo

```bash
# Instalar como devDependency
npm install --save-dev claude-git-hooks
```

Luego añade esto a tu `package.json`:

```json
{
  "scripts": {
    "postinstall": "claude-hooks install"
  },
  "devDependencies": {
    "claude-git-hooks": "^1.2.0"
  }
}
```

## 🤖 Características

**✨ Auto-actualización incorporada**: Los hooks se actualizan automáticamente en cada commit.

**Hooks disponibles**:

- `pre-commit`: Análisis de código con Claude (solo archivos Java/config)
- `prepare-commit-msg`: Generación automática de mensajes de commit

## 🎯 Funcionamiento

### Hook pre-commit (Análisis de código)

1. **Intercepta cada intento de commit** (en WSL)
2. **Extrae y filtra archivos modificados**:
   - Solo analiza: Java, XML, properties, yml, yaml
   - Omite archivos mayores a 100KB
   - Límite de 10 archivos por commit
3. **Modos de análisis disponibles**:
   - **Estándar**: Formato clásico con score y recomendaciones detalladas
   - **SonarQube**: Simula salida de SonarQube con Quality Gate, métricas y clasificación de issues
4. **Construye prompt inteligente**:
   - Lee las pautas desde `CLAUDE_PRE_COMMIT.md` o `CLAUDE_PRE_COMMIT_SONAR.md`
   - Incluye el diff completo para archivos nuevos
   - Muestra solo cambios para archivos existentes
5. **Envía a Claude CLI para revisión**
6. **Procesa respuesta JSON**:
   - En modo estándar: evalúa `approved`, `score`, `recommendations`
   - En modo SonarQube: verifica `QUALITY_GATE`, muestra métricas y issues por severidad
7. **Decisión final**:
   - Si hay problemas críticos o quality gate falla → commit bloqueado
   - Si todo está bien → commit procede

### Hook prepare-commit-msg (Generación automática de mensajes)

1. **Se activa cuando el mensaje es**:
   - `"auto"`
2. **Analiza los cambios del staging area**:
   - Lista archivos modificados con estadísticas
   - Incluye diffs completos para archivos < 100KB
3. **Genera mensaje en formato Conventional Commits**:
   - Determina tipo: feat, fix, docs, style, refactor, test, chore
   - Crea título conciso y descriptivo
   - Añade body con detalles si es necesario
4. **Manejo de errores**:
   - Si falla la generación → cancela el commit completamente
   - No usa mensajes genéricos de fallback

### Características adicionales

- **Auto-actualización**: Los hooks se sincronizan automáticamente con las versiones en `git-hooks/`
- **Modo debug**: `DEBUG=1 git commit` guarda respuestas en `debug-claude-response.json`
- **Configuración persistente**: Guarda preferencias en `.claude-analysis-mode`
- **Validación de dependencias**: Verifica que Claude CLI esté autenticado antes de ejecutar

## 🛠️ Uso

**IMPORTANTE**: Todos los comandos git deben ejecutarse desde WSL.

### Commit normal

```bash
# Desde WSL
git add .
git commit -m "feat: nueva funcionalidad"
```

### Commit con mensaje automático 🤖

```bash
# Desde WSL
git add .
git commit -m "auto"  # Claude generará el mensaje automáticamente
```

Claude analizará los cambios y generará un mensaje de commit siguiendo las convenciones (feat, fix, docs, etc.).

**⚠️ Si la generación automática falla**: El commit se cancelará completamente. Simplemente ejecuta `git commit -m "tu mensaje"` manualmente.

### Modos de análisis 📊

Puedes elegir entre dos formatos de análisis:

#### 🎯 Configurar Modo (Recomendado)

```bash
# Cambiar a modo SonarQube (métricas y quality gate)
claude-hooks set-mode sonar

# Cambiar a modo estándar (score y recomendaciones)
claude-hooks set-mode standard

# Ver modo actual
claude-hooks status
```

#### 🔧 Variable de Entorno (Temporal)

```bash
# Sobrescribir temporalmente el modo configurado
export CLAUDE_ANALYSIS_MODE=sonar
git commit -m "mensaje"

# Volver al modo configurado
unset CLAUDE_ANALYSIS_MODE
```

#### 📋 Diferencias entre Modos

**Modo Estándar**:
- Análisis con puntuación del 1-10
- Recomendaciones detalladas por categoría
- Formato tradicional fácil de leer

**Modo SonarQube**:
- Quality Gate (PASSED/FAILED)
- Métricas: Reliability, Security, Maintainability
- Issues clasificados por severidad (Blocker, Critical, Major, Minor, Info)
- Security hotspots

#### 🔄 Cambio de Modo Interactivo

```bash
# Sin parámetros muestra ayuda interactiva
claude-hooks set-mode
```

### Saltar la revisión (usar con precaución)

```bash
# Desde WSL
git commit --no-verify -m "fix: corrección urgente"
```

### Modo debug

```bash
# Desde WSL
DEBUG=1 git commit -m "mensaje"
```

## 📊 Formato de Respuesta

Claude responde con un JSON que incluye:

- `approved`: Si el commit es aprobado
- `score`: Puntuación del 1-10
- `commitMessage`: Mensaje de commit generado (type, title, body)
- `recommendations`: Recomendaciones de mejora
- `blockingIssues`: Problemas que bloquean el commit

## 🔄 Desactivar/Activar

```bash
# Desactivar todos los hooks
claude-hooks disable

# Desactivar un hook específico
claude-hooks disable pre-commit
claude-hooks disable prepare-commit-msg

# Habilitar todos los hooks
claude-hooks enable

# Habilitar un hook específico
claude-hooks enable pre-commit
claude-hooks enable prepare-commit-msg

# Ver estado actual
claude-hooks status
```

## ⚙️ Configuración

### Variables de entorno disponibles

- **`CLAUDE_ANALYSIS_MODE`**: Selecciona el modo de análisis

  - Valores: `"standard"` o `"sonar"`
  - Ejemplo: `CLAUDE_ANALYSIS_MODE=sonar git commit -m "mensaje"`
  - Sobrescribe la preferencia guardada en `.claude-analysis-mode`

- **`DEBUG`**: Activa el modo debug
  - Valores: `1` para activar
  - Ejemplo: `DEBUG=1 git commit -m "mensaje"`
  - Guarda las respuestas de Claude en `debug-claude-response.json`

### Variables modificables en los archivos de hooks

En el archivo `pre-commit`:

- **`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 para modo estándar (default: "CLAUDE_PRE_COMMIT.md")
- **`GUIDELINES_FILE_SONAR`**: Archivo de pautas para modo SonarQube (default: "CLAUDE_PRE_COMMIT_SONAR.md")

En el archivo `prepare-commit-msg`:

- **`MAX_FILE_SIZE`**: Tamaño máximo para incluir diff completo (default: 100KB)
- **`CLAUDE_CLI`**: Comando de Claude CLI (default: "claude")

## 🐛 Troubleshooting

### "Claude CLI no está instalado"

```bash
# Desde WSL
npm install -g @anthropic-ai/claude-cli
claude auth login
```

### "No se recibió respuesta JSON válida"

- Verifica que Claude CLI esté autenticado en WSL
- Ejecuta en modo DEBUG para ver la respuesta completa
- Revisa que el archivo de pautas esté bien formateado

### El hook no se ejecuta

- Verifica que estés ejecutando git desde WSL
- Verifica permisos: `ls -la .git/hooks/pre-commit`
- Debe mostrar permisos de ejecución (-rwxr-xr-x)

### Problemas con line endings

- Si ves errores de "^M" o caracteres extraños:
  ```bash
  # En WSL
  git config core.autocrlf input
  ```

### Los hooks se vacían o corrompen

Este problema suele ocurrir por conflictos de configuración de line endings:

1. **Verifica configuraciones**:

   ```bash
   git config --local core.autocrlf  # Debe ser 'input'
   git config --global core.autocrlf # Debe ser 'input'
   ```

2. **Si están diferentes, corrige**:

   ```bash
   git config --local core.autocrlf input
   ```

3. **Restaura los hooks**:
   ```bash
   ./git-hooks/setup-wsl.sh --sync
   ```

### Credenciales no funcionan en WSL

- Las credenciales de Windows no se comparten automáticamente con WSL
- Reconfigura tus credenciales git en WSL

## 📝 Personalización

Puedes modificar las pautas de evaluación editando `CLAUDE_PRE_COMMIT.md` para adaptarlas a los estándares de tu equipo.

## 🔄 Arquitectura del Sistema

```
WSL Terminal
     │
     ├─→ git add/commit
     │
     └─→ .git/hooks/pre-commit
              │
              ├─→ Lee archivos modificados
              ├─→ Lee CLAUDE_PRE_COMMIT.md
              ├─→ Construye prompt
              │
              └─→ Claude CLI
                       │
                       └─→ Respuesta JSON
                              │
                              ├─→ ✅ Approved → Commit procede
                              └─→ ❌ Rejected → Commit bloqueado
```

## 📌 Notas Importantes

1. **Todo en WSL**: Claude CLI solo funciona en WSL, por lo que todos los comandos git deben ejecutarse desde ahí
2. **Line Endings**: La configuración de `core.autocrlf` es crítica para evitar problemas entre Windows y Linux
3. **Credenciales**: Necesitarás reconfigurar tus credenciales git en WSL
4. **Performance**: La revisión puede tardar unos segundos dependiendo del tamaño de los cambios

## 🔧 Desarrollo y Contribución

### Estructura del Proyecto

```
claude-git-hooks/
├── bin/
│   └── claude-hooks          # CLI principal con verificación completa
├── templates/
│   ├── pre-commit            # Hook de análisis de código
│   ├── prepare-commit-msg    # Hook de generación de mensajes
│   ├── CLAUDE_PRE_COMMIT.md  # Pautas estándar
│   └── CLAUDE_PRE_COMMIT_SONAR.md # Pautas SonarQube
├── package.json              # Configuración NPM
├── README.md                 # Este archivo
├── CHANGELOG.md              # Historial de versiones
└── PUBLISH.md                # Guía de publicación
```

### Configuración del Entorno de Desarrollo

```bash
# 1. Clonar el repositorio
git clone https://github.com/pablorovito/claude-git-hooks.git
cd claude-git-hooks

# 2. Instalar dependencias (si las hubiera)
npm install

# 3. Enlazar para desarrollo local
npm link

# 4. Probar en un repositorio de prueba
cd /path/to/test-repo
claude-hooks install
```

### Workflow de Desarrollo

#### 1. Modificar Hooks

Los hooks están en `templates/`:

- `templates/pre-commit` - Lógica de análisis de código
- `templates/prepare-commit-msg` - Lógica de generación de mensajes

#### 2. Probar Localmente

```bash
# Después de modificar archivos
npm link

# En un repo de prueba
claude-hooks install --force  # Fuerza reinstalación

# Probar funcionalidad
git add .
git commit -m "auto"  # Probar generación automática
git commit -m "test"  # Probar análisis
```

#### 3. Actualizar Documentación

- `README.md` - Documentación principal
- `README-NPM.md` - Para usuarios de NPM
- `templates/CLAUDE_PRE_COMMIT*.md` - Pautas de evaluación

#### 4. Versioning y Publicación

```bash
# Actualizar versión
npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

# Publicar nueva versión
npm publish

# Tag en git
git push --tags
```

### Debugging

#### Modo Debug

```bash
# Activar debug en hooks
DEBUG=1 git commit -m "test"

# Ver logs del CLI
claude-hooks install --debug
```

#### Logs Útiles

- `debug-claude-response.json` - Respuestas de Claude en modo debug
- `~/.npm/_logs/` - Logs de npm install
- `.git/hooks/` - Verificar que hooks están instalados

### Testing

#### Test Manual

```bash
# 1. Crear repo de prueba
mkdir test-repo && cd test-repo
git init

# 2. Instalar hooks
claude-hooks install

# 3. Crear archivos de prueba
echo 'public class Test {}' > Test.java
git add .

# 4. Probar análisis
git commit -m "test: nueva clase"

# 5. Probar generación automática
echo 'public void newMethod() {}' >> Test.java
git add .
git commit -m "auto"
```

#### Casos de Prueba

- ✅ Análisis de código Java
- ✅ Generación automática de mensajes
- ✅ Modo SonarQube
- ✅ Archivos grandes (>100KB)
- ✅ Commits sin archivos Java
- ✅ Enable/disable hooks
- ✅ Modo debug

### Contribuir

1. **Fork** el repositorio
2. **Crear branch** para tu feature: `git checkout -b feature/nueva-funcionalidad`
3. **Commit** tus cambios: `git commit -m "feat: nueva funcionalidad"`
4. **Push** al branch: `git push origin feature/nueva-funcionalidad`
5. **Abrir Pull Request**

### Roadmap

- [ ] Soporte para más lenguajes (Python, JavaScript, etc.)
- [ ] Configuración más granular por proyecto
- [ ] Integration con IDEs populares
- [ ] Métricas de uso y performance
- [ ] Tests automatizados