Development Guide

Environment Setup

ast-grep is written in Rust and hosted by git.

You need to have rust environment installed to build ast-grep. The recommended way to install rust is via rustup. Once you have rustup installed, you can install rust by running:

rustup install stable

You also need prek to setup git hooks for type checking, formatting and clippy.

Run prek install to set up the git hook scripts.

prek install

Optionally, you can also install nodejs and yarn for napi binding development.

That's it! You have setup the environment for ast-grep!

Common Commands

The below are some cargo commands common to any Rust project.

cargo test     # Run test
cargo check    # Run checking
cargo clippy   # Run clippy
cargo fmt      # Run formatting

Below are some ast-grep specific commands.

N-API Development

@ast-grep/napi is the nodejs binding for ast-grep.

The source code of napi binding is under the crates/napi folder. You can refer to the package.json for available commands.

cd crates/napi
yarn   # Install dependencies
yarn build # Build the binding
yarn test # Run test

Commit Conventions

ast-grep loosely follows the commit conventions.

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

To quote the conventional commits doc:

The commit contains the following structural elements, to communicate intent to the consumers of your library:

• fix: a commit of the type fix patches a bug in your codebase.
• feat: a commit of the type feat introduces a new feature to the codebase.
• types other than fix: and feat: are allowed, for example, build:, chore:, ci:, docs:, style:, refactor:, perf:, and test:.
• BREAKING CHANGE: a commit that has a footer BREAKING CHANGE: introduces a breaking API change. A BREAKING CHANGE can be part of commits of any type.
• footers other than BREAKING CHANGE: <description> may be provided and follow a convention similar to git trailer format.

TIP

BREAKING CHANGE will be picked up and written in CHANGELOG by cargo xtask.

Run Benchmark

ast-grep's Benchmark is not included in the default cargo test. You need to run the benchmark command in benches folder.

cd benches
cargo bench

ast-grep's benchmarking suite is not well developed yet. The result may fluctuate too much.

Release New Version

The command below will bump version and create a git tag for ast-grep. Once pushed to GitHub, the tag will trigger GitHub actions to build and publish the new version to crates.io, npm and PyPi.

cargo xtask [version-number]

See xtask file for more details.