# sg saderība

`vendor/bin/sg` ir ar ast-grep saderīgs iesaiņotājs. Tas pieņem visbiežāk lietotos `ast-grep` karodziņus un izmanto to pašu `Greph\Ast\AstSearcher` dzini, ko izmanto `vendor/bin/greph -p`. Pārbaudītā funkcionalitāte ir iegūta, veicot pārbaudes ar sākotnējo `sg` bināro failu, un aprakstīta sadaļā [Papildu informācija / Funkciju matrica](https://greph.inline0.dev/lv/docs/advanced/feature-matrix).

## Kad to izmantot

Izmantojiet iesaiņotāju, ja:

- Jums jau ir rīks, aģents vai skripts, kas izsauc `sg`.
- Vēlaties uzreiz lietojamu aizstājēju, kas darbojas vidēs, kurās nevarat instalēt pašu `ast-grep`.
- Vēlaties izmantot ast-grep ērtības instalācijā, kur pieejams tikai Composer.

Izmantojiet vietējo `vendor/bin/greph -p`, ja:

- Rakstāt jaunu kodu un jums nav vajadzīga ast-grep CLI forma.
- Vēlaties to pašu karodziņu kopu, ko teksta režīmā (vietējais binārais fails apvieno abus režīmus).

## Lietošana

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

`run` ir kanoniskā ast-grep komanda. `scan` un `rewrite` ir tikai iesaiņotāja aizstājvārdi, kas atbilst ierastajam lietojumam. Arī vienkāršs izsaukums veic vienreizēju meklēšanu:

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

## Raksti

Raksta gramatika ir identiska vietējai AST meklēšanai. Pilnu uzziņu rokasgrāmatu skatiet sadaļā [Režīmi / AST meklēšana](https://greph.inline0.dev/lv/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ārrakstīšana

Iesaiņotājs atbalsta to pašu izmēģinājuma, interaktīvo un rakstīšanas darbplūsmu kā vietējā pārrakstīšana, izmantojot ast-grep karodziņu nosaukumus:

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

`--json` izvada ast-grep formas JSON datus. Tiek atbalstīti trīs stili:

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

| Stils | Forma |
|---|---|
| `--json` (noklusējuma `pretty`) | Viens glīti formatēts JSON masīvs |
| `--json=stream` | Viena atbilstība katrā rindā, ar jaunās rindas rakstzīmēm atdalīts JSON |
| `--json=compact` | Viens kompakts JSON masīvs |

## Pārbaudītās funkcijas

Tālāk norādītie karodziņi ir pārbaudīti ar sākotnējo `sg` bināro failu sadaļā [funkciju matrica](https://greph.inline0.dev/lv/docs/advanced/feature-matrix). Ja karodziņam ir divi pieraksti (`-p` un `--pattern`, `--glob` un `--globs`), pārbaudē tiek izmantots viens no tiem, un iesaiņotājs abus pierakstus apstrādā kā vienu un to pašu opciju.

### Raksta karodziņi

- `--pattern PATTERN` (augšējā līmenī un `run` iekšienē)
- `-p PATTERN` (aizstājvārds)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Atbilstības karodziņi

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

### Pārlūkošanas karodziņi

- `--no-ignore hidden` (apvienotā forma)
- `--glob GLOB`, `--globs GLOB`

### Darbplūsmu izpildītāju karodziņi

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

### Pieņemtie karodziņi bez pārbaudes

Iesaiņotājs pieņem arī šos karodziņus, taču tie vēl nav pārbaudīti funkciju matricā:

- `--no-ignore` atsevišķi vai ar vērtību, kas nav `hidden`
- `--type NAME`, `--type-not NAME`

### Tikai iesaiņotāja papildu opcijas

Iesaiņotājs piedāvā dažas palīgfunkcijas, kuru pašam ast-grep nav:

- `scan` un `rewrite` aizstājvārdi `run`
- `--hidden` karodziņš (ast-grep to apvieno ar `--no-ignore hidden`)
- `--dry-run` pārrakstīšanas priekšskatījuma aizstājvārds
- `--interactive` pārrakstīšanas apstiprināšanas darbplūsma

## Ierobežojumi

Greph `sg` aptver strukturālās meklēšanas un pārrakstīšanas funkcijas, ko izmanto lielākā daļa rīku un aģentu. Pašlaik tajā nav pieejamas šādas ast-grep funkcijas:

- YAML noteikumu faili (`--rule`, `--config`)
- Vairāku valodu skenēšana ārpus PHP
- Pārveidotāji, kas nav balstīti uz paraugiem (`--debug-query`, `--inspect`)
- LSP integrācija

Ja trūkst kāda karodziņa, iesniedziet problēmas ziņojumu, pievienojot pārbaudi, ko veicāt pret upstream `sg`, un sagaidāmo izvadi.

## Atbilstība darbībā

Wrapper mērķis ir nodrošināt uzvedības, nevis baitu līmeņa atbilstību. Izvade ir semantiski ekvivalenta, taču var atšķirties kosmētiskās detaļās. Pārbaudes, ko izmanto [funkciju matricā](https://greph.inline0.dev/lv/docs/advanced/feature-matrix), ekvivalencei salīdzina parserim būtiskos laukus (faila ceļu, rindas numuru, uztverto kodu, uztvertās vērtības, JSON formu), nevis baitu plūsmu.