# Compatibilidade com sg

`vendor/bin/sg` é um wrapper de compatibilidade no estilo ast-grep. Ele aceita os sinalizadores `ast-grep` mais usados e reutiliza o mesmo mecanismo `Greph\Ast\AstSearcher` usado por `vendor/bin/greph -p`. A interface verificada foi reproduzida a partir de sondagens do binário upstream `sg` e está em [Avançado / Matriz de recursos](https://greph.inline0.dev/pt/docs/advanced/feature-matrix).

## Quando usar

Use o wrapper quando:

- Você tem uma ferramenta, um agente ou um script existente que já chama `sg`.
- Você quer uma substituição direta que funcione em ambientes nos quais não é possível instalar `ast-grep`.
- Você quer a praticidade de ast-grep em uma instalação que só oferece Composer.

Use `vendor/bin/greph -p` nativo quando:

- Você está escrevendo código novo e não precisa do formato ast-grep CLI.
- Você quer o mesmo conjunto de sinalizadores do modo de texto (o binário nativo unifica os dois).

## Uso

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

`run` é o verbo canônico de ast-grep. `scan` e `rewrite` são aliases exclusivos do wrapper que refletem o uso comum. Uma chamada sem argumentos funciona como pesquisa pontual:

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

## Padrões

A gramática dos padrões é idêntica à da pesquisa AST nativa. Consulte [Modos / Pesquisa AST](https://greph.inline0.dev/pt/docs/modes/ast) para ver a referência 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
```

## Reescritas

O wrapper oferece o mesmo fluxo de trabalho de simulação / interação / gravação que a reescrita nativa, com nomes de sinalizadores 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
```

## Saída JSON

`--json` emite ast-grep no formato de JSON. Há suporte para três 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` (padrão `pretty`) | Uma única matriz JSON bem formatada |
| `--json=stream` | Uma correspondência por linha, delimitada por quebras de linha JSON |
| `--json=compact` | Uma única matriz JSON compacta |

## Interface verificada

Os sinalizadores a seguir foram verificados em relação ao binário upstream `sg` na [matriz de recursos](https://greph.inline0.dev/pt/docs/advanced/feature-matrix). Quando um sinalizador tem duas formas (`-p` e `--pattern`, `--glob` e `--globs`), a sondagem usa uma delas e o wrapper interpreta ambas como a mesma opção.

### Sinalizadores de padrão

- `--pattern PATTERN` (no nível superior e dentro de `run`)
- `-p PATTERN` (alias)
- `--rewrite TEMPLATE`
- `-r TEMPLATE`
- `--lang NAME`, `-l NAME`

### Sinalizadores de correspondência

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

### Sinalizadores do percurso

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

### Sinalizadores de workers

- `-j N`, `--threads N`

### Aceitos sem sondagem

O wrapper também aceita estes sinalizadores, mas nenhuma sondagem da matriz de recursos os cobre ainda:

- `--no-ignore` sozinho ou com um valor diferente de `hidden`
- `--type NAME`, `--type-not NAME`

### Recursos exclusivos do wrapper

O wrapper oferece alguns recursos auxiliares que o próprio ast-grep não tem:

- Aliases `scan` e `rewrite` para `run`
- Sinalizador `--hidden` (ast-grep inclui essa opção em `--no-ignore hidden`)
- Alias `--dry-run` para visualizar reescritas
- Fluxo de confirmação de reescrita `--interactive`

## Limitações

O wrapper de `sg` de Greph cobre a interface de pesquisa estrutural e reescrita usada pela maioria das ferramentas e agentes. No momento, não oferece os seguintes recursos ast-grep:

- Arquivos de regras YAML (`--rule`, `--config`)
- Varredura em várias linguagens além de PHP
- Transformadores que não usam padrões (`--debug-query`, `--inspect`)
- Integração LSP

Se estiver faltando um sinalizador, abra uma issue com a sondagem executada no `sg` upstream e a saída esperada.

## Paridade de comportamento

O wrapper busca paridade de comportamento, não paridade byte a byte. A saída é semanticamente equivalente, mas pode diferir em detalhes visuais. As sondagens usadas na [matriz de recursos](https://greph.inline0.dev/pt/docs/advanced/feature-matrix) verificam a equivalência dos campos relevantes para o analisador (caminho do arquivo, número da linha, código capturado, capturas, formato JSON), e não do fluxo de bytes.