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.

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

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:

./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 para ver a referência completa.

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

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

./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

Interface verificada

Os sinalizadores a seguir foram verificados em relação ao binário upstream sg na matriz de recursos. 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 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.