outlinedriven/ast-grep

ast-grep (sg)

ast-grep is a fast and polyglot tool for code searching, linting, and rewriting based on Abstract Syntax Trees (AST). It excels at structural search and replace where regex fails.

When to use

• Structural Search: Finding code based on structure (e.g., "all function calls to foo with 2 arguments") regardless of whitespace.
• Refactoring: Renaming variables, changing function signatures, or transforming code patterns safely.
• Linting: Creating custom rules to enforce code style or best practices.
• Code Analysis: Extracting information from codebases.

Quick Start

CLI Basics

# Search (pattern must be in single quotes)
ast-grep -p '$A + $B' --lang ts

# Rewrite (dry run)
ast-grep -p '$A != null' --rewrite '$A' --lang ts

# Interactive Rewrite
ast-grep -p 'var $A = $B' --rewrite 'const $A = $B' --interactive

Pattern Syntax

• Meta-variables: $VAR matches any single node.
• Multi-meta-variables: $$$ARGS matches zero or more nodes (list of items).
• Wildcard: $_ matches any node (non-capturing).
• Anonymous: $$ matches any list of nodes (non-capturing).

See Pattern Syntax for details.

Core Concepts

Understanding Named vs Unnamed nodes and Matching Strictness is crucial for precise patterns.

• Named Nodes: identifier, function_definition (matched by $VAR).
• Unnamed Nodes: (, ), ; (skipped by default in smart mode).
• Strictness: Control matching precision (smart, cst, ast, relaxed, signature).

See Core Concepts for details.

Rule Configuration (YAML)

For complex tasks, use YAML configuration files.

id: no-console-log
language: TypeScript
rule:
  pattern: console.log($$$ARGS)
  inside:
    kind: function_declaration
    stopBy: end
fix: '' # Remove the log

See Rule Configuration for details.

Advanced Rewriting

ast-grep supports complex transformations (regex replace, case conversion) and rewriters for sub-node transformation.

See Rewriting & Transformations for details.

Project Setup & Testing

For larger projects, organize rules and tests using sgconfig.yml.

• Scaffold: ast-grep new project
• Config: sgconfig.yml defines rule and test directories.
• Testing: Define valid and invalid cases to ensure rule accuracy.

See Project Setup & Testing for details.

Utility Rules

Reuse logic with local or global utility rules. Enables recursive matching.

utils:
  is-literal:
    any: [{kind: string}, {kind: number}]
rule:
  matches: is-literal

See Utility Rules for details.

Configuration Reference

Full reference for YAML fields (id, severity, files, ignores) and supported languages.

See Configuration Reference for details.

CLI Reference

Common commands: scan, run, new, test, lsp.

See CLI Reference for details.