# sg-ühilduvus

`vendor/bin/sg` on ast-grep-stiilis ühilduvusümbris. See aktsepteerib sagedamini kasutatavaid `ast-grep` lippe ja kasutab sama `Greph\Ast\AstSearcher` mootorit, mida kasutab `vendor/bin/greph -p`. Kontrollitud funktsioonide loend põhineb ülesvoolu binaarfaili `sg` vastaste testide tulemustel ja on saadaval lehel [Täpsemad teemad / funktsioonide maatriks](https://greph.inline0.dev/et/docs/advanced/feature-matrix).

## Millal seda kasutada

Kasutage ümbrist, kui:

- Teil on olemas tööriist, agent või skript, mis käivitab juba `sg`.
- Soovite asenduslahendust, mis töötab keskkondades, kuhu ei saa installida `ast-grep`-i ennast.
- Soovite ast-grep kasutusmugavust ainult Composer-iga paigalduses.

Kasutage natiivset `vendor/bin/greph -p`-i, kui:

- Kirjutate uut koodi ega vaja kuju ast-grep CLI.
- Soovite sama lippude komplekti mis tekstirežiimis (natiivne binaarfail ühendab mõlemad režiimid).

## Kasutamine

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

`run` on kanooniline ast-grep-verb. `scan` ja `rewrite` on ainult ümbrise varjunimed, mis järgivad levinud kasutust. Ka paljas käivitus toimib ühekordse otsinguna:

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

## Mustrid

Mustrite grammatika on identne natiivse AST-otsingu omaga. Täielikku viitejuhendit vaadake jaotisest [Režiimid / AST-otsing](https://greph.inline0.dev/et/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
```

## Ümberkirjutused

Ümbris toetab sama proovikäivituse / interaktiivse / failidesse kirjutamise töövoogu mis natiivne ümberkirjutus, kasutades ast-grep lipunimesid:

```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-väljund

`--json` väljastab ast-grep-kujulisi JSON-andmeid. Toetatud on kolm stiili:

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

| Stiil | Kuju |
|---|---|
| `--json` (vaikimisi `pretty`) | Üks ilusasti vormindatud JSON-massiiv |
| `--json=stream` | Üks sobivus rea kohta, reavahetustega eraldatud JSON |
| `--json=compact` | Üks kompaktne JSON-massiiv |

## Kontrollitud funktsioonid

Järgmised lipud on kontrollitud ülesvoolu binaarfaili `sg` suhtes lehel [funktsioonide maatriks](https://greph.inline0.dev/et/docs/advanced/feature-matrix). Kui lipul on kaks kirjapilti (`-p` ja `--pattern`, `--glob` ja `--globs`), kasutab vastastest üht neist ning ümbris käsitleb mõlemat sama suvandina.

### Mustrilipud

- `--pattern PATTERN` (tipptasemel ja `run` sees)
- `-p PATTERN` (alias)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Sobivuse lipud

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

### Läbija lipud

- `--no-ignore hidden` (ühendatud vorm)
- `--glob GLOB`, `--globs GLOB`

### Tööliste lipud

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

### Ilma vastastestita aktsepteeritud lipud

Ümbris aktsepteerib ka järgmisi lippe, kuid funktsioonide maatriksi vastastestid neid veel ei hõlma:

- `--no-ignore` üksi või väärtusega, mis pole `hidden`
- `--type NAME`, `--type-not NAME`

### Ainult ümbrise lisad

Ümbris pakub mõningaid abifunktsioone, mida ast-grep-is endas pole:

- Varjunimed `scan` ja `rewrite` väärtusele `run`
- `--hidden` lipp (ast-grep liidab selle suvandiga `--no-ignore hidden`)
- Ümberkirjutuse eelvaate varjunimi `--dry-run`
- Ümberkirjutuse kinnitamise töövoog suvandiga `--interactive`

## Piirangud

Greph `sg`-ümbris katab struktuurse otsingu ja ümberkirjutamise funktsionaalsuse, mida enamik tööriistu ja agente kasutab. Praegu ei paku see järgmisi ast-grep funktsioone:

- YAML reeglifailid (`--rule`, `--config`)
- Mitme keele skannimine peale PHP
- Mustritel mittepõhinevad teisendajad (`--debug-query`, `--inspect`)
- LSP-integratsioon

Kui mõni lipp puudub, esitage probleem koos ülesvoolu `sg`-i vastu käivitatud vastastesti ja oodatud väljundiga.

## Käitumise vastavus

Ümbrise eesmärk on käitumise vastavus, mitte baitide täpne kattumine. Väljund on semantiliselt samaväärne, kuid kosmeetilised üksikasjad võivad erineda. [Funktsioonide maatriksi](https://greph.inline0.dev/et/docs/advanced/feature-matrix) vastastestid kontrollivad samaväärsust parseri jaoks oluliste väljade (failitee, reanumber, hõivatud kood, hõivatud osad, JSON kuju) alusel, mitte baitvoo järgi.