oimiragieo/code-structural-search

Code Structural Search

Use ast-grep for AST-based code pattern matching.

When to Use

• Find code by structure, not keywords
• "Find all functions with 3 arguments"
• "Find all classes that extend X"
• "Find all database queries"
• "Find all error handling patterns"
• Precise code refactoring (change exact patterns)

Interface

Skill({ skill: 'code-structural-search', args: 'pattern-here --lang ts' });

Language Support

ast-grep supports 20+ languages via tree-sitter:

| Language | Flag | File Extensions | | ---------- | --------------- | -------------------- | | JavaScript | --lang js | .js, .jsx | | TypeScript | --lang ts | .ts, .tsx | | Python | --lang py | .py, .pyi | | Go | --lang go | .go | | Rust | --lang rs | .rs | | Java | --lang java | .java | | C | --lang c | .c, .h | | C++ | --lang cpp | .cpp, .cc, .hpp, .hh | | C# | --lang cs | .cs | | Kotlin | --lang kt | .kt, .kts | | Swift | --lang swift | .swift | | PHP | --lang php | .php | | Ruby | --lang rb | .rb | | Lua | --lang lua | .lua | | Elixir | --lang ex | .ex, .exs | | HTML | --lang html | .html, .htm | | CSS | --lang css | .css | | JSON | --lang json | .json | | Bash | --lang bash | .sh, .bash | | Thrift | --lang thrift | .thrift |

Pattern Examples

JavaScript/TypeScript

Find all functions:

function $NAME($ARGS) { $$ }

Find functions with exactly 2 arguments:

function $NAME($A, $B) { $$ }

Find async functions:

async function $NAME($ARGS) { $$ }

Find class methods:

class $NAME {
  $METHOD($ARGS) { $$ }
}

Find arrow functions:

const $NAME = ($ARGS) => { $$ }

Find console.log statements:

console.log($$$)

Find try-catch blocks:

try { $$ } catch ($ERR) { $$ }

Python

Find all functions:

def $NAME($ARGS): $$$

Find class definitions:

class $NAME: $$$

Find async functions:

async def $NAME($ARGS): $$$

Find imports:

import $MODULE

Find from imports:

from $MODULE import $$$

Go

Find all functions:

func $NAME($ARGS) $RETURN { $$ }

Find struct definitions:

type $NAME struct { $$$ }

Find interface definitions:

type $NAME interface { $$$ }

Rust

Find all functions:

fn $NAME($ARGS) -> $RETURN { $$ }

Find impl blocks:

impl $NAME { $$$ }

Find pub functions:

pub fn $NAME($ARGS) -> $RETURN { $$ }

Java

Find all methods:

public $RETURN $NAME($ARGS) { $$ }

Find class definitions:

public class $NAME { $$$ }

Find interface definitions:

public interface $NAME { $$$ }

Pattern Syntax

| Symbol | Meaning | Example | | ------- | ------------------------------- | --------------------- | | $NAME | Single node/identifier | function $NAME() {} | | $$$ | Zero or more statements/nodes | class $NAME { $$$ } | | $$ | Zero or more statements (block) | if ($COND) { $$ } | | $_ | Anonymous wildcard (discard) | console.log($_) |

Performance

• Speed: <50ms per search (typical)
• Best combined with semantic search (Phase 1)
• Use ripgrep first for initial file discovery

vs Other Tools

vs Ripgrep (grep):

• Ripgrep: Fast text search, finds keywords
• ast-grep: Structural search, finds exact code patterns
• Use ripgrep first → then ast-grep to refine

vs Semantic Search (Phase 1):

• Semantic: Understands code meaning
• ast-grep: Understands code structure
• Combined: Best results (Phase 2)

Usage Workflow

1. Broad search with ripgrep:

   Skill({ skill: 'ripgrep', args: 'authenticate --type ts' })
   

2. Structural refinement with ast-grep:

   Skill({ skill: 'code-structural-search', args: 'function authenticate($$$) { $$ } --lang ts' })
   

3. Semantic understanding with Phase 1:

   Skill({ skill: 'code-semantic-search', args: 'authentication logic' })
   

Common Use Cases

Security Patterns

Find unvalidated inputs:

router.post($PATH, ($REQ, $RES) => { $$ })

Find SQL queries (potential injection):

db.query(`SELECT * FROM ${$VAR}`)

Find eval usage:

eval($$$)

Code Quality Patterns

Find deeply nested functions:

function $NAME($ARGS) {
  if ($COND) {
    if ($COND2) {
      if ($COND3) { $$ }
    }
  }
}

Find long parameter lists (>5 params):

function $NAME($A, $B, $C, $D, $E, $F, $$$) { $$ }

Find unused variables:

const $NAME = $VALUE;

Refactoring Patterns

Find old API usage:

oldAPI.deprecatedMethod($$$)

Find callback patterns (convert to async/await):

$FUNC($ARGS, ($ERR, $DATA) => { $$ })

Find React class components (convert to hooks):

class $NAME extends React.Component { $$$ }

Iron Laws

1. ALWAYS specify the language with --lang flag — without a language flag, ast-grep applies heuristics that produce false positives; specify --lang ts, --lang py, etc. for accurate AST parsing.
2. ALWAYS use ripgrep/keyword search first to narrow the target set — structural search over the whole codebase is slow; use ripgrep to find candidate files first, then apply ast-grep for precise matching.
3. NEVER use regex for structural code patterns — regex breaks on formatting differences, nested structures, and multi-line code; AST patterns are format-independent and semantically precise.
4. ALWAYS test patterns on a known match before running project-wide — patterns with incorrect syntax silently match nothing; verify the pattern finds at least one known example before broad application.
5. ALWAYS use $$$ for variable argument lists, not * or . — ast-grep uses metavariable syntax ($NAME, $$$, $$); regex or glob syntax in patterns produces silent failures.

Anti-Patterns

| Anti-Pattern | Why It Fails | Correct Approach | | ----------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------ | | No --lang flag | Wrong parser applied; produces false positives and misses | Always specify --lang ts, --lang py, etc. | | Running project-wide without ripgrep pre-filter | Slow on large codebases; many irrelevant results | Use ripgrep to identify candidate files first | | Regex for structural matching | Breaks on multi-line, whitespace variations, nesting | Use ast-grep AST patterns ($NAME, $$$, etc.) | | Untested pattern on full codebase | Incorrect patterns silently return nothing | Test on one known match first | | Using * or . for wildcards | Not valid ast-grep syntax; ignored or errors | Use $NAME for single node, $$$ for sequences |

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern → .claude/context/memory/learnings.md
• Issue found → .claude/context/memory/issues.md
• Decision made → .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.