# Matricea funcționalităților

Matricea funcționalităților este un raport generat care înregistrează, pentru fiecare opțiune și comportament acceptat, dacă instrumentul nativ și wrapper-ul Greph produc rezultate echivalente. Este sursa de referință pentru întrebările de tipul „acceptă Greph acest lucru?”.

Matricea este regenerată prin teste reale cu comenzi, rulate într-un spațiu de lucru de testare determinist. Dovezile brute se află în [`FEATURE_MATRIX.json`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.json), iar tabelul redat în [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## Legendă de stare

| Stare | Semnificație |
|---|---|
| `Pass` | Testul a rulat și a corespuns comportamentului așteptat |
| `Fail` | Testul a rulat, dar nu a îndeplinit comportamentul așteptat |
| `Unavailable` | Comanda furnizorului nu era disponibilă în acest mediu |

## Secțiuni

Matricea este organizată în șase secțiuni:

1. **Suprafața de compatibilitate rg**: fiecare test rulează atât cu binarul `rg` din proiectul original, cât și cu `bin/rg`. Ambele trebuie să `Pass` pentru ca rândul să fie marcat ca acceptat.
2. **Suprafața de compatibilitate sg**: fiecare test rulează atât cu binarul `sg` din proiectul original, cât și cu `bin/sg`. Ambele trebuie să `Pass` pentru ca rândul să fie marcat ca acceptat.
3. **Suprafața exclusivă wrapper-ului sg**: teste care vizează doar `bin/sg` (funcționalități suplimentare oferite de wrapper, dar absente din ast-grep propriu-zis).
4. **Suprafața nativă greph**: teste care exercită direct `bin/greph`. Nu există un instrument original cu care să fie comparat; testele verifică comportamentul așteptat în spațiul de lucru de testare.
5. **Suprafața greph indexată**: teste care exercită `bin/greph-index` (compilare, reîmprospătare și căutare text încălzită).
6. **Suprafața bibliotecii AST indexate**: teste care apelează PHP API (`Greph::buildAstIndex()`, `Greph::searchAstIndexed()`, `Greph::buildAstCache()`, `Greph::searchAstCached()`) și verifică compilarea, căutarea și reîmprospătarea.

## Regenerarea matricei

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

Rulați dintr-o clonă a depozitului cu `rg` și `sg` pe `PATH`; `bin/feature-matrix` nu face parte din pachetul Composer. Acesta compilează spațiul de lucru de testare, rulează fiecare test de compatibilitate cu binarul original (dacă este instalat) și cu wrapper-ul Greph, înregistrează rezultatul structurat și scrie atât `FEATURE_MATRIX.json`, cât și `FEATURE_MATRIX.md`. Transmiteți `--stdout` pentru a afișa Markdown fără a scrie niciunul dintre fișiere.

Fișierele incluse în depozit sunt regenerate manual; CI nu le regenerează. Suita PHPUnit rulată de CI include un test care generează matricea cu instrumentele originale marcate ca indisponibile și verifică structura raportului, astfel încât eșecul unui singur test să nu oprească CI. Regenerați matricea și examinați diferențele înainte de o lansare.

## Ce se află în matrice și ce în documentație

Referința CLI și paginile [Compatibilitate / rg](https://greph.inline0.dev/ro/docs/compatibility/rg) și [Compatibilitate / sg](https://greph.inline0.dev/ro/docs/compatibility/sg) descriu suprafața *intenționată*. Matricea funcționalităților înregistrează suprafața *verificată*, cu argumentele exacte ale testului lângă fiecare rând.

Dacă ceva este documentat, dar lipsește din matrice, documentația este învechită. Dacă ceva apare în matrice, dar nu este documentat, trebuie completată documentația. Ambele trebuie să corespundă.

## Exemple de rânduri

### Compatibilitate rg (extras)

| Funcționalitate | rg | bin/rg | Note |
|---|---|---|---|
| Căutare cu șir fix | Reușit | Reușit | Test: `-F needle single.txt` |
| Căutare cu șir fix fără diferențiere între majuscule și minuscule | Reușit | Reușit | Test: `-F -i needle single.txt` |
| Căutare după cuvânt întreg | Reușit | Reușit | Test: `-F -w needle words.txt` |
| Filtru Glob | Reușit | Reușit | Test: `--glob *.php function .` |
| Fișiere ascunse | Reușit | Reușit | Test: `--hidden -F secret .` |
| Rezultat JSON structurat | Reușit | Reușit | Test: `--json -F needle single.txt` cu semantica evenimentelor ripgrep JSON |

### Compatibilitate sg (extras)

| Funcționalitate | sg | bin/sg | Note |
|---|---|---|---|
| Căutare după model cu `run --pattern` | Reușit | Reușit | Test: `run --pattern array($$$ITEMS) src/App.php` |
| Rescriere prin `run --rewrite` | Reușit | Reușit | Test: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php` |
| Rezultat flux JSON structurat | Reușit | Reușit | Test: `run --json=stream --pattern dispatch($EVENT) src/App.php` |
| Rescriere cu actualizare globală | Reușit | Reușit | Test: `run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php` |

Pentru tabelul complet, consultați [`FEATURE_MATRIX.md`](https://github.com/inline0/greph/blob/main/FEATURE_MATRIX.md).

## De ce teste bazate pe probe

Un tabel de compatibilitate întreținut manual ajunge să nu mai fie actualizat. Scopul wrapper-elor este să le puteți folosi în locurile în care apelați de obicei `rg` sau `sg`, iar ele să funcționeze în continuare; singurul mod de a păstra această promisiune este să rulați efectiv instrumentul original și wrapper-ul unul lângă altul și să comparați rezultatele. Executorul de teste face exact acest lucru de fiecare dată când matricea este regenerată.