# Matrika funkcij

Matrika funkcij je ustvarjeno poročilo, ki za vsako podprto zastavico in vedenje beleži, ali izvorno orodje in ovojnica Greph ustvarita enakovreden izhod. Je merodajni vir za vprašanja »Ali Greph to podpira?«.

Matrika se znova ustvari na podlagi dejanskih preizkusov ukazov v determinističnem navideznem delovnem prostoru. Surovi dokazi so v [`FEATURE_MATRIX.json`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json), upodobljena tabela pa v [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Legenda stanj

| Stanje | Pomen |
|---|---|
| `Pass` | Preizkus se je izvedel in ustrezal pričakovanemu vedenju |
| `Fail` | Preizkus se je izvedel, vendar ni ustrezal pričakovanemu vedenju |
| `Unavailable` | Ukaz ponudnika v tem okolju ni bil na voljo |

## Razdelki

Matrika je razdeljena na šest razdelkov:

1. **Površina združljivosti rg**: vsak preizkus se izvede tako z izvorno binarno datoteko `rg` kot z `bin/rg`. Obe orodji morata `Pass`, da je vrstica označena kot podprta.
2. **Površina združljivosti sg**: vsak preizkus se izvede tako z izvorno binarno datoteko `sg` kot z `bin/sg`. Obe orodji morata `Pass`, da je vrstica označena kot podprta.
3. **Površina samo ovojnice sg**: preizkusi, ki ciljajo samo na `bin/sg` (dodatne funkcije, ki jih izpostavlja ovojnica, ast-grep pa jih sam nima).
4. **Izvorna površina greph**: preizkusi, ki neposredno preverjajo `bin/greph`. Ni izvornega orodja za primerjavo; preizkusi preverjajo pričakovano vedenje v navideznem delovnem prostoru.
5. **Indeksirana površina greph**: preizkusi, ki preverjajo `bin/greph-index` (gradnjo, osveževanje in ogreto iskanje besedila).
6. **Površina indeksirane knjižnice AST**: preizkusi, ki kličejo PHP API (`Greph::buildAstIndex()`, `Greph::searchAstIndexed()`, `Greph::buildAstCache()`, `Greph::searchAstCached()`) ter preverjajo gradnjo, iskanje in osveževanje.

## Ponovno ustvarjanje matrike

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

Zaženite ga iz klona repozitorija z `rg` in `sg` v `PATH`; `bin/feature-matrix` ni del paketa Composer. Zgradi navidezni delovni prostor, izvede vsak preizkus združljivosti z izvorno binarno datoteko (če je nameščena) in ovojnico Greph, zabeleži strukturiran rezultat ter zapiše datoteki `FEATURE_MATRIX.json` in `FEATURE_MATRIX.md`. Z argumentom `--stdout` izpišite Markdown, ne da bi zapisali katero koli datoteko.

Zavezanih datotek ne ustvarja CI, temveč se ustvarijo ročno. Zbirka PHPUnit, ki jo zažene CI, vključuje preizkus, ki ustvari matriko z označenimi nedosegljivimi izvornimi orodji in preveri obliko poročila, zato posamezen preizkus, ki začne odpovedovati, ne povzroči neuspeha CI. Pred izdajo znova ustvarite matriko in preglejte razlike.

## Kaj sodi v matriko in kaj v dokumentacijo

Referenčni dokument CLI ter strani [Združljivost / rg](https://greph.inline0.dev/sl/docs/compatibility/rg) in [Združljivost / sg](https://greph.inline0.dev/sl/docs/compatibility/sg) opisujejo *predvideni* obseg. Matrika funkcij beleži *preverjeni* obseg, pri čemer so ob vsaki vrstici navedeni natančni argumenti preizkusa.

Če je nekaj dokumentirano, vendar manjka v matriki, je dokumentacija zastarela. Če je nekaj v matriki, vendar ni dokumentirano, je treba dokumentacijo dopolniti. Oboje se mora ujemati.

## Primeri vrstic

### Združljivost rg (izsek)

| Funkcija | rg | bin/rg | Opombe |
|---|---|---|---|
| Iskanje fiksnega niza | Uspešno | Uspešno | Preizkus: `-F needle single.txt` |
| Iskanje fiksnega niza brez razlikovanja med velikimi in malimi črkami | Uspešno | Uspešno | Preizkus: `-F -i needle single.txt` |
| Iskanje celih besed | Uspešno | Uspešno | Preizkus: `-F -w needle words.txt` |
| Filter glob | Uspešno | Uspešno | Preizkus: `--glob *.php function .` |
| Skrite datoteke | Uspešno | Uspešno | Preizkus: `--hidden -F secret .` |
| Strukturirani izhod JSON | Uspešno | Uspešno | Preizkus: `--json -F needle single.txt` z uporabo semantike dogodkov ripgrep JSON |

### Združljivost sg (izsek)

| Funkcija | sg | bin/sg | Opombe |
|---|---|---|---|
| Iskanje vzorca z `run --pattern` | Uspešno | Uspešno | Preizkus: `run --pattern array($$$ITEMS) src/App.php` |
| Prepis z `run --rewrite` | Uspešno | Uspešno | Preizkus: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| Izhod strukturiranega toka JSON | Uspešno | Uspešno | Preizkus: `run --json=stream --pattern dispatch($EVENT) src/App.php` |
| Prepis vseh pojavitev | Uspešno | Uspešno | Preizkus: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

Celotno tabelo najdete v [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Zakaj preverjanje s preizkusi

Ročno vzdrževana tabela združljivosti zastara. Bistvo ovojnic je, da jih »namestite namesto klicev `rg` ali `sg` in še naprej delujejo«, to obljubo pa lahko ohranimo samo tako, da dejansko zaženemo izvorno orodje in ovojnico drugo ob drugem ter primerjamo rezultate. Izvajalnik preizkusov naredi prav to vsakič, ko znova ustvarimo matriko.