structural-search

Search code by AST structure using ast-grep. Find semantic patterns like function calls, imports, class definitions instead of text patterns. Triggers on: find all calls to X, search for pattern, refactor usages, find where function is used, structural search, ast-grep, sg.

⭐3stars🔀0forks📁View on GitHub🕐Updated Dec 27, 2025

When & Why to Use This Skill

This Claude skill enables advanced structural code search and refactoring using ast-grep. Unlike traditional text-based search, it understands the Abstract Syntax Tree (AST) of your code, allowing you to find and transform complex semantic patterns like function definitions, React hooks, and security vulnerabilities across multiple programming languages with high precision.

Use Cases

  • Large-scale Refactoring: Safely migrate APIs or rename variables by matching structural patterns (e.g., changing 'var' to 'const') across an entire codebase without the false positives of regex.
  • Security & Anti-pattern Detection: Identify critical security risks like XSS vectors (innerHTML) or insecure functions (eval), and find code smells such as loose equality operators (==) or missing error handling.
  • Codebase Exploration: Quickly locate specific architectural implementations, such as all instances of a particular React hook usage or specific async/await patterns, to understand complex logic flow.
  • Automated Code Review: Streamline the review process by programmatically scanning for structural violations of team coding standards or identifying deprecated library usages.
namestructural-search
description"Search code by AST structure using ast-grep. Find semantic patterns like function calls, imports, class definitions instead of text patterns. Triggers on: find all calls to X, search for pattern, refactor usages, find where function is used, structural search, ast-grep, sg."
compatibility"Requires ast-grep (sg) CLI tool. Install: brew install ast-grep (macOS) or cargo install ast-grep (cross-platform)."
allowed-tools"Bash"

Structural Search

Search code by its abstract syntax tree (AST) structure. Finds semantic patterns that regex cannot match reliably.

Tools

Tool Command Use For
ast-grep sg -p 'pattern' AST-aware code search

Pattern Syntax

Pattern Matches Example
$NAME Named identifier function $NAME() {}
$_ Any single node console.log($_)
$$$ Zero or more nodes function $_($$$) {}

Top 10 Essential Patterns

# 1. Find console.log calls
sg -p 'console.log($_)'

# 2. Find React hooks
sg -p 'const [$_, $_] = useState($_)'
sg -p 'useEffect($_, [$$$])'

# 3. Find function definitions
sg -p 'function $NAME($$$) { $$$ }'
sg -p 'def $NAME($$$): $$$' --lang python

# 4. Find imports
sg -p 'import $_ from "$_"'
sg -p 'from $_ import $_' --lang python

# 5. Find async patterns
sg -p 'await $_'
sg -p 'async function $NAME($$$) { $$$ }'

# 6. Find error handling
sg -p 'try { $$$ } catch ($_) { $$$ }'
sg -p 'if err != nil { $$$ }' --lang go

# 7. Find potential issues
sg -p '$_ == $_'           # == instead of ===
sg -p 'eval($_)'           # Security risk
sg -p '$_.innerHTML = $_'  # XSS vector

# 8. Preview refactoring
sg -p 'console.log($_)' -r 'logger.info($_)'

# 9. Apply refactoring
sg -p 'var $NAME = $_' -r 'const $NAME = $_' --rewrite

# 10. Search specific language
sg -p 'pattern' --lang typescript

Quick Reference

Task Command
Find pattern sg -p 'pattern'
Specific language sg -p 'pattern' --lang python
Replace (preview) sg -p 'old' -r 'new'
Replace (apply) sg -p 'old' -r 'new' --rewrite
Show context sg -p 'pattern' -A 3
JSON output sg -p 'pattern' --json
File list only sg -p 'pattern' -l
Count matches sg -p 'pattern' --count
Run YAML rules sg scan

When to Use

  • Finding all usages of a function/method
  • Locating specific code patterns (hooks, API calls)
  • Preparing for large-scale refactoring
  • When regex would match false positives
  • Detecting anti-patterns and security issues
  • Creating custom linting rules

Additional Resources

For complete patterns, load:

  • ./references/js-ts-patterns.md - JavaScript/TypeScript patterns
  • ./references/python-patterns.md - Python patterns
  • ./references/go-rust-patterns.md - Go and Rust patterns
  • ./references/security-patterns.md - Security vulnerability detection
  • ./references/advanced-usage.md - YAML rules and tool integration
  • ./assets/rule-template.yaml - Starter template for custom rules