# Võrdlustestid

Andmehoidlas on võrdlustestide raamistik asukohtades `bin/` ja `benchmarks/`. See mõõdab iga otsingurežiimi pärisandmestike (WordPress, Laravel) ja genereeritud sünteetiliste andmestike põhjal, salvestab struktureeritud aruandeid ning võimaldab võrrelda kaht aruannete seeriat.

Raamistik kuulub andmehoidlasse, mitte Composer paketti: kuna 0.2.3, `benchmarks/` ja `bin/bench*` skriptid ei kuulu paketti, käivitage need kloonitud andmehoidlast (`git clone https://github.com/inline0/greph && cd greph && composer install`).

[README](https://github.com/inline0/greph#performance) avaldatud tulemused pärinevad GitHub Actions käivitustest, mitte kunagi kohalikest arvutitest. Kohalikud käivitused sobivad arendamiseks; tõeallikaks on CI käivitused.

## Andmestikud

Sünteetilised andmestikud (`synthetic-1k`, `synthetic-10k`, `synthetic-100k-single`) genereeritakse esimesel käivitamisel kataloogi `benchmarks/corpora/synthetic/`. Pärisandmestikud ei kuulu komplekti: paigutage koopia asukohta `benchmarks/corpora/wordpress` või `benchmarks/corpora/laravel` (CI töövoog kloonib `WordPress/WordPress` käsuga `--depth=1`). Puuduva kataloogiga andmestik jäetakse vahele.

## Võrdlustestide käivitamine

```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` võrdleb kaht seeriafaili (`bench-series` või `bench-aggregate` väljundit) ja prindib Markdown kokkuvõtte, mis on kasulik jõudluskriitilise kooditee täiustamisel. `bin/bench-ci` käivitab Benchmarki töövoo harus GitHub Actions käsu `gh` CLI kaudu.

## Kategooriad

README avaldab kaheksa tulemusrühma, millest igaüks mõõdab mootori kindlat kihti. Iga rühm koondab ühe või mitu raamistikus `benchmarks/suites/` määratletud kategooriat.

### Skannimisrežiim: tekst

Algupärane tekstiotsing literaalsete, regulaaravaldiste ja kombineeritud mustritega. Avaldatud baastest käivitatakse andmestikuga WordPress ja sisaldab järgmist:

- Literaalne `function`
- Literaalne, tõstutundetu
- Literaalne terve sõna
- Regulaaravaldis, uus eksemplar
- Regulaaravaldise massiivikutse
- Regulaaravaldise eesliite literaal
- Regulaaravaldise järelliite literaal
- Regulaaravaldise täpse rea literaal
- Regulaaravaldise literaali kokkuliitmine

### Skannimisrežiim: läbimine

Ainult failide läbimine, otsingut ei tehta. Mõõdab eraldi gitignore'i arvestava läbija kulu.

### Skannimisrežiim: paralleelne tekst

Fikseeritud stringi otsing väärtusele `function` tööde arvuga `1`, `2` ja `4`. Selle mustri puhul käivitub töötajate kogum alles üle `jobs * 4_000` faili korral (vt [Paralleelsed töötajad](https://greph.inline0.dev/et/docs/advanced/parallel)), mida andmestikus WordPress on rohkem, seega toimuvad kõik kolm avaldatud mõõtmist ühe protsessina ega näita kogumi skaleerumist ([#8](https://github.com/inline0/greph/issues/8)).

### Skannimisrežiim: AST

Algupärane AST-otsing tüüpiliste mustritega:

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

### Indekseeritud tekstirežiim

Soojendatud indeksi tekstiotsing samade mustritega mis skannimisrežiimis. Sisaldab literaal-, tõstutundetuid, terve sõna, lühikese märgijada ja regulaaravaldise päringuid.

### Indekseeritud kokkuvõttepäringud

Soojendatud indeksi tekstiotsing, mille väljundid on vastete arv, vastetega failid ja vasteteta failid. Need kasutavad postituste hoidlat kõige rohkem, sest failipõhine töö on kõige väiksem.

### Indekseeritud / vahemällu salvestatud AST

Soojendatud AST faktide otsing ja vahemällu salvestatud AST otsing samade mustritega mis AST skannimisrežiimis.

### Järgu kulud

Trigrammiindeksi, AST faktide indeksi ja AST vahemälu külmkäivituse kulud. Kasulik, kui otsustate, millist režiimi konkreetse töökoormuse jaoks hooldada.

## Avaldatud tulemuste lugemine

README avaldab iga baastesti kohta uusima CI käivituse hetkeseisu. Iga jaotis põhineb konkreetsel GitHub Actions käivitusel ning on märgitud andmestiku, käivitaja, PHP versiooni ning mõõdetud käivituste ja soojenduste arvuga. Tulemuse kordamiseks kasutage kohalikul käivitamisel sama kombinatsiooni.

Võrdlusveerud (`rg`, `grep`, `sg`) kogutakse samas töös, samal käivitajal ja sama andmestikuga. Need ei põhine välistest võrdlustestidest tuletatud hinnangutel.

## Võrdlustesti lisamine

1. Lisage võrdlustesti määratlus asukohta `benchmarks/`.
2. Lisage regressioonitestide komplekti vastav stsenaarium, kui samaväärset veel pole (nii kontrollitakse ka mõõdetavat käitumist).
3. Käivitage `./bin/bench --category <yours>` uue võrdlustesti valideerimiseks.
4. Võrrelge tulemust käsuga `main` Benchmarki töövoos, mis käivitub tõmbetaotlustel, mis puudutavad asukohti `src/`, `benchmarks/` või `bin/`, ning lisab käivituse kokkuvõttesse võrdluse uuema ja algse versiooni vahel.
5. Uuendage tabelit README pärast seda, kui uue võrdlustesti sisaldav CI käivitus on harus `main` lõpule jõudnud.

## Jõudluse põhimõtted

Greph ei püüa külmkäivituse skannimisel ripgrep või grepiga kiiruses võistelda. Ripgrep on rakendatud keeles Rust käsitsi häälestatud SIMD-literaaliotsinguga ning avaldatud tulemuste järgi on iga külma tekstiotsingu puhul nii `rg` kui ka GNU `grep` kiirem kui Greph. Eesmärgid on teistsugused:

- Olla piisavalt kiire, et interaktiivne kasutus ja agenditsüklid tunduksid loomulikud.
- Vastata korduvatele päringutele soojendatud indeksite abil: indekseeritud regulaaravaldiste, arvu ja faililoendi päringud on kiiremad kui sama puu skannimine nii `rg` kui ka `grep` abil.
- Edestada `ast-grep` indekseeritud ja vahemällu salvestatud AST töökoormustes, kus Greph soojad vahemälud väldivad puu kordusparsimist. Külma AST otsingu tulemused on segased: `new $CLASS()` on kiirem kui `sg`, `array($$$ITEMS)` on aeglasem.
- Muuta iga jõudluse parandus mõõdetavaks ja korratavaks.

Jõudlusväited, mida võrdlustesti aruanne ei toeta, jäävad ühendamata.