# sg-kompatibilitás

A `vendor/bin/sg` ast-grep-stílusú kompatibilitási burkoló. Elfogadja a leggyakrabban használt `ast-grep` jelzőket, és ugyanazt a `Greph\Ast\AstSearcher` motort használja, mint a `vendor/bin/greph -p`. Az ellenőrzött felület a felsőbb szintű `sg` bináris fájllal végzett próbaeredmények alapján készült, és az [Haladó / Funkciómátrix](https://greph.inline0.dev/hu/docs/advanced/feature-matrix) oldalon található.

## Mikor használja

Akkor használja a burkolót, ha:

- Van egy meglévő eszköze, ügynöke vagy szkriptje, amely már a `sg` eszközt hívja.
- Olyan közvetlenül behelyettesíthető megoldást szeretne, amely olyan környezetben is működik, ahol magát a `ast-grep` eszközt nem telepítheti.
- Composer-alapú telepítésből szeretné élvezni a ast-grep használatának kényelmét.

Akkor használja a natív `vendor/bin/greph -p` eszközt, ha:

- Új kódot ír, és nincs szüksége a ast-grep CLI formátumára.
- A szöveges móddal megegyező jelzőkészletet szeretné használni (a natív bináris fájl egységesíti a kettőt).

## Használat

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

A `run` a kanonikus ast-grep ige. A `scan` és a `rewrite` csak a burkolóban elérhető aliasok, amelyek a szokásos használatot követik. Az argumentum nélküli meghívás egyszeri keresésként is működik:

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

## Minták

A mintanyelvtan megegyezik a natív AST-keresésével. A teljes leírást lásd a [Módok / AST-keresés](https://greph.inline0.dev/hu/docs/modes/ast) oldalon.

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

## Átírások

A burkoló ugyanazt a próbaüzemű / interaktív / írási munkafolyamatot támogatja, mint a natív átírás, ast-grep jelzőnevekkel:

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

A `--json` ast-grep-formátumú JSON kimenetet állít elő. Három stílus támogatott:

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

| Stílus | Formátum |
|---|---|
| `--json` (alapértelmezett `pretty`) | Egyetlen, szépen formázott JSON tömb |
| `--json=stream` | Soronként egy egyezés, újsorokkal elválasztott JSON |
| `--json=compact` | Egyetlen tömör JSON tömb |

## Ellenőrzött felület

A következő jelzők ellenőrzése a felsőbb szintű `sg` bináris fájlon történt, a [funkciómátrix](https://greph.inline0.dev/hu/docs/advanced/feature-matrix) szerint. Ha egy jelzőnek két alakja van (`-p` és `--pattern`, `--glob` és `--globs`), a próba ezek egyikét használja, a burkoló pedig mindkettőt ugyanazon beállításként értelmezi.

### Mintajelzők

- `--pattern PATTERN` (legfelső szinten és a `run` belsejében)
- `-p PATTERN` (alias)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Egyezési jelzők

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

### Bejárási jelzők

- `--no-ignore hidden` (kombinált forma)
- `--glob GLOB`, `--globs GLOB`

### Munkásjelzők

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

### Próba nélkül elfogadott jelzők

A burkoló ezeket a jelzőket is elfogadja, de a funkciómátrix még nem tartalmaz hozzájuk próbát:

- A `--no-ignore` önmagában vagy a `hidden` értéktől eltérő értékkel
- `--type NAME`, `--type-not NAME`

### Csak a burkolóban elérhető kiegészítők

A burkoló néhány olyan segédeszközt is biztosít, amellyel maga a ast-grep nem rendelkezik:

- `scan` és `rewrite` aliasok a következőhöz: `run`
- `--hidden` jelző (a ast-grep ezt a `--no-ignore hidden` részévé teszi)
- `--dry-run` átírási előnézet alias
- `--interactive` átírás-megerősítési folyamat

## Korlátozások

A Greph `sg`-burkolója a legtöbb eszköz és ügynök által használt strukturális keresési és átírási felületet biztosítja. Jelenleg a következő ast-grep funkciókat nem teszi elérhetővé:

- YAML szabályfájlok (`--rule`, `--config`)
- Többnyelvű vizsgálat a PHP nyelven túli nyelveken
- Nem mintaalapú átalakítók (`--debug-query`, `--inspect`)
- LSP-integráció

Ha hiányzó jelzőbe ütközik, nyisson hibajegyet az upstream `sg` ellen futtatott próbával és az elvárt kimenettel együtt.

## Viselkedésbeli egyezés

A burkoló viselkedésbeli, nem pedig bájtszintű egyezésre törekszik. A kimenet szemantikailag egyenértékű, de kozmetikai részletekben eltérhet. A [funkciómátrix](https://greph.inline0.dev/hu/docs/advanced/feature-matrix) próbái a parser szempontjából lényeges mezők (fájlútvonal, sorszám, rögzített kód, rögzítések, JSON formátuma) egyezését ellenőrzik, nem a bájtfolyam azonosságát.