# Združljivost z sg

`vendor/bin/sg` je ovojnica za združljivost v slogu ast-grep. Sprejema najpogosteje uporabljene zastavice `ast-grep` in ponovno uporablja isti pogon `Greph\Ast\AstSearcher`, kot ga uporablja `vendor/bin/greph -p`. Preverjeni nabor je povzet po izvajanju preizkusov z izvorno binarno datoteko `sg` in je na voljo v [Napredno / Matrika funkcij](https://greph.inline0.dev/sl/docs/advanced/feature-matrix).

## Kdaj jo uporabiti

Ovojnico uporabite, kadar:

- Imate obstoječe orodje, agenta ali skript, ki že kliče `sg`.
- Želite neposredno zamenjavo, ki deluje v okoljih, kjer ne morete namestiti samega `ast-grep`.
- Želite uporabnost ast-grep pri namestitvi, ki podpira samo Composer.

Izvorno različico `vendor/bin/greph -p` uporabite, kadar:

- Pišete novo kodo in ne potrebujete oblike ast-grep CLI.
- Želite isti nabor zastavic kot v besedilnem načinu (izvorna binarna datoteka združuje oba načina).

## Uporaba

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

`run` je kanonični glagol ast-grep. `scan` in `rewrite` sta vzdevka, namenjena samo ovojnici, ki odražata običajno rabo. Samostojen klic deluje za enkratno iskanje:

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

## Vzorci

Slovnica vzorcev je enaka kot pri izvornem iskanju AST. Celotno referenco najdete v [Načini / Iskanje AST](https://greph.inline0.dev/sl/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
```

## Prepisovanje

Ovojnica podpira enak potek dela za poskusni zagon, interaktivno delo in zapisovanje kot izvorno prepisovanje, z imeni zastavic 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
```

## Izhod JSON

`--json` izpiše vsebino ast-grep v obliki JSON. Podprti so trije slogi:

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

| Slog | Oblika |
|---|---|
| `--json` (privzeto `pretty`) | Eno lepo oblikovano polje JSON |
| `--json=stream` | Eno ujemanje na vrstico, razmejeno z znaki za novo vrstico JSON |
| `--json=compact` | Eno zgoščeno polje JSON |

## Preverjeni nabor

Naslednje zastavice so preverjene glede na izvorno binarno datoteko `sg` v [matriki funkcij](https://greph.inline0.dev/sl/docs/advanced/feature-matrix). Če ima zastavica dve obliki (`-p` in `--pattern`, `--glob` in `--globs`), preizkus uporabi eno od njiju, ovojnica pa obe razčleni kot isto možnost.

### Zastavice vzorca

- `--pattern PATTERN` (na najvišji ravni in znotraj `run`)
- `-p PATTERN` (vzdevek)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Zastavice ujemanja

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

### Zastavice pregledovalnika

- `--no-ignore hidden` (združena oblika)
- `--glob GLOB`, `--globs GLOB`

### Zastavice delavcev

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

### Sprejete brez preizkusa

Ovojnica sprejema tudi te zastavice, vendar jih še ne pokriva noben preizkus matrike funkcij:

- `--no-ignore` samostojno ali z vrednostjo, ki ni `hidden`
- `--type NAME`, `--type-not NAME`

### Dodatki samo za ovojnico

Ovojnica ponuja nekaj pripomočkov, ki jih sam ast-grep nima:

- Vzdevka `scan` in `rewrite` za `run`
- Zastavica `--hidden` (ast-grep to vključi v `--no-ignore hidden`)
- Vzdevek `--dry-run` za predogled prepisov
- Potek potrjevanja prepisov `--interactive`

## Omejitve

Ovojnica `sg` orodja Greph pokriva možnosti strukturnega iskanja in prepisovanja, ki jih uporablja večina orodij in agentov. Trenutno ne ponuja naslednjih funkcij ast-grep:

- Datoteke s pravili YAML (`--rule`, `--config`)
- Pregledovanje več jezikov poleg PHP
- Pretvorniki, ki ne temeljijo na vzorcih (`--debug-query`, `--inspect`)
- Integracija z LSP

Če vam manjka zastavica, prijavite težavo in priložite preizkus, ki ste ga izvedli z izvornim programom `sg`, ter pričakovani izhod.

## Ujemanje vedenja

Ovojnica si prizadeva za ujemanje vedenja, ne bajtov. Izhod je semantično enakovreden, vendar se lahko kozmetične podrobnosti razlikujejo. Preizkusi za [matriko funkcij](https://greph.inline0.dev/sl/docs/advanced/feature-matrix) preverjajo enakovrednost polj, pomembnih za razčlenjevalnik (pot do datoteke, številka vrstice, zajeta koda, zajetja, oblika JSON), ne pa enakosti bajtnega toka.