Dotfiles-nix ast-grep

Guide for writing ast-grep rules to perform structural code search and analysis. Use when users need to search codebases using Abstract Syntax Tree patterns, find specific code structures, or perform complex code queries that go beyond simple text search.

install

source · Clone the upstream repo

git clone https://github.com/not-matthias/dotfiles-nix

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/not-matthias/dotfiles-nix "$T" && mkdir -p ~/.claude/skills && cp -r "$T/modules/home/programs/cli-agents/shared/skills/ast-grep" ~/.claude/skills/not-matthias-dotfiles-nix-ast-grep && rm -rf "$T"

manifest: modules/home/programs/cli-agents/shared/skills/ast-grep/SKILL.md

source content

ast-grep Code Search

Overview

This skill helps translate natural language queries into ast-grep rules for structural code search. ast-grep (sg) is a high-performance, polyglot tool (C, C++, Go, HTML, Java, Python, Rust, TS/JS, YAML) that uses Abstract Syntax Tree (AST) patterns to match code based on its structure rather than just text.

When to Use This Skill

Use this skill when users:

Need to search for code patterns using structural matching (e.g., "find all async functions that don't have error handling")
Want to locate specific language constructs (e.g., "find all function calls with specific parameters")
Request searches that require understanding code structure rather than just text
Ask to search for code with particular AST characteristics
Need to perform complex code queries that traditional text search cannot handle

General Workflow

Step 1: Understand the Query

Clearly understand what the user wants to find. Ask clarifying questions if needed:

What specific code pattern or structure are they looking for?
Which programming language?
Are there specific edge cases or variations to consider?
What should be included or excluded from matches?

Step 2: Create Example Code

Write a simple code snippet that represents what the user wants to match. Save this to a temporary file for testing.

Example: If searching for "async functions that use await", create a test file:

// test_example.js
async function example() {
	const result = await fetchData()
	return result
}

Step 3: Write the ast-grep Rule

Translate the pattern into an ast-grep rule. Start simple and add complexity as needed.

Key principles:

Always use
```
stopBy: end
```
for relational rules (
```
inside
```
,
```
has
```
) to ensure search goes to the end of the direction
Use
```
pattern
```
for simple structures
Use
```
kind
```
with
```
has
```
/
```
inside
```
for complex structures
Break complex queries into smaller sub-rules using
```
all
```
,
```
any
```
, or
```
not
```

Example rule file (test_rule.yml):

id: async-with-await
language: javascript
rule:
  kind: function_declaration
  has:
    pattern: await $EXPR
    stopBy: end

See

references/rule_reference.md

for comprehensive rule documentation.

Step 4: Test the Rule

Use ast-grep CLI to verify the rule matches the example code. There are two main approaches:

Option A: Test with inline rules (for quick iterations)

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

Option B: Test with rule files (recommended for complex rules)

ast-grep scan --rule test_rule.yml test_example.js

Debugging if no matches:

Simplify the rule (remove sub-rules)
Add
```
stopBy: end
```
to relational rules if not present
Use
```
--debug-query
```
to understand the AST structure (see below)
Check if
```
kind
```
values are correct for the language

Step 5: Search the Codebase

Once the rule matches the example code correctly, search the actual codebase:

For simple pattern searches:

ast-grep run --pattern 'console.log($ARG)' --lang javascript /path/to/project

For complex rule-based searches:

ast-grep scan --rule my_rule.yml /path/to/project

For inline rules (without creating files):

ast-grep scan --inline-rules "id: my-rule
language: javascript
rule:
  pattern: \$PATTERN" /path/to/project

Rewriting Code with ast-grep

ast-grep is a powerful AST-based tool that can search for code patterns and transform them into new code. It works like a syntax-aware sed/grep that understands code structure rather than just text.

Method 1: Command Line with

--rewrite

The simplest approach is using the

--rewrite

(or

-r

) flag directly in your terminal:

ast-grep run --pattern 'foo' --rewrite 'bar' --lang python

This finds all occurrences of

foo

and replaces them with

bar

. A practical example:

# Convert old-style property checks to optional chaining
ast-grep -p '$PROP && $PROP()' --rewrite '$PROP?.()' --interactive -l ts ./src

Key flags:

```
--interactive
```
or
```
-i
```
: Review each change before applying
```
--update-all
```
or
```
-U
```
: Apply all changes without confirmation

Method 2: YAML Rules with

fix

For more complex transformations, use YAML rule files with the

fix

field:

id: change_def
language: Python
rule:
  pattern: |
    def foo($X):
      $$$S
fix: |-
  def baz($X):
    $$$S

Run with:

ast-grep scan -r rule.yml ./src

Meta-Variables

Meta-variables are the key to powerful rewrites. They act like capture groups in regex:

Meta-variable	Matches
`$NAME`	Any single AST node (expression, identifier, etc.)
`$$$ITEMS`	Multiple nodes (like function arguments)

Example — Swapping assignment sides:

rule:
  pattern: $X = $Y
fix: $Y = $X

Transforms

a = b

into

b = a

Indentation Sensitivity

ast-grep preserves indentation in rewrites. If your fix template has indentation, it's maintained relative to the original code position:

rule:
  pattern: '$B = lambda: $R'
fix: |-
  def $B():
    return $R

