# Matica funkcií

Matica funkcií je generovaná správa, ktorá pre každý podporovaný príznak a správanie zaznamenáva, či natívny nástroj a obal Greph poskytujú rovnocenný výstup. Je zdrojom pravdivých informácií pri otázkach typu „Podporuje Greph túto funkciu?“.

Matica sa znovu generuje pomocou skutočných príkazov testovaných v deterministickom pracovnom priestore s pripravenými súbormi. Nespracované dôkazy sú v [`FEATURE_MATRIX.json`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json) a vykreslená tabuľka je v [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Legenda stavov

| Stav | Význam |
|---|---|
| `Pass` | Testovacia sonda sa spustila a výsledok zodpovedal očakávanému správaniu |
| `Fail` | Testovacia sonda sa spustila, ale výsledok nezodpovedal očakávanému správaniu |
| `Unavailable` | Príkaz poskytovateľa v tomto prostredí nebol dostupný |

## Sekcie

Matica je rozdelená do šiestich sekcií:

1. **Kompatibilita rg**: každá sonda sa spúšťa s binárnym súborom upstream `rg` aj s `bin/rg`. Aby bol riadok označený ako podporovaný, oba musia `Pass`.
2. **Kompatibilita sg**: každá sonda sa spúšťa s binárnym súborom upstream `sg` aj s `bin/sg`. Aby bol riadok označený ako podporovaný, oba musia `Pass`.
3. **Funkcie dostupné iba v obale sg**: sondy zamerané iba na `bin/sg` (doplnkové funkcie sprístupnené obalom, ktoré samotný ast-grep nemá).
4. **Natívne rozhranie greph**: sondy, ktoré priamo testujú `bin/greph`. Neexistuje upstream nástroj na porovnanie; sondy overujú očakávané správanie v pracovnom priestore s pripravenými súbormi.
5. **Indexované rozhranie greph**: sondy, ktoré testujú `bin/greph-index` (zostavenie, obnovenie a vyhľadávanie textu v zahriatom indexe).
6. **Knižnica indexovaného AST**: sondy, ktoré volajú PHP API (`Greph::buildAstIndex()`, `Greph::searchAstIndexed()`, `Greph::buildAstCache()`, `Greph::searchAstCached()`) a overujú zostavenie, vyhľadávanie a obnovenie.

## Opätovné vytvorenie matice

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

Spustite ju z klonu repozitára s `rg` a `sg` v `PATH`; `bin/feature-matrix` nie je súčasťou balíka Composer. Zostaví pracovný priestor s pripravenými súbormi, spustí každú sondu kompatibility s binárnym súborom upstream (ak je nainštalovaný) aj s obalom Greph, zaznamená štruktúrovaný výsledok a zapíše súbory `FEATURE_MATRIX.json` aj `FEATURE_MATRIX.md`. Ak chcete výsledok Markdown iba vypísať bez zápisu do súborov, zadajte `--stdout`.

Potvrdené súbory sa obnovujú ručne; CI ich negeneruje. Súprava testov PHPUnit, ktorú spúšťa CI, obsahuje test generujúci maticu s nástrojmi upstream označenými ako nedostupné a overujúci štruktúru správy. Jedna zlyhávajúca sonda preto nespôsobí zlyhanie CI. Pred vydaním obnovte maticu a skontrolujte rozdiely.

## Čo patrí do matice a čo do dokumentácie

Referencia CLI a stránky [Kompatibilita / rg](https://greph.inline0.dev/sk/docs/compatibility/rg) a [Kompatibilita / sg](https://greph.inline0.dev/sk/docs/compatibility/sg) opisujú *zamýšľaný* rozsah funkcií. Matica funkcií zaznamenáva *overený* rozsah a pri každom riadku uvádza presné argumenty sondy.

Ak je niečo zdokumentované, ale chýba to v matici, dokumentácia je zastaraná. Ak je niečo v matici, ale nie v dokumentácii, treba dokumentáciu doplniť. Obe musia byť v súlade.

## Príkladové riadky

### Kompatibilita rg (ukážka)

| Funkcia | rg | bin/rg | Poznámky |
|---|---|---|---|
| Vyhľadávanie pevného reťazca | Úspešné | Úspešné | Sonda: `-F needle single.txt` |
| Vyhľadávanie pevného reťazca bez rozlišovania veľkosti písmen | Úspešné | Úspešné | Sonda: `-F -i needle single.txt` |
| Vyhľadávanie celých slov | Úspešné | Úspešné | Sonda: `-F -w needle words.txt` |
| Filter Glob | Úspešné | Úspešné | Sonda: `--glob *.php function .` |
| Skryté súbory | Úspešné | Úspešné | Sonda: `--hidden -F secret .` |
| Štruktúrovaný výstup JSON | Úspešné | Úspešné | Sonda: `--json -F needle single.txt` s použitím sémantiky udalostí ripgrep JSON |

### Kompatibilita sg (ukážka)

| Funkcia | sg | bin/sg | Poznámky |
|---|---|---|---|
| Vyhľadávanie vzorov pomocou `run --pattern` | Úspešné | Úspešné | Sonda: `run --pattern array($$$ITEMS) src/App.php` |
| Prepísanie pomocou `run --rewrite` | Úspešné | Úspešné | Sonda: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| Štruktúrovaný výstup streamu JSON | Úspešné | Úspešné | Sonda: `run --json=stream --pattern dispatch($EVENT) src/App.php` |
| Prepísanie všetkého | Úspešné | Úspešné | Sonda: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

Úplnú tabuľku nájdete v [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Prečo testovať sondami

Ručne udržiavaná tabuľka kompatibility zastaráva. Zmyslom obalov je „nahradiť nimi volania `rg` alebo `sg` a zachovať funkčnosť“ a jediný spôsob, ako tento prísľub dodržať, je spúšťať pôvodný nástroj a obal vedľa seba a porovnávať ich výsledky. Pri každom opätovnom vytvorení matice vykoná testovací nástroj presne toto.