ast-grep — busca estrutural de código

ast-grep

Fluxo de Trabalho

1. Escreva um snippet de teste representando o código alvo
2. Escreva a regra (comece com pattern, evolua para kind + has/inside se necessário)
3. Teste com --stdin antes de buscar no código
4. Busque no código assim que a regra corresponder

Armadilhas Críticas

Sempre use stopBy: end em regras relacionais

Sem isso, has/inside param no primeiro nó não correspondente em vez de percorrer toda a subárvore:

# ERRADO — não encontrará correspondências aninhadas profundamente
has:
  pattern: await $EXPR

# CERTO
has:
  pattern: await $EXPR
  stopBy: end

Escape metavariáveis no shell

$VAR é interpretado pelo shell. Escape ou use aspas simples:

# Com aspas duplas: escape com barra invertida
ast-grep scan --inline-rules "id: test
language: javascript
rule:
  pattern: await \$EXPR" .

# Com aspas simples: nenhum escape necessário
ast-grep scan --inline-rules 'id: test
language: javascript
rule:
  pattern: await $EXPR' .

Metavariáveis devem ser o conteúdo único de um nó AST

Isso não funciona: obj.on$EVENT, "Hello $WORLD", a $OP b, $jq

Use $$OP para nós não nomeados (operadores, pontuação). Use $$$ARGS para zero ou mais nós.

Testando com --stdin

echo "async function test() { await fetch(); }" | ast-grep scan --inline-rules 'id: test
language: javascript
rule:
  kind: function_declaration
  has:
    pattern: await $EXPR
    stopBy: end' --stdin

Depurando com --debug-query

Quando as regras não correspondem, inspecione a AST para encontrar os valores corretos de kind:

ast-grep run --pattern 'your code here' --lang javascript --debug-query=cst

Formatos: cst (todos os nós), ast (apenas nomeados), pattern (como o ast-grep vê seu padrão).

Sintaxe de regras

Veja references/rule_reference.md para a referência completa de regras (regras atômicas, relacionais, compostas e metavariáveis).