Get the FREE Ultimate OpenClaw Setup Guide →

ast-grep

npx machina-cli add skill OutlineDriven/odin-claude-plugin/ast-grep --openclaw
Files (1)
SKILL.md
3.2 KB

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.

Source

git clone https://github.com/OutlineDriven/odin-claude-plugin/blob/main/skills/ast-grep/SKILL.mdView on GitHub

Overview

ast-grep (sg) is a fast, polyglot tool for code searching, linting, and rewriting based on Abstract Syntax Trees. It excels at structural search and safe refactoring where regex fails, enabling precise pattern matching and transformations.

How This Skill Works

Pattern matching uses meta-variables, multi-meta-variables, and wildcards to capture code structure. You run searches or rewrites with -p and --lang, optionally in dry-run or interactive modes, and you can configure complex tasks with YAML rule files and sgconfig.yml for project-wide automation.

When to Use It

  • Structural search: find code by structure (e.g., all function calls to foo with 2 arguments) regardless of whitespace.
  • Refactoring: rename variables, change function signatures, or transform patterns safely across a codebase.
  • Linting: create custom rules to enforce code style or best practices.
  • Code analysis: extract information from codebases using AST queries.
  • Complex transformations: apply multi-step rewrites and interactive edits across files.

Quick Start

  1. Step 1: ast-grep -p '$A + $B' --lang ts
  2. Step 2: ast-grep -p '$A != null' --rewrite '$A' --lang ts
  3. Step 3: ast-grep -p 'var $A = $B' --rewrite 'const $A = $B' --interactive

Best Practices

  • Start with small patterns and verify with a dry run to minimize unintended changes.
  • Use interactive rewrites for risky transformations to review changes before applying.
  • Leverage YAML rule configurations for repeatable, project-wide tasks.
  • Use meta-variables ($VAR, $$$ARGS) to precisely capture node shapes and arguments.
  • Tune Strictness (smart, cst, ast, relaxed, signature) to balance precision and performance.

Example Use Cases

  • Create a rule to remove all console.log calls in TypeScript projects with id: no-console-log and a rule pattern like console.log($$$ARGS).
  • Rename a variable across a codebase: pattern var $A = $B rewrite to let/const $A = $B as appropriate.
  • Refactor function signatures safely by rewriting parameter patterns within function_declaration scopes.
  • Enforce a lint rule that disallows deprecated API usage using a dedicated sg rule.
  • Interactively rewrite var $A = $B to const $A = $B inside function scopes using the interactive mode.

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