# ast-grep Rule Template
# Place in project root or rules/ directory
# Run with: sg scan

id: rule-id-here
language: typescript  # js, python, go, rust, etc.

rule:
  # Basic pattern match
  pattern: console.log($$$)

  # Or use conditions:
  # any:
  #   - pattern: console.log($$$)
  #   - pattern: console.warn($$$)
  #
  # not:
  #   pattern: console.error($$$)
  #
  # inside:
  #   pattern: function $_ { $$$ }

message: "Description of the issue"
severity: warning  # error | warning | info | hint

# Optional auto-fix
# fix: "replacement using $METAVARS"

# Optional additional context
# note: "Explanation for developers"

# Optional metadata
# metadata:
#   category: security
#   references:
#     - https://example.com/docs

# Advanced Usage

Advanced ast-grep features including YAML rules, output formatting, and tool integration.

## Context and Output Options

```bash
# Show surrounding lines (context)
sg -p 'console.log($_)' -A 3    # 3 lines after
sg -p 'console.log($_)' -B 3    # 3 lines before
sg -p 'console.log($_)' -C 3    # 3 lines both

# JSON output (for scripting)
sg -p 'console.log($_)' --json

# File names only
sg -p 'TODO' -l
sg -p 'TODO' --files-with-matches

# Count matches
sg -p 'console.log($_)' --count

# Report format
sg -p 'console.log($_)' --report
```

## Combining with Other Tools

```bash
# Find and process with jq
sg -p 'fetch($_)' --json | jq '.matches[].file'

# Find in specific files
fd -e ts | xargs sg -p 'useState($_)'

# Interactive selection with fzf
sg -p 'console.log($_)' -l | fzf | xargs code

# Parallel search in large codebases
fd -e ts -e tsx | xargs -P 4 sg -p 'useEffect($_)'

# Combine with ripgrep for pre-filtering
rg -l 'useState' | xargs sg -p 'const [$_, $_] = useState($_)'
```

## YAML Rules (Reusable Patterns)

Create `.ast-grep.yml` or `sgconfig.yml` in project root:

```yaml
# Single rule file
id: no-console-log
language: typescript
rule:
  pattern: console.log($$$)
message: Remove console.log before committing
severity: warning
```

### Multiple Rules

Create `rules/` directory with individual files:

```yaml
# rules/no-console.yml
id: no-console-log
language: typescript
rule:
  pattern: console.log($$$)
message: Remove console.log statements
severity: warning
fix: "// removed: console.log"

---
# rules/prefer-const.yml
id: prefer-const
language: typescript
rule:
  pattern: var $NAME = $_
message: Use const instead of var
severity: error
fix: const $NAME = $_
```

### Rule Configuration

```yaml
id: rule-identifier
language: typescript  # js, python, go, rust, etc.

rule:
  # Match a pattern
  pattern: console.log($$$)

  # Or use multiple conditions
  any:
    - pattern: console.log($$$)
    - pattern: console.warn($$$)

  # Negative patterns
  not:
    pattern: console.error($$$)

  # Inside specific context
  inside:
    pattern: function $_ { $$$ }

message: "Human-readable warning message"
severity: error | warning | info | hint
note: "Additional context for the developer"

# Optional auto-fix
fix: "replacement code using $METAVARS"

# Optional metadata
metadata:
  category: best-practice
  references:
    - https://example.com/rule-explanation
```

### Running Rules

```bash
# Scan with all rules
sg scan

# Scan specific directory
sg scan src/

# Scan with specific config
sg scan --config sgconfig.yml

# Test rules
sg test

# Auto-fix issues
sg scan --fix
```

## Project Configuration

Create `sgconfig.yml` in project root:

```yaml
# sgconfig.yml
ruleDirs:
  - rules/         # Directory containing rule files
  - .ast-grep/     # Alternative rules location

testConfigs:
  - testDir: rules/tests/

# Ignore patterns
ignores:
  - "**/node_modules/**"
  - "**/dist/**"
  - "**/*.min.js"

# Language-specific settings
languageGlobs:
  typescript:
    - "**/*.ts"
    - "**/*.tsx"
  python:
    - "**/*.py"
```

## Rule Testing

Create test files for rules:

```yaml
# rules/tests/no-console-test.yml
id: no-console-log
valid:
  - const x = 1;
  - logger.info("message");
invalid:
  - console.log("test");
  - console.log(variable);
```

Run tests:
```bash
sg test
```

## Integration Patterns

### Pre-commit Hook

```yaml
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: ast-grep
        name: ast-grep security
        entry: sg scan --fail-on warning
        language: system
        types: [file]
```

### CI/CD Pipeline

```yaml
# GitHub Actions
- name: AST Security Scan
  run: |
    sg scan --json > ast-grep-results.json
    if [ $(jq '.diagnostics | length' ast-grep-results.json) -gt 0 ]; then
      echo "Security issues found"
      jq '.diagnostics[]' ast-grep-results.json
      exit 1
    fi
```

