# Funkciómátrix

A funkciómátrix egy generált jelentés, amely minden támogatott jelző és viselkedés esetén rögzíti, hogy a natív eszköz és a Greph burkoló azonos kimenetet ad-e. Ez a hiteles forrás az olyan kérdések megválaszolásához, hogy „Támogatja ezt a Greph?”.

A mátrix determinisztikus teszt-munkaterületen végzett valós parancsprobákból készül újra. A nyers bizonyíték a [`FEATURE_MATRIX.json`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json) helyen, a megjelenített táblázat pedig a [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md) helyen található.

## Állapotjelmagyarázat

| Állapot | Jelentés |
|---|---|
| `Pass` | A próba lefutott, és megfelelt a várt viselkedésnek |
| `Fail` | A próba lefutott, de nem felelt meg a várt viselkedésnek |
| `Unavailable` | A szolgáltató parancsa nem volt elérhető ebben a környezetben |

## Szakaszok

A mátrix hat szakaszra tagolódik:

1. **rg-kompatibilitási felület**: minden próbát a felsőbb projektből származó `rg` binárissal és a `bin/rg` eszközzel is lefuttatnak. Mindkettőnek `Pass` kell ahhoz, hogy a sor támogatottnak minősüljön.
2. **sg-kompatibilitási felület**: minden próbát a felsőbb projektből származó `sg` binárissal és a `bin/sg` eszközzel is lefuttatnak. Mindkettőnek `Pass` kell ahhoz, hogy a sor támogatottnak minősüljön.
3. **Csak az sg-burkolóra vonatkozó felület**: olyan próbák, amelyek csak a `bin/sg` eszközt célozzák (a burkoló által elérhetővé tett kiegészítések, amelyekkel maga a ast-grep nem rendelkezik).
4. **Natív greph-felület**: a `bin/greph` eszközt közvetlenül használó próbák. Nincs összehasonlítható felsőbb szintű eszköz; a próbák a teszt-munkaterületen ellenőrzik az elvárt viselkedést.
5. **Indexelt greph-felület**: a `bin/greph-index` eszközt használó próbák (felépítés, frissítés és bemelegített szöveges keresés).
6. **Indexelt AST-könyvtárfelület**: a PHP API (`Greph::buildAstIndex()`, `Greph::searchAstIndexed()`, `Greph::buildAstCache()`, `Greph::searchAstCached()`) közvetlenül meghívó, illetve a felépítést, keresést és frissítést ellenőrző próbák.

## A mátrix újragenerálása

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

A tároló klónjából futtassa az `rg` és az `sg` paranccsal a `PATH` rendszeren; a `bin/feature-matrix` nem része a Composer csomagnak. Létrehozza a teszt-munkaterületet, minden kompatibilitási próbát lefuttat a felsőbb projektből származó binárissal (ha telepítve van) és a Greph burkolóval szemben, rögzíti a strukturált eredményt, majd kiírja a `FEATURE_MATRIX.json` és a `FEATURE_MATRIX.md` fájlt. Adja meg a `--stdout` kapcsolót, ha a Markdown kiírását kéri fájlírás nélkül.

A beküldött fájlokat kézzel kell újragenerálni; a CI nem végzi el ezt. A CI által futtatott PHPUnit tesztcsomag tartalmaz egy tesztet, amely az upstream eszközöket nem elérhetőként megjelölve generálja a mátrixot, és ellenőrzi a jelentés szerkezetét, így egyetlen sikertelen próba miatt sem bukik el a CI. Kiadás előtt generálja újra a mátrixot, és tekintse át a változásokat.

## Mi szerepel a mátrixban és a dokumentációban

A CLI referencia és a [Kompatibilitás / rg](https://greph.inline0.dev/hu/docs/compatibility/rg), valamint a [Kompatibilitás / sg](https://greph.inline0.dev/hu/docs/compatibility/sg) oldalak a *tervezett* felületet írják le. A funkciómátrix a *hitelesített* felületet rögzíti, minden sor mellett a pontos próbaargumentumokkal.

Ha valami szerepel a dokumentációban, de hiányzik a mátrixból, akkor a dokumentáció elavult. Ha valami szerepel a mátrixban, de nincs dokumentálva, akkor ki kell egészíteni a dokumentációt. A kettőnek összhangban kell lennie.

## Példasorok

### rg-kompatibilitás (részlet)

| Funkció | rg | bin/rg | Megjegyzések |
|---|---|---|---|
| Rögzített karakterlánc keresése | Sikeres | Sikeres | Próba: `-F needle single.txt` |
| Kis- és nagybetűket figyelmen kívül hagyó rögzített karakterlánc keresése | Sikeres | Sikeres | Próba: `-F -i needle single.txt` |
| Teljes szavas keresés | Sikeres | Sikeres | Próba: `-F -w needle words.txt` |
| Glob szűrő | Sikeres | Sikeres | Próba: `--glob *.php function .` |
| Rejtett fájlok | Sikeres | Sikeres | Próba: `--hidden -F secret .` |
| Strukturált JSON kimenet | Sikeres | Sikeres | Próba: `--json -F needle single.txt`, ripgrep JSON-esemény szemantikával |

### sg-kompatibilitás (részlet)

| Funkció | sg | bin/sg | Megjegyzések |
|---|---|---|---|
| Mintakeresés a következővel: `run --pattern` | Sikeres | Sikeres | Próba: `run --pattern array($$$ITEMS) src/App.php` |
| Átírás a következővel: `run --rewrite` | Sikeres | Sikeres | Próba: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| Strukturált JSON adatfolyam-kimenet | Sikeres | Sikeres | Próba: `run --json=stream --pattern dispatch($EVENT) src/App.php` |
| Összes találatot átíró művelet | Sikeres | Sikeres | Próba: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

A teljes táblázatot lásd itt: [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Miért próbákon alapul?

A kézzel karbantartott kompatibilitási táblázat idővel elavul. A burkolók lényege, hogy „helyettesítsék a `rg` vagy `sg` eszköz hívását, és továbbra is működjön”, és ezt az ígéretet csak úgy lehet betartani, ha a felsőbb projektből származó eszközt és a burkolót egymás mellett futtatjuk, majd összehasonlítjuk az eredményeket. A próba-futtató pontosan ezt teszi a mátrix minden újragenerálásakor.