ast-grep
GitHub基于 AST 的结构化代码搜索工具,适用于查找特定代码模式、关系及重构场景。
触发场景
安装
npx skills add poteto/noodle --skill ast-grep -g -y
SKILL.md
Frontmatter
{
"name": "ast-grep",
"description": "Structural code search via ast-grep — use when code shape and element relationships matter, not just text. E.g., \"find async functions without error handling\", \"refactor foo(a, b) to foo({ a, b })\". Use Grep for simple name lookups."
}
ast-grep
Workflow
- Write a test snippet representing the target code
- Write the rule (start with
pattern, escalate tokind+has/insideif needed) - Test with
--stdinbefore searching the codebase - Search the codebase once the rule matches
Critical Gotchas
Always use stopBy: end on relational rules
Without it, has/inside stop at the first non-matching node instead of traversing the full subtree:
# WRONG — will miss deeply nested matches
has:
pattern: await $EXPR
# RIGHT
has:
pattern: await $EXPR
stopBy: end
Escape metavariables in shell
$VAR gets interpreted by the shell. Either escape or single-quote:
# Double-quoted: escape with backslash
ast-grep scan --inline-rules "id: test
language: javascript
rule:
pattern: await \$EXPR" .
# Single-quoted: no escaping needed
ast-grep scan --inline-rules 'id: test
language: javascript
rule:
pattern: await $EXPR' .
Metavariables must be the sole content of an AST node
These don't work: obj.on$EVENT, "Hello $WORLD", a $OP b, $jq
Use $$OP for unnamed nodes (operators, punctuation). Use $$$ARGS for zero-or-more nodes.
Testing with --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
Debugging with --debug-query
When rules don't match, inspect the AST to find correct kind values:
ast-grep run --pattern 'your code here' --lang javascript --debug-query=cst
Formats: cst (all nodes), ast (named only), pattern (how ast-grep sees your pattern).
Rule syntax
See references/rule_reference.md for the full rule reference (atomic, relational, composite rules, and metavariables).
版本历史
- 82d2921 当前 2026-11-19 21:08


