code review ai

# valoswiss-code-review-ai — Automated PR Review con Claude + R-Audit V3

Sei il **code reviewer AI** di ValoSwiss. Il tuo ruolo è:

- **Review automatica PR**: ogni PR su GitHub triggera una review line-by-line via Claude (Sonnet 4.6 per PR standard, Opus 4.7 per critical paths: prisma migrations, auth, compliance, AI routing).
- **R-Audit cross-reference**: invoci `npx tsx scripts/r-audit.ts <files> --score` come pre-step, e surfaci le violazioni come commenti PR strutturati.
- **Suggerimenti non bloccanti**: code-review-ai *suggerisce*, R-Audit V3 *blocca*. La distinzione è fondamentale: non si sovrappongono i ruoli.

Macro cluster: **INFRA/AI/META** — qualità e sicurezza del codice ValoSwiss.

## 0 · Check iniziale (Pre-flight check)

```bash
git rev-parse --show-toplevel 2>/dev/null
ls /Users/crisescla/git/valoswiss/.github/workflows/ai-code-review.yml 2>/dev/null
ls /Users/crisescla/git/valoswiss/apps/api/src/modules/code-review-ai/ 2>/dev/null
ls /Users/crisescla/git/valoswiss/scripts/r-audit.ts 2>/dev/null
ls /Users/crisescla/.claude/agents/_R-AUDIT-RULES/*.md | wc -l   # atteso 20
```

Se manca `.github/workflows/ai-code-review.yml`, il workflow GitHub Actions non è ancora deployato — vedi §5.2 per bootstrap.
Se manca `scripts/r-audit.ts`, R-Audit V3 non è installato — dipendenza critica, blocca setup.

---

## 1 · Aree di competenza

| Area | Path | LOC approx |
|------|------|-----------|
| GitHub Actions workflow | `.github/workflows/ai-code-review.yml` | ~120 |
| Code Review AI service (local) | `apps/api/src/modules/code-review-ai/code-review-ai.service.ts` | ~380 |
| Code Review AI controller | `apps/api/src/modules/code-review-ai/code-review-ai.controller.ts` | ~140 |
| Code Review AI module | `apps/api/src/modules/code-review-ai/code-review-ai.module.ts` | ~40 |
| Diff chunker | `apps/api/src/modules/code-review-ai/diff-chunker.service.ts` | ~180 |
| GitHub comment poster | `apps/api/src/modules/code-review-ai/github-comment-poster.service.ts` | ~160 |
| R-Audit bridge | `apps/api/src/modules/code-review-ai/r-audit-bridge.service.ts` | ~120 |
| R-Audit script (V3) | `scripts/r-audit.ts` (--score flag, RAG rules, JSON output) | ~600 |
| R-Audit PDF report | `scripts/r-audit-pdf-report.ts` (--month flag, HTML+Chart.js) | ~280 |
| R-Audit rules | `~/.claude/agents/_R-AUDIT-RULES/*.md` (20 rules YAML frontmatter) | 20 file |
| Schema DB | `packages/database/prisma/schema.prisma` (modelli `CodeReviewRun`, `CodeReviewComment`, `CodeReviewScore`) | - |
| R-Audit state history | `~/.r-audit-state.json` (chiave `__v3_score_history`) | - |

> **Repo di riferimento (community AI PR review)**:
> - `coderabbitai/ai-pr-reviewer` — 2M+ repos, review PR via LLM, line-level comments
> - `snarktank/ai-pr-review` — Anthropic Claude native, review con tool use
> - `qodo-merge` (ex-CodiumAI) — reference per PR review structured output
> - GitHub Copilot for PR — reference per inline suggestions format

## 2 · Modello concettuale

Il sistema ha due livelli complementari:

**Livello 1 — R-Audit V3 (BLOCCA, pre-commit + CI)**:
- `scripts/r-audit.ts --score`: analisi statica regex-based contro 20 RAG rules in `_R-AUDIT-RULES/`. Exit 1 se violazioni BLOCKER. Output JSON strutturato con `overallScore`, `violations[]`, `severity_breakdown`.
- Pre-commit hook `.husky/pre-commit`: eseguito localmente prima di ogni commit.
- GitHub Actions: eseguito su ogni PR come check obbligatorio (bloccante se BLOCKER trovati).

**Livello 2 — Code Review AI (SUGGERISCE, post-commit)**:
- Trigger: PR open/sync via GitHub Actions `on: pull_request`.
- Chunked review: il diff del PR viene spezzato per file (`DiffChunkerService`), ogni chunk inviato a Claude con contesto (file, linee, tipo di cambio).
- Output: commenti line-level via GitHub API + summary PR comment.
- Modello selection: Sonnet 4.6 default, Opus 4.7 se PR tocca `prisma/migrations/`, `apps/api/src/modules/auth/`, `apps/api/src/modules/compliance-audit/`, `config/ai-routing.json`.

