ast-grep

ast-grep Community Best Practices

Comprehensive best practices guide for ast-grep rule writing and usage, maintained by the ast-grep community. Contains 46 rules across 8 categories, prioritized by impact to guide automated rule generation and code transformation.

When to Apply

Reference these guidelines when:

• Writing new ast-grep rules for linting or search
• Debugging patterns that don't match expected code
• Optimizing rule performance for large codebases
• Setting up ast-grep projects with proper organization
• Reviewing ast-grep rules for correctness and maintainability

General Workflow

Follow this workflow when creating ast-grep rules for code search:

Step 1: Understand the Query

Clarify what you want to find:

• Target programming language
• Edge cases to handle
• What to include vs exclude

Step 2: Create Example Code

Write a sample code snippet representing the desired match pattern.

Step 3: Write the ast-grep Rule

Choose the right approach:

• Use pattern for simple structures
• Use kind with has/inside for complex structures
• Combine with all, any, or not for compound queries
• Always use stopBy: end for relational rules (inside, has) to ensure complete search

Step 4: Test the Rule

# Inspect AST structure
ast-grep run --pattern '[code]' --lang [language] --debug-query=ast

# Test inline rule
echo "[code]" | ast-grep scan --inline-rules "[rule]" --stdin

# Test from file
ast-grep scan --rule [file.yml] [path]

Step 5: Search the Codebase

Deploy the validated rule:

# Search with pattern (simple matches)
ast-grep run --pattern '[pattern]' --lang [language] [path]

# Search with rule file (complex queries)
ast-grep scan --rule [file.yml] [path]

# Apply fixes interactively
ast-grep scan --rule [file.yml] --interactive [path]

Quick Tips

1. Always use stopBy: end - Ensures complete subtree traversal for relational rules
2. Start simple, add complexity - Begin with patterns, progress to kinds, then relational rules
3. Debug with AST inspection - Use --debug-query=ast to verify structure matching
4. Escape in inline rules - Use \$VAR or single quotes for shell commands
5. Test in playground first - Use https://ast-grep.github.io/playground.html for rapid iteration