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 pre-commit to setup git hooks for type checking, formatting and clippy.

Run pre-commit install to set up the git hook scripts.

pre-commit 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.