### VS Code Integration

Install `ast-grep.ast-grep-vscode` extension for:
- Real-time pattern matching
- Inline warnings from rules
- Quick fixes

## Performance Tips

```bash
# Limit to specific directories
sg -p 'pattern' src/ lib/

# Use file type filters
sg -p 'pattern' --lang typescript

# Combine with fd for speed
fd -e ts -x sg -p 'pattern' {}

# Parallel processing
find . -name "*.ts" -print0 | xargs -0 -P 4 sg -p 'pattern'
```

# Go and Rust Patterns

Complete pattern library for ast-grep in Go and Rust.

## Go Patterns

### Function Declarations

```bash
# Find function declarations
sg -p 'func $NAME($$$) $_ { $$$ }' --lang go

# Find functions without return type
sg -p 'func $NAME($$$) { $$$ }' --lang go

# Find method declarations
sg -p 'func ($_ $_) $NAME($$$) $_ { $$$ }' --lang go

# Find pointer receiver methods
sg -p 'func ($_ *$_) $NAME($$$) $_ { $$$ }' --lang go
```

### Type Definitions

```bash
# Find interface definitions
sg -p 'type $NAME interface { $$$ }' --lang go

# Find struct definitions
sg -p 'type $NAME struct { $$$ }' --lang go

# Find type aliases
sg -p 'type $NAME = $_' --lang go
```

### Error Handling

```bash
# Find error checks
sg -p 'if err != nil { $$$ }' --lang go

# Find error returns
sg -p 'return $_, err' --lang go

# Find error wrapping
sg -p 'fmt.Errorf($$$)' --lang go
```

### Concurrency

```bash
# Find goroutines
sg -p 'go $_' --lang go

# Find defer statements
sg -p 'defer $_' --lang go

# Find channel operations
sg -p '$_ <- $_' --lang go

# Find select statements
sg -p 'select { $$$ }' --lang go

# Find mutex locks
sg -p '$_.Lock()' --lang go
sg -p '$_.Unlock()' --lang go
```

### Common Patterns

```bash
# Find make calls
sg -p 'make($_)' --lang go

# Find new calls
sg -p 'new($_)' --lang go

# Find range loops
sg -p 'for $_, $_ := range $_ { $$$ }' --lang go

# Find init functions
sg -p 'func init() { $$$ }' --lang go
```

---

## Rust Patterns

### Function Definitions

```bash
# Find function definitions with return type
sg -p 'fn $NAME($$$) -> $_ { $$$ }' --lang rust

# Find function definitions without return
sg -p 'fn $NAME($$$) { $$$ }' --lang rust

# Find async functions
sg -p 'async fn $NAME($$$) -> $_ { $$$ }' --lang rust

# Find public functions
sg -p 'pub fn $NAME($$$) -> $_ { $$$ }' --lang rust
```

### Impl Blocks

```bash
# Find impl blocks
sg -p 'impl $_ { $$$ }' --lang rust

# Find trait implementations
sg -p 'impl $_ for $_ { $$$ }' --lang rust

# Find generic impl
sg -p 'impl<$_> $_ { $$$ }' --lang rust
```

### Error Handling

```bash
# Find unwrap calls (potential panics)
sg -p '$_.unwrap()' --lang rust

# Find expect calls
sg -p '$_.expect($_)' --lang rust

# Find ? operator
sg -p '$_?' --lang rust

# Find Result types
sg -p 'Result<$_, $_>' --lang rust

# Find Option types
sg -p 'Option<$_>' --lang rust
```

### Match Expressions

```bash
# Find match expressions
sg -p 'match $_ { $$$ }' --lang rust

# Find if let patterns
sg -p 'if let $_ = $_ { $$$ }' --lang rust

# Find while let patterns
sg -p 'while let $_ = $_ { $$$ }' --lang rust
```

### Macros and Attributes

```bash
# Find derive attributes
sg -p '#[derive($$$)]' --lang rust

# Find macro invocations
sg -p '$_!($$$)' --lang rust

# Find specific macros
sg -p 'println!($$$)' --lang rust
sg -p 'vec![$$$]' --lang rust
```

### Async/Await

```bash
# Find .await calls
sg -p '$_.await' --lang rust

# Find tokio::spawn
sg -p 'tokio::spawn($_)' --lang rust

# Find async blocks
sg -p 'async { $$$ }' --lang rust
```

### Smart Pointers

```bash
# Find Box usage
sg -p 'Box::new($_)' --lang rust

# Find Rc usage
sg -p 'Rc::new($_)' --lang rust

# Find Arc usage
sg -p 'Arc::new($_)' --lang rust

# Find RefCell
sg -p 'RefCell::new($_)' --lang rust
```

