#tree-sitter #javascript #stack-graphs

bin+lib tree-sitter-stack-graphs-javascript

Stack graphs definition for JavaScript using tree-sitter-javascript

2 unstable releases

0.1.0 Mar 8, 2024
0.0.1 May 10, 2023

#288 in Programming languages

Download history 4/week @ 2024-02-21 10/week @ 2024-02-28 121/week @ 2024-03-06 12/week @ 2024-03-13

147 downloads per month

MIT/Apache

280KB
1.5K SLoC

JavaScript 1K SLoC // 0.4% comments Rust 351 SLoC // 0.2% comments Forge Config 1 SLoC

tree-sitter-stack-graphs definition for JavaScript

This project defines tree-sitter-stack-graphs rules for JavaScript using the tree-sitter-javascript grammar.

Using the API

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

[dependencies]
tree-sitter-stack-graphs-javascript = "0.1"

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-javascript 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-javascript
    

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

  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-javascript 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-javascript 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-javascript status SOURCE_DIR
    

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

    tree-sitter-stack-graphs-javascript 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-javascript 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.

Development

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

The project is organized as follows:

  • The stack graph rules are defined in src/stack-graphs.tsg.
  • Builtins sources and configuration are defined in src/builtins.it and builtins.cfg respectively.
  • Tests are put into the test directory.

Running Tests

Run the tests as follows:

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

Writing TSG

The stack graph rules are written in tree-sitter-graph. Checkout the examples, which contain self-contained TSG rules for specific language features. A VSCode extension is available that provides syntax highlighting for TSG files.

Parse and test a single file by executing the following commands:

cargo run --features cli -- parse FILES...
cargo run --features cli -- test TESTFILES...

Generate a visualization to debug failing tests by passing the -V flag:

cargo run --features cli -- test -V TESTFILES...

To generate the visualization regardless of test outcome, execute:

cargo run --features cli -- test -V --output-mode=always TESTFILES...

Go to https://crates.io/crates/tree-sitter-stack-graphs for links to examples and documentation.

Dependencies

~14–29MB
~501K SLoC