# Matrice delle funzionalità

La matrice delle funzionalità è un report generato che registra, per ogni flag e comportamento supportato, se lo strumento nativo e il wrapper Greph producono un output equivalente. È il riferimento per le domande del tipo «Greph supporta questa funzionalità?».

La matrice viene rigenerata eseguendo probe reali su un workspace di fixture deterministico. Le prove grezze si trovano in [`FEATURE_MATRIX.json`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json) e la tabella formattata in [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Legenda degli stati

| Stato | Significato |
|---|---|
| `Pass` | Il probe è stato eseguito e il risultato corrispondeva al comportamento previsto |
| `Fail` | Il probe è stato eseguito, ma il risultato non corrispondeva al comportamento previsto |
| `Unavailable` | Il comando del provider non era disponibile in questo ambiente |

## Sezioni

La matrice è organizzata in sei sezioni:

1. **Superficie di compatibilità con rg**: ogni probe viene eseguito sia con il binario upstream `rg` sia con `bin/rg`. Entrambi devono `Pass` perché la riga risulti supportata.
2. **Superficie di compatibilità con sg**: ogni probe viene eseguito sia con il binario upstream `sg` sia con `bin/sg`. Entrambi devono `Pass` perché la riga risulti supportata.
3. **Superficie solo del wrapper sg**: probe rivolti solo a `bin/sg` (funzionalità aggiuntive esposte dal wrapper e assenti in ast-grep stesso).
4. **Superficie nativa di greph**: probe che esercitano direttamente `bin/greph`. Non esiste uno strumento upstream per il confronto; i probe verificano il comportamento previsto nel workspace di fixture.
5. **Superficie indicizzata di greph**: probe che esercitano `bin/greph-index` (creazione, aggiornamento e ricerca testuale a caldo).
6. **Superficie della libreria AST indicizzata**: probe che chiamano PHP API (`Greph::buildAstIndex()`, `Greph::searchAstIndexed()`, `Greph::buildAstCache()`, `Greph::searchAstCached()`) e verificano creazione, ricerca e aggiornamento.

## Rigenerazione della matrice

```bash
php bin/feature-matrix
```

Eseguilo da un clone del repository con `rg` e `sg` nel `PATH`; `bin/feature-matrix` non fa parte del pacchetto Composer. Crea il workspace di fixture, esegue ogni probe di compatibilità sul binario upstream (se installato) e sul wrapper Greph, registra il risultato strutturato e scrive sia `FEATURE_MATRIX.json` sia `FEATURE_MATRIX.md`. Passa `--stdout` per stampare Markdown senza scrivere nessuno dei due file.

I file nel repository vengono rigenerati manualmente; la CI non li rigenera. La suite PHPUnit eseguita dalla CI include un test che genera la matrice segnando gli strumenti upstream come non disponibili e verifica la struttura del report, così il fallimento di un singolo probe non interrompe la CI. Rigenera la matrice e controlla il diff prima di una release.

## Contenuti della matrice e della documentazione

Il riferimento CLI e le pagine [Compatibilità / rg](https://greph.inline0.dev/it/docs/compatibility/rg) e [Compatibilità / sg](https://greph.inline0.dev/it/docs/compatibility/sg) descrivono le funzionalità *previste*. La matrice registra quelle *verificate*, con gli argomenti esatti dei probe accanto a ogni riga.

Se una funzionalità è documentata ma manca nella matrice, la documentazione è obsoleta. Se è presente nella matrice ma non è documentata, occorre aggiornare la documentazione. Le due fonti dovrebbero corrispondere.

## Righe di esempio

### Compatibilità con rg (estratto)

| Funzionalità | rg | bin/rg | Note |
|---|---|---|---|
| Ricerca a stringa fissa | Pass | Pass | Probe: `-F needle single.txt` |
| Ricerca a stringa fissa senza distinzione tra maiuscole e minuscole | Pass | Pass | Probe: `-F -i needle single.txt` |
| Ricerca per parola intera | Pass | Pass | Probe: `-F -w needle words.txt` |
| Filtro glob | Pass | Pass | Probe: `--glob *.php function .` |
| File nascosti | Pass | Pass | Probe: `--hidden -F secret .` |
| Output strutturato JSON | Pass | Pass | Probe: `--json -F needle single.txt` con semantica degli eventi ripgrep JSON |

### Compatibilità con sg (estratto)

| Funzionalità | sg | bin/sg | Note |
|---|---|---|---|
| Ricerca di pattern con `run --pattern` | Pass | Pass | Probe: `run --pattern array($$$ITEMS) src/App.php` |
| Riscrittura tramite `run --rewrite` | Pass | Pass | Probe: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| Output del flusso strutturato JSON | Pass | Pass | Probe: `run --json=stream --pattern dispatch($EVENT) src/App.php` |
| Riscrittura di tutti i risultati | Pass | Pass | Probe: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

Per la tabella completa, consulta [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Perché usare i probe

Una tabella di compatibilità aggiornata manualmente diventa obsoleta. Lo scopo dei wrapper è «sostituiscili alle chiamate a `rg` o `sg` e continueranno a funzionare», e l'unico modo per mantenere questa promessa è eseguire lo strumento upstream e il wrapper in parallelo e confrontarne i risultati. Il runner dei probe fa proprio questo ogni volta che la matrice viene rigenerata.