Treci la conținut

Matricea funcționalităților

Vizualizați ca Markdown Editați pe GitHub Documentație la d105217

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, iar tabelul redat în 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

Shell
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 și Compatibilitate / 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.

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ă.