Code Search & Refactoring Tools

ast-grep vs ripgrep

When to Use ast-grep

Use ast-grep when structure matters. It parses code and matches AST nodes, so results ignore comments/strings, understand syntax, and can safely rewrite code.

Best for:

• Refactors/codemods: rename APIs, change import forms, rewrite call sites or variable kinds
• Policy checks: enforce patterns across a repo (scan with rules + test)
• Editor/automation: LSP mode; --json output for tooling
• Any operation where you'll apply changes to code

When to Use ripgrep

Use ripgrep when text is enough. It's the fastest way to grep literals/regex across files.

Best for:

• Recon: find strings, TODOs, log lines, config values, or non‑code assets
• Pre-filter: narrow candidate files before a precise pass
• Quick searches where you just need to find text

Rule of Thumb

• Need correctness over speed, or you'll apply changes → start with ast-grep
• Need raw speed or you're just hunting text → start with rg
• Often combine: rg to shortlist files, then ast-grep to match/modify with precision

Usage Examples

ast-grep Examples

Find structured code (ignores comments/strings):

ast-grep run -l TypeScript -p 'import $X from "$P"'

Codemod (only real var declarations become let):

ast-grep run -l JavaScript -p 'var $A = $B' -r 'let $A = $B' -U

Find function calls with specific patterns:

ast-grep run -l Python -p 'logger.$METHOD($$$ARGS)'

Replace with transformation:

ast-grep run -l TypeScript \
  -p 'useQuery($ARGS)' \
  -r 'useSuspenseQuery($ARGS)' \
  -U

ripgrep Examples

Quick textual hunt:

rg -n 'console\.log\(' -t js

Find in specific file types:

rg 'TODO|FIXME' -t py -t js

Context around matches:

rg -C 3 'error' -t log

List files with matches:

rg -l 'import.*React' -t tsx

Combined Approach

Speed + Precision: Use rg to find candidates, then ast-grep for precise operations:

rg -l -t ts 'useQuery\(' | xargs ast-grep run -l TypeScript \
  -p 'useQuery($A)' \
  -r 'useSuspenseQuery($A)' \
  -U

Mental Model

Aspect	ast-grep	ripgrep
Unit of match	AST node	Line
False positives	Low (understands syntax)	Depends on regex
Rewrites	First-class, safe	Requires sed/awk, risky
Speed	Slower (parses code)	Fastest (text only)
Use case	Structural search/refactor	Text search/grep

Quick Decision Tree

Need to modify code?
├─ Yes → ast-grep (safe, structural rewrites)
└─ No
   ├─ Searching code structure? → ast-grep (accurate)
   └─ Just finding text? → ripgrep (fastest)

Common Patterns

Finding all function definitions

# ast-grep (language-aware)
ast-grep run -l Python -p 'def $NAME($$$PARAMS): $$$BODY'

# ripgrep (text-based, faster but less precise)
rg '^def \w+\(' -t py

Refactoring API calls

# ast-grep: Safe, precise
ast-grep run -l JavaScript \
  -p 'axios.get($URL)' \
  -r 'fetch($URL)' \
  -U

# ripgrep: Don't use for rewrites (will match in comments/strings)

Finding TODOs

# ripgrep: Perfect for this
rg 'TODO:|FIXME:' --color=always

# ast-grep: Overkill for text search