howto-ast-grep

What this skill does

# Using ast-grep for Structural Code Search

## Overview

ast-grep (`sg`) matches code by AST structure, not text. Use it instead of grep/ripgrep when you need to match code patterns regardless of whitespace, variable names, or formatting. Patterns must be valid, parsable code in the target language.

## When to Use

**Prefer ast-grep over grep when:**

- Finding function calls with specific argument shapes
- Matching patterns where variable names differ but structure is the same
- Rewriting code patterns across a codebase (migrations, deprecations)
- Finding anti-patterns that regex can't express (e.g. "await inside a loop")

**Use grep instead when:**

- Searching for string literals, comments, or non-code text
- Simple keyword search (import names, error messages)
- ast-grep is not installed

## CLI Quick Reference

```bash
# Search for a pattern
sg run -p 'console.log($$$ARGS)' -l javascript src/

# Search and replace (interactive)
sg run -p '$A && $A()' -r '$A?.()' -l typescript --interactive src/

# Apply all replacements without prompting
sg run -p 'var $X = $Y' -r 'const $X = $Y' -l javascript -U src/

# JSON output for programmatic use
sg run -p '$FUNC($$$)' -l python --json src/

# Read from stdin
echo 'let x = 1' | sg run -p 'let $X = $Y' -l javascript --stdin
```

## Metavariable Syntax

| Syntax | Matches | Example |
|--------|---------|---------|
| `$NAME` | Exactly one AST node | `console.log($MSG)` matches `console.log("hi")` but not `console.log("hi", 2)` |
| `$$$NAME` | Zero or more nodes | `console.log($$$ARGS)` matches any number of arguments |
| `$_NAME` | One node, non-capturing | `$_OBJ.$METHOD()` matches without binding `$_OBJ` |

**Reuse enforces equality:** `$A == $A` matches `x == x` but not `x == y`.

## Language-Specific Patterns

Always pass `-l <language>`. The language determines how patterns are parsed.

**JavaScript/TypeScript:**

```bash
# Find React hooks
sg run -p 'use$HOOK($$$)' -l typescript src/

# Optional chaining candidates
sg run -p '$A && $A.$B' -r '$A?.$B' -l typescript src/

# Async/await patterns
sg run -p 'await $PROMISE' -l javascript src/
```

**Python:**

```bash
# Find print statements
sg run -p 'print($$$)' -l python src/

# Dictionary access patterns
sg run -p '$DICT[$KEY]' -l python src/

# With statement patterns
sg run -p 'with open($$$ARGS) as $F: $$$BODY' -l python src/
```

**Go:**

```bash
# Error handling
sg run -p 'if $ERR != nil { return $$$VALS }' -l go ./

# Function calls
sg run -p '$PKG.$FUNC($$$)' -l go ./
```

**Rust:**

```bash
# Unwrap calls (potential panics)
sg run -p '$EXPR.unwrap()' -l rust src/

# Match expressions
sg run -p 'match $VAL { $$$ARMS }' -l rust src/
```

## Pattern Pitfalls

| Mistake | Why It Fails | Fix |
|---------|-------------|-----|
| Using regex in `-p` | Patterns must be valid code | Write the code structure you want to find |
| `$VAR + Name` | Parsed as `$VARN + ame` | Use constraints or transform in YAML rules |
| Single quotes in C/Rust patterns | `'x'` is a char literal, not a string | Use `"x"` for strings |
| Forgetting `-l` flag | ast-grep cannot infer language from patterns | Always specify language explicitly |
| `$A($B, $C)` for variadic calls | Only matches exactly 2 args | Use `$A($$$ARGS)` for any arity |

## YAML Rules for Complex Matching

When CLI patterns aren't expressive enough, use YAML rules:

```yaml
id: no-unwrap-in-production
language: rust
rule:
  pattern: $EXPR.unwrap()
  not:
    inside:
      kind: function_item
      has:
        field: name
        regex: '^test_'
message: "Use expect() or proper error handling instead of unwrap()"
severity: warning
```

**Key rule combinators:**

- `all`: All sub-rules must match (AND)
- `any`: Any sub-rule can match (OR)
- `not`: Sub-rule must NOT match
- `inside`: Target is inside another node
- `has`: Target contains a descendant
- `follows`/`precedes`: Sibling ordering

**Run rules:** `sg scan --rule path/to/rule.yml src/`

## Red Flags

- Using grep with complex regex when ast-grep would match the structure directly
- Forgetting `$$$` and missing variadic matches
- Writing patterns that aren't valid code in the target language
- Not specifying `-l` and getting parse failures