/sonarqube

name: sonarqube
description: "Levantar SonarQube con Docker, analizar el código y proponer mejoras. También: análisis estático, deuda técnica, code smells, cobertura, calidad automatizada."
disable-model-invocation: true

Análisis de calidad con SonarQube

Resumen

Este skill levanta una instancia de SonarQube con Docker, ejecuta un análisis del código del proyecto y traduce los resultados en propuestas de mejora accionables. SonarQube detecta bugs, vulnerabilidades, code smells y problemas de cobertura que las herramientas de linting no cubren.

No sustituye al qa-engineer ni al security-officer: complementa su trabajo con una segunda opinión automatizada basada en reglas estáticas probadas en millones de proyectos.

Proceso

Paso 1: preflight de Docker y permisos

Comprobar si Docker está disponible y si el daemon responde:

docker --version
docker info

Interpreta el resultado con estas reglas:

• **Si `docker --version` falla**: Docker no está instalado. Explica al usuario que SonarQube lo necesita y que la instalación puede requerir permisos de administrador.
• **Si `docker --version` funciona pero `docker info` falla**: Docker está instalado, pero el daemon no está disponible. Explica al usuario que hay que arrancar Docker Desktop o el servicio del sistema antes de continuar.

**No instales Docker, no abras Docker Desktop y no arranques el daemon sin aprobación explícita del usuario.** Si la orden viene desde `/alfred audit`, respeta la decisión tomada en su preflight. Si no existe una autorización previa, pídela ahora y espera respuesta.

Si el usuario autoriza la instalación, instala la última versión estable según la plataforma:

**macOS:**

brew install --cask docker
open -a Docker

**Linux (Ubuntu/Debian):**

curl -fsSL https://get.docker.com | sh
sudo systemctl start docker
sudo usermod -aG docker $USER

**Windows (PowerShell como administrador):**

winget install Docker.DockerDesktop

Si el usuario autoriza arrancar Docker cuando está instalado pero el daemon no responde, usa la estrategia mínima necesaria para la plataforma:

**macOS:**

open -a Docker

**Linux (systemd):**

sudo systemctl start docker

**Windows (PowerShell):**

Start-Process "C:\Program Files\Docker\Docker\Docker Desktop.exe"

Después de instalar o arrancar Docker, verifica otra vez con `docker info`.

• Si `docker info` responde correctamente, continúa.
• Si el usuario rechaza la instalación o el arranque, o si el daemon sigue sin responder, **detén aquí la rama de SonarQube** y devuelve un resultado explícito: "SonarQube omitido por decisión del usuario o por falta de permisos". No intentes forzarlo por otras vías.

Paso 2: levantar SonarQube

Antes de levantar el contenedor:

• Comprueba si ya existe `sonarqube-alfred`. Si existe de una ejecución anterior, elimínalo primero para evitar conflictos:

docker rm -f sonarqube-alfred 2>/dev/null || true

• Comprueba si el puerto `9000` ya está en uso. Si lo está, detén la ejecución y pregunta al usuario si quiere liberar ese puerto o continuar sin SonarQube. No mates procesos por tu cuenta.

docker run -d --name sonarqube-alfred -p 9000:9000 sonarqube:community

Esperar a que SonarQube esté listo (puede tardar 1-2 minutos):

Usa este bucle exacto o uno equivalente. **No uses la variable `status` en scripts de shell**: en `zsh` es de solo lectura y romperá la espera. Si necesitas guardar el estado en una variable, usa `sonar_status`.

until curl -s http://localhost:9000/api/system/status | grep -q '"status":"UP"'; do sleep 5; done

Credenciales por defecto: admin/admin. Cambiar la contraseña en el primer acceso.

Paso 3: configurar el proyecto

• Crear un proyecto en SonarQube (vía API o interfaz web).
• Generar un token de autenticación para el análisis.
• Crear o verificar el fichero `sonar-project.properties` en la raíz del proyecto:

sonar.projectKey=nombre-del-proyecto
sonar.sources=src
sonar.tests=tests
sonar.language=ts
sonar.sourceEncoding=UTF-8

Adaptar según el stack del proyecto (lenguaje, directorios de código y tests).

Paso 4: ejecutar el análisis

Para proyectos Node/TypeScript:

npx sonarqube-scanner

Para proyectos Python:

pip install pysonar-scanner && pysonar-scanner

Alternativa universal con Docker:

docker run --rm -v "$(pwd):/usr/src" sonarsource/sonar-scanner-cli

Paso 5: interpretar resultados

Acceder a http://localhost:9000 y revisar el dashboard del proyecto. Clasificar los hallazgos por:

• **Bugs**: errores que pueden causar comportamiento incorrecto. Prioridad alta.
• **Vulnerabilidades**: problemas de seguridad detectados por reglas OWASP/CWE. Notificar al security-officer.
• **Code smells**: problemas de mantenibilidad. Priorizar los de mayor impacto.
• **Cobertura**: porcentaje de código cubierto por tests. Identificar zonas sin cobertura críticas.

Paso 6: generar informe de mejoras

Crear un informe con:

• Resumen ejecutivo: métricas principales (bugs, vulnerabilidades, cobertura, deuda técnica).
• Top 10 hallazgos por impacto con la corrección propuesta.
• Zonas de código con mayor densidad de problemas.
• Comparación con el análisis anterior si existe.

Paso 7: limpiar

Cuando el análisis esté completo y los resultados revisados:

docker stop sonarqube-alfred && docker rm sonarqube-alfred

Si el análisis falla a mitad del proceso, intenta igualmente la limpieza final del contenedor temporal antes de salir.

Qué NO hacer

• No dejar SonarQube corriendo indefinidamente. Es una herramienta de análisis puntual, no un servicio permanente.
• No instalar Docker, arrancar el daemon ni abrir Docker Desktop sin permiso explícito del usuario.
• No tratar todos los hallazgos como iguales. Priorizar por impacto real, no por cantidad.
• No corregir hallazgos sin entender por qué SonarQube los marca.