# Macierz funkcji

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`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json), a wyrenderowana tabela w [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/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

```bash
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](https://greph.inline0.dev/pl/docs/compatibility/rg) oraz [Zgodność / sg](https://greph.inline0.dev/pl/docs/compatibility/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`](https://github.com/inline0/greph/blob/main/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.