3 releases (breaking)
0.3.0 | Jul 10, 2024 |
---|---|
0.2.0 | Mar 6, 2024 |
0.1.0 | Feb 8, 2023 |
#479 in Text processing
702 downloads per month
110KB
2.5K
SLoC
tree-sitter-stack-graphs definition for TypeScript
This project defines tree-sitter-stack-graphs rules for TypeScript using the tree-sitter-typescript grammar.
Using the API
To use this library, add the following to your Cargo.toml
:
[dependencies]
tree-sitter-stack-graphs-typescript = "0.3"
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-typescript
lets you do stack graph based analysis and lookup from the command line.
The CLI can be run as follows:
-
(Installed) Install the CLI using Cargo as follows:
cargo install --features cli tree-sitter-stack-graphs-typescript
After this, the CLI should be available as
tree-sitter-stack-graphs-typescript
. -
(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-typescript
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:
-
Index a source folder as follows:
tree-sitter-stack-graphs-typescript 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-typescript status SOURCE_DIR
To clean the database and start with a clean slate, run:
tree-sitter-stack-graphs-typescript clean
Pass the
--delete
flag to not just empty the database, but also delete it. This is useful to resolveunsupported database version
errors that may occur after a version update. -
Run a query to find the definition(s) for a reference on a given line and column, run:
tree-sitter-stack-graphs-typescript 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
andbuiltins.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
~27–42MB
~1M SLoC