ast-grep

sg (também instalado como ast-grep) é uma ferramenta de busca e reescrita ciente de AST em 25 idiomas. Ele trata seu padrão como código, o analisa da mesma forma que analisa seu projeto e corresponde estruturalmente. É a ferramenta certa sempre que sua pergunta depende da forma do código em vez de bytes de texto.

Esta habilidade envia um wrapper Python em scripts/ast_grep_helper.py e scripts de instalação de plataforma em install.sh (POSIX) e install.ps1 (Windows). O helper adiciona validação de padrão offline, o truque de reescrita de duas passagens e resolução automática de binários. Use-o como seu ponto de entrada padrão.

Nativo OmO: as ferramentas MCP ast-grep (caminho mais rápido, sem CLI necessário)

O OmO nativo também registra um servidor MCP ast-grep agrupado. Suas três ferramentas são adiadas: elas estão ausentes da lista de ferramentas residentes e ativam automaticamente na primeira vez que você as chama pelo nome — sem necessidade de viagem de ida e volta tool_search.

• mcp__ast_grep_search({ pattern, language, paths }) — busca de forma AST, o equivalente MCP de sg run -p. Prefira isso em vez de usar o shell para sg para pesquisas pontuais: sem instalação, sem problemas de PATH.
• mcp__ast_grep_rewrite({ pattern, rewrite, language, paths, apply }) — visualiza correspondências (apply: false, o padrão) ou aplica a reescrita (apply: true). Mesma disciplina de duas passagens que sg run -r: visualize primeiro, depois aplique.
• mcp__ast_grep_scan({ paths }) — executa regras YAML de projeto (sgconfig.yml, rules/), o equivalente MCP de sg scan.

Mesma linguagem de padrão que a CLI: $VAR corresponde a um nó AST, $$$VAR corresponde a zero ou mais, e o padrão é código, não regex. paths aceita uma lista de arquivos ou diretórios; language é necessário para padrões que são ambíguos entre idiomas.

Quando usar esta habilidade

Use-a sempre que a pergunta do usuário for sobre estrutura de código, não bytes:

• "Encontre todas as funções que recebem um parâmetro Request."
• "Reescreva todos os console.log(x) para logger.info(x)."
• "Remova todas as conversões as any."
• "Substitua require(...) por import em todo o repositório."
• "Encontre blocos catch vazios."
• "Migre Optional[X] para X | None."
• "Aplique este codemod em estes 200 arquivos."
• "Execute nossas regras de lint YAML e exiba as violações."

Mude para grep / rg simples quando a pergunta for em formato de texto (conteúdo de literais de string, comentários, cabeçalhos de licença, nomes de arquivos, regex entre idiomas). Em caso de dúvida, pergunte: "a resposta depende da árvore de sintaxe do idioma, ou apenas dos bytes do arquivo?" Se for o primeiro, ast-grep. Se for o último, grep.

Três coisas que o agente deve internalizar

1. ast-grep NÃO é regex

Os curingas são $VAR (um nó AST) e $$$ (zero ou mais nós). A sintaxe regex falha silenciosamente:

A tabela completa de antipadrões está em references/pitfalls.md §1. O helper validate pega esses problemas mecanicamente — chame-o antes de depurar "sem correspondências" manualmente.

2. Padrões devem ser código válido

O próprio padrão deve ser analisável. def $FN($$$): falha porque o : final o torna incompleto; use def $FN($$$). function $NAME sem parâmetros/corpo falha; use function $NAME($$$) { $$$ }. Tabela completa por idioma em references/pitfalls.md §2.

3. --update-all e --json são mutuamente exclusivos (silenciosamente)

Este é o maior problema ao scriptar. sg run -p P -r R --json --update-all retorna o JSON, mas não modifica os arquivos. Para visualizar E aplicar, execute duas passagens:

sg run -p P -r R --json=compact .   # pass 1: see what would change
sg run -p P -r R --update-all .     # pass 2: actually apply

O helper faz isso automaticamente quando você chama replace --apply. Leia references/pitfalls.md §9.

O script helper — scripts/ast_grep_helper.py

Um wrapper Python 3 de arquivo único da biblioteca padrão. O mesmo em todos os sistemas operacionais. O ponto de entrada padrão do agente.

search — encontra todas as correspondências de um padrão

python3 scripts/ast_grep_helper.py search 'console.log($MSG)' --lang ts src/

Valida o padrão offline primeiro. Se o padrão parecer regex (\w, .*, |, etc.), o helper sai com uma dica e nunca chama sg — economiza uma viagem de ida e volta. Passe --force para pular a validação.

Flags:

…