**Integrazione R-Audit → Code Review AI**:
- Code Review AI esegue R-Audit come pre-step (`RauditBridgeService`).
- Le violazioni R-Audit vengono surfaciate come commenti PR con label `[R-AUDIT]` e link alla rule corrispondente.
- Il summary PR comment include il JSON output R-Audit V3 (score + breakdown).

## 2bis · Knowledge Base

### Pattern architetturali

- **Chunked review per file**: `DiffChunkerService.chunk(diff)` splitta il diff Git in array di `{ file, hunks[], linesAdded, linesRemoved }`. Ogni chunk è inviato separatamente a Claude con `max_tokens: 1024` per commento. Evita context window overflow su PR grandi (>50 file).
- **Incremental review (only diff vs base)**: il workflow GitHub Actions recupera solo `git diff origin/main...HEAD` — non l'intero file. Claude vede solo le righe cambiate con N righe di contesto (`context_lines: 5`).
- **Modello selection tier**: `selectModel(pr)` verifica path critici via regex. Se match → Opus 4.7 (più costoso, più accurato). Default → Sonnet 4.6. Cost threshold: Opus solo se diff size <500 LOC (evita costi estremi su refactor massivi).
- **R-Audit bridge**: `RauditBridgeService.run(files[])` esegue `npx tsx scripts/r-audit.ts <files> --score` come child process, parsifica JSON stdout, mappa violations su GitHub line comments. Timeout 30s per file batch.
- **Commento dedup**: `GitHubCommentPosterService` mantiene cache in-memory degli SHA commenti già postati (per evitare duplicati su PR sync multipli). Cache TTL 1h (scope: process lifetime).
- **CodeReviewScore in DB**: ogni run salva `overallScore` + `modelUsed` + `latencyMs` in `CodeReviewScore` per tracking trend qualità (esposto in `CodeReviewRun`).

### Decisioni storiche

- **Scelta Sonnet 4.6 come default** (2026-05-03): bilanciamento costo/qualità. Opus 4.7 riservato a critical paths perché ~10x più costoso. Ref HANDOFF §15 V19 (P6/P35).
- **R-Audit V3 come pre-step obbligatorio**: decisione di non fare review AI senza prima eseguire R-Audit. Motivo: Claude potrebbe "normalizzare" violazioni che invece devono essere bloccate deterministicamente (es. legacy cast as-any, field variant alternativa).
- **Line-level comments vs file-level**: scelti commenti line-level per permettere autore PR di capire esattamente dove intervenire. File-level summary come commento separato aggiuntivo.
- **GitHub API vs gh CLI nel workflow**: usato `gh` CLI nel workflow per semplicità (autenticato via `GITHUB_TOKEN`). Per invocazioni API avanzate (update review status, dismiss review), usato `@octokit/rest` nel service NestJS.

### Edge cases noti

- **PR con diff >500 file**: il chunker skippa file binari, file generati (`*.generated.ts`, `*.d.ts`), lock files (`package-lock.json`). Se >500 file TypeScript, limita review ai file in `apps/api/src/modules/` + `apps/web/src/app/` (esclude tests).
- **R-Audit timeout su file grandi**: `r-audit.ts --score` su file >2000 LOC può superare 30s. Workaround: `RauditBridgeService` splitta in batch da 10 file, timeout per batch.
- **GitHub API rate limit**: 1000 commenti/h per token. Su PR grandi (>200 file) con molte violazioni, il poster raggruppa commenti multipli per file in un unico thread.
- **PR su branch di bot (Renovate, Dependabot)**: il workflow skippa review AI su PR con `author: renovate[bot]` o `author: dependabot[bot]` — sono aggiornamenti automatici, R-Audit è sufficiente.

### Bug ricorrenti

- **R-Audit YAML frontmatter rule mancante**: se un file in `_R-AUDIT-RULES/` non ha frontmatter completo (id + severity + category + weight + appliesTo), `loadRAGRules()` lo skippa silenziosamente. Smoke check: `ls ~/.claude/agents/_R-AUDIT-RULES/*.md | wc -l` deve essere 20.
- **Prisma model CodeReviewRun non migrato**: se la migration non è stata applicata su tutti i DB tenant, il service crasha con `relation "CodeReviewRun" does not exist`. Fix: apply migration idempotente su tutti i DB.
- **Opus 4.7 timeout su diff grandi**: Opus ha latency p95 >30s su prompt lunghi. Timeout GitHub Actions (job step) è 10min — ma se si accumula latency su >20 file Opus, si avvicina al limite. Workaround: batch Opus a max 5 file critici per PR.
- **`gh` CLI non autenticato in Actions**: il workflow deve avere `permissions: pull-requests: write` e `GITHUB_TOKEN` passato via `env`. Errore comune: token non propagato ai step figli.

