Vai al contenuto

Matrice delle funzionalità

Visualizza come Markdown Modifica su GitHub Documentazione di d105217

La matrice delle funzionalità è un report generato che registra, per ogni flag e comportamento supportato, se lo strumento nativo e il wrapper Greph producono un output equivalente. È il riferimento per le domande del tipo «Greph supporta questa funzionalità?».

La matrice viene rigenerata eseguendo probe reali su un workspace di fixture deterministico. Le prove grezze si trovano in FEATURE_MATRIX.json e la tabella formattata in FEATURE_MATRIX.md.

Legenda degli stati

Stato Significato
Pass Il probe è stato eseguito e il risultato corrispondeva al comportamento previsto
Fail Il probe è stato eseguito, ma il risultato non corrispondeva al comportamento previsto
Unavailable Il comando del provider non era disponibile in questo ambiente

Sezioni

La matrice è organizzata in sei sezioni:

  1. Superficie di compatibilità con rg: ogni probe viene eseguito sia con il binario upstream rg sia con bin/rg. Entrambi devono Pass perché la riga risulti supportata.
  2. Superficie di compatibilità con sg: ogni probe viene eseguito sia con il binario upstream sg sia con bin/sg. Entrambi devono Pass perché la riga risulti supportata.
  3. Superficie solo del wrapper sg: probe rivolti solo a bin/sg (funzionalità aggiuntive esposte dal wrapper e assenti in ast-grep stesso).
  4. Superficie nativa di greph: probe che esercitano direttamente bin/greph. Non esiste uno strumento upstream per il confronto; i probe verificano il comportamento previsto nel workspace di fixture.
  5. Superficie indicizzata di greph: probe che esercitano bin/greph-index (creazione, aggiornamento e ricerca testuale a caldo).
  6. Superficie della libreria AST indicizzata: probe che chiamano PHP API (Greph::buildAstIndex(), Greph::searchAstIndexed(), Greph::buildAstCache(), Greph::searchAstCached()) e verificano creazione, ricerca e aggiornamento.

Rigenerazione della matrice

Shell
php bin/feature-matrix

Eseguilo da un clone del repository con rg e sg nel PATH; bin/feature-matrix non fa parte del pacchetto Composer. Crea il workspace di fixture, esegue ogni probe di compatibilità sul binario upstream (se installato) e sul wrapper Greph, registra il risultato strutturato e scrive sia FEATURE_MATRIX.json sia FEATURE_MATRIX.md. Passa --stdout per stampare Markdown senza scrivere nessuno dei due file.

I file nel repository vengono rigenerati manualmente; la CI non li rigenera. La suite PHPUnit eseguita dalla CI include un test che genera la matrice segnando gli strumenti upstream come non disponibili e verifica la struttura del report, così il fallimento di un singolo probe non interrompe la CI. Rigenera la matrice e controlla il diff prima di una release.

Contenuti della matrice e della documentazione

Il riferimento CLI e le pagine Compatibilità / rg e Compatibilità / sg descrivono le funzionalità previste. La matrice registra quelle verificate, con gli argomenti esatti dei probe accanto a ogni riga.

Se una funzionalità è documentata ma manca nella matrice, la documentazione è obsoleta. Se è presente nella matrice ma non è documentata, occorre aggiornare la documentazione. Le due fonti dovrebbero corrispondere.

Righe di esempio

Compatibilità con rg (estratto)

Funzionalità rg bin/rg Note
Ricerca a stringa fissa Pass Pass Probe: -F needle single.txt
Ricerca a stringa fissa senza distinzione tra maiuscole e minuscole Pass Pass Probe: -F -i needle single.txt
Ricerca per parola intera Pass Pass Probe: -F -w needle words.txt
Filtro glob Pass Pass Probe: --glob *.php function .
File nascosti Pass Pass Probe: --hidden -F secret .
Output strutturato JSON Pass Pass Probe: --json -F needle single.txt con semantica degli eventi ripgrep JSON

Compatibilità con sg (estratto)

Funzionalità sg bin/sg Note
Ricerca di pattern con run --pattern Pass Pass Probe: run --pattern array($$$ITEMS) src/App.php
Riscrittura tramite run --rewrite Pass Pass Probe: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php
Output del flusso strutturato JSON Pass Pass Probe: run --json=stream --pattern dispatch($EVENT) src/App.php
Riscrittura di tutti i risultati Pass Pass Probe: run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php

Per la tabella completa, consulta FEATURE_MATRIX.md.

Perché usare i probe

Una tabella di compatibilità aggiornata manualmente diventa obsoleta. Lo scopo dei wrapper è «sostituiscili alle chiamate a rg o sg e continueranno a funzionare», e l'unico modo per mantenere questa promessa è eseguire lo strumento upstream e il wrapper in parallelo e confrontarne i risultati. Il runner dei probe fa proprio questo ogni volta che la matrice viene rigenerata.