🧪 Qualidade de Código

speech-ai-hexagonal · Fase 2 · SonarQube + JaCoCo + Quality Gates

🎯 Objetivo da Fase 2

A Fase 2 adiciona uma camada de maturidade técnica focada em:

JaCoCo

Geração automatizada de relatórios de cobertura para garantir validação contínua dos casos de uso e regras de domínio.

SonarQube

Análise estática local para identificação de bugs, vulnerabilidades, code smells e dívida técnica.

Coverage Gate

Threshold mínimo de cobertura aplicado no build para impedir regressões silenciosas de qualidade.

Pipeline Local

Execução completa de qualidade diretamente no ambiente do desenvolvedor, antes da CI remota.

📍 Roadmap da Fase 2

Versão Item Status
v2.1.0 Infraestrutura Local (Docker Compose) planejado
v2.2.0 Plugins, Dependências e Task Graph no Gradle planejado
v2.3.0 Thresholds e Exclusões do JaCoCo planejado
v2.4.0 Variáveis de Ambiente e Propriedades do Sonar planejado
v2.5.0 Validação do Pipeline Local planejado

⚙️ Fluxo de Qualidade

./gradlew clean test jacocoTestReport sonar

Pipeline completa de validação local da qualidade do projeto.

↓
test
  • executa testes unitários
  • executa testes de integração
  • gera métricas iniciais de cobertura
↓
jacocoTestReport
  • gera relatório HTML
  • gera relatório XML
  • exporta cobertura para o SonarQube
↓
jacocoTestCoverageVerification
  • valida threshold mínimo ≥ 60%
  • interrompe build em caso de cobertura insuficiente
↓
sonar
  • envia métricas para o SonarQube
  • executa análise estática
  • gera indicadores de qualidade
↓
Dashboard SonarQube
  • bugs
  • vulnerabilidades
  • code smells
  • coverage
  • dívida técnica

🚫 Exclusões de cobertura

Algumas classes não entram no coverage gate por não possuírem lógica de negócio relevante.

Pacote/Classe Motivo
infrastructure/config Configuração Spring
*Application.java Bootstrap do Spring Boot
dto/ Objetos sem regra de negócio
record Estruturas imutáveis sem comportamento

🔐 Variáveis de ambiente

Variável Descrição
SONAR_HOST_URL URL do servidor SonarQube
SONAR_TOKEN Token de autenticação
SONAR_PROJECT_KEY Identificador do projeto
export SONAR_HOST_URL=http://localhost:9000 export SONAR_TOKEN=local export SONAR_PROJECT_KEY=speech-ai-hexagonal

⚠️ Troubleshooting

SonarQube não sobe

Linux exige configuração mínima de memória virtual.

sudo sysctl -w vm.max_map_count=524288

Build falhando no coverage

O threshold mínimo não foi atingido. Adicione testes para:

  • use cases
  • domain services
  • adapters
  • mappers

Dashboard sem cobertura

Verifique se o XML do JaCoCo foi gerado corretamente.

./gradlew jacocoTestReport