# Compatibilità con sg

`vendor/bin/sg` è un wrapper di compatibilità in stile ast-grep. Accetta i flag `ast-grep` più usati e riutilizza lo stesso motore `Greph\Ast\AstSearcher` usato da `vendor/bin/greph -p`. Le funzionalità verificate, riprodotte da test con il binario upstream `sg`, sono riportate in [Avanzate / Matrice delle funzionalità](https://greph.inline0.dev/it/docs/advanced/feature-matrix).

## Quando usarlo

Usa il wrapper quando:

- Hai uno strumento, un agente o uno script esistente che invoca già `sg`.
- Vuoi un sostituto compatibile che funzioni in ambienti in cui non puoi installare direttamente `ast-grep`.
- Vuoi la praticità di ast-grep con un'installazione che supporta solo Composer.

Usa `vendor/bin/greph -p` nativo quando:

- Stai scrivendo nuovo codice e non ti serve la struttura ast-grep CLI.
- Vuoi lo stesso set di flag della modalità testuale (il binario nativo unifica entrambe).

## Utilizzo

```bash
sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]
```

`run` è il verbo canonico di ast-grep. `scan` e `rewrite` sono alias disponibili solo nei wrapper, che riproducono l'uso comune. Funziona anche un'invocazione senza argomenti per una ricerca singola:

```bash
./vendor/bin/sg --pattern 'array($$$ITEMS)' src
```

## Pattern

La grammatica dei pattern è identica a quella della ricerca AST nativa. Per il riferimento completo, consulta [Modalità / Ricerca AST](https://greph.inline0.dev/it/docs/modes/ast).

```bash
./vendor/bin/sg run --pattern 'array($$$ITEMS)' src
./vendor/bin/sg run --pattern '$obj->$method($$$ARGS)' src
./vendor/bin/sg run --pattern 'new $CLASS()' src
```

## Riscritture

Il wrapper supporta lo stesso flusso di lavoro di esecuzione di prova, interattivo e di scrittura della riscrittura nativa, con i nomi dei flag ast-grep:

```bash
# Preview only (default)
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src

# Apply without confirmation
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src

# Confirm each match
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --interactive src

# Wrapper-only aliases
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src
```

## Output JSON

`--json` genera ast-grep strutturati in JSON. Sono supportati tre stili:

```bash
./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src
./vendor/bin/sg run --json=stream --pattern 'dispatch($EVENT)' src
./vendor/bin/sg run --json=compact --pattern 'dispatch($EVENT)' src
```

| Stile | Struttura |
|---|---|
| `--json` (predefinito `pretty`) | Un singolo array JSON formattato in modo leggibile |
| `--json=stream` | Una corrispondenza per riga, in formato JSON delimitato da righe |
| `--json=compact` | Un singolo array JSON compatto |

## Funzionalità verificate

I seguenti flag sono verificati rispetto al binario upstream `sg` nella [matrice delle funzionalità](https://greph.inline0.dev/it/docs/advanced/feature-matrix). Quando un flag ha due forme (`-p` e `--pattern`, `--glob` e `--globs`), il test ne usa una e il wrapper le interpreta entrambe come la stessa opzione.

### Flag dei pattern

- `--pattern PATTERN` (al livello superiore e all'interno di `run`)
- `-p PATTERN` (alias)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Flag delle corrispondenze

- `--files-with-matches`
- `--json` (`pretty`, `stream`, `compact`)
- `--update-all`, `-U`

### Flag di scansione

- `--no-ignore hidden` (forma combinata)
- `--glob GLOB`, `--globs GLOB`

### Flag dei worker

- `-j N`, `--threads N`

### Accettati senza test

Il wrapper accetta anche i seguenti flag, che non sono ancora coperti dai test della matrice delle funzionalità:

- `--no-ignore` da solo oppure con un valore diverso da `hidden`
- `--type NAME`, `--type-not NAME`

### Funzioni aggiuntive del wrapper

Il wrapper espone alcune funzioni che ast-grep non offre:

- Alias `scan` e `rewrite` per `run`
- Flag `--hidden` (ast-grep lo integra in `--no-ignore hidden`)
- Alias `--dry-run` per l'anteprima della riscrittura
- Flusso di conferma della riscrittura `--interactive`

## Limitazioni

Il wrapper Greph `sg` copre le funzionalità di ricerca strutturale e riscrittura usate dalla maggior parte degli strumenti e degli agenti. Al momento non espone le seguenti funzionalità ast-grep:

- File di regole YAML (`--rule`, `--config`)
- Scansione multilingue oltre a PHP
- Trasformatori non basati su pattern (`--debug-query`, `--inspect`)
- Integrazione LSP

Se ti manca un flag, segnala il problema indicando il test eseguito su `sg` upstream e l'output previsto.

## Parità di comportamento

Il wrapper punta alla parità di comportamento, non a quella byte per byte. L'output è semanticamente equivalente, ma può differire in dettagli estetici. I test usati per la [matrice delle funzionalità](https://greph.inline0.dev/it/docs/advanced/feature-matrix) verificano l'equivalenza dei campi rilevanti per il parser (percorso del file, numero di riga, codice acquisito, acquisizioni, struttura JSON), non del flusso di byte.