# Kompatibilitas sg

`vendor/bin/sg` adalah pembungkus kompatibilitas bergaya ast-grep. Pembungkus ini menerima flag `ast-grep` yang paling umum digunakan dan menggunakan kembali mesin `Greph\Ast\AstSearcher` yang sama dengan yang digunakan `vendor/bin/greph -p`. Antarmuka yang telah diverifikasi berasal dari uji probe terhadap biner upstream `sg` dan tersedia di [Lanjutan / Matriks Fitur](https://greph.inline0.dev/id/docs/advanced/feature-matrix).

## Kapan menggunakannya

Gunakan pembungkus jika:

- Anda memiliki alat, agen, atau skrip yang sudah menjalankan `sg`.
- Anda menginginkan pengganti siap pakai yang berfungsi di lingkungan tempat Anda tidak dapat memasang `ast-grep` itu sendiri.
- Anda menginginkan kemudahan penggunaan ast-grep dari instalasi yang hanya berisi Composer.

Gunakan `vendor/bin/greph -p` native jika:

- Anda sedang menulis kode baru dan tidak memerlukan bentuk ast-grep CLI.
- Anda menginginkan kumpulan flag yang sama seperti mode teks (biner native menyatukan keduanya).

## Penggunaan

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

`run` adalah kata kerja ast-grep kanonis. `scan` dan `rewrite` adalah alias khusus pembungkus yang mencerminkan penggunaan umum. Pemanggilan tanpa argumen tambahan berfungsi sebagai pencarian sekali jalan:

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

## Pola

Tata bahasa pola identik dengan pencarian AST native. Lihat [Mode / Pencarian AST](https://greph.inline0.dev/id/docs/modes/ast) untuk referensi lengkap.

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

## Penulisan ulang

Pembungkus mendukung alur kerja uji coba / interaktif / penulisan yang sama seperti penulisan ulang native, dengan nama 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
```

## Output JSON

`--json` menghasilkan ast-grep berbentuk JSON. Tiga gaya didukung:

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

| Gaya | Bentuk |
|---|---|
| `--json` (default `pretty`) | Satu array JSON yang dicetak dengan format rapi |
| `--json=stream` | Satu kecocokan per baris, JSON dipisahkan baris baru |
| `--json=compact` | Satu array JSON ringkas |

## Antarmuka yang diverifikasi

Flag berikut telah diverifikasi terhadap biner upstream `sg` dalam [matriks fitur](https://greph.inline0.dev/id/docs/advanced/feature-matrix). Jika sebuah flag memiliki dua ejaan (`-p` dan `--pattern`, `--glob` dan `--globs`), probe menggunakan salah satunya dan pembungkus mengurai keduanya sebagai opsi yang sama.

### Flag pola

- `--pattern PATTERN` (tingkat teratas dan di dalam `run`)
- `-p PATTERN` (alias)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Flag kecocokan

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

### Flag penelusur

- `--no-ignore hidden` (bentuk gabungan)
- `--glob GLOB`, `--globs GLOB`

### Flag pekerja

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

### Diterima tanpa probe

Pembungkus juga menerima flag berikut, tetapi belum ada probe matriks fitur yang mencakupnya:

- `--no-ignore` jika digunakan sendiri atau dengan nilai selain `hidden`
- `--type NAME`, `--type-not NAME`

### Fitur tambahan khusus pembungkus

Pembungkus menyediakan beberapa bantuan yang tidak dimiliki ast-grep:

- Alias `scan` dan `rewrite` untuk `run`
- Flag `--hidden` (ast-grep menggabungkan ini ke dalam `--no-ignore hidden`)
- Alias pratinjau penulisan ulang `--dry-run`
- Alur konfirmasi penulisan ulang `--interactive`

## Batasan

Pembungkus `sg` milik Greph mencakup permukaan pencarian struktural dan penulisan ulang yang digunakan sebagian besar alat dan agen. Saat ini, pembungkus tersebut belum menyediakan fitur ast-grep berikut:

- File aturan YAML (`--rule`, `--config`)
- Pemindaian multibahasa di luar PHP
- Transformer nonpola (`--debug-query`, `--inspect`)
- Integrasi LSP

Jika Anda menemukan flag yang belum tersedia, ajukan issue dengan probe yang Anda jalankan terhadap upstream `sg` dan output yang diharapkan.

## Kesetaraan perilaku

Pembungkus ini menargetkan kesetaraan perilaku, bukan kesetaraan byte. Output setara secara semantik, tetapi dapat berbeda dalam detail kosmetik. Probe dalam [matriks fitur](https://greph.inline0.dev/id/docs/advanced/feature-matrix) memeriksa kesetaraan field yang relevan bagi parser (jalur file, nomor baris, kode yang ditangkap, hasil tangkapan, bentuk JSON), bukan aliran byte.