Ga naar de inhoud

Functiematrix

Bekijken als Markdown Bewerken op GitHub Documentatie op d105217

De functiematrix is een gegenereerd rapport dat voor elke ondersteunde vlag en elk gedrag vastlegt of de native tool en de Greph-wrapper gelijkwaardige uitvoer produceren. Dit is de bron van waarheid voor vragen als 'ondersteunt Greph dit?'.

De matrix wordt opnieuw gegenereerd met echte opdrachtprobes in een deterministische fixturewerkruimte. Het ruwe bewijsmateriaal staat in FEATURE_MATRIX.json en de weergegeven tabel staat in FEATURE_MATRIX.md.

Statuslegenda

Status Betekenis
Pass De probe is uitgevoerd en kwam overeen met het verwachte gedrag
Fail De probe is uitgevoerd, maar voldeed niet aan het verwachte gedrag
Unavailable De provideropdracht was niet beschikbaar in deze omgeving

Secties

De matrix is ingedeeld in zes secties:

  1. rg-compatibiliteitsoppervlak: elke probe wordt uitgevoerd met zowel de upstream-rg-binary als bin/rg. Beide moeten Pass om de rij als ondersteund te markeren.
  2. sg-compatibiliteitsoppervlak: elke probe wordt uitgevoerd met zowel de upstream-sg-binary als bin/sg. Beide moeten Pass om de rij als ondersteund te markeren.
  3. Alleen de sg-wrapper: probes die alleen bin/sg testen (extra's die de wrapper aanbiedt, maar die ast-grep zelf niet heeft).
  4. Native greph-oppervlak: probes die bin/greph rechtstreeks testen. Er is geen upstream-tool om mee te vergelijken; de probes controleren het verwachte gedrag in de fixturewerkruimte.
  5. Geïndexeerd greph-oppervlak: probes die bin/greph-index testen (build, vernieuwing en opgewarmd zoeken in tekst).
  6. Oppervlak van de geïndexeerde AST-bibliotheek: probes die PHP API aanroepen (Greph::buildAstIndex(), Greph::searchAstIndexed(), Greph::buildAstCache(), Greph::searchAstCached()) en build, zoeken en vernieuwing controleren.

De matrix opnieuw genereren

Shell
php bin/feature-matrix

Voer dit uit vanuit een kloon van de repository met rg en sg op de PATH; bin/feature-matrix maakt geen deel uit van het Composer-pakket. Het bouwt de fixturewerkruimte, voert elke compatibiliteitsprobe uit met de upstream-binary (indien geïnstalleerd) en de Greph-wrapper, legt het gestructureerde resultaat vast en schrijft zowel FEATURE_MATRIX.json als FEATURE_MATRIX.md. Geef --stdout mee om de Markdown weer te geven zonder een van beide bestanden te schrijven.

De gecommitte bestanden worden handmatig opnieuw gegenereerd; CI doet dit niet. De PHPUnit-suite die CI uitvoert, bevat een test die de matrix genereert terwijl de upstream-tools als niet beschikbaar zijn gemarkeerd en de structuur van het rapport controleert. Daardoor laat één probe die begint te falen CI niet mislukken. Genereer de matrix opnieuw en controleer de diff vóór een release.

Wat in de matrix staat en wat in de documentatie

De CLI-referentie en de pagina's Compatibiliteit / rg en Compatibiliteit / sg beschrijven het beoogde aanbod. De functiematrix legt het geverifieerde aanbod vast, met de exacte probe-argumenten bij elke rij.

Als iets wel is gedocumenteerd maar niet in de matrix staat, is de documentatie verouderd. Staat iets wel in de matrix maar niet in de documentatie, dan moet de documentatie worden aangevuld. Beide moeten overeenkomen.

Voorbeeldrijen

rg-compatibiliteit (fragment)

Functie rg bin/rg Opmerkingen
Zoeken naar een vaste tekenreeks Geslaagd Geslaagd Probe: -F needle single.txt
Zoeken naar een vaste tekenreeks zonder onderscheid tussen hoofdletters en kleine letters Geslaagd Geslaagd Probe: -F -i needle single.txt
Zoeken naar hele woorden Geslaagd Geslaagd Probe: -F -w needle words.txt
Glob-filter Geslaagd Geslaagd Probe: --glob *.php function .
Verborgen bestanden Geslaagd Geslaagd Probe: --hidden -F secret .
Gestructureerde JSON-uitvoer Geslaagd Geslaagd Probe: --json -F needle single.txt met gebeurtenissemantiek van ripgrep JSON

sg-compatibiliteit (fragment)

Functie sg bin/sg Opmerkingen
Patronen zoeken met run --pattern Geslaagd Geslaagd Probe: run --pattern array($$$ITEMS) src/App.php
Herschrijven via run --rewrite Geslaagd Geslaagd Probe: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php
Gestructureerde JSON-streamuitvoer Geslaagd Geslaagd Probe: run --json=stream --pattern dispatch($EVENT) src/App.php
Alles herschrijven Geslaagd Geslaagd Probe: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php

Zie voor de volledige tabel FEATURE_MATRIX.md.

Waarom probes gebruiken

Een compatibiliteitstabel die handmatig wordt bijgehouden, raakt achterhaald. Het hele idee achter de wrappers is: 'vervang de plek waar u vroeger rg of sg aanriep en ze blijven werken'. De enige manier om die belofte waar te maken, is de upstream-tool en de wrapper naast elkaar uit te voeren en de resultaten te vergelijken. De probetest doet dat telkens wanneer de matrix opnieuw wordt gegenereerd.