# sg-yhteensopivuus

`vendor/bin/sg` on ast-grep-tyylinen yhteensopivuuskerros. Se hyväksyy yleisimmin käytetyt `ast-grep`-valitsimet ja käyttää samaa `Greph\Ast\AstSearcher`-moottoria kuin `vendor/bin/greph -p`. Vahvistetut ominaisuudet on toisinnettu kokeista, jotka on ajettu alkuperäistä `sg`-binääriä vasten, ja ne löytyvät kohdasta [Lisäasetukset / Ominaisuusmatriisi](https://greph.inline0.dev/fi/docs/advanced/feature-matrix).

## Milloin sitä kannattaa käyttää

Käytä yhteensopivuuskerrosta, kun:

- Käytössäsi on työkalu, agentti tai skripti, joka kutsuu jo komentoa `sg`.
- Haluat suoraan korvaavan työkalun, joka toimii ympäristöissä, joihin et voi asentaa itse `ast-grep`-ohjelmaa.
- Haluat ast-grep-käyttömukavuuden vain Composer-asennuksesta.

Käytä natiivia komentoa `vendor/bin/greph -p`, kun:

- Kirjoitat uutta koodia etkä tarvitse ast-grep CLI -muotoa.
- Haluat saman valitsinjoukon kuin tekstitilassa (natiivissa binäärissä molemmat on yhdistetty).

## Käyttö

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

`run` on kanoninen ast-grep-verbi. `scan` ja `rewrite` ovat vain yhteensopivuuskerroksen aliaksia, jotka vastaavat yleistä käyttötapaa. Myös pelkkä komento toimii kertaluonteisena hakuna:

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

## Kuviot

Mallikieli on sama kuin natiivissa AST-haussa. Katso täydellinen viite kohdasta [Tilat / AST-haku](https://greph.inline0.dev/fi/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
```

## Uudelleenkirjoitukset

Yhteensopivuuskerros tukee samaa kokeiluajoa / vuorovaikutteista / kirjoittavaa työnkulkua kuin natiivin uudelleenkirjoitustila, käyttäen ast-grep-valitsinten nimiä:

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

`--json` tuottaa ast-grep-muotoisia JSON-tuloksia. Tuettuja tyylejä on kolme:

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

| Tyyli | Muoto |
|---|---|
| `--json` (oletus `pretty`) | Yksi kauniisti muotoiltu JSON-taulukko |
| `--json=stream` | Yksi osuma rivillä, rivinvaihdoilla erotettu JSON |
| `--json=compact` | Yksi tiivis JSON-taulukko |

## Vahvistetut ominaisuudet

Seuraavat valitsimet on testattu alkuperäistä `sg`-binääriä vasten [ominaisuusmatriisissa](https://greph.inline0.dev/fi/docs/advanced/feature-matrix). Jos valitsimella on kaksi kirjoitusasua (`-p` ja `--pattern`, `--glob` ja `--globs`), kokeessa käytetään jompaakumpaa, ja yhteensopivuuskerros tulkitsee molemmat samaksi asetukseksi.

### Mallivalitsimet

- `--pattern PATTERN` (ylimmällä tasolla ja `run`-asetuksen sisällä)
- `-p PATTERN` (alias)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Osumavalitsimet

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

### Läpikäynnin valitsimet

- `--no-ignore hidden` (yhdistetty muoto)
- `--glob GLOB`, `--globs GLOB`

### Työntekijävalitsimet

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

### Hyväksytään ilman koetta

Yhteensopivuuskerros hyväksyy myös seuraavat valitsimet, mutta niitä ei ole vielä testattu ominaisuusmatriisissa:

- `--no-ignore` yksinään tai arvolla, joka ei ole `hidden`
- `--type NAME`, `--type-not NAME`

### Vain yhteensopivuuskerroksen lisätoiminnot

Yhteensopivuuskerros tarjoaa muutamia aputoimintoja, joita itse ast-grep-ohjelmassa ei ole:

- `scan`- ja `rewrite`-aliakset komennolle `run`
- `--hidden`-valitsin (ast-grep sisällyttää tämän toimintoon `--no-ignore hidden`)
- `--dry-run`-alias uudelleenkirjoituksen esikatseluun
- `--interactive`-toiminto uudelleenkirjoitusten vahvistamiseen

## Rajoitukset

Greph-komennon `sg`-yhteensopivuuskerros kattaa useimpien työkalujen ja agenttien käyttämät rakenteisen haun ja uudelleenkirjoituksen ominaisuudet. Se ei tällä hetkellä tarjoa seuraavia ast-grep-ominaisuuksia:

- YAML-sääntötiedostot (`--rule`, `--config`)
- Monikielinen läpikäynti kohteen PHP lisäksi
- Malliin perustumattomat muuntimet (`--debug-query`, `--inspect`)
- LSP-integraatio

Jos jokin valitsin puuttuu, luo ilmoitus ja liitä mukaan alkuperäistä `sg`-komentoa vasten tekemäsi koe sekä odotettu tuloste.

## Käyttäytymisen vastaavuus

Yhteensopivuuskerroin tavoitteena on vastaava toiminta, ei tavuntarkka vastaavuus. Tuloste on semanttisesti vastaava, mutta kosmeettisissa yksityiskohdissa voi olla eroja. [Ominaisuusmatriisin](https://greph.inline0.dev/fi/docs/advanced/feature-matrix) kokeissa tarkistetaan jäsentimen kannalta olennaisten kenttien (tiedostopolku, rivinumero, talteen otettu koodi, talteen otetut osumat, JSON-muoto) vastaavuus, ei tavujonoa.