Gå til indhold

Funktionsmatrix

Vis som Markdown Rediger på GitHub Dokumentation hos d105217

Funktionsmatrixen er en genereret rapport, der for hvert understøttet flag og hver adfærd registrerer, om det indbyggede værktøj og wrapperen Greph giver tilsvarende output. Den er autoritativ kilde til svar på spørgsmål som »understøtter Greph dette?«.

Matrixen gendannes ud fra reelle kommandoprober mod et deterministisk fixture-arbejdsområde. De rå data findes i FEATURE_MATRIX.json, og den gengivne tabel findes i FEATURE_MATRIX.md.

Statusforklaring

Status Betydning
Pass Proben blev kørt og svarede til den forventede adfærd
Fail Proben blev kørt, men opfyldte ikke den forventede adfærd
Unavailable Udbyderkommandoen findes ikke i dette miljø

Afsnit

Matrixen er organiseret i seks afsnit:

  1. rg-kompatibilitetsflade: hver probe køres mod både den oprindelige rg-binærfil og bin/rg. Begge skal Pass, før rækken markeres som understøttet.
  2. sg-kompatibilitetsflade: hver probe køres mod både den oprindelige sg-binærfil og bin/sg. Begge skal Pass, før rækken markeres som understøttet.
  3. Kun sg-wrapperflade: prober, der kun retter sig mod bin/sg (ekstra funktioner, som wrapperen stiller til rådighed, og som ast-grep ikke selv har).
  4. Indbygget greph-flade: prober, der tester bin/greph direkte. Der findes intet oprindeligt værktøj at sammenligne med; proberne kontrollerer den forventede adfærd i fixture-arbejdsområdet.
  5. Indekseret greph-flade: prober, der tester bin/greph-index (opbygning, opdatering og opvarmet tekstsøgning).
  6. Indekseret AST-biblioteksflade: prober, der kalder PHP API (Greph::buildAstIndex(), Greph::searchAstIndexed(), Greph::buildAstCache(), Greph::searchAstCached()) og kontrollerer opbygning, søgning og opdatering.

Gendan matrixen

Shell
php bin/feature-matrix

Kør det fra en klon af repositoryet med rg og sg på PATH; bin/feature-matrix er ikke en del af pakken Composer. Det opbygger fixture-arbejdsområdet, kører hver kompatibilitetsprobe mod den oprindelige binærfil (hvis den er installeret) og wrapperen Greph, registrerer det strukturerede resultat og skriver både FEATURE_MATRIX.json og FEATURE_MATRIX.md. Angiv --stdout for at udskrive Markdown uden at skrive nogen af filerne.

De indcheckede filer gendannes manuelt; CI gendanner dem ikke. PHPUnit-pakken, som CI kører, indeholder en test, der genererer matrixen med de oprindelige værktøjer markeret som utilgængelige og kontrollerer rapportens struktur, så en enkelt probe, der begynder at fejle, ikke får CI til at fejle. Gendan matrixen, og gennemgå diffen før en udgivelse.

Hvad hører til i matrixen og i dokumentationen

CLI-referencen og siderne Kompatibilitet / rg og Kompatibilitet / sg beskriver den tilsigtede flade. Funktionsmatrixen registrerer den verificerede flade med de præcise probe-argumenter ved hver række.

Hvis noget er dokumenteret, men mangler i matrixen, er dokumentationen forældet. Hvis noget står i matrixen, men ikke er dokumenteret, skal dokumentationen opdateres. De to skal stemme overens.

Eksempelrækker

rg-kompatibilitet (uddrag)

Funktion rg bin/rg Noter
Søgning efter fast streng Bestået Bestået Probe: -F needle single.txt
Søgning efter fast streng uden forskel på store og små bogstaver Bestået Bestået Probe: -F -i needle single.txt
Søgning efter hele ord Bestået Bestået Probe: -F -w needle words.txt
Glob-filter Bestået Bestået Probe: --glob *.php function .
Skjulte filer Bestået Bestået Probe: --hidden -F secret .
Struktureret JSON-output Bestået Bestået Probe: --json -F needle single.txt med semantik for ripgrep-hændelser i JSON

sg-kompatibilitet (uddrag)

Funktion sg bin/sg Noter
Mønstersøgning med run --pattern Bestået Bestået Probe: run --pattern array($$$ITEMS) src/App.php
Omskrivning via run --rewrite Bestået Bestået Probe: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php
Struktureret JSON-streamoutput Bestået Bestået Probe: run --json=stream --pattern dispatch($EVENT) src/App.php
Omskrivning af alle Bestået Bestået Probe: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php

Se hele tabellen her: FEATURE_MATRIX.md.

Hvorfor probe-baseret

En kompatibilitetstabel, der vedligeholdes manuelt, bliver forældet. Hele formålet med wrapperne er, at du kan »sætte dem ind dér, hvor du tidligere kaldte rg eller sg, og så virker de stadig«. Den eneste måde at leve op til det løfte på er faktisk at køre det oprindelige værktøj og wrapperen side om side og sammenligne resultaterne. Probe-runneren gør netop det, hver gang matrixen gendannes.