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)
```yaml
- name: Send test results to SonarQube
  run: |
    ./mvnw sonar:sonar \
      -Dsonar.projectKey=labfusion \
      -Dsonar.modules=api-gateway \
      # ... other properties
```

#### Service Adapters (Python)
```yaml
- name: Send results to SonarQube
  run: |
    sonar-scanner \
      -Dsonar.projectKey=labfusion \
      -Dsonar.modules=service-adapters \
      # ... other properties
```

#### API Docs & Frontend (Node.js)
```yaml
- name: Send results to SonarQube
  run: |
    sonar-scanner \
      -Dsonar.projectKey=labfusion \
      -Dsonar.modules=api-docs \
      # ... other properties
```

## Maven Plugins Added

### SonarQube Maven Plugin
```xml
<plugin>
    <groupId>org.sonarsource.scanner.maven</groupId>
    <artifactId>sonar-maven-plugin</artifactId>
    <version>3.10.0.2594</version>
</plugin>
```

### JaCoCo Maven Plugin
```xml
<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
```properties
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
```properties
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
```properties
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

```bash
# 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](https://docs.sonarqube.org/)
- [SonarQube Maven Plugin](https://docs.sonarqube.org/latest/analysis/scan/sonarscanner-for-maven/)
- [JaCoCo Maven Plugin](https://www.jacoco.org/jacoco/trunk/doc/maven.html)