# Compatibilité avec sg

`vendor/bin/sg` est une enveloppe de compatibilité de type ast-grep. Elle accepte les options `ast-grep` les plus couramment utilisées et réutilise le même moteur `Greph\Ast\AstSearcher` qu’utilise `vendor/bin/greph -p`. Les fonctionnalités vérifiées sont reproduites à partir de tests exploratoires du binaire `sg` en amont et sont répertoriées dans [Avancé / Matrice des fonctionnalités](https://greph.inline0.dev/fr/docs/advanced/feature-matrix).

## Quand l’utiliser

Utilisez l’enveloppe si :

- Vous avez déjà un outil, un agent ou un script qui appelle `sg`.
- Vous voulez un remplacement direct qui fonctionne dans des environnements où vous ne pouvez pas installer `ast-grep` lui-même.
- Vous souhaitez bénéficier de l’ergonomie de ast-grep avec une installation limitée à Composer.

Utilisez `vendor/bin/greph -p` en natif si :

- Vous écrivez du nouveau code et n’avez pas besoin de la forme ast-grep CLI.
- Vous voulez le même ensemble d’options qu’en mode texte (le binaire natif unifie les deux modes).

## Utilisation

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

`run` est la commande canonique de type ast-grep. `scan` et `rewrite` sont des alias réservés à l’enveloppe, qui reprennent les usages courants. Un appel sans argument lance une recherche ponctuelle :

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

## Modèles de blocs

La grammaire des motifs est identique à celle de la recherche AST native. Consultez [Modes / Recherche AST](https://greph.inline0.dev/fr/docs/modes/ast) pour la référence complète.

```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
```

## Réécritures

L’enveloppe prend en charge le même flux de travail de simulation, interactif et d’écriture que la réécriture native, avec des noms d’options 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
```

## Sortie JSON

`--json` émet des ast-grep de forme JSON. Trois styles sont pris en charge :

```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
```

| Style | Structure |
|---|---|
| `--json` (`pretty` par défaut) | Tableau JSON unique joliment mis en forme |
| `--json=stream` | Une correspondance par ligne, en JSON délimité par des sauts de ligne |
| `--json=compact` | Tableau JSON unique et compact |

## Fonctionnalités vérifiées

Les options suivantes ont été vérifiées par rapport au binaire `sg` en amont dans la [matrice des fonctionnalités](https://greph.inline0.dev/fr/docs/advanced/feature-matrix). Lorsqu’une option possède deux formes (`-p` et `--pattern`, `--glob` et `--globs`), le test en utilise une seule et l’enveloppe les interprète toutes deux comme la même option.

### Options de motif

- `--pattern PATTERN` (au niveau supérieur et dans `run`)
- `-p PATTERN` (alias)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Options de correspondance

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

### Options de parcours

- `--no-ignore hidden` (forme combinée)
- `--glob GLOB`, `--globs GLOB`

### Options de processus de travail

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

### Options acceptées sans test

L’enveloppe accepte également les options suivantes, qui ne sont toutefois pas encore couvertes par un test de la matrice des fonctionnalités :

- `--no-ignore` seul ou avec une valeur autre que `hidden`
- `--type NAME`, `--type-not NAME`

### Options supplémentaires de l’enveloppe

L’enveloppe propose quelques utilitaires que ast-grep ne possède pas :

- Alias `scan` et `rewrite` pour `run`
- Option `--hidden` (ast-grep l’intègre à `--no-ignore hidden`)
- Alias `--dry-run` pour prévisualiser les réécritures
- Flux de confirmation des réécritures `--interactive`

## Limites

L’enveloppe `sg` de Greph couvre les fonctionnalités de recherche structurelle et de réécriture utilisées par la plupart des outils et agents. Elle ne propose actuellement pas les fonctionnalités ast-grep suivantes :

- Fichiers de règles YAML (`--rule`, `--config`)
- Analyse multilingue au-delà de PHP
- Transformateurs autres que par motifs (`--debug-query`, `--inspect`)
- Intégration LSP

Si une option vous manque, signalez le problème en indiquant le test exécuté sur `sg` en amont et le résultat attendu.

## Parité de comportement

L’enveloppe vise la parité de comportement, pas la parité octet par octet. La sortie est sémantiquement équivalente, mais certains détails visuels peuvent différer. Les tests utilisés dans la [matrice des fonctionnalités](https://greph.inline0.dev/fr/docs/advanced/feature-matrix) vérifient l’équivalence des champs pertinents pour l’analyse (chemin du fichier, numéro de ligne, code capturé, captures, structure JSON), et non celle du flux d’octets.