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

`vendor/bin/sg` е обвивка за съвместимост в стил ast-grep. Приема най-често използваните флагове на `ast-grep` и използва повторно същата машина `Greph\Ast\AstSearcher`, която ползва `vendor/bin/greph -p`. Потвърденият обхват е възпроизведен чрез пробни изпълнения на оригиналния двоичен файл `sg` и е публикуван в [Разширени / Матрица на функциите](https://greph.inline0.dev/bg/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/bg/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/bg/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/bg/docs/advanced/feature-matrix) проверяват еквивалентността на важните за анализатора полета (път до файла, номер на ред, уловен код, уловени стойности, структура JSON), а не на потока от байтове.