# Primerjalni preizkusi

V repozitoriju je orodje za primerjalne preizkuse v imenikih `bin/` in `benchmarks/`. Meri vsak način iskanja na resničnih korpusih (WordPress, Laravel) in ustvarjenih sintetičnih naborih podatkov, zajema strukturirana poročila ter omogoča primerjavo dveh serij poročil.

Orodje je del repozitorija, ne paketa Composer: ker so 0.2.3, `benchmarks/` in skripti `bin/bench*` izključeni iz paketa, jih zaženite iz klona (`git clone https://github.com/inline0/greph && cd greph && composer install`).

Objavljene številke v [README](https://github.com/inline0/greph#performance) temeljijo na zagonih GitHub Actions, nikoli na lokalnih računalnikih. Lokalni zagoni so uporabni pri iteriranju; merodajni so zagoni CI.

## Korpusi

Sintetični korpusi (`synthetic-1k`, `synthetic-10k`, `synthetic-100k-single`) se ob prvem zagonu ustvarijo v `benchmarks/corpora/synthetic/`. Resnični korpusi niso vključeni: kopijo repozitorija namestite v `benchmarks/corpora/wordpress` ali `benchmarks/corpora/laravel` (potek dela CI klonira `WordPress/WordPress` z `--depth=1`). Korpus, katerega imenik manjka, se preskoči.

## Zagon primerjalnih preizkusov

```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` primerja dve datoteki serij (izhod ukaza `bench-series` ali `bench-aggregate`) in izpiše povzetek Markdown, uporaben pri iteriranju na kritični poti. `bin/bench-ci` sproži potek dela Benchmark v GitHub Actions prek `gh` CLI.

## Kategorije

README objavlja osem skupin rezultatov, od katerih vsaka meri določeno plast pogona. Vsaka skupina združuje eno ali več kategorij orodja, določenih v `benchmarks/suites/`.

### Način pregledovanja: besedilo

Izvorno iskanje besedila z dobesednimi vzorci, vzorci regex in kombiniranimi vzorci. Objavljena osnovna meritev se izvaja na korpusu WordPress in vključuje:

- Dobesedni `function`
- Iskanje dobesednega niza brez razlikovanja med velikimi in malimi črkami
- Iskanje celih besed
- Regex z novo instanco
- Klic z naborom regexov
- Dobesedni predponski regex
- Dobesedni priponski regex
- Dobesedni regex za natančno ujemanje vrstice
- Združevanje dobesednih regexov

### Način pregledovanja: prehod

Samo sprehod po datotekah, brez iskanja. Meri strošek sprehajalnika, ki upošteva gitignore.

### Način pregledovanja: vzporedno besedilo

Iskanje fiksnega niza `function` z `1`, `2` in `4` opravili. Za ta vzorec se skupina delavcev zažene šele nad `jobs * 4_000` datotekami (glejte [Vzporedni delavci](https://greph.inline0.dev/sl/docs/advanced/parallel)), kar je več, kot jih vsebuje korpus WordPress, zato se vse tri objavljene vrstice izvajajo v enem procesu in ne prikazujejo skaliranja skupine ([#8](https://github.com/inline0/greph/issues/8)).

### Način pregledovanja: AST

Izvorno iskanje AST na reprezentativnih vzorcih:

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

### Indeksirani način besedila

Iskanje po ogretem besedilnem indeksu z enakimi vzorci kot pri načinu pregledovanja. Vključuje poizvedbe za dobesedne nize, brez razlikovanja med velikimi in malimi črkami, za cele besede, kratke žetone in regex.

### Indeksirane povzetne poizvedbe

Iskanje po ogretem besedilnem indeksu z izhodi za štetje, datoteke z zadetki in datoteke brez zadetkov. Te poizvedbe imajo največ koristi od shrambe objav, saj je delo na posamezni datoteki najmanj zahtevno.

### Indeksirani / predpomnjeni AST

Iskanje po dejstvih AST in iskanje po predpomnjenem AST z enakimi vzorci kot pri načinu pregledovanja AST.

### Stroški gradnje

Stroški hladne gradnje indeksa trigramov, indeksa dejstev AST in predpomnilnika AST. Uporabno pri odločanju, kateri način vzdrževati za določeno delovno obremenitev.

## Branje objavljenih številk

README objavi posnetek najnovejšega zagona CI za vsako osnovno meritev. Vsak razdelek temelji na določenem zagonu GitHub Actions in je označen s korpusom, izvajalnikom, različico PHP ter številom meritev in ogrevalnih zagonov. Če želite ponoviti meritev, uporabite enako kombinacijo lokalno.

Primerjalni stolpci (`rg`, `grep`, `sg`) so zbrani v istem opravilu, na istem izvajalniku in na istem korpusu. Niso ekstrapolirani iz zunanjih primerjalnih preizkusov.

## Kako dodati primerjalni preizkus

1. Dodajte definicijo primerjalnega preizkusa v `benchmarks/`.
2. Če še ni enakovrednega scenarija, dodajte ustrezen scenarij v zbirko regresijskih preizkusov (tako preverite tudi merjeno vedenje).
3. Zaženite `./bin/bench --category <yours>`, da preverite nov primerjalni preizkus.
4. Primerjajte z `main` prek poteka dela Benchmark, ki se zažene pri zahtevah za združitev, ki spreminjajo `src/`, `benchmarks/` ali `bin/`, ter v povzetek zagona objavi primerjavo trenutne in osnovne različice.
5. Posodobite tabelo README, ko je zagon CI, ki vključuje nov primerjalni preizkus, združen v `main`.

## Filozofija zmogljivosti

Greph ne poskuša prehiteti ripgrep ali grepa pri hladnih pregledovanjih. Ripgrep je implementiran v Rust z ročno prilagojenim iskanjem dobesednih nizov SIMD; v objavljenih meritvah sta tako `rg` kot GNU `grep` hitrejša od Greph pri vsakem hladnem iskanju besedila. Cilji so drugačni:

- Biti dovolj hiter, da sta interaktivna uporaba in zanke agentov odzivni kot domača aplikacija.
- Ponavljajoče se poizvedbe odgovarjati iz ogretih indeksov: indeksirani regex ter indeksirane poizvedbe za štetje in seznam datotek so hitrejši od pregledovanja istega drevesa z `rg` in `grep`.
- Prehiteti `ast-grep` pri obremenitvah z indeksiranim in predpomnjenim AST, kjer ogreti predpomnilniki Greph preprečijo ponovno razčlenjevanje drevesa. Pri hladnem iskanju AST so rezultati mešani: `new $CLASS()` je hitrejši od `sg`, `array($$$ITEMS)` pa počasnejši.
- Poskrbeti, da je vsako izboljšanje zmogljivosti merljivo in ponovljivo.

Trditve o zmogljivosti, ki niso podprte s poročilom primerjalnih preizkusov, niso vključene.