Przejdź do treści

Macierz funkcji

Wyświetl jako Markdown Edytuj w GitHub Dokumentacja: d105217

Macierz funkcji to wygenerowany raport, który dla każdej obsługiwanej flagi i zachowania odnotowuje, czy narzędzie natywne i wrapper Greph zwracają równoważne wyniki. Jest źródłem prawdy w odpowiedzi na pytanie: „czy Greph to obsługuje?”.

Macierz jest generowana ponownie na podstawie rzeczywistych testów poleceń w deterministycznym środowisku testowym. Surowe dane znajdują się w FEATURE_MATRIX.json, a wyrenderowana tabela w FEATURE_MATRIX.md.

Legenda statusów

Status Znaczenie
Pass Test został uruchomiony i wynik był zgodny z oczekiwanym zachowaniem
Fail Test został uruchomiony, ale wynik nie odpowiadał oczekiwanemu zachowaniu
Unavailable Polecenie dostawcy nie było dostępne w tym środowisku

Sekcje

Macierz jest podzielona na sześć sekcji:

  1. Zakres zgodności rg: każdy test jest uruchamiany zarówno na oryginalnym pliku binarnym rg, jak i na bin/rg. Aby wiersz został oznaczony jako obsługiwany, oba wyniki muszą być zgodne z Pass.
  2. Zakres zgodności sg: każdy test jest uruchamiany zarówno na oryginalnym pliku binarnym sg, jak i na bin/sg. Aby wiersz został oznaczony jako obsługiwany, oba wyniki muszą być zgodne z Pass.
  3. Zakres wyłącznie wrappera sg: testy dotyczące tylko bin/sg (dodatkowych funkcji udostępnianych przez wrapper, których nie ma samo ast-grep).
  4. Zakres natywnego greph: testy bezpośrednio sprawdzające bin/greph. Nie ma tu oryginalnego narzędzia do porównania; testy sprawdzają oczekiwane zachowanie w środowisku testowym.
  5. Zakres indeksowanego greph: testy sprawdzające bin/greph-index (budowanie, odświeżanie i rozgrzane wyszukiwanie tekstu).
  6. Zakres biblioteki indeksowanego AST: testy wywołujące PHP API (Greph::buildAstIndex(), Greph::searchAstIndexed(), Greph::buildAstCache(), Greph::searchAstCached()) i sprawdzające budowanie, wyszukiwanie oraz odświeżanie.

Ponowne generowanie macierzy

Powłoka
php bin/feature-matrix

Uruchom skrypt ze sklonowanego repozytorium, mając rg i sg na PATH; bin/feature-matrix nie należy do pakietu Composer. Skrypt buduje środowisko testowe, uruchamia każdy test zgodności na oryginalnym pliku binarnym (jeśli jest zainstalowany) oraz wrapperze Greph, zapisuje ustrukturyzowany wynik i tworzy pliki FEATURE_MATRIX.json oraz FEATURE_MATRIX.md. Podaj --stdout, aby wyświetlić Markdown bez zapisywania żadnego z plików.

Pliki w repozytorium są generowane ponownie ręcznie; CI ich nie generuje. Zestaw PHPUnit uruchamiany przez CI zawiera test generujący macierz z oznaczonymi jako niedostępne oryginalnymi narzędziami i sprawdzający strukturę raportu. Dzięki temu niepowodzenie pojedynczego testu nie powoduje awarii CI. Przed wydaniem wygeneruj ponownie macierz i sprawdź różnice.

Zawartość macierzy a dokumentacja

Dokumentacja CLI i strony Zgodność / rg oraz Zgodność / sg opisują zamierzony zakres. Macierz funkcji przedstawia zakres zweryfikowany, wraz z dokładnymi argumentami testów przy każdym wierszu.

Jeśli coś jest udokumentowane, ale brakuje tego w macierzy, dokumentacja jest nieaktualna. Jeśli coś znajduje się w macierzy, ale nie ma tego w dokumentacji, należy ją uzupełnić. Obie wersje powinny być zgodne.

Przykładowe wiersze

Zgodność rg (fragment)

Funkcja rg bin/rg Uwagi
Wyszukiwanie dokładnego ciągu Powodzenie Powodzenie Test: -F needle single.txt
Wyszukiwanie dokładnego ciągu bez uwzględniania wielkości liter Powodzenie Powodzenie Test: -F -i needle single.txt
Wyszukiwanie całych słów Powodzenie Powodzenie Test: -F -w needle words.txt
Filtr glob Powodzenie Powodzenie Test: --glob *.php function .
Ukryte pliki Powodzenie Powodzenie Test: --hidden -F secret .
Ustrukturyzowane wyjście JSON Powodzenie Powodzenie Test: --json -F needle single.txt z użyciem semantyki zdarzeń ripgrep JSON

Zgodność sg (fragment)

Funkcja sg bin/sg Uwagi
Wyszukiwanie wzorca z run --pattern Powodzenie Powodzenie Test: run --pattern array($$$ITEMS) src/App.php
Przepisywanie za pomocą run --rewrite Powodzenie Powodzenie Test: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php
Ustrukturyzowany strumień wyjściowy JSON Powodzenie Powodzenie Test: run --json=stream --pattern dispatch($EVENT) src/App.php
Przepisanie wszystkich wystąpień Powodzenie Powodzenie Test: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php

Pełna tabela znajduje się na stronie FEATURE_MATRIX.md.

Dlaczego testy

Ręcznie utrzymywana tabela zgodności z czasem przestaje być aktualna. Cały sens wrapperów polega na tym, że „wstawiasz je tam, gdzie wcześniej wywoływałeś rg lub sg, a one nadal działają”. Jedynym sposobem dotrzymania tej obietnicy jest równoczesne uruchomienie oryginalnego narzędzia i wrappera oraz porównanie wyników. Runner testów robi dokładnie to za każdym razem, gdy macierz jest generowana ponownie.