Saltar al contenido

Compatibilidad con sg

Ver como Markdown Editar en GitHub Documentación de d105217

vendor/bin/sg es un envoltorio de compatibilidad al estilo de ast-grep. Acepta las opciones ast-grep más utilizadas y reutiliza el mismo motor Greph\Ast\AstSearcher que emplea vendor/bin/greph -p. La interfaz verificada se reproduce a partir de pruebas de sondeo con el binario original de sg y se encuentra en Avanzado / Matriz de funciones.

Cuándo usarlo

Use el envoltorio cuando:

  • Ya tiene una herramienta, un agente o un script que invoque sg.
  • Quiere un reemplazo directo que funcione en entornos donde no pueda instalar ast-grep.
  • Quiere la facilidad de uso de ast-grep en una instalación que solo tenga Composer.

Use vendor/bin/greph -p de forma nativa cuando:

  • Escriba código nuevo y no necesite la interfaz de ast-grep CLI.
  • Quiera el mismo conjunto de opciones que en el modo de texto (el binario nativo unifica ambos modos).

Uso

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

run es el verbo canónico de ast-grep. scan y rewrite son alias exclusivos del envoltorio que reflejan el uso habitual. También funciona una invocación sin argumentos para realizar una búsqueda puntual:

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

Patrones

La gramática de patrones es idéntica a la de la búsqueda AST nativa. Consulte Modos / Búsqueda AST para ver la referencia completa.

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

Reescrituras

El envoltorio admite el mismo flujo de trabajo de simulación / interacción / escritura que la reescritura nativa, con los nombres de opciones 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

Salida de JSON

--json genera ast-grep con formato de JSON. Admite tres estilos:

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
Estilo Formato
--json (pretty predeterminado) Una sola matriz JSON con formato legible
--json=stream Una coincidencia por línea, con delimitación de saltos de línea JSON
--json=compact Una sola matriz JSON compacta

Interfaz verificada

Las siguientes opciones se han verificado con el binario original de sg en la matriz de funciones. Si una opción tiene dos formas (-p y --pattern, --glob y --globs), la prueba usa una de ellas y el envoltorio interpreta ambas como la misma opción.

Opciones de patrón

  • --pattern PATTERN (en el nivel superior y dentro de run)
  • -p PATTERN (alias)
  • --rewrite TEMPLATE
  • -r TEMPLATE
  • --lang NAME, -l NAME

Opciones de coincidencia

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

Opciones del recorrido

  • --no-ignore hidden (forma combinada)
  • --glob GLOB, --globs GLOB

Opciones de procesos de trabajo

  • -j N, --threads N

Aceptadas sin una prueba

El envoltorio también acepta estas opciones, pero todavía no hay pruebas de la matriz de funciones que las cubran:

  • --no-ignore por sí sola o con un valor distinto de hidden
  • --type NAME, --type-not NAME

Funciones adicionales del envoltorio

El envoltorio ofrece algunas utilidades que ast-grep no incluye:

  • Alias scan y rewrite para run
  • Opción --hidden (ast-grep la integra en --no-ignore hidden)
  • Alias --dry-run para previsualizar reescrituras
  • Flujo de confirmación de reescrituras con --interactive

Limitaciones

El envoltorio sg de Greph cubre las funciones de búsqueda estructural y reescritura que usan la mayoría de las herramientas y los agentes. Actualmente no ofrece estas funciones de ast-grep:

  • Archivos de reglas YAML (--rule, --config)
  • Análisis en varios lenguajes además de PHP
  • Transformadores que no usan patrones (--debug-query, --inspect)
  • Integración con LSP

Si necesita una opción que falta, abra una incidencia e incluya la prueba que ejecutó con el sg original y el resultado esperado.

Paridad de comportamiento

El envoltorio busca la paridad de comportamiento, no la paridad byte a byte. La salida es semánticamente equivalente, pero puede diferir en detalles visuales. Las pruebas de la matriz de funciones comprueban la equivalencia de los campos pertinentes para el analizador (ruta del archivo, número de línea, código capturado, capturas, formato JSON), no del flujo de bytes.