Zum Inhalt springen

Feature-Matrix

Als Markdown anzeigen Auf GitHub bearbeiten Dokumentation zu d105217

Die Feature-Matrix ist ein generierter Bericht, der für jedes unterstützte Flag und Verhalten festhält, ob das native Tool und der Greph-Wrapper eine gleichwertige Ausgabe erzeugen. Sie ist maßgeblich für die Frage: „Wird das von Greph unterstützt?“

Die Matrix wird anhand echter Befehlsprüfungen in einem deterministischen Fixture-Arbeitsbereich neu generiert. Die Rohdaten liegen unter FEATURE_MATRIX.json, die formatierte Tabelle unter FEATURE_MATRIX.md.

Statuslegende

Status Bedeutung
Pass Die Prüfung wurde ausgeführt und entsprach dem erwarteten Verhalten
Fail Die Prüfung wurde ausgeführt, erfüllte aber nicht die erwarteten Anforderungen
Unavailable Der Anbieterbefehl war in dieser Umgebung nicht vorhanden

Abschnitte

Die Matrix ist in sechs Abschnitte gegliedert:

  1. rg-Kompatibilitätsoberfläche: Jede Prüfung wird sowohl mit der vorgelagerten rg-Binärdatei als auch mit bin/rg ausgeführt. Beide müssen Pass, damit die Zeile als unterstützt markiert wird.
  2. sg-Kompatibilitätsoberfläche: Jede Prüfung wird sowohl mit der vorgelagerten sg-Binärdatei als auch mit bin/sg ausgeführt. Beide müssen Pass, damit die Zeile als unterstützt markiert wird.
  3. Nur vom sg-Wrapper unterstützte Funktionen: Prüfungen, die sich ausschließlich auf bin/sg beziehen (zusätzliche Funktionen des Wrappers, die ast-grep selbst nicht bietet).
  4. Native greph-Oberfläche: Prüfungen, die bin/greph direkt ausführen. Es gibt kein vorgelagertes Tool für einen Vergleich; die Prüfungen bestätigen das erwartete Verhalten im Fixture-Arbeitsbereich.
  5. Indexierte greph-Oberfläche: Prüfungen, die bin/greph-index ausführen (Erstellung, Aktualisierung und aufgewärmte Textsuche).
  6. Indexierte AST-Bibliotheksoberfläche: Prüfungen, die PHP API aufrufen (Greph::buildAstIndex(), Greph::searchAstIndexed(), Greph::buildAstCache(), Greph::searchAstCached()) und Erstellung, Suche sowie Aktualisierung überprüfen.

Matrix neu generieren

Shell
php bin/feature-matrix

Führe das Skript in einem geklonten Repository mit rg und sg auf dem PATH aus; bin/feature-matrix ist nicht Teil des Composer-Pakets. Es erstellt den Fixture-Arbeitsbereich, führt jede Kompatibilitätsprüfung mit der vorgelagerten Binärdatei aus (falls installiert) sowie mit dem Greph-Wrapper, erfasst das strukturierte Ergebnis und schreibt sowohl FEATURE_MATRIX.json als auch FEATURE_MATRIX.md. Übergib --stdout, um die Markdown auszugeben, ohne eine der beiden Dateien zu schreiben.

Die eingecheckten Dateien werden manuell neu generiert; CI generiert sie nicht. Die von CI ausgeführte PHPUnit-Suite enthält einen Test, der die Matrix mit als nicht verfügbar markierten Upstream-Tools erstellt und die Struktur des Berichts überprüft. So lässt eine einzelne fehlschlagende Prüfung CI nicht fehlschlagen. Generiere die Matrix vor einer Veröffentlichung neu und überprüfe die Änderungen.

Was in die Matrix und was in die Dokumentation gehört

Die CLI-Referenz und die Seiten Kompatibilität / rg sowie Kompatibilität / sg beschreiben den beabsichtigten Funktionsumfang. Die Feature-Matrix dokumentiert den überprüften Umfang und führt neben jeder Zeile die genauen Argumente der Prüfung auf.

Wenn etwas dokumentiert, aber nicht in der Matrix enthalten ist, ist die Dokumentation veraltet. Wenn etwas in der Matrix steht, aber nicht dokumentiert ist, muss die Dokumentation ergänzt werden. Beides sollte übereinstimmen.

Beispielzeilen

rg-Kompatibilität (Auszug)

Funktion rg bin/rg Hinweise
Feststringsuche Bestanden Bestanden Prüfung: -F needle single.txt
Groß- und Kleinschreibung bei Feststringsuche ignorieren Bestanden Bestanden Prüfung: -F -i needle single.txt
Suche nach ganzen Wörtern Bestanden Bestanden Prüfung: -F -w needle words.txt
Glob-Filter Bestanden Bestanden Prüfung: --glob *.php function .
Versteckte Dateien Bestanden Bestanden Prüfung: --hidden -F secret .
Strukturierte JSON-Ausgabe Bestanden Bestanden Prüfung: --json -F needle single.txt mit ripgrep-JSON-Ereignissemantik

sg-Kompatibilität (Auszug)

Funktion sg bin/sg Hinweise
Mustersuche mit run --pattern Bestanden Bestanden Prüfung: run --pattern array($$$ITEMS) src/App.php
Umschreiben mit run --rewrite Bestanden Bestanden Prüfung: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php
Strukturierte JSON-Stream-Ausgabe Bestanden Bestanden Prüfung: run --json=stream --pattern dispatch($EVENT) src/App.php
Alles umschreiben Bestanden Bestanden Prüfung: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php

Die vollständige Tabelle findest du unter FEATURE_MATRIX.md.

Warum Prüfungen die Grundlage bilden

Eine manuell gepflegte Kompatibilitätstabelle veraltet mit der Zeit. Der ganze Zweck der Wrapper besteht darin, sie dort einzusetzen, wo du zuvor rg oder sg aufgerufen hast, und damit alles weiterhin funktioniert. Dieses Versprechen lässt sich nur einhalten, indem man das Upstream-Tool und den Wrapper tatsächlich nebeneinander ausführt und die Ergebnisse vergleicht. Genau das macht der Prüfungs-Runner bei jeder Neugenerierung der Matrix.