# Kıyaslamalar

Depoda `bin/` ve `benchmarks/` altında bir kıyaslama düzeneği bulunur. Bu düzenek her arama modunu gerçek derlemler (WordPress, Laravel) ve oluşturulmuş yapay veri kümeleri üzerinde ölçer, yapılandırılmış raporlar alır ve iki rapor dizisini birbiriyle karşılaştırmanızı sağlar.

Düzenek, Composer paketinin değil deponun bir parçasıdır: 0.2.3, `benchmarks/` ve `bin/bench*` betikleri pakete dahil edilmediğinden, bunları bir klondan (`git clone https://github.com/inline0/greph && cd greph && composer install`) çalıştırın.

[README](https://github.com/inline0/greph#performance) içinde yayımlanan sayılar yerel makinelerden değil, GitHub Actions çalıştırmalarından alınır. Yerel çalıştırmalar denemeler için kullanışlıdır; doğru değerleri CI çalıştırmaları verir.

## Derlemler

Yapay derlemler (`synthetic-1k`, `synthetic-10k`, `synthetic-100k-single`) ilk çalıştırmada `benchmarks/corpora/synthetic/` altında oluşturulur. Gerçek derlemler dahil değildir: `benchmarks/corpora/wordpress` veya `benchmarks/corpora/laravel` konumuna bir depo kopyası yerleştirin (CI iş akışı, `--depth=1` kullanarak `WordPress/WordPress` deposunu klonlar). Dizini eksik olan derlem atlanır.

## Kıyaslamaları çalıştırma

```bash
# Full benchmark suite, every corpus that is present
./bin/bench

# Specific category (the category names used in benchmarks/suites/)
./bin/bench --category text
./bin/bench --category ast

# Compare against external tools when available
./bin/bench --compare rg,grep
./bin/bench --compare sg

# Choose a corpus
./bin/bench --corpus wordpress
./bin/bench --corpus laravel
./bin/bench --corpus synthetic-1k

# Write the run as JSON
./bin/bench --corpus wordpress --output build/run-1.json

# Measured series: 5 runs after 1 warmup run
./bin/bench-series --repeat 5 --warmup 1 --corpus wordpress --output build/head-series.json

# Aggregate separate runs into one series
./bin/bench-aggregate --output build/head-series.json build/run-*.json
```

`bin/bench-compare base-series.json head-series.json` iki dizi dosyasını (`bench-series` veya `bench-aggregate` çıktısını) karşılaştırır ve yoğun kullanılan bir kod yolunda denemeler yaparken faydalı olan bir Markdown özeti yazdırır. `bin/bench-ci`, `gh` CLI aracılığıyla GitHub Actions üzerinde Kıyaslama iş akışını başlatır.

## Kategoriler

README, her biri motorun belirli bir katmanını ölçen sekiz sonuç grubu yayımlar. Her grupta `benchmarks/suites/` içinde tanımlanan bir veya daha fazla düzenek kategorisi yer alır.

### Tarama Modu: Metin

Düz metin, regex ve birleşik desenlerde yerel metin araması. Yayımlanan temel ölçüm WordPress derlemi üzerinde çalışır ve şunları içerir:

- Düz metin: `function`
- Büyük/küçük harfe duyarsız düz metin
- Tam sözcük düz metni
- Yeni örnekle regex
- Dizi çağrısıyla regex
- Önek düz metniyle regex
- Sonek düz metniyle regex
- Tam satır düz metniyle regex
- Düz metin daraltmalı regex

### Tarama Modu: Gezinme

Arama yapmadan yalnızca dosyaları gezme. gitignore uyumlu gezginin kendi maliyetini ölçer.

### Tarama Modu: Paralel Metin

`function` için `1`, `2` ve `4` işli sabit dize araması. Bu desen için işçi havuzu yalnızca `jobs * 4_000` dosyayı aşınca başlar (bkz. [Paralel İşçiler](https://greph.inline0.dev/tr/docs/advanced/parallel)); WordPress derleminde bu sayıdan az dosya olduğundan, yayımlanan üç satırın tümü tek süreçte çalışır ve havuzun ölçeklenmesini göstermez ([#8](https://github.com/inline0/greph/issues/8)).

### Tarama Modu: AST

Temsili desenlerde yerel AST araması:

- `new $CLASS()`
- `array($$$ITEMS)`

### Dizinli Metin Modu

Tarama modundaki desenlerle aynı desenleri kullanan, ısıtılmış dizinli metin araması. Düz metin, büyük/küçük harfe duyarsız, tam sözcük, kısa belirteç ve regex sorgularını içerir.

### Dizinli Özet Sorguları

Eşleşme sayısı, eşleşme içeren dosyalar ve eşleşme içermeyen dosyalar çıktıları kullanan ısıtılmış dizinli metin araması. Dosya başına yapılan işlem en ucuz olduğundan, bunlar en çok gönderim deposundan yararlanır.

### Dizinli / Önbelleğe Alınmış AST

AST tarama modundaki desenlerle aynı desenleri kullanan, ısıtılmış AST olgusu araması ve önbelleğe alınmış AST araması.

### Derleme Maliyetleri

Trigram dizininin, AST olgu dizininin ve AST önbelleğinin soğuk derleme maliyetleri. Belirli bir iş yükü için hangi modu sürdüreceğinize karar verirken kullanışlıdır.

## Yayımlanan sayıları okuma

README, her temel ölçüm için en güncel CI çalıştırmasının anlık görüntüsünü yayımlar. Her bölüm belirli bir GitHub Actions çalıştırmasından alınır; derlem, çalıştırıcı, PHP sürümü, ölçülen çalıştırma ve ısınma sayılarıyla etiketlenir. Bir sayıyı yeniden üretmeniz gerekirse yerel olarak aynı bileşimi kullanın.

Karşılaştırma sütunları (`rg`, `grep`, `sg`) aynı işte, aynı çalıştırıcıda ve aynı derlem üzerinde toplanır. Harici kıyaslamalardan tahmin edilmez.

## Kıyaslama ekleme

1. `benchmarks/` altında bir kıyaslama tanımı ekleyin.
2. Henüz eşdeğeri yoksa gerileme test paketine karşılık gelen bir senaryo ekleyin (ölçülen davranışın da doğrulanması için).
3. Yeni kıyaslamayı doğrulamak için `./bin/bench --category <yours>` çalıştırın.
4. `src/`, `benchmarks/` veya `bin/` dosyalarına dokunan çekme isteklerinde çalışan Kıyaslama iş akışıyla `main` karşılaştırın ve çalıştırma özetinde son değişiklik ile temel sürümün karşılaştırmasını yayımlayın.
5. Yeni kıyaslamayı içeren CI çalıştırması `main` üzerinde tamamlandığında README tablosunu güncelleyin.

## Performans yaklaşımı

Greph, soğuk taramalarda ripgrep veya grep'ten daha hızlı olmayı hedeflemiyor. Ripgrep, elle ayarlanmış SIMD düz metin taramasıyla Rust içinde uygulanır ve yayımlanan sayılara göre her soğuk metin taramasında hem `rg` hem de GNU `grep`, Greph'den daha hızlıdır. Hedefler farklıdır:

- Etkileşimli kullanımın ve ajan döngülerinin yerelmiş gibi hissettirmesi için yeterince hızlı olmak.
- Isıtılmış dizinlerde tekrarlanan sorguları yanıtlamak: dizinli regex, dizinli sayım ve dosya listesi sorguları, aynı ağacı tarayan hem `rg` hem de `grep` işleminden daha hızlıdır.
- Dizinli ve önbelleğe alınmış AST iş yüklerinde `ast-grep`'yi geçmek; bu iş yüklerinde Greph'ün ısıtılmış önbellekleri ağacı yeniden ayrıştırmayı önler. Soğuk AST araması değişken sonuç verir: `new $CLASS()`, `sg`'ten hızlıdır; `array($$$ITEMS)` ise yavaştır.
- Her performans iyileştirmesini ölçülebilir ve tekrarlanabilir kılmak.

Bir kıyaslama raporuyla desteklenmeyen performans iddiaları kabul edilmez.