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

description

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)

   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

   tools/linter/run_clang-tidy.sh --fix archivo1.cpp archivo2.hpp
   

2. Informar cambios

   • Listar archivos modificados
   • Recomendar revisión manual

3. Recompilar

   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