Ugrás a tartalomhoz

Funkciómátrix

Megtekintés Markdownként Szerkesztés itt: GitHub Dokumentáció itt: d105217

A funkciómátrix egy generált jelentés, amely minden támogatott jelző és viselkedés esetén rögzíti, hogy a natív eszköz és a Greph burkoló azonos kimenetet ad-e. Ez a hiteles forrás az olyan kérdések megválaszolásához, hogy „Támogatja ezt a Greph?”.

A mátrix determinisztikus teszt-munkaterületen végzett valós parancsprobákból készül újra. A nyers bizonyíték a FEATURE_MATRIX.json helyen, a megjelenített táblázat pedig a FEATURE_MATRIX.md helyen található.

Állapotjelmagyarázat

Állapot Jelentés
Pass A próba lefutott, és megfelelt a várt viselkedésnek
Fail A próba lefutott, de nem felelt meg a várt viselkedésnek
Unavailable A szolgáltató parancsa nem volt elérhető ebben a környezetben

Szakaszok

A mátrix hat szakaszra tagolódik:

  1. rg-kompatibilitási felület: minden próbát a felsőbb projektből származó rg binárissal és a bin/rg eszközzel is lefuttatnak. Mindkettőnek Pass kell ahhoz, hogy a sor támogatottnak minősüljön.
  2. sg-kompatibilitási felület: minden próbát a felsőbb projektből származó sg binárissal és a bin/sg eszközzel is lefuttatnak. Mindkettőnek Pass kell ahhoz, hogy a sor támogatottnak minősüljön.
  3. Csak az sg-burkolóra vonatkozó felület: olyan próbák, amelyek csak a bin/sg eszközt célozzák (a burkoló által elérhetővé tett kiegészítések, amelyekkel maga a ast-grep nem rendelkezik).
  4. Natív greph-felület: a bin/greph eszközt közvetlenül használó próbák. Nincs összehasonlítható felsőbb szintű eszköz; a próbák a teszt-munkaterületen ellenőrzik az elvárt viselkedést.
  5. Indexelt greph-felület: a bin/greph-index eszközt használó próbák (felépítés, frissítés és bemelegített szöveges keresés).
  6. Indexelt AST-könyvtárfelület: a PHP API (Greph::buildAstIndex(), Greph::searchAstIndexed(), Greph::buildAstCache(), Greph::searchAstCached()) közvetlenül meghívó, illetve a felépítést, keresést és frissítést ellenőrző próbák.

A mátrix újragenerálása

Shell
php bin/feature-matrix

A tároló klónjából futtassa az rg és az sg paranccsal a PATH rendszeren; a bin/feature-matrix nem része a Composer csomagnak. Létrehozza a teszt-munkaterületet, minden kompatibilitási próbát lefuttat a felsőbb projektből származó binárissal (ha telepítve van) és a Greph burkolóval szemben, rögzíti a strukturált eredményt, majd kiírja a FEATURE_MATRIX.json és a FEATURE_MATRIX.md fájlt. Adja meg a --stdout kapcsolót, ha a Markdown kiírását kéri fájlírás nélkül.

A beküldött fájlokat kézzel kell újragenerálni; a CI nem végzi el ezt. A CI által futtatott PHPUnit tesztcsomag tartalmaz egy tesztet, amely az upstream eszközöket nem elérhetőként megjelölve generálja a mátrixot, és ellenőrzi a jelentés szerkezetét, így egyetlen sikertelen próba miatt sem bukik el a CI. Kiadás előtt generálja újra a mátrixot, és tekintse át a változásokat.

Mi szerepel a mátrixban és a dokumentációban

A CLI referencia és a Kompatibilitás / rg, valamint a Kompatibilitás / sg oldalak a tervezett felületet írják le. A funkciómátrix a hitelesített felületet rögzíti, minden sor mellett a pontos próbaargumentumokkal.

Ha valami szerepel a dokumentációban, de hiányzik a mátrixból, akkor a dokumentáció elavult. Ha valami szerepel a mátrixban, de nincs dokumentálva, akkor ki kell egészíteni a dokumentációt. A kettőnek összhangban kell lennie.

Példasorok

rg-kompatibilitás (részlet)

Funkció rg bin/rg Megjegyzések
Rögzített karakterlánc keresése Sikeres Sikeres Próba: -F needle single.txt
Kis- és nagybetűket figyelmen kívül hagyó rögzített karakterlánc keresése Sikeres Sikeres Próba: -F -i needle single.txt
Teljes szavas keresés Sikeres Sikeres Próba: -F -w needle words.txt
Glob szűrő Sikeres Sikeres Próba: --glob *.php function .
Rejtett fájlok Sikeres Sikeres Próba: --hidden -F secret .
Strukturált JSON kimenet Sikeres Sikeres Próba: --json -F needle single.txt, ripgrep JSON-esemény szemantikával

sg-kompatibilitás (részlet)

Funkció sg bin/sg Megjegyzések
Mintakeresés a következővel: run --pattern Sikeres Sikeres Próba: run --pattern array($$$ITEMS) src/App.php
Átírás a következővel: run --rewrite Sikeres Sikeres Próba: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php
Strukturált JSON adatfolyam-kimenet Sikeres Sikeres Próba: run --json=stream --pattern dispatch($EVENT) src/App.php
Összes találatot átíró művelet Sikeres Sikeres Próba: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php

A teljes táblázatot lásd itt: FEATURE_MATRIX.md.

Miért próbákon alapul?

A kézzel karbantartott kompatibilitási táblázat idővel elavul. A burkolók lényege, hogy „helyettesítsék a rg vagy sg eszköz hívását, és továbbra is működjön”, és ezt az ígéretet csak úgy lehet betartani, ha a felsőbb projektből származó eszközt és a burkolót egymás mellett futtatjuk, majd összehasonlítjuk az eredményeket. A próba-futtató pontosan ezt teszi a mátrix minden újragenerálásakor.