# Zgodność z sg

`vendor/bin/sg` to warstwa zgodności w stylu ast-grep. Przyjmuje najczęściej używane flagi `ast-grep` i korzysta z tego samego silnika `Greph\Ast\AstSearcher` co `vendor/bin/greph -p`. Zweryfikowany zakres odtworzono na podstawie uruchomień próbnych wobec nadrzędnego pliku wykonywalnego `sg` i opisano w sekcji [Zaawansowane / macierz funkcji](https://greph.inline0.dev/pl/docs/advanced/feature-matrix).

## Kiedy używać

Użyj warstwy opakowującej, gdy:

- Masz istniejące narzędzie, agenta lub skrypt, który już wywołuje `sg`.
- Chcesz zamiennika, który działa w środowiskach, w których nie możesz zainstalować samego `ast-grep`.
- Chcesz korzystać z wygody ast-grep w instalacji obsługującej wyłącznie Composer.

Użyj natywnego `vendor/bin/greph -p`, gdy:

- Piszesz nowy kod i nie potrzebujesz formatu ast-grep CLI.
- Chcesz używać tego samego zestawu flag co w trybie tekstowym (natywny plik wykonywalny łączy oba tryby).

## Użycie

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

`run` to kanoniczne polecenie ast-grep. `scan` i `rewrite` to aliasy dostępne wyłącznie w warstwie zgodności, odzwierciedlające typowe użycie. Samo wywołanie uruchamia jednorazowe wyszukiwanie:

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

## Wzorce

Składnia wzorców jest identyczna jak w natywnym wyszukiwaniu AST. Pełny opis znajdziesz w sekcji [Tryby / wyszukiwanie AST](https://greph.inline0.dev/pl/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
```

## Przepisywanie

Warstwa opakowująca obsługuje ten sam proces próbny / interaktywny / zapisu co natywne przepisywanie, z nazwami flag 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
```

## Dane wyjściowe JSON

`--json` emituje dane ast-grep w kształcie JSON. Obsługiwane są trzy style:

```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 | Struktura |
|---|---|
| `--json` (domyślnie `pretty`) | Pojedyncza, ładnie sformatowana tablica JSON |
| `--json=stream` | Jedno dopasowanie w każdym wierszu, rozdzielane znakami nowego wiersza JSON |
| `--json=compact` | Pojedyncza, zwarta tablica JSON |

## Zweryfikowany zakres

Poniższe flagi zweryfikowano względem nadrzędnego pliku wykonywalnego `sg` w [macierzy funkcji](https://greph.inline0.dev/pl/docs/advanced/feature-matrix). Gdy flaga ma dwie nazwy (`-p` i `--pattern`, `--glob` i `--globs`), próba używa jednej z nich, a warstwa opakowująca rozpoznaje obie jako tę samą opcję.

### Flagi wzorca

- `--pattern PATTERN` (na najwyższym poziomie i wewnątrz `run`)
- `-p PATTERN` (alias)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Flagi dopasowania

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

### Flagi przechodzenia po plikach

- `--no-ignore hidden` (forma łączona)
- `--glob GLOB`, `--globs GLOB`

### Flagi procesów roboczych

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

### Akceptowane bez próby

Warstwa opakowująca akceptuje także poniższe flagi, ale nie zostały one jeszcze objęte próbą w macierzy funkcji:

- Samo `--no-ignore` lub z wartością inną niż `hidden`
- `--type NAME`, `--type-not NAME`

### Dodatkowe opcje tylko w warstwie opakowującej

Warstwa opakowująca udostępnia kilka pomocniczych opcji, których samo ast-grep nie ma:

- Aliasy `scan` i `rewrite` dla `run`
- Flaga `--hidden` (ast-grep łączy tę opcję z `--no-ignore hidden`)
- Alias `--dry-run` do podglądu przepisywania
- `--interactive` do potwierdzania przepisywania

## Ograniczenia

Warstwa opakowująca `sg` dla Greph obejmuje funkcje wyszukiwania strukturalnego i przepisywania używane przez większość narzędzi i agentów. Obecnie nie udostępnia następujących funkcji ast-grep:

- Pliki reguł YAML (`--rule`, `--config`)
- Skanowanie wielu języków poza PHP
- Transformatory inne niż wzorcowe (`--debug-query`, `--inspect`)
- Integracja LSP

Jeśli brakuje jakiejś flagi, zgłoś problem i dołącz próbę uruchomioną wobec nadrzędnego `sg` oraz oczekiwane dane wyjściowe.

## Zgodność zachowania

Warstwa opakowująca dąży do zgodności zachowania, a nie zgodności bajtowej. Dane wyjściowe są równoważne semantycznie, ale mogą różnić się w szczegółach kosmetycznych. Próby użyte w [macierzy funkcji](https://greph.inline0.dev/pl/docs/advanced/feature-matrix) sprawdzają równoważność pól istotnych dla parsera (ścieżki pliku, numeru wiersza, przechwyconego kodu, przechwyceń i struktury JSON), a nie strumienia bajtów.