# JavaScript/TypeScript Patterns

Complete pattern library for ast-grep in JavaScript and TypeScript.

## Function Calls

```bash
# Find all console.log calls
sg -p 'console.log($_)'

# Find all console methods
sg -p 'console.$_($_)'

# Find fetch calls
sg -p 'fetch($_)'

# Find await fetch
sg -p 'await fetch($_)'

# Find specific function calls
sg -p 'getUserById($_)'

# Find method chaining
sg -p '$_.then($_).catch($_)'
```

## React Patterns

```bash
# Find useState hooks
sg -p 'const [$_, $_] = useState($_)'

# Find useEffect with dependencies
sg -p 'useEffect($_, [$$$])'

# Find useEffect without dependencies (runs every render)
sg -p 'useEffect($_, [])'

# Find component definitions
sg -p 'function $NAME($$$) { return <$$$> }'

# Find specific prop usage
sg -p '<Button onClick={$_}>'

# Find useState without destructuring
sg -p 'useState($_)'
```

## Imports

```bash
# Find all imports from a module
sg -p 'import $_ from "react"'

# Find named imports
sg -p 'import { $_ } from "lodash"'

# Find default and named imports
sg -p 'import $_, { $$$ } from $_'

# Find dynamic imports
sg -p 'import($_)'

# Find require calls
sg -p 'require($_)'
```

## Async Patterns

```bash
# Find async functions
sg -p 'async function $NAME($$$) { $$$ }'

# Find async arrow functions
sg -p 'async ($$$) => { $$$ }'

# Find try-catch blocks
sg -p 'try { $$$ } catch ($_) { $$$ }'

# Find Promise.all
sg -p 'Promise.all([$$$])'

# Find unhandled promises (no await)
sg -p '$_.then($_)'
```

## Error Prone Patterns

```bash
# Find == instead of ===
sg -p '$_ == $_'

# Find assignments in conditions
sg -p 'if ($_ = $_)'

# Find empty catch blocks
sg -p 'catch ($_) {}'

# Find console.log (for cleanup)
sg -p 'console.log($$$)'

# Find TODO comments
sg -p '// TODO$$$'

# Find debugger statements
sg -p 'debugger'
```

## Refactoring Patterns

### Find and Replace

```bash
# Preview replacement
sg -p 'console.log($_)' -r 'logger.info($_)'

# Replace in place
sg -p 'console.log($_)' -r 'logger.info($_)' --rewrite

# Replace with context
sg -p 'var $NAME = $_' -r 'const $NAME = $_'
```

### Common Refactors

```bash
# Convert function to arrow
sg -p 'function $NAME($ARGS) { return $BODY }' \
   -r 'const $NAME = ($ARGS) => $BODY'

# Convert require to import
sg -p 'const $NAME = require("$MOD")' \
   -r 'import $NAME from "$MOD"'

# Add optional chaining
sg -p '$OBJ.$PROP' -r '$OBJ?.$PROP'
```

# Python Patterns

Complete pattern library for ast-grep in Python.

## Function Definitions

```bash
# Find function definitions
sg -p 'def $NAME($$$): $$$' --lang python

# Find async function definitions
sg -p 'async def $NAME($$$): $$$' --lang python

# Find class definitions
sg -p 'class $NAME: $$$' --lang python

# Find class with inheritance
sg -p 'class $NAME($_): $$$' --lang python
```

## Decorators

```bash
# Find any decorated functions
sg -p '@$_
def $NAME($$$): $$$' --lang python

# Find pytest fixtures
sg -p '@pytest.fixture
def $NAME($$$): $$$' --lang python

# Find Flask routes
sg -p '@app.route($_)
def $NAME($$$): $$$' --lang python

# Find property decorators
sg -p '@property
def $NAME($$$): $$$' --lang python

# Find classmethod/staticmethod
sg -p '@classmethod
def $NAME($$$): $$$' --lang python
```

## Imports

```bash
# Find standard imports
sg -p 'import $_' --lang python

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

# Find aliased imports
sg -p 'import $_ as $_' --lang python

# Find wildcard imports (anti-pattern)
sg -p 'from $_ import *' --lang python
```

## Control Flow

```bash
# Find try-except blocks
sg -p 'try:
    $$$
except $_:
    $$$' --lang python

# Find with statements (context managers)
sg -p 'with $_ as $_: $$$' --lang python

# Find list comprehensions
sg -p '[$_ for $_ in $_]' --lang python

# Find dict comprehensions
sg -p '{$_: $_ for $_ in $_}' --lang python

# Find generator expressions
sg -p '($_ for $_ in $_)' --lang python
```

## String Formatting

```bash
# Find f-strings
sg -p 'f"$$$"' --lang python

# Find .format() calls
sg -p '"$$$".format($$$)' --lang python

# Find % formatting (old style)
sg -p '"$$$" % $_' --lang python
```

