primer commit

.claude/commands/lint-clang-tidy.md

@@ -0,0 +1,172 @@
+---
+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
+```