# Benchmarkresultater

Repositoryet har et benchmarkværktøj under `bin/` og `benchmarks/`. Det måler alle søgetilstande mod virkelige datasæt (WordPress, Laravel) og genererede syntetiske datasæt, indsamler strukturerede rapporter og lader dig sammenligne to rapportserier.

Værktøjet er en del af repositoryet, ikke af pakken Composer: da 0.2.3, `benchmarks/` og scriptsene `bin/bench*` er udeladt af pakken, skal du køre dem fra en klon (`git clone https://github.com/inline0/greph && cd greph && composer install`).

De offentliggjorte tal i [README](https://github.com/inline0/greph#performance) stammer fra kørsler i GitHub Actions, aldrig fra lokale maskiner. Lokale kørsler er nyttige under udvikling; CI-kørslerne er den autoritative kilde.

## Datasæt

De syntetiske datasæt (`synthetic-1k`, `synthetic-10k`, `synthetic-100k-single`) genereres under `benchmarks/corpora/synthetic/` ved første kørsel. De virkelige datasæt er ikke inkluderet: placér en checkout under `benchmarks/corpora/wordpress` eller `benchmarks/corpora/laravel` (CI-workflowet kloner `WordPress/WordPress` med `--depth=1`). Et datasæt, hvis mappe mangler, springes over.

## Kør benchmarks

```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` sammenligner to seriesfiler (outputtet fra `bench-series` eller `bench-aggregate`) og udskriver en Markdown-opsummering, som er nyttig, når du arbejder på en kritisk kodevej. `bin/bench-ci` udløser Benchmark-workflowet på GitHub Actions via `gh` CLI.

## Kategorier

README offentliggør otte resultatgrupper, der hver måler et bestemt lag i motoren. Hver gruppe samler en eller flere af værktøjets kategorier, som er defineret i `benchmarks/suites/`.

### Scanningstilstand: tekst

Indbygget tekstsøgning efter bogstavelige mønstre, regex og kombinerede mønstre. Den offentliggjorte baseline køres på datasættet WordPress og omfatter:

- Bogstavelig `function`
- Bogstavelig, uden forskel på store og små bogstaver
- Bogstavelig søgning efter hele ord
- Ny regex-instans
- Kald med regex-array
- Regex med bogstaveligt præfiks
- Regex med bogstaveligt suffiks
- Regex med bogstavelig hel linje
- Sammenfoldning af bogstavelig regex

### Scanningstilstand: gennemgang

Kun filgennemgang, ingen søgning. Måler omkostningen ved gitignore-bevidst gennemgang isoleret set.

### Scanningstilstand: parallel tekst

Søgning efter den faste streng `function` med `1`, `2` og `4` job. For dette mønster starter worker-puljen kun ved mere end `jobs * 4_000` filer (se [Parallel Workers](https://greph.inline0.dev/da/docs/advanced/parallel)), hvilket er flere end i datasættet WordPress. Derfor køres alle tre offentliggjorte rækker i én proces, og de viser ikke skalering af puljen ([#8](https://github.com/inline0/greph/issues/8)).

### Scanningstilstand: AST

Indbygget AST-søgning efter repræsentative mønstre:

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

### Indekseret teksttilstand

Opvarmet indekseret tekstsøgning efter de samme mønstre som scanningstilstanden. Omfatter forespørgsler efter bogstavelig tekst, uden forskel på store og små bogstaver, hele ord, korte tokens og regex.

### Indekserede opsummeringsforespørgsler

Opvarmet indekseret tekstsøgning med output for antal, filer med match og filer uden match. Disse forespørgsler får størst fordel af postings-lageret, fordi arbejdet pr. fil er mindst.

### Indekseret / cachelagret AST

Opvarmet søgning i AST-fakta og cachelagret AST-søgning efter de samme mønstre som AST-scanningstilstanden.

### Buildomkostninger

Omkostninger ved kold opbygning af trigramindekset, AST-faktaindekset og AST-cachen. Nyttigt, når du skal vælge, hvilken tilstand der skal vedligeholdes til en given arbejdsbelastning.

## Sådan læser du de offentliggjorte tal

README offentliggør et øjebliksbillede af den seneste CI-kørsel for hver baseline. Hvert afsnit stammer fra en bestemt GitHub Actions-kørsel og er mærket med datasættet, runneren, versionen af PHP samt antal målinger og opvarmninger. Hvis du vil reproducere et tal, skal du bruge samme kombination lokalt.

Sammenligningskolonnerne (`rg`, `grep`, `sg`) indsamles i samme job, på samme runner og mod samme datasæt. De er ikke ekstrapoleret fra eksterne benchmarks.

## Sådan tilføjer du et benchmark

1. Tilføj en benchmarkdefinition under `benchmarks/`.
2. Tilføj et tilsvarende scenarie til regressionstesten, hvis der endnu ikke findes et tilsvarende (så den målte adfærd også verificeres).
3. Kør `./bin/bench --category <yours>` for at validere det nye benchmark.
4. Sammenlign med `main` via Benchmark-workflowet, som kører på pull requests, der berører `src/`, `benchmarks/` eller `bin/`, og viser en sammenligning mellem head og base i kørselsopsummeringen.
5. Opdatér tabellen README, når CI-kørslen med det nye benchmark er landet på `main`.

## Principper for ydeevne

Greph forsøger ikke at overgå ripgrep eller grep ved kolde scanninger. Ripgrep er implementeret i Rust med håndoptimeret SIMD-scanning af bogstavelige strenge, og i de offentliggjorte tal er både `rg` og GNU `grep` hurtigere end Greph ved hver kold tekstscanning. Målene er forskellige:

- Vær hurtig nok til, at interaktiv brug og agentforløb føles naturlige.
- Besvar gentagne forespørgsler fra opvarmede indekser: indekseret regex samt indekserede forespørgsler efter antal og fillister er hurtigere end både `rg` og `grep`, der scanner det samme træ.
- Overgå `ast-grep` ved indekserede og cachelagrede AST-arbejdsbelastninger, hvor Grephs varme caches undgår at parse træet igen. Kold AST-søgning varierer: `new $CLASS()` er hurtigere end `sg`, `array($$$ITEMS)` er langsommere.
- Gør hver ydeevneforbedring målbar og reproducerbar.

Ydeevnepåstande, der ikke understøttes af en benchmarkrapport, bliver ikke integreret.