# Compatibilitate cu sg

`vendor/bin/sg` este un wrapper de compatibilitate în stilul ast-grep. Acceptă cele mai utilizate opțiuni `ast-grep` și reutilizează același motor `Greph\Ast\AstSearcher` pe care îl folosește `vendor/bin/greph -p`. Interfața verificată, reprodusă pe baza testelor efectuate cu binarul upstream `sg`, este disponibilă în [Avansat / Matricea de funcționalități](https://greph.inline0.dev/ro/docs/advanced/feature-matrix).

## Când să îl folosiți

Folosiți wrapperul când:

- Aveți deja un instrument, agent sau script care apelează `sg`.
- Doriți un înlocuitor direct care funcționează în medii în care nu puteți instala `ast-grep` propriu-zis.
- Doriți ușurința în utilizare a ast-grep folosind o instalare care oferă numai Composer.

Folosiți `vendor/bin/greph -p` nativ când:

- Scrieți cod nou și nu aveți nevoie de forma ast-grep CLI.
- Doriți același set de opțiuni ca în modul text (binarul nativ le unifică pe amândouă).

## Utilizare

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

`run` este verbul canonic ast-grep. `scan` și `rewrite` sunt aliasuri disponibile doar în wrapper, care reflectă utilizarea obișnuită. O invocare fără argumente funcționează pentru o căutare unică:

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

## Modele

Gramatica modelelor este identică cu cea din căutarea AST nativă. Consultați [Moduri / Căutare AST](https://greph.inline0.dev/ro/docs/modes/ast) pentru referința completă.

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

## Rescrieri

Wrapperul acceptă același flux de lucru pentru simulare, interacțiune și scriere ca rescrierea nativă, cu nume de opțiuni 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
```

## Ieșire JSON

`--json` emite ast-grep structurate în JSON. Sunt acceptate trei stiluri:

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

| Stil | Structură |
|---|---|
| `--json` (implicit `pretty`) | Un singur tablou JSON formatat pe mai multe linii |
| `--json=stream` | O potrivire pe linie, în format JSON delimitat prin linii noi |
| `--json=compact` | Un singur tablou JSON compact |

## Interfață verificată

Următoarele opțiuni au fost verificate în raport cu binarul upstream `sg` și sunt listate în [matricea de funcționalități](https://greph.inline0.dev/ro/docs/advanced/feature-matrix). Când o opțiune are două forme (`-p` și `--pattern`, `--glob` și `--globs`), testul folosește una dintre ele, iar wrapperul le interpretează pe amândouă ca aceeași opțiune.

### Opțiuni pentru modele

- `--pattern PATTERN` (la nivel superior și în interiorul lui `run`)
- `-p PATTERN` (alias)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Opțiuni pentru potriviri

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

### Opțiuni pentru parcurgere

- `--no-ignore hidden` (formă combinată)
- `--glob GLOB`, `--globs GLOB`

### Opțiuni pentru lucrători

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

### Acceptate fără un test de verificare

Wrapperul acceptă și următoarele opțiuni, pentru care încă nu există teste în matricea de funcționalități:

- `--no-ignore` folosit singur sau cu o valoare diferită de `hidden`
- `--type NAME`, `--type-not NAME`

### Funcții suplimentare disponibile doar în wrapper

Wrapperul oferă câteva instrumente ajutătoare pe care ast-grep nu le include:

- Aliasurile `scan` și `rewrite` pentru `run`
- Opțiunea `--hidden` (ast-grep o integrează în `--no-ignore hidden`)
- Aliasul `--dry-run` pentru previzualizarea rescrierilor
- Fluxul de confirmare pentru rescrierile `--interactive`

## Limitări

Wrapperul `sg` al Greph acoperă funcțiile de căutare structurală și rescriere pe care le folosesc majoritatea instrumentelor și agenților. În prezent, nu expune următoarele funcții ast-grep:

- Fișiere de reguli YAML (`--rule`, `--config`)
- Scanare în mai multe limbaje în afara PHP
- Transformatoare care nu folosesc modele (`--debug-query`, `--inspect`)
- Integrare LSP

Dacă vă lipsește o opțiune, raportați problema și includeți testul efectuat cu `sg` upstream și rezultatul așteptat.

## Paritate de comportament

Wrapperul urmărește paritatea de comportament, nu identitatea la nivel de octet. Rezultatul este echivalent semantic, dar detaliile cosmetice pot diferi. Testele folosite de [matricea de funcționalități](https://greph.inline0.dev/ro/docs/advanced/feature-matrix) verifică echivalența câmpurilor relevante pentru analizator (calea fișierului, numărul liniei, codul capturat, capturile, structura JSON), nu a fluxului de octeți.