Aller au contenu

Matrice des fonctionnalités

Afficher au format Markdown Modifier sur GitHub Documentation de d105217

La matrice des fonctionnalités est un rapport généré qui indique, pour chaque option et comportement pris en charge, si l’outil natif et le wrapper Greph produisent une sortie équivalente. C’est la référence pour répondre aux questions du type « est-ce pris en charge par Greph ? ».

La matrice est régénérée à partir de sondes de commandes réelles exécutées sur un espace de travail de test déterministe. Les données brutes se trouvent dans FEATURE_MATRIX.json et le tableau rendu dans FEATURE_MATRIX.md.

Légende des statuts

Statut Signification
Pass La sonde s’est exécutée et correspond au comportement attendu
Fail La sonde s’est exécutée, mais le comportement attendu n’a pas été obtenu
Unavailable La commande du fournisseur n’était pas disponible dans cet environnement

Sections

La matrice est organisée en six sections :

  1. Surface de compatibilité rg : chaque sonde est exécutée à la fois avec le binaire amont rg et bin/rg. Les deux doivent Pass pour que la ligne soit marquée comme prise en charge.
  2. Surface de compatibilité sg : chaque sonde est exécutée à la fois avec le binaire amont sg et bin/sg. Les deux doivent Pass pour que la ligne soit marquée comme prise en charge.
  3. Surface propre au wrapper sg : sondes qui ciblent uniquement bin/sg (fonctionnalités supplémentaires exposées par le wrapper, absentes de ast-grep lui-même).
  4. Surface native greph : sondes qui exercent directement bin/greph. Aucun outil amont n’est disponible pour comparaison ; les sondes vérifient le comportement attendu dans l’espace de travail de test.
  5. Surface greph indexée : sondes qui exercent bin/greph-index (compilation, actualisation et recherche textuelle avec index préchauffé).
  6. Surface de la bibliothèque AST indexée : sondes qui appellent PHP API (Greph::buildAstIndex(), Greph::searchAstIndexed(), Greph::buildAstCache(), Greph::searchAstCached()) et vérifient la compilation, la recherche et l’actualisation.

Régénérer la matrice

Shell
php bin/feature-matrix

Exécutez-le depuis un clone du dépôt avec rg et sg sur le PATH ; bin/feature-matrix ne fait pas partie du paquet Composer. Le script crée l’espace de travail de test, exécute chaque sonde de compatibilité avec le binaire amont (s’il est installé) et avec le wrapper Greph, consigne le résultat structuré et écrit FEATURE_MATRIX.json et FEATURE_MATRIX.md. Passez --stdout pour afficher le Markdown sans écrire de fichier.

Les fichiers suivis sont régénérés manuellement ; l’intégration continue ne les régénère pas. La suite PHPUnit exécutée par l’intégration continue comprend un test qui génère la matrice en indiquant que les outils amont sont indisponibles et vérifie la structure du rapport. Ainsi, l’échec d’une seule sonde ne fait pas échouer l’intégration continue. Régénérez la matrice et vérifiez les différences avant une version.

Contenu de la matrice et documentation

La référence CLI et les pages Compatibilité / rg et Compatibilité / sg décrivent la surface prévue. La matrice des fonctionnalités consigne la surface vérifiée, avec les arguments exacts des sondes à côté de chaque ligne.

Si une fonctionnalité est documentée, mais absente de la matrice, la documentation est obsolète. Si elle figure dans la matrice, mais pas dans la documentation, celle-ci doit être complétée. Les deux doivent correspondre.

Exemples de lignes

Compatibilité rg (extrait)

Fonctionnalité rg bin/rg Notes
Recherche à chaîne fixe Réussite Réussite Sonde : -F needle single.txt
Recherche à chaîne fixe sans distinction de casse Réussite Réussite Sonde : -F -i needle single.txt
Recherche de mot entier Réussite Réussite Sonde : -F -w needle words.txt
Filtre glob Réussite Réussite Sonde : --glob *.php function .
Fichiers cachés Réussite Réussite Sonde : --hidden -F secret .
Sortie JSON structurée Réussite Réussite Sémantique d’événements ripgrep JSON utilisée par la sonde --json -F needle single.txt

Compatibilité sg (extrait)

Fonctionnalité sg bin/sg Notes
Recherche de motif avec run --pattern Réussite Réussite Sonde : run --pattern array($$$ITEMS) src/App.php
Réécriture avec run --rewrite Réussite Réussite Sonde : run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] src/App.php
Sortie du flux JSON structuré Réussite Réussite Sonde : run --json=stream --pattern dispatch($EVENT) src/App.php
Réécriture de toutes les occurrences Réussite Réussite Sonde : run --pattern array($$$ITEMS) --rewrite [$$$ITEMS] --update-all src/App.php

Pour consulter le tableau complet, voir FEATURE_MATRIX.md.

Pourquoi utiliser des sondes

Un tableau de compatibilité tenu à jour manuellement finit par diverger. L’objectif des wrappers est de « les utiliser à la place de rg ou sg et continuer à travailler comme avant ». Le seul moyen de tenir cette promesse consiste à exécuter l’outil amont et le wrapper côte à côte et à comparer leurs résultats. C’est exactement ce que fait le programme de sondes à chaque régénération de la matrice.