ast-grep

ast-grep Structural Search

Use ast-grep when the user needs code structure, not just text. The useful outcome is a validated rule plus a clear statement of what it matches and what it may miss.

Triage

Start with the smallest tool that can answer the question.

• Use rg for exact names, strings, comments, or simple text.
• Use language tooling for semantic facts such as type resolution, references, imports, or rename safety.
• Use ast-grep for syntax shape: descendants, ancestors, call forms, decorators, missing constructs, nested contexts, or multi-language structural searches.

If ast-grep is not installed, say so and offer an rg fallback only when the fallback will not pretend to be structural.

Workflow

1. Identify the language and target files.

   • Infer from paths and extensions when possible.
   • Ask only if the language or include/exclude scope cannot be inferred.

2. Write a tiny fixture before searching the real repository.

   • Include at least one positive example.
   • Add a negative example when false positives would be costly.

3. Start with the simplest pattern.

   • Use ast-grep run --pattern ... --lang ... for a single-node search.
   • Move to a YAML rule when the search needs has, inside, not, any, all, regex, nthChild, or reusable metadata.

4. Debug the parsed structure when the first rule misses.

   • Use ast-grep run --pattern '<sample code>' --lang <lang> --debug-query=ast.
   • --debug-query prints diagnostic output and may exit non-zero; treat the printed tree as useful debug output, not as a failed repository search.

5. Validate on the fixture before running on the repository.

   • Keep the rule as simple as possible until it matches the fixture.
   • Then scan the real path and report expected false-negative boundaries.

6. Report the final rule, command, and caveats.

   • Name node kinds or language constructs intentionally excluded.
   • Prefer JSON output when a downstream script will consume matches.