# Matice funkcí

Matice funkcí je generovaný report, který pro každý podporovaný příznak a chování zaznamenává, zda nativní nástroj a obal Greph poskytují ekvivalentní výstup. Je zdrojem pravdy pro otázky typu „Podporuje to Greph?“.

Matice se znovu generuje pomocí skutečných příkazových sond nad deterministickým pracovním prostorem s testovacími daty. Surové důkazy jsou v [`FEATURE_MATRIX.json`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json) a vykreslená tabulka v [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Legenda stavů

| Stav | Význam |
|---|---|
| `Pass` | Sonda proběhla a výsledek odpovídal očekávanému chování |
| `Fail` | Sonda proběhla, ale výsledek neodpovídal očekávanému chování |
| `Unavailable` | Příkaz poskytovatele v tomto prostředí nebyl k dispozici |

## Sekce

Matice je rozdělena do šesti sekcí:

1. **Kompatibilita s rg**: každá sonda se spouští proti původní binárce `rg` i proti `bin/rg`. Aby byl řádek označen jako podporovaný, obě musí `Pass`.
2. **Kompatibilita se sg**: každá sonda se spouští proti původní binárce `sg` i proti `bin/sg`. Aby byl řádek označen jako podporovaný, obě musí `Pass`.
3. **Funkce dostupné pouze v obalu sg**: sondy zaměřené pouze na `bin/sg` (funkce navíc, které samotné ast-grep nemá).
4. **Nativní rozhraní greph**: sondy, které testují přímo `bin/greph`. Neexistuje žádný původní nástroj pro srovnání; sondy ověřují očekávané chování v pracovním prostoru s testovacími daty.
5. **Indexované rozhraní greph**: sondy testující `bin/greph-index` (sestavení, obnovení a vyhledávání v zahřátém textovém indexu).
6. **Rozhraní knihovny pro indexované AST**: sondy volající PHP API (`Greph::buildAstIndex()`, `Greph::searchAstIndexed()`, `Greph::buildAstCache()`, `Greph::searchAstCached()`) a ověřující sestavení, vyhledávání a obnovení.

## Opětovné vygenerování matice

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

Spusťte ji z klonu repozitáře s `rg` a `sg` na `PATH`; `bin/feature-matrix` není součástí balíčku Composer. Sestaví pracovní prostor s testovacími daty, spustí každou sondu kompatibility proti původní binárce (je-li nainstalována) i obalu Greph, zaznamená strukturovaný výsledek a zapíše soubory `FEATURE_MATRIX.json` i `FEATURE_MATRIX.md`. Parametrem `--stdout` vypíšete Markdown bez zápisu obou souborů.

Verzované soubory se znovu generují ručně; CI je negeneruje. Sada PHPUnit spouštěná v CI obsahuje test, který generuje matici s nedostupnými původními nástroji a kontroluje strukturu reportu, takže selhání jediné sondy nezpůsobí selhání CI. Před vydáním matici znovu vygenerujte a zkontrolujte rozdíly.

## Co patří do matice a co do dokumentace

Reference CLI a stránky [Kompatibilita / rg](https://greph.inline0.dev/cs/docs/compatibility/rg) a [Kompatibilita / sg](https://greph.inline0.dev/cs/docs/compatibility/sg) popisují *zamýšlené* rozhraní. Matice funkcí zaznamenává *ověřené* rozhraní a u každého řádku uvádí přesné argumenty sondy.

Pokud je něco zdokumentováno, ale v matici chybí, dokumentace je zastaralá. Pokud je něco v matici, ale není zdokumentováno, je třeba dokumentaci doplnit. Obojí by mělo souhlasit.

## Příklady řádků

### Kompatibilita s rg (ukázka)

| Funkce | rg | bin/rg | Poznámky |
|---|---|---|---|
| Vyhledávání pevného řetězce | Prošlo | Prošlo | Sonda: `-F needle single.txt` |
| Vyhledávání pevného řetězce bez rozlišování velikosti písmen | Prošlo | Prošlo | Sonda: `-F -i needle single.txt` |
| Vyhledávání celých slov | Prošlo | Prošlo | Sonda: `-F -w needle words.txt` |
| Filtr globem | Prošlo | Prošlo | Sonda: `--glob *.php function .` |
| Skryté soubory | Prošlo | Prošlo | Sonda: `--hidden -F secret .` |
| Strukturovaný výstup JSON | Prošlo | Prošlo | Sonda: `--json -F needle single.txt` používající sémantiku událostí ripgrep JSON |

### Kompatibilita se sg (ukázka)

| Funkce | sg | bin/sg | Poznámky |
|---|---|---|---|
| Vyhledávání vzorů pomocí `run --pattern` | Prošlo | Prošlo | Sonda: `run --pattern array($$$ITEMS) src/App.php` |
| Přepis pomocí `run --rewrite` | Prošlo | Prošlo | Sonda: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| Strukturovaný výstup proudu JSON | Prošlo | Prošlo | Sonda: `run --json=stream --pattern dispatch($EVENT) src/App.php` |
| Přepis všech výskytů | Prošlo | Prošlo | Sonda: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

Úplnou tabulku najdete v [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Proč jsou sondy základem

Tabulka kompatibility udržovaná ručně zastarává. Smyslem obalů je „nasadit je tam, kde jste dříve volali `rg` nebo `sg`, a budou dál fungovat“; jediný způsob, jak tento slib dodržet, je skutečně spouštět původní nástroj i obal vedle sebe a porovnávat výsledky. Přesně to běžec sond dělá při každém novém vygenerování matice.