# Kompatibilita s sg

`vendor/bin/sg` je wrapper kompatibilní se stylem ast-grep. Přijímá nejčastěji používané příznaky `ast-grep` a znovu používá stejný engine `Greph\Ast\AstSearcher`, který používá `vendor/bin/greph -p`. Ověřené možnosti vycházejí z testovacích běhů s upstreamovým binárním souborem `sg` a jsou uvedeny v [Rozšířené funkce / Matice funkcí](https://greph.inline0.dev/cs/docs/advanced/feature-matrix).

## Kdy jej použít

Wrapper použijte, když:

- Máte existující nástroj, agenta nebo skript, který už spouští `sg`.
- Chcete přímou náhradu, která funguje v prostředích, kde nelze nainstalovat samotný `ast-grep`.
- Chcete pohodlí ast-grep v instalaci, která obsahuje pouze Composer.

Nativní `vendor/bin/greph -p` použijte, když:

- Píšete nový kód a nepotřebujete rozhraní ast-grep CLI.
- Chcete používat stejnou sadu příznaků jako v textovém režimu (nativní binární soubor oba režimy sjednocuje).

## Použití

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

`run` je kanonický příkaz ast-grep. `scan` a `rewrite` jsou pouze aliasy wrapperu, které odpovídají běžnému použití. Funguje i samotné spuštění jako jednorázové vyhledávání:

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

## Vzory

Gramatika vzorů je totožná s nativním vyhledáváním v AST. Úplné informace najdete v části [Režimy / Vyhledávání v AST](https://greph.inline0.dev/cs/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
```

## Přepisy

Wrapper podporuje stejný pracovní postup nanečisto / interaktivní / zápis jako nativní přepis; používá názvy příznaků 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` vydává ast-grep ve formátu JSON. Podporuje tři styly:

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

| Styl | Formát |
|---|---|
| `--json` (výchozí `pretty`) | Jediné hezky formátované pole JSON |
| `--json=stream` | Jedna shoda na řádek, data JSON oddělená novým řádkem |
| `--json=compact` | Jediné kompaktní pole JSON |

## Ověřené možnosti

Následující příznaky jsou ověřeny proti upstreamovému binárnímu souboru `sg` v [matici funkcí](https://greph.inline0.dev/cs/docs/advanced/feature-matrix). Má-li příznak dva zápisy (`-p` a `--pattern`, `--glob` a `--globs`), test používá jeden z nich a wrapper oba zpracuje jako tutéž volbu.

### Příznaky vzoru

- `--pattern PATTERN` (na nejvyšší úrovni i uvnitř `run`)
- `-p PATTERN` (alias)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Příznaky shody

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

### Příznaky procházení

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

### Příznaky pracovníků

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

### Přijímané bez testu

Wrapper přijímá také následující příznaky, na které se zatím nevztahuje žádný test matice funkcí:

- `--no-ignore` samostatně nebo s jinou hodnotou než `hidden`
- `--type NAME`, `--type-not NAME`

### Další možnosti pouze ve wrapperu

Wrapper nabízí několik pomocných možností, které samotné ast-grep nemá:

- Aliasy `scan` a `rewrite` pro `run`
- Příznak `--hidden` (ast-grep jej zahrnuje do `--no-ignore hidden`)
- Alias `--dry-run` pro náhled přepisu
- Průběh potvrzení přepisu `--interactive`

## Omezení

Wrapper `sg` pro Greph pokrývá možnosti strukturálního vyhledávání a přepisu, které využívá většina nástrojů a agentů. V současnosti nezpřístupňuje tyto funkce ast-grep:

- Soubory pravidel YAML (`--rule`, `--config`)
- Prohledávání více jazyků kromě PHP
- Transformátory, které nepoužívají vzory (`--debug-query`, `--inspect`)
- Integrace LSP

Pokud narazíte na chybějící příznak, založte hlášení a přiložte test provedený proti upstreamovému `sg` i očekávaný výstup.

## Shoda chování

Cílem wrapperu je shoda chování, nikoli shoda po bajtech. Výstup je sémanticky rovnocenný, ale může se lišit v kosmetických detailech. Testy použité v [matici funkcí](https://greph.inline0.dev/cs/docs/advanced/feature-matrix) ověřují shodu polí důležitých pro parser (cesta k souboru, číslo řádku, zachycený kód, zachycené hodnoty, struktura JSON), nikoli bajtového proudu.