mcpField
A
ast-grep

ast-grep

github.com/potetoDevelopment590268 installsUpdated 33w ago
Repository

About ast-grep

A skill for writing and debugging ast-grep rules to search code by syntax. It guides rule construction, testing with `--stdin`, and inspection of AST query details.

Key features

  1. 01Build rules from test snippets
  2. 02Test rules with `--stdin`
  3. 03Inspect queries with `--debug-query`
  4. 04Handle relational-rule traversal
  5. 05Escape shell metavariables correctly

Use cases

  1. 01Find syntax patterns in a codebase
  2. 02Check a rule before repository-wide searches
  3. 03Debug rules that miss nested nodes

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/poteto/noodle --skill ast-grep

After installing, type/ast-grepin Claude Code to confirm it loaded.

Bundled filesreferences/rule_reference.md

Details

From the project README

ast-grep

Workflow

  1. Write a test snippet representing the target code
  2. Write the rule (start with pattern, escalate to kind + has/inside if needed)
  3. Test with --stdin before searching the codebase
  4. 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).

Comments

Markdown supported