🔧 Chore — Achieve SonarQube Quality Gate Compliance

🧭 Chore Summary

Drive the project's SonarQube quality-gate to 0 actionable issues while keeping all tests green.

🧱 Areas Affected

• Pre-commit hooks / linters
• Build system / Make targets (make sonarqube, make pre-commit)
• GitHub Actions / CI pipeline
• Runtime codebase (quality fixes, code smells, coverage improvements, etc.)

⚙️ Context / Rationale

SonarQube static analysis surfaces code quality issues, vulnerabilities, bugs, and code smells before they reach production. A clean quality gate lets us maintain high code standards and ensures new code meets our quality baseline.

📦 Related Make Targets

Bold targets are mandatory; CI must fail if any of them reports issues.

📋 Acceptance Criteria

• make sonarqube passes the configured Quality Gate (no New Code bugs/vulns/security-hotspots).
• Code coverage meets the Quality Gate threshold (typically 80%+).
• make pre-commit runs clean with no diffs.
• make test and make smoketest pass.
• GitHub Actions enforces SonarQube Quality Gate (e.g. Sonar qualitygate step).
• Changelog entry under "Maintenance".

🛠️ Task List (suggested flow)

1. Baseline scan

   make sonarqube   # (requires SONAR_TOKEN)

2. SonarQube remediation priorities

   • Bugs - Fix immediately (can cause runtime errors)
   • Vulnerabilities - Security issues that need addressing
   • Security Hotspots - Review and mark as safe or fix
   • Code Smells - Refactor to improve maintainability
   • Coverage Gaps - Add missing unit tests

3. Common SonarQube fixes

   Issue Type	Fix Strategy
   Cognitive Complexity	Break down complex functions, extract methods
   Duplicated Code	Extract common functionality into shared utilities
   Uncovered Lines	Add unit tests for untested code paths
   Security Hotspots	Review and either fix or mark as safe with justification
   Code Smells	Follow suggested refactoring patterns

4. Coverage improvement

   • Focus on critical business logic first
   • Add edge case tests
   • Test error handling paths
   • Use coverage reports to identify gaps

5. Suppressions (last resort)

   • In Sonar, mark false positives as Won't Fix with a clear reason
   • Use inline comments sparingly: # NOSONAR with justification
   • Document any architectural decisions that lead to suppressions

6. CI integration

   • Extend GitHub Actions to run SonarQube analysis
   • Configure Quality Gate to fail the build if not met
   • Set up branch analysis for PRs

7. Local & container smoke-tests (unchanged but reiterated)

   • make venv install install-dev test smoketest – full local pass.

   • Docker: make docker-prod docker-run-ssl-host – build prod image & run containerised smoke-tests.

   • Compose: make compose-up (Postgres + Redis) with freshly-built :latest image.

   • DB migrations: run full Alembic cycle.

   • Helm / minikube:

     make minikube-install minikube-start
     helm upgrade --install mcp charts/mcp-stack

   • PyPI dry-run:

     make devpi-install devpi-init devpi-start
     make devpi-upload
     make clean

8. Final validation

   make lint test smoketest sonarqube

📖 References

• SonarQube Python Analyzer: https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/languages/python/
• Quality Gates: https://docs.sonarsource.com/sonarqube/latest/user-guide/quality-gates/
• Code Coverage: https://docs.sonarsource.com/sonarqube/latest/analyzing-source-code/test-coverage/

🧩 Additional Notes

• SonarQube's Quality Gate thresholds are configurable; work with your team to set appropriate levels.
• Keep fixes granular (one issue type or module per commit) to simplify review & blame.
• Consider setting up SonarLint in your IDE for real-time feedback before commits.