orni_attack/tools/hooks/README.md

# Git Hooks - Orni Attack

Este directorio contiene los **git hooks** versionados para el proyecto Orni Attack.

Los hooks permiten ejecutar automáticamente verificaciones de calidad de código antes de hacer commits.

---

## 📦 Instalación

### Instalación automática (recomendada)

Ejecuta el script de instalación desde la raíz del proyecto:

```bash
./tools/hooks/install.sh
```

### Instalación manual

```bash
cp tools/hooks/pre-commit .git/hooks/
chmod +x .git/hooks/pre-commit
```

---

## 🔍 Hooks disponibles

### `pre-commit`

**Se ejecuta automáticamente antes de cada commit.**

Realiza dos verificaciones en los archivos `.cpp` y `.hpp` modificados:

#### 1. 🎨 clang-format (formato de código)

- **Acción**: Formatea automáticamente el código según `.clang-format`
- **Comportamiento**: Si encuentra problemas de formato, los arregla automáticamente y añade los cambios al commit
- **Resultado**: Código siempre bien formateado sin esfuerzo manual

#### 2. 🔍 clang-tidy (análisis estático)

- **Acción**: Verifica el código según las reglas de `.clang-tidy`
- **Comportamiento**:
  - ✅ Si no hay errores → commit permitido
  - ❌ Si hay errores → commit **bloqueado** y muestra los errores
- **Resultado**: Previene commits con problemas de calidad

---

## 📋 Ejemplo de uso

```bash
# 1. Modificas código
vim source/game/entities/nau.cpp

# 2. Añades al staging
git add source/game/entities/nau.cpp

# 3. Intentas commit
git commit -m "feat: añadir nueva funcionalidad"

# → El hook se ejecuta automáticamente:
🔍 Pre-commit hook: verificando código...
📝 Archivos a revisar: source/game/entities/nau.cpp

🎨 Ejecutando clang-format...
  ✏️  Formateado: source/game/entities/nau.cpp
✅ Archivos formateados automáticamente y añadidos al commit

🔍 Ejecutando clang-tidy...
  ✅ source/game/entities/nau.cpp

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Pre-commit hook: TODO OK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  🎨 clang-format: OK (archivos formateados)
  🔍 clang-tidy: OK (sin errores)

[main abc1234] feat: añadir nueva funcionalidad
 1 file changed, 10 insertions(+)
```

---

## ❌ ¿Qué pasa si hay errores?

Si clang-tidy encuentra errores, el hook **bloquea el commit** y te muestra:

```bash
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ COMMIT BLOQUEADO: clang-tidy encontró errores
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❌ Errores en source/game/entities/nau.cpp:
source/game/entities/nau.cpp:42:10: error: method 'getPosition' can be made const
      ^
                                                                      const

💡 Soluciones:
  1. Corrige los errores manualmente
  2. O ejecuta: make tidy (aplica fixes automáticos)
  3. Luego: git add <archivos> && git commit

⚠️  Si necesitas saltarte el hook (NO RECOMENDADO):
  git commit --no-verify
```

### Soluciones

**Opción 1: Arreglar manualmente**

Edita el archivo y corrige los errores que muestra clang-tidy.

**Opción 2: Auto-fix con make tidy**

```bash
make tidy              # Aplica fixes automáticos
git add .              # Añade los cambios
git commit -m "..."    # Intenta commit de nuevo
```

**Opción 3: Saltar el hook (NO RECOMENDADO)**

```bash
git commit --no-verify -m "mensaje"
```

⚠️ **Solo usa `--no-verify` en casos excepcionales**, ya que permite commits con código de baja calidad.

---

## 🚀 Ventajas

✅ **Solo código nuevo**: Revisa únicamente archivos modificados (rápido)
✅ **Automático**: No tienes que acordarte de ejecutar clang-tidy
✅ **Formato automático**: clang-format arregla el código por ti
✅ **Bloquea errores**: Previene commits con problemas de calidad
✅ **No ralentiza compilación**: Solo se ejecuta en commits, no en `make`
✅ **Excluye código externo**: Ignora automáticamente `audio/` y `legacy/`

---

## 🔧 Configuración

Los hooks usan las configuraciones del proyecto:

- **`.clang-format`**: Reglas de formato de código
- **`.clang-tidy`**: Reglas de análisis estático
- **`CMakeLists.txt`**: Exclusiones de directorios (audio/, legacy/)

Si modificas estas configuraciones, los hooks aplicarán automáticamente las nuevas reglas.

---

## 🗑️ Desinstalación

Para desinstalar el hook:

```bash
rm .git/hooks/pre-commit
```

O para deshabilitarlo temporalmente:

```bash
mv .git/hooks/pre-commit .git/hooks/pre-commit.disabled
```

Para volver a habilitarlo:

```bash
mv .git/hooks/pre-commit.disabled .git/hooks/pre-commit
```

---

## 📚 Más información

- **clang-format**: https://clang.llvm.org/docs/ClangFormat.html
- **clang-tidy**: https://clang.llvm.org/extra/clang-tidy/
- **Git hooks**: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks

---

## ⚠️ Nota para desarrolladores

Los hooks de git están en `.git/hooks/` y **no se versionan automáticamente**. Por eso este directorio `tools/hooks/` contiene copias versionadas que se pueden instalar fácilmente.

**Cada nuevo desarrollador debe ejecutar el instalador** al clonar el repositorio:

```bash
git clone <repo-url>
cd orni
./tools/hooks/install.sh
```

---

## 🐛 Troubleshooting

### "clang-format: command not found"

Instala clang-format:

```bash
# macOS
brew install clang-format

# Ubuntu/Debian
sudo apt install clang-format

# Arch Linux
sudo pacman -S clang
```

### "clang-tidy: command not found"

Instala clang-tidy:

```bash
# macOS
brew install llvm
export PATH="/opt/homebrew/opt/llvm/bin:$PATH"

# Ubuntu/Debian
sudo apt install clang-tidy

# Arch Linux
sudo pacman -S clang
```

### Hook no se ejecuta

Verifica que el hook tiene permisos de ejecución:

```bash
ls -la .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

### Errores en macOS sobre SDK

El hook detecta automáticamente el SDK de macOS usando `xcrun --show-sdk-path`. Si falla, asegúrate de tener Command Line Tools instaladas:

```bash
xcode-select --install
```