labFusion/docs/SONARQUBE_INTEGRATION.md

SonarQube Integration for LabFusion

This document explains how to configure SonarQube integration for all LabFusion services in a unified project.

Overview

All LabFusion services (API Gateway, Service Adapters, API Docs, Frontend) now send test results, code coverage, and quality metrics directly to a single unified SonarQube project called "LabFusion" instead of using external test reporters.

Required Configuration

1. SonarQube Secrets

You need to configure the following secrets in your Gitea repository:

• SONAR_HOST_URL: Your SonarQube server URL (e.g., http://localhost:9000 or https://sonar.yourdomain.com)
• SONAR_TOKEN: Your SonarQube authentication token

2. SonarQube Project Setup

1. Create a unified project in SonarQube:

   • Project Key: labfusion
   • Project Name: LabFusion
   • Main Branch: main

2. Generate an authentication token:

   • Go to User > My Account > Security
   • Generate a new token with appropriate permissions
   • Copy the token for use in SONAR_TOKEN secret

3. SonarQube Quality Gates

Configure quality gates in SonarQube to enforce:

• Minimum code coverage percentage
• Maximum code duplication percentage
• Maximum technical debt ratio
• Code smell thresholds

What Gets Sent to SonarQube

Unified LabFusion Project Structure

• Project Key: labfusion
• Project Name: LabFusion
• Modules:
  • api-gateway (Java Spring Boot)
  • service-adapters (Python FastAPI)
  • api-docs (Node.js Express)
  • frontend (React)

Test Results

• API Gateway: JUnit XML reports from target/surefire-reports/
• Service Adapters: pytest XML reports from tests/reports/junit.xml
• API Docs: Jest XML reports from test-results.xml
• Frontend: Jest XML reports from test-results.xml

Code Coverage

• API Gateway: JaCoCo XML report from target/site/jacoco/jacoco.xml
• Service Adapters: Coverage XML from coverage.xml
• API Docs: LCOV report from coverage/lcov.info
• Frontend: LCOV report from coverage/lcov.info

Code Quality Metrics

• Source code analysis results for all languages
• Code smells and issues across all services
• Security vulnerabilities detection
• Maintainability ratings per module

Pipeline Integration

All Services Send to Unified Project

Each service workflow includes a SonarQube integration step:

API Gateway (Java)

- name: Send test results to SonarQube
  run: |
    ./mvnw sonar:sonar \
      -Dsonar.projectKey=labfusion \
      -Dsonar.modules=api-gateway \
      # ... other properties

Service Adapters (Python)

- name: Send results to SonarQube
  run: |
    sonar-scanner \
      -Dsonar.projectKey=labfusion \
      -Dsonar.modules=service-adapters \
      # ... other properties

API Docs & Frontend (Node.js)

- name: Send results to SonarQube
  run: |
    sonar-scanner \
      -Dsonar.projectKey=labfusion \
      -Dsonar.modules=api-docs \
      # ... other properties

Maven Plugins Added

SonarQube Maven Plugin

<plugin>
    <groupId>org.sonarsource.scanner.maven</groupId>
    <artifactId>sonar-maven-plugin</artifactId>
    <version>3.10.0.2594</version>
</plugin>

JaCoCo Maven Plugin

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.11</version>
    <!-- Configured for test phase execution -->
</plugin>

SonarQube Properties

Each service generates its own sonar-project.properties with module-specific settings:

API Gateway

sonar.projectKey=labfusion
sonar.projectName=LabFusion
sonar.projectVersion=1.0.0
sonar.modules=api-gateway
sonar.sources=src/main/java
sonar.tests=src/test/java
sonar.java.binaries=target/classes
sonar.java.test.binaries=target/test-classes
sonar.junit.reportPaths=target/surefire-reports
sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml

Service Adapters

sonar.projectKey=labfusion
sonar.projectName=LabFusion
sonar.projectVersion=1.0.0
sonar.modules=service-adapters
sonar.sources=.
sonar.tests=tests
sonar.python.coverage.reportPaths=coverage.xml
sonar.python.xunit.reportPath=tests/reports/junit.xml

API Docs & Frontend

sonar.projectKey=labfusion
sonar.projectName=LabFusion
sonar.projectVersion=1.0.0
sonar.modules=api-docs
sonar.sources=.
sonar.tests=__tests__
sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.testExecutionReportPaths=test-results.xml

Benefits

1. Centralized Quality Management

• All quality metrics in one place
• Historical trend analysis
• Cross-project comparisons

2. Automated Quality Gates

• Pipeline fails if quality standards not met
• Enforces consistent code quality
• Prevents regression in code quality

3. Detailed Reporting

• Comprehensive test coverage reports
• Code smell identification
• Security vulnerability detection
• Technical debt tracking

4. Integration Benefits

• No external service dependencies
• Local data control
• Customizable quality rules
• Team collaboration features

Troubleshooting

Common Issues

1. Authentication Failed

   • Verify SONAR_TOKEN is correct
   • Check token permissions in SonarQube
   • Ensure token hasn't expired

2. Connection Refused

   • Verify SONAR_HOST_URL is accessible
   • Check network connectivity
   • Ensure SonarQube is running

3. Project Not Found

   • Create project in SonarQube first
   • Verify project key matches configuration
   • Check project permissions

4. No Test Results

   • Ensure test files exist in src/test/java/
   • Verify Maven Surefire plugin configuration
   • Check test execution logs

Debug Commands

# Test SonarQube connection
curl -u $SONAR_TOKEN: $SONAR_HOST_URL/api/system/status

# Check project exists
curl -u $SONAR_TOKEN: $SONAR_HOST_URL/api/projects/search?q=labfusion-api-gateway

# Verify test reports exist
ls -la target/surefire-reports/
ls -la target/site/jacoco/

Next Steps

1. Configure SonarQube secrets in your Gitea repository
2. Set up quality gates in SonarQube
3. Run the pipeline to test integration
4. Review results in SonarQube dashboard
5. Customize quality rules as needed

References

• SonarQube Documentation
• SonarQube Maven Plugin
• JaCoCo Maven Plugin