ast-grep/README.md

ast-grep(sg)

ast-grep(sg) is a ligthning fast and user friendly tool for code searching, linting, rewriting at large scale.

Introduction

ast-grep is a AST-based tool to search code by pattern code. Think it as your old-friend grep but it matches AST node instead of text. You can write pattern as if you are writing ordinary code. It will match all code that has the same syntactical structure. You can use $ sign + upper case letters as wildcard, e.g. $MATCH, to match any single AST node. Think it as REGEX dot ., except it is not textual.

Try the online playground for a taste!

Demo

Installation

Install from source is the only way to try ast-grep locally at the moment. You need install rustup, clone the repository and then

cargo install --path ./crates/cli

Once the API is stablized, ast-grep will be available via package manager.

Command line usage example

ast-grep has following form.

sg --pattern 'var code = $PATTERN' --rewrite 'let code = new $PATTERN' --lang ts

Example

• Rewrite code in null coalescing operator

sg -p '$A && $A()' -l ts -r '$A?.()'

• Rewrite Zodios

sg -p 'new Zodios($URL,  $CONF as const,)' -l ts -r 'new Zodios($URL, $CONF)' -i

• Implement eslint rule using YAML.

Feature Highlight

ASTGrep's core is an algorithm to search and replace code based on abstract syntax tree produced by tree-sitter. It can help you to do lightweight static analysis and massive scale code manipulation in an intuitive way.

Key highlights:

• An intuitive pattern to find and replace AST. ASTGrep's pattern looks like ordinary code you would write every day. (You can call the pattern is isomorphic to code).

• jQuery like API for AST traversal and manipulatioin.

• YAML configuration to write new linting rules or code modification.

• Written in compiled language, parsing with tree-sitter and utilizing multiple cores.

• Beautiful command line interface :)

ast-grep's vision is to democratize abstract syntax tree magic and to liberate one from cumbersome AST programming!

• If you are an open source library author, ast-grep can help your library users adopt breaking changes more easily.
• if you are a tech lead in your team, ast-grep can help you enforce code best practice tailored to your business need.
• If you are a security researcher, ast-grep can helpn you write rules much faster.

CLI Screenshot

Search

Feature	Command	Screenshot
Search	sg -p 'Some($A)' -l rs
Rewrite	sg -p '$F && $F($$$ARGS)' -r '$F?.($ARGS)' -l ts
Report	sg scan

Sponsor

If you find ASTGrep interesting and useful for your work, please buy me a coffee so I can spend more time on the project!