# ast-grep-patterns

> Use this skill when the user asks about ast-grep pattern syntax, structural code search, AST matching, wildcards, or how to write ast-grep patterns. Also use when the user wants to search code by structure rather than text.

- Author: jiangfire
- Repository: jiangfire/ast-grep-plugin
- Version: 20260127214449
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/jiangfire/ast-grep-plugin
- Web: https://mule.run/skillshub/@@jiangfire/ast-grep-plugin~ast-grep-patterns:20260127214449

---

---
skill: ast-grep-patterns
description: Use this skill when the user asks about ast-grep pattern syntax, structural code search, AST matching, wildcards, or how to write ast-grep patterns. Also use when the user wants to search code by structure rather than text.
---

# ast-grep Pattern Syntax

Learn how to write powerful AST-based search patterns that match code structure instead of text.

## When to Use This Skill

Use ast-grep patterns when you need to:
- Search for code by its syntactic structure
- Find patterns that text search would miss or over-match
- Match code regardless of formatting or whitespace
- Capture and reuse parts of matched code

## Core Concept: Pattern as Code

Write patterns as if you're writing normal code. ast-grep matches the Abstract Syntax Tree (AST) structure, not the text.

**Example:**
```javascript
// Pattern
console.log($MSG)

// Matches all of these:
console.log("hello")
console.log(variable)
console.log(a + b)
console.log(
  "multi-line"
)
```

## Wildcards: The `$` Syntax

Use `$UPPERCASE` to match any single AST node (like regex `.` but for syntax trees).

### Basic Wildcards

```javascript
// Match any function call
$FUNC($ARGS)

// Match any variable declaration
let $VAR = $VALUE

// Match any if statement
if ($COND) { $BODY }
```

### Named Wildcards

Wildcards capture matched content for reuse in rewrites:

```javascript
// Pattern
var $NAME = $VALUE

// Rewrite
let $NAME = $VALUE

// Transforms: var x = 1  →  let x = 1
```

## Language-Specific Examples

See `references/language-patterns.md` for detailed examples in:
- TypeScript/JavaScript
- Python
- Go
- Java
- Rust

## Pattern Strictness

Control how precisely patterns match using `--strictness`:

- `smart` (default): Ignores whitespace and comments
- `ast`: Matches only AST nodes
- `cst`: Matches exact concrete syntax tree
- `relaxed`: Ignores comments
- `signature`: Ignores text, matches structure only

## Advanced Features

### Selectors

Extract sub-parts of patterns:

```bash
ast-grep --pattern "function $NAME() { $BODY }" --selector function_declaration
```

### Multi-line Patterns

Patterns can span multiple lines naturally:

```javascript
class $CLASS {
  constructor($PARAMS) {
    $BODY
  }
}
```

## Common Patterns

### Find Function Definitions

**JavaScript/TypeScript:**
```javascript
function $NAME($PARAMS) { $BODY }
```

**Python:**
```python
def $NAME($PARAMS):
    $BODY
```

**Go:**
```go
func $NAME($PARAMS) $RETURN { $BODY }
```

### Find Method Calls

**JavaScript:**
```javascript
$OBJ.$METHOD($ARGS)
```

**Python:**
```python
$OBJ.$METHOD($ARGS)
```

### Find Imports

**JavaScript:**
```javascript
import $WHAT from "$MODULE"
```

**Python:**
```python
from $MODULE import $WHAT
```

**Go:**
```go
import "$PACKAGE"
```

## Tips for Writing Patterns

1. **Start simple**: Begin with the core structure, add details later
2. **Test incrementally**: Use `--debug-query=ast` to see how patterns parse
3. **Use wildcards liberally**: `$VAR` matches any single node
4. **Match structure, not text**: Focus on syntax, not formatting
5. **Check language docs**: Each language has different AST structures

## Testing Patterns

Use `--debug-query` to understand how your pattern is parsed:

```bash
ast-grep --pattern "console.log($MSG)" --lang js --debug-query=ast
```

## Next Steps

- See `references/language-patterns.md` for language-specific pattern libraries
- See `examples/common-patterns.yml` for ready-to-use pattern examples
- See `references/advanced-patterns.md` for complex matching techniques

## Related Commands

- `/ast-grep:search` - Execute pattern searches
- `/ast-grep:rewrite` - Use patterns for code transformation