# Совместимость с sg

`vendor/bin/sg` — оболочка совместимости в стиле ast-grep. Она поддерживает наиболее часто используемые флаги `ast-grep` и использует тот же движок `Greph\Ast\AstSearcher`, что и `vendor/bin/greph -p`. Подтвержденный набор возможностей составлен по результатам проверок исходного исполняемого файла `sg` и опубликован в разделе [Дополнительно / Матрица возможностей](https://greph.inline0.dev/ru/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/ru/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` выводит ast-grep в формате JSON. Поддерживаются три стиля:

```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/ru/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/ru/docs/advanced/feature-matrix) сравнивают поля, важные для парсера (путь к файлу, номер строки, захваченный код, захваты, формат JSON), а не поток байтов.