# CI/CD Setup Guide

## Quick Start

### 1. Add GitHub Secrets

Nel repository GitHub (Settings → Secrets and variables → Actions → New repository secret):

**CODESCENE_TOKEN**
```
<il tuo CodeScene PAT — stesso di ~/.codescene/token>
```

**CODESCENE_PROJECT_ID**  
Trova l'ID del progetto nella dashboard CodeScene (URL: `https://codescene.io/projects/<PROJECT_ID>/...`)

### 2. Enable GitHub Actions

- Vai su Settings → Actions → General
- Assicurati che "Allow all actions and reusable workflows" sia selezionato

### 3. Configure Branch Protection (Optional ma Raccomandato)

Settings → Branches → Add branch protection rule:

**Branch name pattern**: `main`

Abilita:
- ✅ Require status checks to pass before merging
  - Select: `Tests & Quality Checks`
- ✅ Require branches to be up to date before merging
- ✅ Do not allow bypassing the above settings

Questo forza tutti i check a passare prima di poter fare merge su main.

### 4. Test Locally Prima di Pushare

```bash
# Full test suite
pnpm test && cargo test --manifest-path=src-tauri/Cargo.toml

# Coverage
pnpm test:coverage

# Lint
pnpm lint
cargo clippy --manifest-path=src-tauri/Cargo.toml

# Format check
cargo fmt --manifest-path=src-tauri/Cargo.toml -- --check
```

## What Gets Checked

### ✅ Tests
- Frontend: Vitest
- Backend: `cargo test`

### 📊 Coverage
- Threshold: 70% (lines, functions, branches, statements)
- Configurabile in `vite.config.ts`

### 🏥 Code Health
- CodeScene delta analysis
- **Fail se code health diminuisce**
- Confronta HEAD vs base branch

### 📝 Documentation
- **Warning se modifichi `src/` o `src-tauri/` ma non aggiorni `docs/`**
- Non blocca il merge, solo un reminder
- Skip il check con `[skip docs]` nel commit message
- Aggiorna docs solo se la modifica invalida qualcosa già documentato

### 🎨 Lint & Format
- ESLint per frontend
- Clippy + rustfmt per Rust

## Workflow File

Il workflow è in `.github/workflows/ci.yml`.

**Trigger**: 
- Push su `main` o `experiment/*`
- Pull request verso `main`

**Runner**: `macos-latest` (necessario per Tauri + Rust)

## Customization

### Soglie Coverage

Modifica `vite.config.ts`:

```typescript
coverage: {
  thresholds: {
    lines: 80,     // Aumenta se vuoi più coverage
    functions: 80,
    branches: 80,
    statements: 80,
  }
}
```

### Documentation Check

Il check **avvisa** (non fallisce) se:
1. Modifichi file in `src/` o `src-tauri/`
2. NON modifichi nulla in `docs/`

**Quando aggiornare docs:**
- Cambi architettura → aggiorna `docs/ARCHITECTURE.md`
- Cambi astrazioni chiave → aggiorna `docs/ABSTRACTIONS.md`
- Cambi theme system → aggiorna `docs/THEMING.md`
- Bug fix / refactor interno → `[skip docs]` nel commit message

**Skip il check:**
```bash
git commit -m "fix: editor scroll bug [skip docs]"
```

### CodeScene Fail Threshold

Nel workflow, modifica:

```yaml
- name: CodeScene Delta Analysis
  uses: codescene-oss/codescene-delta-analysis-action@v1
  with:
    fail-on-declining-code-health: true  # Cambia a false per warning-only
    minimum-code-health-score: 8.0       # Aggiungi per soglia assoluta
```

## Troubleshooting

### CodeScene fails con "Project not found"
- Verifica che `CODESCENE_PROJECT_ID` sia corretto
- Controlla che il token abbia accesso al progetto

### Coverage check fails
- Verifica che `@vitest/coverage-v8` sia installato: `pnpm add -D @vitest/coverage-v8`
- Le soglie sono configurabili in `vite.config.ts`

### Docs check avvisa anche se non serve aggiornare docs
- È solo un warning, non blocca
- Skip con `[skip docs]` nel commit message
- Oppure ignora — è un reminder, non un requisito

### Workflow non si attiva
- Verifica che il file sia in `.github/workflows/ci.yml`
- Controlla che GitHub Actions sia abilitato nelle settings
- Il workflow parte solo su push/PR verso `main` o branch `experiment/*`

## Example CI Pass

```
✅ Run frontend tests
✅ Run Rust tests
✅ Run frontend coverage (75% lines, 73% functions)
✅ CodeScene Delta Analysis (code health: 9.2 → 9.3)
✅ Check docs are updated (docs/ARCHITECTURE.md modified)
✅ Lint frontend
✅ Clippy (Rust)
✅ Format check (Rust)
```

## Example CI Warning

```
⚠️  Code files changed but docs/ not updated
   Changed code files:
   - src/components/Editor.tsx
   - src-tauri/src/vault.rs
   
   If this change affects architecture/abstractions/design documented in docs/,
   please update the relevant documentation files.
   
   To skip this check, include [skip docs] in your commit message.
```

Questo è solo un reminder. Se la modifica non invalida la documentazione esistente, puoi ignorarlo o usare `[skip docs]`.
