Aller au contenu

Compatibilité avec sg

Afficher au format Markdown Modifier sur GitHub Documentation de d105217

vendor/bin/sg est une enveloppe de compatibilité de type ast-grep. Elle accepte les options ast-grep les plus couramment utilisées et réutilise le même moteur Greph\Ast\AstSearcher qu’utilise vendor/bin/greph -p. Les fonctionnalités vérifiées sont reproduites à partir de tests exploratoires du binaire sg en amont et sont répertoriées dans Avancé / Matrice des fonctionnalités.

Quand l’utiliser

Utilisez l’enveloppe si :

  • Vous avez déjà un outil, un agent ou un script qui appelle sg.
  • Vous voulez un remplacement direct qui fonctionne dans des environnements où vous ne pouvez pas installer ast-grep lui-même.
  • Vous souhaitez bénéficier de l’ergonomie de ast-grep avec une installation limitée à Composer.

Utilisez vendor/bin/greph -p en natif si :

  • Vous écrivez du nouveau code et n’avez pas besoin de la forme ast-grep CLI.
  • Vous voulez le même ensemble d’options qu’en mode texte (le binaire natif unifie les deux modes).

Utilisation

Shell
sg run --pattern PATTERN [options] [path...]
sg scan -p PATTERN [options] [path...]
sg rewrite -p PATTERN -r TEMPLATE [options] [path...]

run est la commande canonique de type ast-grep. scan et rewrite sont des alias réservés à l’enveloppe, qui reprennent les usages courants. Un appel sans argument lance une recherche ponctuelle :

Shell
./vendor/bin/sg --pattern 'array($$$ITEMS)' src

Modèles de blocs

La grammaire des motifs est identique à celle de la recherche AST native. Consultez Modes / Recherche AST pour la référence complète.

Shell
./vendor/bin/sg run --pattern 'array($$$ITEMS)' src
./vendor/bin/sg run --pattern '$obj->$method($$$ARGS)' src
./vendor/bin/sg run --pattern 'new $CLASS()' src

Réécritures

L’enveloppe prend en charge le même flux de travail de simulation, interactif et d’écriture que la réécriture native, avec des noms d’options ast-grep :

Shell
# Preview only (default)
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' src

# Apply without confirmation
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --update-all src

# Confirm each match
./vendor/bin/sg run --pattern 'array($$$ITEMS)' --rewrite '[$$$ITEMS]' --interactive src

# Wrapper-only aliases
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --dry-run src
./vendor/bin/sg rewrite -p 'array($$$ITEMS)' -r '[$$$ITEMS]' --interactive src

Sortie JSON

--json émet des ast-grep de forme JSON. Trois styles sont pris en charge :

Shell
./vendor/bin/sg run --json --pattern 'dispatch($EVENT)' src
./vendor/bin/sg run --json=stream --pattern 'dispatch($EVENT)' src
./vendor/bin/sg run --json=compact --pattern 'dispatch($EVENT)' src
Style Structure
--json (pretty par défaut) Tableau JSON unique joliment mis en forme
--json=stream Une correspondance par ligne, en JSON délimité par des sauts de ligne
--json=compact Tableau JSON unique et compact

Fonctionnalités vérifiées

Les options suivantes ont été vérifiées par rapport au binaire sg en amont dans la matrice des fonctionnalités. Lorsqu’une option possède deux formes (-p et --pattern, --glob et --globs), le test en utilise une seule et l’enveloppe les interprète toutes deux comme la même option.

Options de motif

  • --pattern PATTERN (au niveau supérieur et dans run)
  • -p PATTERN (alias)
  • --rewrite TEMPLATE
  • -r TEMPLATE
  • --lang NAME, -l NAME

Options de correspondance

  • --files-with-matches
  • --json (pretty, stream, compact)
  • --update-all, -U

Options de parcours

  • --no-ignore hidden (forme combinée)
  • --glob GLOB, --globs GLOB

Options de processus de travail

  • -j N, --threads N

Options acceptées sans test

L’enveloppe accepte également les options suivantes, qui ne sont toutefois pas encore couvertes par un test de la matrice des fonctionnalités :

  • --no-ignore seul ou avec une valeur autre que hidden
  • --type NAME, --type-not NAME

Options supplémentaires de l’enveloppe

L’enveloppe propose quelques utilitaires que ast-grep ne possède pas :

  • Alias scan et rewrite pour run
  • Option --hidden (ast-grep l’intègre à --no-ignore hidden)
  • Alias --dry-run pour prévisualiser les réécritures
  • Flux de confirmation des réécritures --interactive

Limites

L’enveloppe sg de Greph couvre les fonctionnalités de recherche structurelle et de réécriture utilisées par la plupart des outils et agents. Elle ne propose actuellement pas les fonctionnalités ast-grep suivantes :

  • Fichiers de règles YAML (--rule, --config)
  • Analyse multilingue au-delà de PHP
  • Transformateurs autres que par motifs (--debug-query, --inspect)
  • Intégration LSP

Si une option vous manque, signalez le problème en indiquant le test exécuté sur sg en amont et le résultat attendu.

Parité de comportement

L’enveloppe vise la parité de comportement, pas la parité octet par octet. La sortie est sémantiquement équivalente, mais certains détails visuels peuvent différer. Les tests utilisés dans la matrice des fonctionnalités vérifient l’équivalence des champs pertinents pour l’analyse (chemin du fichier, numéro de ligne, code capturé, captures, structure JSON), et non celle du flux d’octets.