# Kompatibilita s sg

`vendor/bin/sg` je obal kompatibilný so štýlom ast-grep. Prijíma najčastejšie používané prepínače `ast-grep` a opätovne využíva ten istý modul `Greph\Ast\AstSearcher` ako `vendor/bin/greph -p`. Overený rozsah vychádza zo skúšobných behov s pôvodným binárnym súborom `sg` a je uvedený v [Rozšírené / Matica funkcií](https://greph.inline0.dev/sk/docs/advanced/feature-matrix).

## Kedy ho použiť

Obal použite, keď:

- Už máte nástroj, agenta alebo skript, ktorý volá `sg`.
- Chcete priamu náhradu použiteľnú v prostrediach, kde nemožno nainštalovať samotné `ast-grep`.
- Chcete pohodlné používanie ast-grep v inštalácii, ktorá obsahuje iba Composer.

Natívne `vendor/bin/greph -p` použite, keď:

- Píšete nový kód a nepotrebujete formát ast-grep CLI.
- Chcete rovnakú množinu prepínačov ako v textovom režime (natívny binárny súbor oba režimy spája).

## Použitie

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

`run` je kanonické sloveso ast-grep. `scan` a `rewrite` sú aliasy dostupné iba v obaloch, ktoré kopírujú bežné používanie. Samotné zavolanie funguje ako jednorazové vyhľadávanie:

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

## Vzory

Gramatika vzorov je totožná s natívnym vyhľadávaním AST. Úplnú referenciu nájdete v časti [Režimy / Vyhľadávanie AST](https://greph.inline0.dev/sk/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
```

## Prepisovanie

Obal podporuje rovnaký pracovný postup pre skúšobné spustenie, interaktívne úpravy a zápis ako natívne prepisovanie, pričom používa názvy prepínačov 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
```

## Výstup JSON

`--json` vytvára výstup v tvare ast-grep JSON. Podporované sú tri štýly:

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

| Štýl | Tvar |
|---|---|
| `--json` (predvolený `pretty`) | Jedno pekne naformátované pole JSON |
| `--json=stream` | Jedna zhoda na riadok, oddelené znakmi nového riadka JSON |
| `--json=compact` | Jedno kompaktné pole JSON |

## Overený rozsah

Nasledujúce prepínače sú overené oproti pôvodnému binárnemu súboru `sg` v [matica funkcií](https://greph.inline0.dev/sk/docs/advanced/feature-matrix). Ak má prepínač dva zápisy (`-p` a `--pattern`, `--glob` a `--globs`), skúška používa jeden z nich a obal oba rozpozná ako rovnakú možnosť.

### Prepínače vzorov

- `--pattern PATTERN` (na najvyššej úrovni aj v rámci `run`)
- `-p PATTERN` (alias)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Prepínače zhody

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

### Prepínače prechádzača

- `--no-ignore hidden` (kombinovaný tvar)
- `--glob GLOB`, `--globs GLOB`

### Prepínače pracovníkov

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

### Prijaté bez skúšobného overenia

Obal prijíma aj tieto prepínače, zatiaľ ich však neoveruje žiadna skúška matice funkcií:

- Samotné `--no-ignore` alebo s hodnotou odlišnou od `hidden`
- `--type NAME`, `--type-not NAME`

### Doplnkové možnosti dostupné iba v obale

Obal poskytuje niekoľko pomocných možností, ktoré samotné ast-grep nemá:

- Aliasy `scan` a `rewrite` pre `run`
- Prepínač `--hidden` (ast-grep zlučuje túto možnosť s `--no-ignore hidden`)
- Alias `--dry-run` na zobrazenie náhľadu prepisu
- Postup na potvrdenie prepisu `--interactive`

## Obmedzenia

Obal Greph pre `sg` pokrýva funkcie štrukturálneho vyhľadávania a prepisovania, ktoré používajú najčastejšie nástroje a agenti. V súčasnosti neposkytuje nasledujúce funkcie ast-grep:

- Súbory pravidiel YAML (`--rule`, `--config`)
- Prehľadávanie vo viacerých jazykoch okrem PHP
- Transformátory, ktoré nepoužívajú vzory (`--debug-query`, `--inspect`)
- Integrácia s LSP

Ak vám chýba nejaký prepínač, nahláste problém spolu s výsledkom skúšky, ktorú ste vykonali voči pôvodnému `sg`, a očakávaným výstupom.

## Zhoda správania

Obal sa zameriava na zhodu správania, nie na zhodu bajtov. Výstup je sémanticky ekvivalentný, no v kozmetických detailoch sa môže líšiť. Testy použité v matici funkcií [ kontrolujú zhodu polí dôležitých pre parser (cesta k súboru, číslo riadka, zachytený kód, zachytené hodnoty, tvar JSON), nie zhodu bajtového toku.](https://greph.inline0.dev/sk/docs/advanced/feature-matrix)