---
description: Ejecuta clang-tidy en archivos C++ y analiza los resultados
---

# Lint clang-tidy Command

Ejecuta análisis estático con clang-tidy en archivos C++ específicos, analiza los resultados inteligentemente, e identifica issues reales vs falsos positivos.

## Propósito

clang-tidy detecta:
- Oportunidades de modernización C++ (auto, range-for, etc.)
- Problemas de legibilidad del código
- Potenciales bugs y memory leaks
- Optimizaciones de performance
- Violaciones de mejores prácticas

## Workflow de Ejecución

1. **Solicitar archivos al usuario** (si no se especifican)
   - Pedir rutas de archivos `.cpp` o `.hpp` a analizar
   - Validar que los archivos existen

2. **Verificar build directory**
   - Confirmar que `build/compile_commands.json` existe
   - Si no existe, informar al usuario que debe compilar primero

3. **Ejecutar clang-tidy (sin --fix)**
   ```bash
   tools/linter/run_clang-tidy.sh archivo1.cpp archivo2.hpp
   ```

4. **Capturar y analizar salida**
   - Parsear mensajes de error/warning
   - Clasificar por categoría (modernize, readability, performance, bugprone, etc.)
   - Identificar falsos positivos conocidos

5. **Presentar resumen al usuario**
   - Agrupar por tipo de issue
   - Separar "Críticos" vs "Recomendaciones" vs "Falsos Positivos"
   - Mostrar líneas de código afectadas con contexto

6. **Ofrecer acciones**
   - Preguntar si aplicar `--fix` automáticamente
   - Si el usuario acepta, ejecutar con `--fix` y recompilar

## Falsos Positivos Conocidos

Ignorar o marcar como "Opcional" estos casos:

### `readability-magic-numbers` / `cppcoreguidelines-avoid-magic-numbers`
- **Contexto:** Game constants (block sizes, velocities, timers)
- **Ejemplo:** `const int BLOCK = 16;`, `player.vx = 3.0F;`
- **Acción:** Marcar como "Opcional - Game constant"

### `modernize-use-trailing-return-type`
- **Contexto:** Funciones con tipos de retorno simples
- **Ejemplo:** `int getValue() { return x_; }`
- **Acción:** Marcar como "Opcional - Style preference"

### Errores en `defaults.hpp`
- **Contexto:** Archivos de constantes del juego
- **Acción:** Ignorar completamente, mencionar al usuario que es conocido

### `readability-identifier-length`
- **Contexto:** Variables cortas comunes en loops o coordenadas (`x`, `y`, `i`, `j`)
- **Acción:** Marcar como "Opcional - Common convention"

## Categorización de Issues

### 🔴 Críticos (Requieren atención)
- `bugprone-*`: Potenciales bugs
- `cert-*`: Security issues
- Memory leaks y null pointer dereferences
- Undefined behavior

### 🟡 Recomendados (Mejoran calidad)
- `modernize-*`: C++20 modernization
- `performance-*`: Optimizaciones
- `readability-*`: Mejoras de legibilidad (excepto magic-numbers)

### ⚪ Opcionales (A criterio)
- `readability-magic-numbers` en game constants
- `modernize-use-trailing-return-type`
- `readability-identifier-length` para `x`, `y`, `i`, `j`

### ⚫ Ignorar (Falsos positivos)
- Errores en `defaults.hpp`
- Issues en carpeta `external/`
- Warnings en headers del sistema

## Formato de Reporte al Usuario

```
=== clang-tidy Analysis Results ===

📁 Archivos analizados:
  - source/game/entities/player.cpp
  - source/game/entities/player.hpp

🔴 Críticos (2):
  player.cpp:145 [bugprone-use-after-move] - Uso de variable después de std::move()
  player.cpp:230 [cert-err58-cpp] - Excepción en inicialización estática

🟡 Recomendados (5):
  player.cpp:67 [modernize-use-auto] - Puede usar 'auto' en lugar de tipo explícito
  player.cpp:102 [performance-unnecessary-copy-initialization] - Copia innecesaria
  player.hpp:23 [readability-redundant-access-specifiers] - Especificador de acceso redundante

⚪ Opcionales (3):
  player.cpp:88 [readability-magic-numbers] - Magic number '16' (Game constant: BLOCK size)
  player.cpp:120 [modernize-use-trailing-return-type] - Style preference

✅ Total: 10 issues (2 críticos, 5 recomendados, 3 opcionales)

---

💡 Recomendaciones:
1. Corregir los 2 issues críticos manualmente
2. Aplicar --fix para 5 recomendaciones (revisa cambios antes de commitear)
3. Los opcionales son aceptables en código de juego

¿Deseas aplicar fixes automáticos para los issues recomendados? (y/n)
```

## Aplicar Fixes Automáticos

Si el usuario acepta:

1. **Ejecutar con --fix**
   ```bash
   tools/linter/run_clang-tidy.sh --fix archivo1.cpp archivo2.hpp
   ```

2. **Informar cambios**
   - Listar archivos modificados
   - Recomendar revisión manual

3. **Recompilar**
   ```bash
   cmake --build build
   ```

4. **Verificar compilación exitosa**
   - Si falla, informar errores
   - Sugerir revertir cambios si es necesario

## Notas Importantes

- **Siempre analizar sin --fix primero** para revisar cambios propuestos
- **Requiere build/compile_commands.json** - el usuario debe haber compilado antes
- **Contexto importa** - Game code tiene patrones legítimos que linters marcan como issues
- **No aplicar --fix ciegamente** - Algunos fixes pueden romper lógica del juego
- **Archivos específicos** - Siempre analizar archivos concretos, no todo el proyecto

## Integración con Otros Comandos

Este comando puede ser llamado desde:
- `/refactor-class` - Después de refactorizar una clase
- Manualmente por el usuario para análisis ad-hoc
- Antes de commits importantes

---

**Uso:**
```
/lint-clang-tidy
(El comando preguntará qué archivos analizar)

O especificar directamente:
/lint-clang-tidy source/game/entities/player.cpp
```