labFusion/docs/SONARQUBE_INTEGRATION.md

# SonarQube Integration for LabFusion

This document explains how to configure SonarQube integration for all LabFusion services using individual projects per service.

## Overview

Each LabFusion service has its own dedicated SonarQube project, providing better isolation, clearer metrics per service, and easier maintenance. This approach allows for service-specific quality gates and more granular reporting.

## 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 individual projects** in SonarQube for each service:
   - **API Gateway**: `labfusion-api-gateway` - "LabFusion API Gateway"
   - **Service Adapters**: `labfusion-service-adapters` - "LabFusion Service Adapters"
   - **API Docs**: `labfusion-api-docs` - "LabFusion API Docs"
   - **Frontend**: `labfusion-frontend` - "LabFusion Frontend"
   - Main Branch: `main` for all projects

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

### Individual Service Projects

#### API Gateway
- **Project Key**: `labfusion-api-gateway`
- **Project Name**: LabFusion API Gateway
- **Language**: Java Spring Boot
- **Test Reports**: JUnit XML from `target/surefire-reports/`
- **Coverage**: JaCoCo XML from `target/site/jacoco/jacoco.xml`

#### Service Adapters
- **Project Key**: `labfusion-service-adapters`
- **Project Name**: LabFusion Service Adapters
- **Language**: Python FastAPI
- **Test Reports**: pytest XML from `tests/reports/junit.xml`
- **Coverage**: Coverage XML from `coverage.xml`

#### API Docs
- **Project Key**: `labfusion-api-docs`
- **Project Name**: LabFusion API Docs
- **Language**: Node.js Express
- **Test Reports**: Jest XML from `test-results.xml`
- **Coverage**: LCOV from `coverage/lcov.info`

#### Frontend
- **Project Key**: `labfusion-frontend`
- **Project Name**: LabFusion Frontend
- **Language**: React
- **Test Reports**: Jest XML from `test-results.xml`
- **Coverage**: LCOV from `coverage/lcov.info`

### Code Quality Metrics
- **Source code analysis** results per service
- **Code smells** and issues per service
- **Security vulnerabilities** detection per service
- **Maintainability ratings** per service
- **Service-specific quality gates** and thresholds

## Pipeline Integration

### Individual Service Projects
Each service workflow sends results to its own dedicated SonarQube project:

#### API Gateway (Java)
```yaml
- name: Send test results to SonarQube
  run: |
    ./mvnw clean verify sonar:sonar \
      -Dsonar.projectKey=labfusion-api-gateway \
      -Dsonar.projectName=LabFusion API Gateway \
      -Dsonar.host.url=${{ secrets.SONAR_HOST_URL }} \
      -Dsonar.token=${{ secrets.SONAR_TOKEN }}
```

#### Service Adapters (Python)
```yaml
- name: Send results to SonarQube
  run: |
    sonar-scanner \
      -Dsonar.projectKey=labfusion-service-adapters \
      -Dsonar.projectName=LabFusion Service Adapters \
      -Dsonar.host.url=${{ secrets.SONAR_HOST_URL }} \
      -Dsonar.login=${{ secrets.SONAR_TOKEN }}
```

#### API Docs (Node.js)
```yaml
- name: Send results to SonarQube
  run: |
    sonar-scanner \
      -Dsonar.projectKey=labfusion-api-docs \
      -Dsonar.projectName=LabFusion API Docs \
      -Dsonar.host.url=${{ secrets.SONAR_HOST_URL }} \
      -Dsonar.login=${{ secrets.SONAR_TOKEN }}
```

#### Frontend (React)
```yaml
- name: Send results to SonarQube
  run: |
    sonar-scanner \
      -Dsonar.projectKey=labfusion-frontend \
      -Dsonar.projectName=LabFusion Frontend \
      -Dsonar.host.url=${{ secrets.SONAR_HOST_URL }} \
      -Dsonar.login=${{ secrets.SONAR_TOKEN }}
```

## 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. Service Isolation
- Each service has its own quality metrics
- Service-specific quality gates and thresholds
- Independent quality tracking per service
- Clear ownership and responsibility

### 2. Granular Reporting
- Service-specific test coverage reports
- Individual code smell identification
- Per-service security vulnerability detection
- Service-level technical debt tracking

### 3. Flexible Quality Gates
- Different quality standards per service type
- Language-specific quality rules
- Service-specific maintenance windows
- Independent quality gate configurations

### 4. Better Organization
- Clear separation of concerns
- Easier to identify problematic services
- Service-specific team assignments
- Independent service evolution

### 5. Integration Benefits
- No external service dependencies
- Local data control
- Customizable quality rules per service
- Team collaboration features per service

## 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)