Přejít k obsahu

Matice funkcí

Zobrazit jako Markdown Upravit na GitHub Dokumentace na d105217

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 a vykreslená tabulka v 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

Shell
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 a Kompatibilita / 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.

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.