bcowdery AST-Aware Code Refactoring
Overview
Transform code patterns systematically using ast-grep, a syntax-aware tool that finds and replaces code based on abstract syntax trees rather than plain text matching.
When to Use
Use this skill when:
- Renaming functions, classes, or variables across the codebase
- Migrating API usage patterns (e.g.,
console.log→logger.info) - Modernizing syntax (e.g.,
var→const,require→import) - Replacing deprecated function calls with new equivalents
- Restructuring code architecture (moving, splitting, combining modules)
- Performing bulk transformations that require syntax awareness
Do NOT use this skill for:
- Searching/exploring code without transformations (use
ast-searchinstead) - Simple text replacements in non-code files (use sed/grep)
- Single-file edits with no pattern repetition (use Edit tool directly)
- Non-structural changes (comments, formatting)
- Bug fixes that don't involve pattern transformation
Quick Reference
# Check if ast-grep is installed
which ast-grep
# Find pattern
ast-grep --pattern 'function $FUNC($$$PARAMS) { $$$ }' --lang javascript
# Search and replace
ast-grep run -p 'var $VAR = $VAL' -r 'const $VAR = $VAL' -l javascript
# Interactive mode
ast-grep run -p 'PATTERN' -r 'REPLACEMENT' -l LANG --interactive
Pattern Syntax
| Pattern | Matches |
|---|---|
$VAR |
Single AST node (variable, expression, etc.) |
$$$ARGS |
Multiple nodes (function arguments) |
$$$ |
Any sequence of nodes within a block |
Workflow
Phase 1: Discovery & Analysis
- Understand the Request: Clarify what structure to refactor
- Find Current Usage: Use ast-grep to discover all instances
- Assess Impact: Count affected files/locations, identify dependencies
# Example: Find all class definitions
ast-grep --pattern 'class $CLASS { $$$ }' --lang typescript
Phase 2: Planning
- Design Transformation: Define find pattern and replacement pattern
- Create Plan: Summarize what/why/impact with before/after examples
Plan format:
## Refactoring Plan: [Title]
**Goal**: [1-2 sentences]
**Impact**: [X files, Y instances]
**Pattern Match**:
```typescript
// Current pattern
Transform To:
// New pattern
Architecture (if applicable):
Current: New:
┌─────────┐ ┌─────────┐
│ Module │ ──────▶ │ Module │
└─────────┘ └─────────┘
Additional Steps: [Manual changes needed]
### Phase 3: User Feedback
1. Present plan with options if multiple approaches exist
2. Gather feedback using AskUserQuestion for architectural decisions
3. Confirm approach before proceeding
### Phase 4: Execution
1. **Verify Git State**: Ensure clean working tree or user acknowledges changes
2. **Apply Transformations**:
```bash
# Simple pattern replacement
ast-grep run -p 'console.log($MSG)' -r 'logger.info($MSG)' -l typescript
# Interactive for careful review
ast-grep run -p 'PATTERN' -r 'REPLACEMENT' -l LANG --interactive
- Verify Changes: Run tests, type checkers, linters
- Document Results: Summarize changes and any remaining manual work
ast-grep Commands
Basic Search
ast-grep --pattern 'useState($$$)' --lang typescript
ast-grep -p 'function $F() { $$$ }' -l javascript -A 3 -B 2
Search & Replace
ast-grep run -p 'var $VAR = $VAL' -r 'const $VAR = $VAL' -l javascript
Rule-Based Refactoring
# rule.yml
id: modernize-hasOwnProperty
language: typescript
rule:
pattern: $OBJ.hasOwnProperty($PROP)
fix: Object.hasOwn($OBJ, $PROP)
message: Use Object.hasOwn instead
ast-grep scan -r rule.yml --update-all
Supported Languages
JavaScript, TypeScript, Python, Go, Rust, Java, C, C++, C#, Kotlin, Swift, Ruby, PHP, and more.
Common Mistakes
| Mistake | Solution |
|---|---|
| Not checking ast-grep installation | Run which ast-grep first, install with brew install ast-grep |
| Running on dirty git state | Verify clean state or get user acknowledgment first |
| Skipping interactive mode for large changes | Use --interactive for 50+ file changes |
| Pattern doesn't match comments/strings | This is correct behavior - ast-grep is syntax-aware |
| Not running tests after | Always verify with tests/type-checker after refactoring |
| Assuming single pass works | Complex refactoring may need multiple ast-grep passes |
Safety Guidelines
- Never run destructive refactoring without user approval
- Always show transformation plan with examples before executing
- Use
--interactiveor--dry-runmodes for significant changes - Verify tests pass after refactoring
- For large refactorings (50+ files), suggest incremental approach
- Work with clean git state, commit refactoring separately from logic changes
Troubleshooting
- Pattern not matching: Verify language flag, check AST structure
- Partial matches: May need multiple patterns for variants
- Syntax errors after refactor: Some edge cases need manual intervention
- Tool not found: Install with
brew install ast-grep