# sg Uyumluluğu

`vendor/bin/sg`, ast-grep tarzı bir uyumluluk sarmalayıcısıdır. En sık kullanılan `ast-grep` bayraklarını kabul eder ve `vendor/bin/greph -p`'ün kullandığı `Greph\Ast\AstSearcher` motorunu kullanır. Doğrulanmış kapsam, üst kaynak `sg` ikili dosyasına karşı yürütülen denemelerden elde edilmiştir ve [Gelişmiş / Özellik Matrisi](https://greph.inline0.dev/tr/docs/advanced/feature-matrix) bölümünde yer alır.

## Ne zaman kullanılır?

Sarmalayıcıyı şu durumlarda kullanın:

- `sg` çağıran mevcut bir aracınız, ajanınız veya betiğiniz varsa.
- `ast-grep`'i yükleyemediğiniz ortamlarda çalışan, doğrudan kullanılabilir bir alternatif istiyorsanız.
- Yalnızca Composer kurulumundan ast-grep kullanım kolaylığı istiyorsanız.

Şu durumlarda yerel `vendor/bin/greph -p` kullanın:

- Yeni kod yazıyor ve ast-grep CLI biçimine ihtiyaç duymuyorsanız.
- Metin kipiyle aynı bayrak kümesini istiyorsanız (yerel ikili dosya her iki kipi birleştirir).

## Kullanım

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

`run` temel ast-grep fiilidir. `scan` ve `rewrite`, yaygın kullanımı yansıtan yalnızca sarmalayıcıya özgü takma adlardır. Parametresiz bir çağrı, tek seferlik arama olarak çalışır:

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

## Desenler

Desen dil bilgisi, yerel AST aramasıyla aynıdır. Tam başvuru için [Kipler / AST Arama](https://greph.inline0.dev/tr/docs/modes/ast) bölümüne bakın.

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

## Yeniden yazmalar

Sarmalayıcı, yerel yeniden yazmayla aynı deneme / etkileşimli / yazma iş akışını, ast-grep bayrak adlarıyla destekler:

```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 çıktısı

`--json`, ast-grep biçimli JSON üretir. Üç stil desteklenir:

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

| Stil | Biçim |
|---|---|
| `--json` (varsayılan `pretty`) | Tek, biçimlendirilmiş JSON dizisi |
| `--json=stream` | Her satırda bir eşleşme; satır sonlarıyla ayrılmış JSON |
| `--json=compact` | Tek, sıkıştırılmış JSON dizisi |

## Doğrulanmış kapsam

Aşağıdaki bayraklar, [özellik matrisinde](https://greph.inline0.dev/tr/docs/advanced/feature-matrix) üst kaynak `sg` ikili dosyasına karşı doğrulanmıştır. Bir bayrağın iki yazımı varsa (`-p` ve `--pattern`, `--glob` ve `--globs`), denemede bunlardan biri kullanılır; sarmalayıcı ikisini de aynı seçenek olarak ayrıştırır.

### Desen bayrakları

- `--pattern PATTERN` (üst düzeyde ve `run` içinde)
- `-p PATTERN` (takma ad)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Eşleşme bayrakları

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

### Gezgin bayrakları

- `--no-ignore hidden` (birleşik biçim)
- `--glob GLOB`, `--globs GLOB`

### İşçi bayrakları

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

### Deneme yapılmadan kabul edilenler

Sarmalayıcı bu bayrakları da kabul eder, ancak özellik matrisi denemeleri henüz bunları kapsamaz:

- Tek başına `--no-ignore` veya `hidden` dışındaki bir değerle
- `--type NAME`, `--type-not NAME`

### Yalnızca sarmalayıcıya özgü ekler

Sarmalayıcı, ast-grep'da bulunmayan birkaç yardımcı özellik sunar:

- `scan` ve `rewrite`, `run` için takma adlar
- `--hidden` bayrağı (ast-grep bunu `--no-ignore hidden` içine alır)
- `--dry-run` yeniden yazma önizleme takma adı
- `--interactive` yeniden yazma onay akışı

## Sınırlamalar

Greph'ın `sg` sarmalayıcısı, çoğu aracın ve ajanın kullandığı yapısal arama ve yeniden yazma kapsamını karşılar. Şu ast-grep özelliklerini şu anda sunmaz:

- YAML kural dosyaları (`--rule`, `--config`)
- PHP ötesinde çok dilli tarama
- Desen tabanlı olmayan dönüştürücüler (`--debug-query`, `--inspect`)
- LSP entegrasyonu

Eksik bir bayrakla karşılaşırsanız, üst kaynak `sg` ile çalıştırdığınız denemeyi ve beklenen çıktıyı içeren bir sorun bildirin.

## Davranış eşdeğerliği

Sarmalayıcı, bayt düzeyinde değil davranış düzeyinde eşdeğerliği hedefler. Çıktı anlamsal olarak eşdeğerdir, ancak görsel ayrıntılarda farklılık gösterebilir. [özellik matrisi](https://greph.inline0.dev/tr/docs/advanced/feature-matrix) için kullanılan denemeler, bayt dizisini değil ayrıştırmayla ilgili alanları (dosya yolu, satır numarası, yakalanan kod, yakalamalar, JSON biçimi) karşılaştırır.