Expanding the Match Range with FixConfig

Sometimes you need to delete surrounding characters (like commas). Use

FixConfig

with

expandStart

and

expandEnd

rule:
  kind: pair
  has:
    field: key
    regex: Remove
fix:
  template: ''
  expandEnd: { regex: ',' } # Also deletes trailing comma

This removes the matched node plus any trailing comma.

Advanced Features: Rewriters

For complex multi-node transformations, use

rewriters

to process lists of matched nodes:

id: barrel-to-single
language: JavaScript
rule:
  pattern: import {$$$IDENTS} from './module'
rewriters:
  - id: rewrite-identifier
    rule:
      pattern: $IDENT
      kind: identifier
    transform:
      LIB: { convert: { source: $IDENT, toCase: lowerCase } }
    fix: import $IDENT from './module/$LIB'
transform:
  IMPORTS:
    rewrite:
      rewriters: [rewrite-identifier]
      source: $$$IDENTS
      joinBy: "\n"
fix: $IMPORTS

This converts barrel imports like

import { A, B } from './module'

into individual imports.

Workflow Summary

Find: Use patterns to match AST nodes
Capture: Meta-variables (
```
$VAR
```
,
```
$$$ARGS
```
) capture matched content
Transform: Optionally process captured content (case conversion, regex replacement)
Patch: Replace matched nodes with the
```
fix
```
template

Tips

Use single quotes on command line to prevent shell expansion of
```
$
```
Non-matched meta-variables become empty strings in the fix

ast-grep CLI Commands

Inspect Code Structure (--debug-query)

Dump the AST structure to understand how code is parsed:

ast-grep run --pattern 'async function example() { await fetch(); }' \
  --lang javascript \
  --debug-query=cst

Available formats:

```
cst
```
: Concrete Syntax Tree (shows all nodes including punctuation)
```
ast
```
: Abstract Syntax Tree (shows only named nodes)
```
pattern
```
: Shows how ast-grep interprets your pattern

Use this to:

Find the correct
```
kind
```
values for nodes
Understand the structure of code you want to match
Debug why patterns aren't matching

Example:

# See the structure of your target code
ast-grep run --pattern 'class User { constructor() {} }' \
  --lang javascript \
  --debug-query=cst

# See how ast-grep interprets your pattern
ast-grep run --pattern 'class $NAME { $$$BODY }' \
  --lang javascript \
  --debug-query=pattern

Test Rules (scan with --stdin)

Test a rule against code snippet without creating files:

echo "const x = await fetch();" | ast-grep scan --inline-rules "id: test
language: javascript
rule:
  pattern: await \$EXPR" --stdin

Add --json for structured output:

echo "const x = await fetch();" | ast-grep scan --inline-rules "..." --stdin --json

Search with Patterns (run)

Simple pattern-based search for single AST node matches:

# Basic pattern search
ast-grep run --pattern 'console.log($ARG)' --lang javascript .

# Search specific files
ast-grep run --pattern 'class $NAME' --lang python /path/to/project

# JSON output for programmatic use
ast-grep run --pattern 'function $NAME($$$)' --lang javascript --json .

When to use:

Simple, single-node matches
Quick searches without complex logic
When you don't need relational rules (inside/has)

Search with Rules (scan)

YAML rule-based search for complex structural queries:

# With rule file
ast-grep scan --rule my_rule.yml /path/to/project

# With inline rules
ast-grep scan --inline-rules "id: find-async
language: javascript
rule:
  kind: function_declaration
  has:
    pattern: await \$EXPR
    stopBy: end" /path/to/project

# JSON output
ast-grep scan --rule my_rule.yml --json /path/to/project

When to use:

Complex structural searches
Relational rules (inside, has, precedes, follows)
Composite logic (all, any, not)
When you need the power of full YAML rules

Tip: For relational rules (inside/has), always add

stopBy: end

to ensure complete traversal.

Tips for Writing Effective Rules

Always Use stopBy: end

For relational rules, always use

stopBy: end

unless there's a specific reason not to:

has:
  pattern: await $EXPR
  stopBy: end

This ensures the search traverses the entire subtree rather than stopping at the first non-matching node.

Start Simple, Then Add Complexity

Begin with the simplest rule that could work:

Try a
```
pattern
```
first
If that doesn't work, try
```
kind
```
to match the node type
Add relational rules (
```
has
```
,
```
inside
```
) as needed
Combine with composite rules (
```
all
```
,
```
any
```
,
```
not
```
) for complex logic

Use the Right Rule Type

Pattern: For simple, direct code matching (e.g.,
```
console.log($ARG)
```
)
Kind + Relational: For complex structures (e.g., "function containing await")
Composite: For logical combinations (e.g., "function with await but not in try-catch")

Debug with AST Inspection

When rules don't match:

Use
```
--debug-query=cst
```
to see the actual AST structure
Check if metavariables are being detected correctly
Verify the node
```
kind
```
matches what you expect
Ensure relational rules are searching in the right direction

Escaping in Inline Rules

When using

--inline-rules

, escape metavariables in shell commands:

Use
```
\$VAR
```
instead of
```
$VAR
```
(shell interprets
```
$
```
as variable)
Or use single quotes:
```
'$VAR'
```
works in most shells