# SonarQube Tim Titik Terang — Panduan untuk AI Agent (Claude Code)

Dokumen ini plain text agar mudah dibaca agent. Versi manusia: https://sonarcube.titikterang.id/

## Ringkasan

- SonarQube self-hosted tim Titik Terang. UI: http://203.55.176.248:9000
- MCP server (Streamable HTTP, stateless): https://sonarcube.titikterang.id/mcp
- Fallback MCP tanpa domain: http://203.55.176.248:8080/mcp
- Project utama: key `e-office-bwi` (private, Laravel 13 + Inertia React 19)
- Edisi: Community Build — hanya menganalisis SATU branch utama; analisa per-branch/PR decoration butuh Developer Edition (berbayar).
- JANGAN PERNAH menulis token ke file, commit, atau chat. Token selalu dari user (env var atau placeholder).

## Jenis token (PENTING — jangan ketukar)

- squ_... = User Token (My Account > Security, type "User Token") — INI yang dipakai untuk MCP/Claude Code. Membawa izin akun user: baca issue, mark False Positive, ubah status hotspot (grup sonar-users sudah punya izin ini).
- sqp_... = Project Analysis Token, sqa_... = Global Analysis Token — keluaran wizard CI. HANYA bisa submit scan; tidak bisa baca/ubah apa pun via API/MCP. Kalau agent merasa "tidak punya izin" padahal tersambung, hampir pasti tokennya sqp_/sqa_ — ganti ke user token squ_.

## 1. Sambungkan MCP (sekali per laptop)

Minta token pribadi user (SonarQube > My Account > Security > Generate Tokens, type "User Token", format squ_...), lalu:

    claude mcp add --transport http sonarqube https://sonarcube.titikterang.id/mcp --header "Authorization: Bearer TOKEN_USER"

Tambahkan `--scope user` bila ingin aktif di semua project.

Verifikasi:

    claude mcp list
    # sonarqube: https://sonarcube.titikterang.id/mcp (HTTP) - Connected

## 2. Membaca hasil analisis (via MCP tools)

Setelah tersambung, gunakan MCP tools sonarqube, contoh alur:
- Cek gate: get_project_quality_gate_status dengan projectKey=e-office-bwi
- Cari issue: search_sonar_issues_in_projects (urutkan severity, perbaiki satu per satu)
- Hotspot: search_security_hotspots lalu show_security_hotspot
- Coverage per file: search_files_by_coverage / get_file_coverage_details
- Duplikasi: search_duplicated_files / get_duplications

Resolusi project key: baca sonar.projectKey dari sonar-project.properties di root repo.

## 3. Scan lokal dari laptop (tanpa CI)

Prasyarat: Node.js + file sonar-project.properties di root repo.

    npx -y @sonar/scan -Dsonar.host.url=http://203.55.176.248:9000 -Dsonar.token=TOKEN_USER

Catatan:
- Scan bisa lama (unduh analyzer di run pertama) — jalankan di background.
- Setelah submit, poll status task: GET {host}/api/ce/task?id=<taskId> sampai SUCCESS (taskId ada di .scannerwork/report-task.txt).
- Cek gate setelahnya: GET {host}/api/qualitygates/project_status?projectKey=e-office-bwi
- Error checksum saat unduh jar scanner: rm -rf ~/.sonar/cache lalu ulangi.
- Warning "Missing blame information": ada file belum di-commit — commit dulu, scan ulang.
- .scannerwork/ dan coverage/ harus masuk .gitignore.

## 4. Coverage (syarat quality gate: new coverage >= 80%)

Generate laporan SEBELUM scan, kalau tidak Sonar menganggap coverage 0%.

PHP (butuh pcov atau xdebug):

    vendor/bin/phpunit --coverage-clover coverage/clover.xml

JS/TS (vitest, reporter lcov):

    npx vitest run --coverage

Wiring di sonar-project.properties:

    sonar.php.coverage.reportPaths=coverage/clover.xml
    sonar.javascript.lcov.reportPaths=coverage/js/lcov.info

Opsional: kecualikan file konfigurasi statis dari perhitungan coverage:

    sonar.coverage.exclusions=config/**

## 5. Setup project baru (GitLab CI)

1. SonarQube > Create Project > Local/Manually > isi Project Key.
2. Wizard > GitLab CI > generate token analisa.
3. GitLab repo > Settings > CI/CD > Variables (Masked + Protected):
   SONAR_HOST_URL = http://203.55.176.248:9000
   SONAR_TOKEN    = squ_xxxxxxxxxxxx
4. Tambah sonar-project.properties di root repo:

    sonar.projectKey=nama-repo
    sonar.projectName=Nama Repo
    sonar.sources=.
    sonar.sourceEncoding=UTF-8
    sonar.exclusions=vendor/**,node_modules/**,public/build/**,storage/**

5. Tambah job di .gitlab-ci.yml:

    sonarqube-check:
      stage: quality
      image:
        name: sonarsource/sonar-scanner-cli:latest
        entrypoint: [""]
      variables:
        SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"
        GIT_DEPTH: "0"
      cache:
        key: "${CI_JOB_NAME}"
        paths:
          - .sonar/cache
      script:
        - sonar-scanner -Dsonar.host.url="${SONAR_HOST_URL}" -Dsonar.token="${SONAR_TOKEN}"
      rules:
        - if: '$CI_COMMIT_BRANCH == "dev"'
        - if: '$CI_COMMIT_BRANCH == "main"'
        - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

## 6. Troubleshooting

- 401/Unauthorized: token salah/expired — generate ulang di My Account > Security.
- "Insufficient privileges" / tidak bisa mark FP atau baca data via MCP: token yang dipakai jenis analysis (sqp_/sqa_), bukan User Token squ_ — lihat bagian "Jenis token".
- Kondisi quality gate "new code" kosong di scan pertama: normal — baseline Previous version butuh pembanding; mulai scan kedua metrik new code aktif.
- MCP not connected: claude mcp remove sonarqube lalu ulangi langkah 1; coba fallback http://203.55.176.248:8080/mcp
- Project tak ketemu: pastikan projectKey persis (mis. e-office-bwi).
- Coverage 0%: laporan belum digenerate sebelum scan, atau path reportPaths tidak cocok.

## Aturan untuk agent

- Jangan hardcode token di file/config apa pun; pakai env var (contoh: .mcp.json memakai ${SONARQUBE_TOKEN}).
- Jangan menyalin source code project ke VPS SonarQube.
- Perbaiki issue Sonar secara bertahap dan jalankan test setelah tiap perubahan.