ast-grep Code Search

Translate a natural-language query into an ast-grep rule, verify it against a sample, then run it on the codebase. Full rule syntax (atomic/relational/composite rules, metavariables, troubleshooting, worked examples) lives in references/rule_reference.md — read it when writing anything beyond a simple pattern.

Prerequisite

ast-grep --version must work. If missing: brew install ast-grep (macOS), npm i -g @ast-grep/cli, or cargo install ast-grep. Invoke as ast-grep (the sg alias collides with the system sg).

Workflow

1. Clarify — language? exact structure to match? edge cases to include/exclude?
2. Make a sample — write a tiny snippet that should match, save to a temp file.
3. Write the rule — start with the simplest thing that could work, then add complexity:
   • pattern for direct code shapes → kind for node types → relational (has/inside) → composite (all/any/not).
   • Always add stopBy: end to relational rules so they traverse the whole subtree instead of stopping at the first non-match.
4. Test against the sample until it matches (see Debugging below).
5. Run on the codebase once it matches.

Commands