# Compatibilidad con sg

`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](https://greph.inline0.dev/es/docs/advanced/feature-matrix).

## 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

```bash
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:

```bash
./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](https://greph.inline0.dev/es/docs/modes/ast) para ver la referencia completa.

```bash
./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:

```bash
# 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:

```bash
./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](https://greph.inline0.dev/es/docs/advanced/feature-matrix). 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](https://greph.inline0.dev/es/docs/advanced/feature-matrix) 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.