claude-mods/skills/structural-search/references/advanced-usage.md

Advanced Usage

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

Context and Output Options

# 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

# 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:

# 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:

# 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

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

# 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:

# 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:

# 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:

sg test

Integration Patterns

Pre-commit Hook

# .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

# 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

# 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'