Preskoči na vsebino

Matrika funkcij

Prikaži kot Markdown Uredi na GitHub Dokumentacija za d105217

Matrika funkcij je ustvarjeno poročilo, ki za vsako podprto zastavico in vedenje beleži, ali izvorno orodje in ovojnica Greph ustvarita enakovreden izhod. Je merodajni vir za vprašanja »Ali Greph to podpira?«.

Matrika se znova ustvari na podlagi dejanskih preizkusov ukazov v determinističnem navideznem delovnem prostoru. Surovi dokazi so v FEATURE_MATRIX.json, upodobljena tabela pa v FEATURE_MATRIX.md.

Legenda stanj

Stanje Pomen
Pass Preizkus se je izvedel in ustrezal pričakovanemu vedenju
Fail Preizkus se je izvedel, vendar ni ustrezal pričakovanemu vedenju
Unavailable Ukaz ponudnika v tem okolju ni bil na voljo

Razdelki

Matrika je razdeljena na šest razdelkov:

  1. Površina združljivosti rg: vsak preizkus se izvede tako z izvorno binarno datoteko rg kot z bin/rg. Obe orodji morata Pass, da je vrstica označena kot podprta.
  2. Površina združljivosti sg: vsak preizkus se izvede tako z izvorno binarno datoteko sg kot z bin/sg. Obe orodji morata Pass, da je vrstica označena kot podprta.
  3. Površina samo ovojnice sg: preizkusi, ki ciljajo samo na bin/sg (dodatne funkcije, ki jih izpostavlja ovojnica, ast-grep pa jih sam nima).
  4. Izvorna površina greph: preizkusi, ki neposredno preverjajo bin/greph. Ni izvornega orodja za primerjavo; preizkusi preverjajo pričakovano vedenje v navideznem delovnem prostoru.
  5. Indeksirana površina greph: preizkusi, ki preverjajo bin/greph-index (gradnjo, osveževanje in ogreto iskanje besedila).
  6. Površina indeksirane knjižnice AST: preizkusi, ki kličejo PHP API (Greph::buildAstIndex(), Greph::searchAstIndexed(), Greph::buildAstCache(), Greph::searchAstCached()) ter preverjajo gradnjo, iskanje in osveževanje.

Ponovno ustvarjanje matrike

Lupina
php bin/feature-matrix

Zaženite ga iz klona repozitorija z rg in sg v PATH; bin/feature-matrix ni del paketa Composer. Zgradi navidezni delovni prostor, izvede vsak preizkus združljivosti z izvorno binarno datoteko (če je nameščena) in ovojnico Greph, zabeleži strukturiran rezultat ter zapiše datoteki FEATURE_MATRIX.json in FEATURE_MATRIX.md. Z argumentom --stdout izpišite Markdown, ne da bi zapisali katero koli datoteko.

Zavezanih datotek ne ustvarja CI, temveč se ustvarijo ročno. Zbirka PHPUnit, ki jo zažene CI, vključuje preizkus, ki ustvari matriko z označenimi nedosegljivimi izvornimi orodji in preveri obliko poročila, zato posamezen preizkus, ki začne odpovedovati, ne povzroči neuspeha CI. Pred izdajo znova ustvarite matriko in preglejte razlike.

Kaj sodi v matriko in kaj v dokumentacijo

Referenčni dokument CLI ter strani Združljivost / rg in Združljivost / sg opisujejo predvideni obseg. Matrika funkcij beleži preverjeni obseg, pri čemer so ob vsaki vrstici navedeni natančni argumenti preizkusa.

Če je nekaj dokumentirano, vendar manjka v matriki, je dokumentacija zastarela. Če je nekaj v matriki, vendar ni dokumentirano, je treba dokumentacijo dopolniti. Oboje se mora ujemati.

Primeri vrstic

Združljivost rg (izsek)

Funkcija rg bin/rg Opombe
Iskanje fiksnega niza Uspešno Uspešno Preizkus: -F needle single.txt
Iskanje fiksnega niza brez razlikovanja med velikimi in malimi črkami Uspešno Uspešno Preizkus: -F -i needle single.txt
Iskanje celih besed Uspešno Uspešno Preizkus: -F -w needle words.txt
Filter glob Uspešno Uspešno Preizkus: --glob *.php function .
Skrite datoteke Uspešno Uspešno Preizkus: --hidden -F secret .
Strukturirani izhod JSON Uspešno Uspešno Preizkus: --json -F needle single.txt z uporabo semantike dogodkov ripgrep JSON

Združljivost sg (izsek)

Funkcija sg bin/sg Opombe
Iskanje vzorca z run --pattern Uspešno Uspešno Preizkus: run --pattern array($$$ITEMS) src/App.php
Prepis z run --rewrite Uspešno Uspešno Preizkus: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php
Izhod strukturiranega toka JSON Uspešno Uspešno Preizkus: run --json=stream --pattern dispatch($EVENT) src/App.php
Prepis vseh pojavitev Uspešno Uspešno Preizkus: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php

Celotno tabelo najdete v FEATURE_MATRIX.md.

Zakaj preverjanje s preizkusi

Ročno vzdrževana tabela združljivosti zastara. Bistvo ovojnic je, da jih »namestite namesto klicev rg ali sg in še naprej delujejo«, to obljubo pa lahko ohranimo samo tako, da dejansko zaženemo izvorno orodje in ovojnico drugo ob drugem ter primerjamo rezultate. Izvajalnik preizkusov naredi prav to vsakič, ko znova ustvarimo matriko.