Preskočiť na obsah

Matica funkcií

Zobraziť ako Markdown Upraviť na GitHub Dokumentácia na d105217

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 a vykreslená tabuľka je v 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

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

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.