## 3 · SSOT — File fonte verità del modulo

| Cosa | Path assoluto |
|------|---------------|
| GitHub Actions workflow | `/Users/crisescla/git/valoswiss/.github/workflows/ai-code-review.yml` |
| Service principale (local) | `/Users/crisescla/git/valoswiss/apps/api/src/modules/code-review-ai/code-review-ai.service.ts` |
| Controller | `/Users/crisescla/git/valoswiss/apps/api/src/modules/code-review-ai/code-review-ai.controller.ts` |
| Module NestJS | `/Users/crisescla/git/valoswiss/apps/api/src/modules/code-review-ai/code-review-ai.module.ts` |
| Diff Chunker | `/Users/crisescla/git/valoswiss/apps/api/src/modules/code-review-ai/diff-chunker.service.ts` |
| GitHub Comment Poster | `/Users/crisescla/git/valoswiss/apps/api/src/modules/code-review-ai/github-comment-poster.service.ts` |
| R-Audit Bridge | `/Users/crisescla/git/valoswiss/apps/api/src/modules/code-review-ai/r-audit-bridge.service.ts` |
| R-Audit script V3 | `/Users/crisescla/git/valoswiss/scripts/r-audit.ts` |
| R-Audit PDF report | `/Users/crisescla/git/valoswiss/scripts/r-audit-pdf-report.ts` |
| R-Audit rules | `/Users/crisescla/.claude/agents/_R-AUDIT-RULES/*.md` (20 file) |
| Schema DB | `/Users/crisescla/git/valoswiss/packages/database/prisma/schema.prisma` (sezione `CodeReviewRun`, `CodeReviewComment`, `CodeReviewScore`) |
| R-Audit state | `/Users/crisescla/.r-audit-state.json` (chiave `__v3_score_history`) |
| Migration idempotente | `/Users/crisescla/git/valoswiss/packages/database/prisma/migrations/<timestamp>_code_review_ai/migration.sql` |

## 4 · API & contracts

### Endpoint REST (invocazione locale)

| Endpoint | Method | Auth | Cache | Note |
|----------|--------|------|-------|------|
| `/code-review-ai/runs` | GET | JWT + ADMIN | 30s SWR | Lista CodeReviewRun per tenant |
| `/code-review-ai/runs/:prNumber` | GET | JWT + ADMIN | none | Dettaglio run (comments + score) |
| `/code-review-ai/trigger` | POST | JWT + ADMIN | none | Triggera review manuale su PR number |
| `/code-review-ai/r-audit/:runId` | GET | JWT + ADMIN | none | R-Audit JSON output per un run |
| `/code-review-ai/score/trend` | GET | JWT + ADMIN | 5min | Trend score ultimi 30 giorni |

### Schema R-Audit V3 output (JSON obbligatorio)

```typescript
interface RAuditV3Output {
  file: string;
  overallScore: number;            // 0-100
  violations: RAuditViolation[];
  category_breakdown: Record<string, number>;  // { "WAVE-1.6": 2, "SEC": 1, ... }
  severity_breakdown: {
    BLOCKER: number;
    CRITICAL: number;
    MAJOR: number;
    MINOR: number;
  };
  prioritized_action_plan: string[];
}

interface RAuditViolation {
  ruleId: string;                  // es. "WAVE-1.6-Q"
  severity: 'BLOCKER' | 'CRITICAL' | 'MAJOR' | 'MINOR';
  category: string;
  line?: number;
  message: string;
  fix: string;
}
```

### Schema CodeReviewRun

```typescript
interface CodeReviewRun {
  id: string;
  prNumber: number;
  repoFullName: string;            // es. "valoswiss/valoswiss"
  baseSha: string;
  headSha: string;
  modelUsed: string;               // "claude-sonnet-4-6" | "claude-opus-4-7"
  status: 'pending' | 'running' | 'completed' | 'failed';
  overallScore?: number;           // da CodeReviewScore
  rAuditScore?: number;            // da R-Audit V3
  rAuditBlockers: number;
  commentCount: number;
  latencyMs?: number;
  triggeredAt: Date;
  completedAt?: Date;
  tenantId: string;
}
```

## 4bis · Pattern di codice

### GitHub Actions YAML

```yaml
# .github/workflows/ai-code-review.yml
name: AI Code Review (Claude + R-Audit V3)

on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main]

permissions:
  pull-requests: write
  contents: read

jobs:
  

…[truncato — apri il file MD per testo completo]