# Funktionsmatrix

Funktionsmatrixen er en genereret rapport, der for hvert understøttet flag og hver adfærd registrerer, om det indbyggede værktøj og wrapperen Greph giver tilsvarende output. Den er autoritativ kilde til svar på spørgsmål som »understøtter Greph dette?«.

Matrixen gendannes ud fra reelle kommandoprober mod et deterministisk fixture-arbejdsområde. De rå data findes i [`FEATURE_MATRIX.json`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json), og den gengivne tabel findes i [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Statusforklaring

| Status | Betydning |
|---|---|
| `Pass` | Proben blev kørt og svarede til den forventede adfærd |
| `Fail` | Proben blev kørt, men opfyldte ikke den forventede adfærd |
| `Unavailable` | Udbyderkommandoen findes ikke i dette miljø |

## Afsnit

Matrixen er organiseret i seks afsnit:

1. **rg-kompatibilitetsflade**: hver probe køres mod både den oprindelige `rg`-binærfil og `bin/rg`. Begge skal `Pass`, før rækken markeres som understøttet.
2. **sg-kompatibilitetsflade**: hver probe køres mod både den oprindelige `sg`-binærfil og `bin/sg`. Begge skal `Pass`, før rækken markeres som understøttet.
3. **Kun sg-wrapperflade**: prober, der kun retter sig mod `bin/sg` (ekstra funktioner, som wrapperen stiller til rådighed, og som ast-grep ikke selv har).
4. **Indbygget greph-flade**: prober, der tester `bin/greph` direkte. Der findes intet oprindeligt værktøj at sammenligne med; proberne kontrollerer den forventede adfærd i fixture-arbejdsområdet.
5. **Indekseret greph-flade**: prober, der tester `bin/greph-index` (opbygning, opdatering og opvarmet tekstsøgning).
6. **Indekseret AST-biblioteksflade**: prober, der kalder PHP API (`Greph::buildAstIndex()`, `Greph::searchAstIndexed()`, `Greph::buildAstCache()`, `Greph::searchAstCached()`) og kontrollerer opbygning, søgning og opdatering.

## Gendan matrixen

```bash
php bin/feature-matrix
```

Kør det fra en klon af repositoryet med `rg` og `sg` på `PATH`; `bin/feature-matrix` er ikke en del af pakken Composer. Det opbygger fixture-arbejdsområdet, kører hver kompatibilitetsprobe mod den oprindelige binærfil (hvis den er installeret) og wrapperen Greph, registrerer det strukturerede resultat og skriver både `FEATURE_MATRIX.json` og `FEATURE_MATRIX.md`. Angiv `--stdout` for at udskrive Markdown uden at skrive nogen af filerne.

De indcheckede filer gendannes manuelt; CI gendanner dem ikke. PHPUnit-pakken, som CI kører, indeholder en test, der genererer matrixen med de oprindelige værktøjer markeret som utilgængelige og kontrollerer rapportens struktur, så en enkelt probe, der begynder at fejle, ikke får CI til at fejle. Gendan matrixen, og gennemgå diffen før en udgivelse.

## Hvad hører til i matrixen og i dokumentationen

CLI-referencen og siderne [Kompatibilitet / rg](https://greph.inline0.dev/da/docs/compatibility/rg) og [Kompatibilitet / sg](https://greph.inline0.dev/da/docs/compatibility/sg) beskriver den *tilsigtede* flade. Funktionsmatrixen registrerer den *verificerede* flade med de præcise probe-argumenter ved hver række.

Hvis noget er dokumenteret, men mangler i matrixen, er dokumentationen forældet. Hvis noget står i matrixen, men ikke er dokumenteret, skal dokumentationen opdateres. De to skal stemme overens.

## Eksempelrækker

### rg-kompatibilitet (uddrag)

| Funktion | rg | bin/rg | Noter |
|---|---|---|---|
| Søgning efter fast streng | Bestået | Bestået | Probe: `-F needle single.txt` |
| Søgning efter fast streng uden forskel på store og små bogstaver | Bestået | Bestået | Probe: `-F -i needle single.txt` |
| Søgning efter hele ord | Bestået | Bestået | Probe: `-F -w needle words.txt` |
| Glob-filter | Bestået | Bestået | Probe: `--glob *.php function .` |
| Skjulte filer | Bestået | Bestået | Probe: `--hidden -F secret .` |
| Struktureret JSON-output | Bestået | Bestået | Probe: `--json -F needle single.txt` med semantik for ripgrep-hændelser i JSON |

### sg-kompatibilitet (uddrag)

| Funktion | sg | bin/sg | Noter |
|---|---|---|---|
| Mønstersøgning med `run --pattern` | Bestået | Bestået | Probe: `run --pattern array($$$ITEMS) src/App.php` |
| Omskrivning via `run --rewrite` | Bestået | Bestået | Probe: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| Struktureret JSON-streamoutput | Bestået | Bestået | Probe: `run --json=stream --pattern dispatch($EVENT) src/App.php` |
| Omskrivning af alle | Bestået | Bestået | Probe: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

Se hele tabellen her: [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Hvorfor probe-baseret

En kompatibilitetstabel, der vedligeholdes manuelt, bliver forældet. Hele formålet med wrapperne er, at du kan »sætte dem ind dér, hvor du tidligere kaldte `rg` eller `sg`, og så virker de stadig«. Den eneste måde at leve op til det løfte på er faktisk at køre det oprindelige værktøj og wrapperen side om side og sammenligne resultaterne. Probe-runneren gør netop det, hver gang matrixen gendannes.