CODEX_ADK/BACKEND/docs/CODE-REVIEW-GUIDE.md

# Code Review Guide - Roslynator + SonarScanner

## Overview
Multiple code review tools are installed for comprehensive analysis:

### Roslynator (Recommended - No Server Required) ✅
- 500+ C# analyzers
- Performance optimizations
- Code style checks
- Auto-fix capabilities

### SonarScanner (Requires SonarQube Server)
- Code smells and bugs
- Security vulnerabilities
- Code duplications
- Technical debt calculation

---

## Quick Start (Recommended)

### Local Code Review with Roslynator
```bash
# Run comprehensive local review (no server needed)
./code-review-local.sh
```

**Output:**
- Console report with findings
- XML results: `code-review-results.xml`
- Summary: `CODE-REVIEW-SUMMARY.md`

**Auto-fix issues:**
```bash
dotnet roslynator fix Codex.sln
dotnet format Codex.sln
```

### Option 2: Full SonarQube Integration (Recommended)

#### Setup SonarQube Server (Docker)
```bash
# Add to docker-compose.yml
docker run -d --name sonarqube -p 9000:9000 sonarqube:lts-community

# Access SonarQube UI
open http://localhost:9000
# Login: admin/admin (change on first login)
```

#### Run Analysis with Server
```bash
./code-review.sh
```

View results at: http://localhost:9000/dashboard?id=codex-adk-backend

---

## Manual Analysis

```bash
# Export PATH
export PATH="$PATH:/Users/jean-philippe/.dotnet/tools"

# Begin analysis
dotnet-sonarscanner begin \
  /k:"codex-adk-backend" \
  /n:"CODEX ADK Backend" \
  /v:"1.0.0" \
  /d:sonar.host.url="http://localhost:9000"

# Build
dotnet build

# End analysis
dotnet-sonarscanner end
```

---

## Configuration

**Location:** `.sonarqube/sonar-project.properties`

**Excluded from analysis:**
- `obj/` directories
- `bin/` directories
- `Migrations/` files
- Test projects

**Modify exclusions:**
```properties
sonar.exclusions=**/obj/**,**/bin/**,**/Migrations/**,**/*.Tests/**
```

---

## CI/CD Integration

### GitHub Actions
```yaml
- name: SonarScanner Analysis
  run: |
    dotnet tool install --global dotnet-sonarscanner
    ./code-review.sh    
  env:
    SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
```

### Pre-commit Hook
```bash
# .git/hooks/pre-commit
#!/bin/bash
./code-review.sh || exit 1
```

---

## SonarCloud (Alternative)

For cloud-based analysis without local server:

1. Sign up: https://sonarcloud.io
2. Create project token
3. Update `code-review.sh`:
```bash
dotnet-sonarscanner begin \
  /k:"your-org_codex-adk-backend" \
  /o:"your-org" \
  /d:sonar.host.url="https://sonarcloud.io" \
  /d:sonar.token="YOUR_TOKEN"
```

---

## Analysis Reports

**Quality Gate Metrics:**
- Bugs: 0 target
- Vulnerabilities: 0 target
- Code Smells: Minimized
- Coverage: >80% (with tests)
- Duplication: <3%

**Report Locations:**
- Local: `.sonarqube/` directory
- Server: http://localhost:9000/dashboard
- Cloud: https://sonarcloud.io

---

## Troubleshooting

### PATH not found
```bash
# Add to ~/.zprofile
export PATH="$PATH:/Users/jean-philippe/.dotnet/tools"

# Reload
source ~/.zprofile
```

### Connection refused
Ensure SonarQube server is running:
```bash
docker ps | grep sonarqube
```

### Build errors during scan
```bash
dotnet clean
dotnet restore
./code-review.sh
```

---

## Best Practices

1. **Run before commits:** Catch issues early
2. **Review warnings:** Address all code smells
3. **Security first:** Fix vulnerabilities immediately
4. **Maintain quality gate:** Keep passing standards
5. **Regular scans:** Integrate into CI/CD pipeline

---

## Resources

- [SonarScanner for .NET](https://docs.sonarqube.org/latest/analysis/scan/sonarscanner-for-msbuild/)
- [Quality Profiles](https://docs.sonarqube.org/latest/instance-administration/quality-profiles/)
- [SonarCloud](https://sonarcloud.io)