# Funktsioonide maatriks

Funktsioonide maatriks on genereeritud aruanne, mis näitab iga toetatud lipu ja käitumise kohta, kas algupärane tööriist ja Greph ümbris annavad samaväärse väljundi. See on tõeallikas küsimustele „kas Greph seda toetab?”.

Maatriks luuakse uuesti tegelike käskude proovide põhjal, kasutades deterministlikku testtööruumi. Algandmed asuvad failis [`FEATURE_MATRIX.json`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json) ning vormindatud tabel failis [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Oleku tähendused

| Olek | Tähendus |
|---|---|
| `Pass` | Proov käivitati ja tulemus vastas oodatud käitumisele |
| `Fail` | Proov käivitati, kuid tulemus ei vastanud oodatud käitumisele |
| `Unavailable` | Pakkuja käsk polnud selles keskkonnas saadaval |

## Jaotised

Maatriks koosneb kuuest jaotisest:

1. **rg ühilduvusliides**: iga proovi käitatakse nii ülesvoolu `rg` binaarfaili kui ka `bin/rg` vastu. Rea märkimiseks toetatuks peavad mõlemad `Pass`.
2. **sg ühilduvusliides**: iga proovi käitatakse nii ülesvoolu `sg` binaarfaili kui ka `bin/sg` vastu. Rea märkimiseks toetatuks peavad mõlemad `Pass`.
3. **Ainult sg ümbrise liides**: proovid, mis sihivad üksnes `bin/sg` (lisafunktsioonid, mida ümbris pakub, kuid ast-grep ise mitte).
4. **Algupärane greph-liides**: proovid, mis kasutavad otseselt `bin/greph`. Võrdlemiseks puudub ülesvoolu tööriist; proovid kontrollivad oodatud käitumist testtööruumis.
5. **Indekseeritud greph-liides**: proovid, mis kasutavad `bin/greph-index` (indeksi loomine ja värskendamine ning soojendatud tekstiotsing).
6. **Indekseeritud AST-teegi liides**: proovid, mis kutsuvad PHP API (`Greph::buildAstIndex()`, `Greph::searchAstIndexed()`, `Greph::buildAstCache()`, `Greph::searchAstCached()`) ning kontrollivad loomist, otsingut ja värskendamist.

## Maatriksi uuesti loomine

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

Käivitage see andmehoidla kloonist, kus `rg` ja `sg` on `PATH`-s; `bin/feature-matrix` ei kuulu Composer paketti. See loob testtööruumi, käivitab iga ühilduvusproovi ülesvoolu binaarfaili vastu (kui see on paigaldatud) ja Greph ümbrisega, salvestab struktureeritud tulemuse ning kirjutab nii `FEATURE_MATRIX.json` kui ka `FEATURE_MATRIX.md`. Lisage `--stdout`, et kuvada Markdown ilma faile kirjutamata.

Versioonihaldusse lisatud failid luuakse uuesti käsitsi; CI seda ei tee. CI-s käivitatav PHPUnit komplekt sisaldab testi, mis loob maatriksi, märkides ülesvoolu tööriistad kättesaamatuks, ja kontrollib aruande struktuuri. Seetõttu ei põhjusta ühe proovi nurjumine CI nurjumist. Enne väljalaset looge maatriks uuesti ja vaadake muudatused üle.

## Maatriksi ja dokumentatsiooni sisu

CLI viitedokument ja lehed [Ühilduvus / rg](https://greph.inline0.dev/et/docs/compatibility/rg) ning [Ühilduvus / sg](https://greph.inline0.dev/et/docs/compatibility/sg) kirjeldavad *kavandatud* liidest. Funktsioonide maatriks näitab *kontrollitud* liidest ning iga rea juures on toodud täpsed proovikäsu argumendid.

Kui midagi on dokumenteeritud, kuid maatriksist puudu, on dokumentatsioon aegunud. Kui midagi on maatriksis, kuid dokumenteerimata, tuleb see dokumentatsiooni lisada. Mõlemad peavad kattuma.

## Näidisread

### rg ühilduvus (väljavõte)

| Funktsioon | rg | bin/rg | Märkused |
|---|---|---|---|
| Fikseeritud stringi otsing | Läbitud | Läbitud | Proov: `-F needle single.txt` |
| Tõstutundetu fikseeritud stringi otsing | Läbitud | Läbitud | Proov: `-F -i needle single.txt` |
| Terve sõna otsing | Läbitud | Läbitud | Proov: `-F -w needle words.txt` |
| Glob-filtr | Läbitud | Läbitud | Proov: `--glob *.php function .` |
| Peidetud failid | Läbitud | Läbitud | Proov: `--hidden -F secret .` |
| Struktureeritud JSON väljund | Läbitud | Läbitud | Proov: `--json -F needle single.txt`, kasutab sündmuse ripgrep semantikat JSON |

### sg ühilduvus (väljavõte)

| Funktsioon | sg | bin/sg | Märkused |
|---|---|---|---|
| Mustriotsing, kasutades `run --pattern` | Läbitud | Läbitud | Proov: `run --pattern array($$$ITEMS) src/App.php` |
| Ümberkirjutamine `run --rewrite` abil | Läbitud | Läbitud | Proov: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| Struktureeritud JSON voo väljund | Läbitud | Läbitud | Proov: `run --json=stream --pattern dispatch($EVENT) src/App.php` |
| Kõigi vastete ümberkirjutamine | Läbitud | Läbitud | Proov: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

Kogu tabelit vaadake jaotises [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Miks proovid juhivad

Käsitsi hallatav ühilduvustabel vananeb. Ümbriste mõte on „asenda tööriistaga, mida kasutasid varem käsku `rg` või `sg` käivitama, ja kõik töötab edasi”. Selle lubaduse täitmiseks tuleb ülesvoolu tööriista ja ümbrist kõrvuti päriselt käivitada ning tulemusi võrrelda. Proovikäivitaja teeb just seda iga kord, kui maatriks uuesti luuakse.