Hoppa till innehåll

Funktionsmatris

Visa som Markdown Redigera på GitHub Dokumentation på d105217

Funktionsmatrisen är en genererad rapport som för varje flagga och beteende som stöds registrerar om det inbyggda verktyget och omslaget Greph ger likvärdiga utdata. Den är facit för frågor av typen ”har Greph stöd för detta?”.

Matrisen genereras på nytt från verkliga kommandoprobningar mot en deterministisk testmiljö. Råunderlaget finns i FEATURE_MATRIX.json och den återgivna tabellen finns i FEATURE_MATRIX.md.

Statusförklaring

Status Betydelse
Pass Proben kördes och motsvarade det förväntade beteendet
Fail Proben kördes men uppfyllde inte det förväntade beteendet
Unavailable Leverantörskommandot fanns inte i den här miljön

Avsnitt

Matrisen är indelad i sex avsnitt:

  1. rg-kompatibilitetsyta: varje probe körs både mot den uppströmsbaserade binärfilen rg och bin/rg. Båda måste Pass för att raden ska markeras som stödd.
  2. sg-kompatibilitetsyta: varje probe körs både mot den uppströmsbaserade binärfilen sg och bin/sg. Båda måste Pass för att raden ska markeras som stödd.
  3. Yta som bara finns i sg-omslaget: prober som endast riktar sig mot bin/sg (funktioner som omslaget exponerar men som ast-grep självt saknar).
  4. Inbyggd greph-yta: prober som testar bin/greph direkt. Det finns inget uppströmsverktyg att jämföra med; proberna kontrollerar det förväntade beteendet i testmiljön.
  5. Indexerad greph-yta: prober som testar bin/greph-index (bygge, uppdatering och uppvärmd textsökning).
  6. Indexerad AST-biblioteksyta: prober som anropar PHP API (Greph::buildAstIndex(), Greph::searchAstIndexed(), Greph::buildAstCache(), Greph::searchAstCached()) och kontrollerar bygge, sökning och uppdatering.

Skapa om matrisen

Shell
php bin/feature-matrix

Kör från en klon av repot med rg och sg på PATH; bin/feature-matrix ingår inte i paketet Composer. Skriptet bygger testmiljön, kör varje kompatibilitetsprobe mot den uppströmsbaserade binärfilen (om den är installerad) och omslaget Greph, registrerar det strukturerade resultatet och skriver både FEATURE_MATRIX.json och FEATURE_MATRIX.md. Ange --stdout för att skriva ut Markdown utan att skriva någon av filerna.

De incheckade filerna genereras om manuellt; CI genererar dem inte. Testsviten PHPUnit som CI kör innehåller ett test som skapar matrisen med uppströmsverktygen markerade som otillgängliga och kontrollerar rapportens struktur. Därför leder en enskild probe som börjar misslyckas inte till att CI misslyckas. Generera om matrisen och granska diffen före en version.

Vad som hör hemma i matrisen respektive dokumentationen

Referensen CLI och sidorna Kompatibilitet / rg samt Kompatibilitet / sg beskriver den avsedda funktionsytan. Funktionsmatrisen registrerar den verifierade funktionsytan, med de exakta probe-argumenten intill varje rad.

Om något är dokumenterat men saknas i matrisen är dokumentationen inaktuell. Om något finns i matrisen men inte är dokumenterat behöver dokumentationen kompletteras. De ska stämma överens.

Exempelrader

rg-kompatibilitet (utdrag)

Funktion rg bin/rg Anteckningar
Sökning med fast sträng Godkänt Godkänt Probe: -F needle single.txt
Sökning med fast sträng utan hänsyn till skiftläge Godkänt Godkänt Probe: -F -i needle single.txt
Helordsökning Godkänt Godkänt Probe: -F -w needle words.txt
Globfilter Godkänt Godkänt Probe: --glob *.php function .
Dolda filer Godkänt Godkänt Probe: --hidden -F secret .
Strukturerad JSON-utdata Godkänt Godkänt Probe: --json -F needle single.txt med händelsesemantik för ripgrep JSON

sg-kompatibilitet (utdrag)

Funktion sg bin/sg Anteckningar
Mönstersökning med run --pattern Godkänt Godkänt Probe: run --pattern array($$$ITEMS) src/App.php
Omskrivning med run --rewrite Godkänt Godkänt Probe: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php
Strukturerad strömutdata JSON Godkänt Godkänt Probe: run --json=stream --pattern dispatch($EVENT) src/App.php
Skriv om alla Godkänt Godkänt Probe: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php

För hela tabellen, se FEATURE_MATRIX.md.

Varför probstyrt

En kompatibilitetstabell som underhålls för hand blir inaktuell. Hela poängen med omslagen är att ”ersätta anropen till rg eller sg med dem och fortsätta arbeta som vanligt”. Det enda sättet att hålla det löftet är att faktiskt köra uppströmsverktyget och omslaget sida vid sida och jämföra resultaten. Proberunnern gör just det varje gång matrisen genereras om.