11 releases (7 breaking)

0.8.1 Mar 6, 2024
0.7.1 Jul 27, 2023
0.7.0 Jun 8, 2023
0.6.0 Jan 13, 2023
0.2.0 Jun 29, 2022

#70 in Visualization

Download history 18/week @ 2024-01-21 5/week @ 2024-01-28 24/week @ 2024-02-04 14/week @ 2024-02-18 63/week @ 2024-02-25 161/week @ 2024-03-03 25/week @ 2024-03-10

263 downloads per month
Used in 5 crates

MIT/Apache

1MB
17K SLoC

tree-sitter-stack-graphs

The tree-sitter-stack-graphs crate lets you create stack graphs using the tree-sitter grammar for a language.

Using the API

To use this library, add the following to your Cargo.toml:

[dependencies]
tree-sitter-stack-graphs = "0.8"

Check out our documentation for more details on how to use this library.

Using the Command-line Program

The command-line program for tree-sitter-stack-graphs lets you do stack graph based analysis and lookup from the command line.

The CLI can be run as follows:

  1. (Installed) Install the CLI using Cargo as follows:

    cargo install --features cli tree-sitter-stack-graphs
    

    After this, the CLI should be available as tree-sitter-stack-graphs.

  2. (From source) Instead of installing the CLI, it can also be run directly from the crate directory, as a replacement for a tree-sitter-stack-graphs invocation, as follows:

    cargo run --features cli --
    

The basic CLI workflow for the command-line program is to index source code and issue queries against the resulting database:

  1. Index a source folder as follows:

    tree-sitter-stack-graphs index SOURCE_DIR
    

    Indexing will skip any files that have already be indexed. To force a re-index, add the -f flag.

    To check the status if a source folder, run:

    tree-sitter-stack-graphs status SOURCE_DIR
    

    To clean the database and start with a clean slate, run:

    tree-sitter-stack-graphs clean
    

    Pass the --delete flag to not just empty the database, but also delete it. This is useful to resolve unsupported database version errors that may occur after a version update.

  2. Run a query to find the definition(s) for a reference on a given line and column, run:

    tree-sitter-stack-graphs query definition SOURCE_PATH:LINE:COLUMN
    

    Resulting definitions are printed, including a source line if the source file is available.

Discover all available commands and flags by passing the -h flag to the CLI directly, or to any of the subcommands.

Getting Started on a new Language

Starting a new project to develop stack graph definitions for your favourite language is as easy as running the init command:

tree-sitter-stack-graphs init PROJECT_DIR

Answer the questions to provide information about the language, the grammar dependency, and the project and hit Generate to generate the new project. Check out PROJECT_DIR/README.md to find out how to start developing.

Check out examples of stack graph rules for typical language features.

Development

The project is written in Rust, and requires a recent version installed. Rust can be installed and updated using rustup.

Build the project by running:

cargo build

Run the tests by running:

cargo test

The project consists of a library and a CLI. By default, running cargo only applies to the library. To run cargo commands on the CLI as well, add --features cli or --all-features.

Run the CLI from source as follows:

cargo run --features cli -- ARGS

Sources are formatted using the standard Rust formatted, which is applied by running:

cargo fmt

License

Licensed under either of

at your option.

Dependencies

~8–26MB
~370K SLoC