76 releases (19 breaking)

new 0.20.5 Apr 11, 2024
0.20.2 Mar 27, 2024
0.16.0 Dec 29, 2023
0.13.2 Nov 20, 2023
0.3.2 Mar 11, 2023

#185 in Programming languages

Download history 43/week @ 2023-12-21 110/week @ 2023-12-28 163/week @ 2024-01-04 271/week @ 2024-01-11 107/week @ 2024-01-18 72/week @ 2024-01-25 158/week @ 2024-02-01 43/week @ 2024-02-08 595/week @ 2024-02-15 675/week @ 2024-02-22 157/week @ 2024-02-29 400/week @ 2024-03-07 230/week @ 2024-03-14 630/week @ 2024-03-21 311/week @ 2024-03-28 460/week @ 2024-04-04

1,676 downloads per month
Used in 5 crates (4 directly)

MIT license

195KB
5.5K SLoC

ast-grep

coverage badge Discord Repology Badge Badge GitHub Sponsors

ast-grep(sg)

ast-grep(sg) is a CLI tool for code structural search, lint, and rewriting.

Introduction

ast-grep is an AST-based tool to search code by pattern code. Think it as your old-friend grep but it matches AST nodes instead of text. You can write patterns 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

demo

See more screenshots on the website.

Installation

You can install it from npm, pip, cargo, homebrew, scoop or MacPorts!

npm install --global @ast-grep/cli
pip install ast-grep-cli
cargo install ast-grep

# install via homebrew, thank @henryhchchc
brew install ast-grep

# install via scoop, thank @brian6932
scoop install main/ast-grep

# install via MacPorts
sudo port install ast-grep

Or you can build ast-grep from source. You need install rustup, clone the repository and then

cargo install --path ./crates/cli

Packages are available on other platforms too.

Command line usage example

ast-grep has following form.

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

Example

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

Sponsor

Sponsors

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

Feature Highlight

ast-grep'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. ast-grep's pattern looks like ordinary code you would write every day (you could say the pattern is isomorphic to code).

  • jQuery like API for AST traversal and manipulation.

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

  • Written in compiled language, with tree-sitter based parsing 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 help you write rules much faster.

lib.rs:

This module defines the supported programming languages for ast-grep.

It provides a set of customized languages with expando_char / pre_process_pattern, and a set of stub languages without preprocessing. A rule of thumb: if your language does not accept identifiers like $VAR. You need use impl_lang_expando! macro and a standalone file for testing. Otherwise, you can define it as a stub language using impl_lang!. To see the full list of languages, visit <https://ast-grep.github.io/reference/languages.html>

Dependencies

~5–62MB
~2M SLoC