tool-ast-grep

name	tool-ast-grep
description	Use ast-grep for structural code search and rewrite based on syntax trees. Trigger when text search is too imprecise for code-aware matching.

tool-ast-grep

When To Use

• Perform syntax-aware code search where regex is too noisy.
• Apply structural refactors with AST-level metavariables.
• Match multi-line language constructs safely.

Trusted Commands

sg --pattern 'console.log($ARG)' --lang ts
sg --pattern 'useEffect($FN, [])' --lang tsx src/
sg --pattern 'console.log($ARG)' --rewrite 'logger.info($ARG)' --lang ts
sg --pattern '$X' --rewrite '$Y' --lang ts --interactive
sg --pattern 'def $NAME($$$ARGS): $$$BODY' --lang python
sg --json --pattern 'print($$$ARGS)' --lang python .

Safe Defaults

• Always set --lang explicitly for predictable parsing.
• Start with search-only patterns before rewrite mode.
• Review every rewrite in git diff before staging.

Common Pitfalls

• Binary name is sg, not ast-grep.
• $VAR matches one node; $$$VARS matches multiple nodes.
• Parse failures in malformed files can hide expected matches.

Output Interpretation

• Default output includes file and location for each match.
• --json returns structured match objects with range and bindings.

Why It Matters For Agents

• Enables safe refactors that understand syntax nesting and boundaries.
• Greatly reduces false positives compared with regex replacements.

Repo Conventions

• Prefer ast-grep over text replacement for semantic code edits.
• Keep rewrite patterns narrow and validated against sample files.

Trigger Examples

• Should trigger: "Replace all Python print(...) calls with logger calls structurally."
• Should trigger: "Find functions missing docstrings by syntax pattern."
• Should not trigger: "Download a binary release artifact over HTTP."