# sg suderinamumas

`vendor/bin/sg` yra ast-grep stiliaus suderinamumo apvalkalas. Jis priima dažniausiai naudojamas `ast-grep` vėliavėles ir naudoja tą patį `Greph\Ast\AstSearcher` variklį kaip `vendor/bin/greph -p`. Patikrintas funkcijų rinkinys atkurtas pagal patikras su pradine `sg` programa ir pateikiamas skiltyje [Išplėstinės funkcijos / funkcijų matrica](https://greph.inline0.dev/lt/docs/advanced/feature-matrix).

## Kada naudoti

Naudokite apvalkalą, kai:

- Turite esamą įrankį, agentą arba scenarijų, kuris jau iškviečia `sg`.
- Norite tiesioginio pakaitalo, veikiančio aplinkose, kuriose negalite įdiegti paties `ast-grep`.
- Norite ast-grep naudojimo patogumo įdiegę tik Composer.

Naudokite vietinį `vendor/bin/greph -p`, kai:

- Rašote naują kodą ir jums nereikia ast-grep CLI formos.
- Norite tokio pat vėliavėlių rinkinio kaip teksto režimu (vietinė programa sujungia abu režimus).

## Naudojimas

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

`run` yra pagrindinis ast-grep veiksmažodis. `scan` ir `rewrite` yra tik apvalkalo slapyvardžiai, atkartojantys įprastą naudojimą. Vykdant be argumentų, atliekama vienkartinė paieška:

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

## Šablonai

Šablonų gramatika sutampa su vietine AST paieška. Visą žinyną rasite skiltyje [Režimai / AST paieška](https://greph.inline0.dev/lt/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
```

## Perrašymai

Apvalkalas palaiko tą pačią bandomojo paleidimo / interaktyvią / įrašymo darbo seką kaip ir vietinio perrašymo funkcija, naudodamas ast-grep vėliavėlių pavadinimus:

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

## JSON išvestis

`--json` pateikia ast-grep formato JSON. Palaikomi trys stiliai:

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

| Stilius | Struktūra |
|---|---|
| `--json` (numatytasis `pretty`) | Vienas gražiai suformatuotas JSON masyvas |
| `--json=stream` | Po vieną atitikmenį eilutėje, JSON įrašai atskirti naujos eilutės simboliais |
| `--json=compact` | Vienas kompaktiškas JSON masyvas |

## Patikrintos funkcijos

Toliau pateiktos vėliavėlės patikrintos pagal pradinę `sg` programą, naudojant [funkcijų matricą](https://greph.inline0.dev/lt/docs/advanced/feature-matrix). Jei vėliavėlė turi du užrašymo variantus (`-p` ir `--pattern`, `--glob` ir `--globs`), tikrinamas vienas iš jų, o apvalkalas abu variantus apdoroja kaip tą pačią parinktį.

### Šablono vėliavėlės

- `--pattern PATTERN` (pagrindiniame lygmenyje ir `run` viduje)
- `-p PATTERN` (slapyvardis)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Atitikmenų vėliavėlės

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

### Failų naršymo vėliavėlės

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

### Vykdytojų vėliavėlės

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

### Priimamos be patikros

Apvalkalas taip pat priima šias vėliavėles, tačiau joms dar neatlikta funkcijų matricos patikra:

- `--no-ignore` atskirai arba su kita nei `hidden` reikšme
- `--type NAME`, `--type-not NAME`

### Tik apvalkalui skirtos papildomos funkcijos

Apvalkalas siūlo keletą pagalbinių funkcijų, kurių pats ast-grep neturi:

- `scan` ir `rewrite` slapyvardžiai, skirti `run`
- `--hidden` vėliavėlė (ast-grep įtraukia ją į `--no-ignore hidden`)
- `--dry-run` perrašymo peržiūros slapyvardis
- `--interactive` perrašymo patvirtinimo eiga

## Apribojimai

Greph `sg` apvalkalas apima struktūrinės paieškos ir perrašymo funkcijas, kurias naudoja dauguma įrankių ir agentų. Šiuo metu jame nėra šių ast-grep funkcijų:

- YAML taisyklių failai (`--rule`, `--config`)
- Kelių kalbų failų paieška už PHP ribų
- Ne pagal šabloną atliekami transformavimai (`--debug-query`, `--inspect`)
- LSP integracija

Jei trūksta vėliavėlės, pateikite problemos aprašą ir pridėkite su pradine `sg` atliktą patikrą.

## Elgsenos lygiavertiškumas

Apvalkalo tikslas – elgsenos, o ne baitų lygiavertiškumas. Išvestis semantiškai sutampa, tačiau gali skirtis kosmetinės detalės. Atliekant [funkcijų matricos](https://greph.inline0.dev/lt/docs/advanced/feature-matrix) patikras vertinamas analizatoriui svarbių laukų (failo kelias, eilutės numeris, užfiksuotas kodas, užfiksuotos reikšmės, JSON struktūra) lygiavertiškumas, o ne baitų srautas.