# Сумісність із sg

`vendor/bin/sg` — обгортка сумісності у стилі ast-grep. Вона приймає найуживаніші прапорці `ast-grep` і повторно використовує той самий рушій `Greph\Ast\AstSearcher`, що й `vendor/bin/greph -p`. Перевірений набір можливостей відтворено за результатами пробних запусків із вихідним бінарним файлом `sg` і наведено в [Додатково / Матриця можливостей](https://greph.inline0.dev/uk/docs/advanced/feature-matrix).

## Коли використовувати

Використовуйте обгортку, якщо:

- У вас є наявний інструмент, агент або скрипт, який уже викликає `sg`.
- Вам потрібна пряма заміна, що працює в середовищах, де не можна встановити сам `ast-grep`.
- Вам потрібна зручність ast-grep під час встановлення лише Composer.

Використовуйте нативний `vendor/bin/greph -p`, якщо:

- Ви пишете новий код і вам не потрібна форма ast-grep CLI.
- Вам потрібен той самий набір прапорців, що й у текстовому режимі (нативний бінарний файл об’єднує обидва режими).

## Використання

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

`run` — канонічна команда ast-grep. `scan` і `rewrite` — псевдоніми лише для обгортки, що відповідають поширеному вжитку. Виклик без аргументів виконує одноразовий пошук:

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

## Візерунки

Синтаксис шаблонів ідентичний синтаксису нативного пошуку AST. Повний опис див. у розділі [Режими / Пошук AST](https://greph.inline0.dev/uk/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
```

## Перезаписи

Обгортка підтримує такий самий процес пробного запуску, інтерактивного режиму й запису, як і нативний перезапис, із назвами прапорців 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
```

## Вивід JSON

`--json` виводить дані JSON у формі ast-grep. Підтримуються три стилі:

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

| Стиль | Форма |
|---|---|
| `--json` (за замовчуванням `pretty`) | Один гарно відформатований масив JSON |
| `--json=stream` | Один збіг у рядку, JSON з розділенням новими рядками |
| `--json=compact` | Один компактний масив JSON |

## Перевірений набір можливостей

Наведені нижче прапорці перевірено на вихідному бінарному файлі `sg` у [матриці можливостей](https://greph.inline0.dev/uk/docs/advanced/feature-matrix). Якщо прапорець має два варіанти написання (`-p` і `--pattern`, `--glob` і `--globs`), у пробі використовується один із них, а обгортка розбирає обидва як один і той самий параметр.

### Прапорці шаблонів

- `--pattern PATTERN` (на верхньому рівні та всередині `run`)
- `-p PATTERN` (псевдонім)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Прапорці збігів

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

### Прапорці обходу

- `--no-ignore hidden` (комбінована форма)
- `--glob GLOB`, `--globs GLOB`

### Прапорці робочих процесів

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

### Приймаються без пробної перевірки

Обгортка також приймає ці прапорці, але їх ще не перевірено пробами в матриці можливостей:

- `--no-ignore` окремо або зі значенням, відмінним від `hidden`
- `--type NAME`, `--type-not NAME`

### Додаткові можливості лише для обгортки

Обгортка надає кілька допоміжних засобів, яких немає навіть у самому ast-grep:

- Псевдоніми `scan` і `rewrite` для `run`
- Прапорець `--hidden` (ast-grep об’єднує цю функцію з `--no-ignore hidden`)
- Псевдонім `--dry-run` для попереднього перегляду перезапису
- Процес підтвердження перезапису `--interactive`

## Обмеження

Обгортка `sg` для Greph охоплює структурний пошук і перезапис, які використовує більшість інструментів та агентів. Наразі вона не надає доступу до таких можливостей ast-grep:

- Файли правил YAML (`--rule`, `--config`)
- Сканування кількох мов, окрім PHP
- Перетворювачі без шаблонів (`--debug-query`, `--inspect`)
- Інтеграція з LSP

Якщо бракує потрібного прапорця, створіть запит на виправлення та додайте пробу, яку ви виконали з вихідним `sg`, і очікуваний вивід.

## Відповідність поведінки

Обгортка прагне відповідності поведінки, а не побітової відповідності. Вивід семантично еквівалентний, але може відрізнятися косметичними деталями. Проби для [матриці можливостей](https://greph.inline0.dev/uk/docs/advanced/feature-matrix) перевіряють еквівалентність важливих для аналізатора полів (шлях до файлу, номер рядка, захоплений код, захоплені значення, форма JSON), а не потоку байтів.