# Funkcijų matrica

Funkcijų matrica yra sugeneruota ataskaita, kurioje kiekvienai palaikomai vėliavai ir elgsenai fiksuojama, ar vietinis įrankis ir Greph apvalkalas pateikia lygiavertę išvestį. Tai yra patikimiausias šaltinis atsakant į klausimus „ar Greph tai palaiko?“.

Matrica iš naujo generuojama vykdant tikras komandų patikras deterministinėje bandomojoje darbo srityje. Neapdoroti įrodymai yra [`FEATURE_MATRIX.json`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json), o sugeneruota lentelė pateikiama [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Būsenų legenda

| Būsena | Reikšmė |
|---|---|
| `Pass` | Zondas paleistas ir jo rezultatas atitiko numatytą elgseną |
| `Fail` | Zondas paleistas, bet jo rezultatas neatitiko numatytos elgsenos |
| `Unavailable` | Teikėjo komandos šioje aplinkoje nėra |

## Skiltys

Matricą sudaro šešios skiltys:

1. **rg suderinamumo sąsaja**: kiekvienas zondas paleidžiamas tiek su pirminiu `rg` dvejetainiu failu, tiek su `bin/rg`. Kad eilutė būtų pažymėta kaip palaikoma, abu turi `Pass`.
2. **sg suderinamumo sąsaja**: kiekvienas zondas paleidžiamas tiek su pirminiu `sg` dvejetainiu failu, tiek su `bin/sg`. Kad eilutė būtų pažymėta kaip palaikoma, abu turi `Pass`.
3. **Tik sg apvalkalo sąsaja**: zondai, skirti tik `bin/sg` (papildomoms funkcijoms, kurias apvalkalas suteikia, bet kurių pati ast-grep neturi).
4. **Vietinė greph sąsaja**: zondai, tiesiogiai tikrinantys `bin/greph`. Nėra pirminio įrankio palyginimui; zondai tikrina numatytą elgseną bandomojoje darbo srityje.
5. **Indeksuota greph sąsaja**: zondai, tikrinantys `bin/greph-index` (sukūrimą, atnaujinimą ir teksto paiešką įšilusiame indekse).
6. **Indeksuota AST bibliotekos sąsaja**: zondai, iškviečiantys PHP API (`Greph::buildAstIndex()`, `Greph::searchAstIndexed()`, `Greph::buildAstCache()`, `Greph::searchAstCached()`) ir tikrinantys sukūrimą, paiešką bei atnaujinimą.

## Matricos generavimas iš naujo

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

Paleiskite klonuotoje saugykloje, turėdami `rg` ir `sg` `PATH`; `bin/feature-matrix` nėra Composer paketo dalis. Jis sukuria bandomąją darbo sritį, paleidžia kiekvieną suderinamumo zondą su pirminiu dvejetainiu failu (jei jis įdiegtas) ir Greph apvalkalu, įrašo struktūrizuotą rezultatą ir sukuria `FEATURE_MATRIX.json` bei `FEATURE_MATRIX.md`. Nurodykite `--stdout`, kad atspausdintumėte Markdown nesukurdami nė vieno failo.

Į saugyklą įtraukti failai sugeneruojami rankiniu būdu; CI jų iš naujo negeneruoja. Į CI vykdomą PHPUnit rinkinio dalį įtrauktas testas, kuris sugeneruoja matricą, pažymėjęs pirminius įrankius kaip nepasiekiamus, ir patikrina ataskaitos struktūrą, todėl vieno zondo nesėkmė nesustabdo CI. Prieš išleidimą sugeneruokite matricą iš naujo ir peržiūrėkite pakeitimus.

## Kas pateikiama matricoje ir dokumentacijoje

CLI žinyne bei puslapiuose [Suderinamumas / rg](https://greph.inline0.dev/lt/docs/compatibility/rg) ir [Suderinamumas / sg](https://greph.inline0.dev/lt/docs/compatibility/sg) aprašoma *numatyta* sąsaja. Funkcijų matricoje pateikiama *patikrinta* sąsaja, prie kiekvienos eilutės nurodant tikslius zondo argumentus.

Jei kas nors aprašyta dokumentacijoje, bet nėra matricoje, dokumentacija pasenusi. Jei kas nors yra matricoje, bet neaprašyta, dokumentaciją reikia papildyti. Abi turi sutapti.

## Eilučių pavyzdžiai

### rg suderinamumas (ištrauka)

| Funkcija | rg | bin/rg | Pastabos |
|---|---|---|---|
| Fiksuotos eilutės paieška | Pass | Pass | Zondas: `-F needle single.txt` |
| Fiksuotos eilutės paieška nepaisant raidžių registro | Pass | Pass | Zondas: `-F -i needle single.txt` |
| Viso žodžio paieška | Pass | Pass | Zondas: `-F -w needle words.txt` |
| Glob filtras | Pass | Pass | Zondas: `--glob *.php function .` |
| Paslėpti failai | Pass | Pass | Zondas: `--hidden -F secret .` |
| Struktūrizuota JSON išvestis | Pass | Pass | Zondas: `--json -F needle single.txt`, naudojantis ripgrep JSON įvykio semantiką |

### sg suderinamumas (ištrauka)

| Funkcija | sg | bin/sg | Pastabos |
|---|---|---|---|
| Šablonų paieška naudojant `run --pattern` | Pass | Pass | Zondas: `run --pattern array($$$ITEMS) src/App.php` |
| Perrašymas naudojant `run --rewrite` | Pass | Pass | Zondas: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| Struktūrizuota JSON srauto išvestis | Pass | Pass | Zondas: `run --json=stream --pattern dispatch($EVENT) src/App.php` |
| Visų atitikmenų perrašymas | Pass | Pass | Zondas: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

Visą lentelę rasite [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Kodėl naudojami zondai

Rankiniu būdu prižiūrima suderinamumo lentelė pasensta. Visų apvalkalų paskirtis – „įdiekite juos ten, kur anksčiau kvietėte `rg` arba `sg`, ir jie veiks toliau“, o šį pažadą galima ištesėti tik greta paleidus pirminį įrankį ir apvalkalą bei palyginus jų rezultatus. Zondų paleidimo įrankis būtent tai daro kiekvieną kartą iš naujo generuojant matricą.