## Common Patterns

```bash
# Find main block
sg -p 'if __name__ == "__main__":
    $$$' --lang python

# Find dataclass definitions
sg -p '@dataclass
class $NAME:
    $$$' --lang python

# Find type hints
sg -p 'def $NAME($$$) -> $_: $$$' --lang python

# Find assert statements
sg -p 'assert $_' --lang python

# Find raise statements
sg -p 'raise $_' --lang python
```

## Testing Patterns

```bash
# Find test functions
sg -p 'def test_$NAME($$$): $$$' --lang python

# Find pytest parametrize
sg -p '@pytest.mark.parametrize($_)
def $NAME($$$): $$$' --lang python

# Find mock patches
sg -p '@patch($_)
def $NAME($$$): $$$' --lang python
```

# Security Patterns

AST patterns for detecting security vulnerabilities and anti-patterns.

## SQL Injection

```bash
# Find string concatenation in queries
sg -p 'query($_ + $_)'
sg -p 'execute("$$$" + $_)'

# Find template literals in queries
sg -p 'query(`$$$${$_}$$$`)'

# Find raw SQL with variables
sg -p 'raw("$$$" + $_)'
sg -p 'execute($_)' # Then inspect for string interpolation
```

## XSS Vectors

```bash
# Find innerHTML assignments
sg -p '$_.innerHTML = $_'

# Find dangerouslySetInnerHTML (React)
sg -p 'dangerouslySetInnerHTML={{ __html: $_ }}'

# Find eval calls
sg -p 'eval($_)'

# Find document.write
sg -p 'document.write($_)'

# Find outerHTML
sg -p '$_.outerHTML = $_'

# Find insertAdjacentHTML
sg -p '$_.insertAdjacentHTML($_, $_)'
```

## Secrets/Credentials

```bash
# Find hardcoded passwords
sg -p 'password = "$_"'
sg -p 'password: "$_"'
sg -p 'PASSWORD = "$_"'

# Find API keys
sg -p 'apiKey = "$_"'
sg -p 'API_KEY = "$_"'
sg -p 'api_key: "$_"'

# Find tokens
sg -p 'token = "$_"'
sg -p 'TOKEN = "$_"'
sg -p 'secret = "$_"'

# Find AWS credentials
sg -p 'aws_access_key_id = "$_"'
sg -p 'aws_secret_access_key = "$_"'
```

## Command Injection

```bash
# Find exec calls with variables
sg -p 'exec($_)' --lang python
sg -p 'system($_)' --lang python
sg -p 'subprocess.call($_)' --lang python

# Find shell=True (dangerous)
sg -p 'subprocess.run($$$, shell=True)' --lang python

# Find child_process in Node.js
sg -p 'exec($_)'
sg -p 'execSync($_)'
sg -p 'spawn($_)'
```

## Path Traversal

```bash
# Find path joins with user input
sg -p 'path.join($_, req.$_)'
sg -p 'os.path.join($_, $_)' --lang python

# Find file operations with variables
sg -p 'readFile($_)'
sg -p 'writeFile($_)'
sg -p 'open($_)' --lang python
```

## Cryptographic Issues

```bash
# Find weak hashing algorithms
sg -p 'md5($_)'
sg -p 'sha1($_)'
sg -p 'createHash("md5")'
sg -p 'createHash("sha1")'

# Find Math.random for crypto (insecure)
sg -p 'Math.random()'
```

## Authentication Issues

```bash
# Find JWT without verification
sg -p 'jwt.decode($_)'  # vs jwt.verify

# Find session without secure flag
sg -p 'session: { secure: false }'

# Find password comparison (timing attack)
sg -p 'password === $_'
sg -p 'password == $_'
```

## Python-Specific Security

```bash
# Find pickle (arbitrary code execution)
sg -p 'pickle.load($_)' --lang python
sg -p 'pickle.loads($_)' --lang python

# Find yaml.load without Loader (unsafe)
sg -p 'yaml.load($_)' --lang python

# Find assert for security checks (removed in -O)
sg -p 'assert $_' --lang python
```

## React/Frontend Security

```bash
# Find target="_blank" without rel (tabnabbing)
sg -p '<$_ target="_blank">'

# Find window.location assignment
sg -p 'window.location = $_'
sg -p 'window.location.href = $_'

# Find postMessage without origin check
sg -p 'postMessage($_)'
```

## Detection Workflow

1. Run security patterns on codebase:
```bash
# Create a security scan script
for pattern in 'eval($_)' '$_.innerHTML = $_' 'password = "$_"'; do
  echo "=== $pattern ==="
  sg -p "$pattern" -l
done
```

2. Review matches for false positives
3. Remediate confirmed issues
4. Add patterns to CI/CD pipeline