Skip to content
This repository was archived by the owner on Sep 9, 2025. It is now read-only.

Commit be38049

Browse files
author
Hendrik van Antwerpen
committed
Update README to include some usage guidance
1 parent e54e308 commit be38049

9 files changed

Lines changed: 465 additions & 188 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 25 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -58,21 +58,32 @@ jobs:
5858
run: cargo test --all-features
5959
- name: Run test suite with all optimizations
6060
run: cargo test --release
61-
# Do the new project test last, because it adds the crate in the current source
62-
# folder, and that shouldn't influence other tests.
61+
62+
test-init:
63+
needs: [test-rust]
64+
runs-on: ubuntu-latest
65+
strategy:
66+
matrix:
67+
rust: [stable]
68+
69+
steps:
70+
- name: Install Rust environment
71+
uses: hecrj/setup-rust-action@v1
72+
with:
73+
rust-version: ${{ matrix.rust }}
74+
- name: Checkout code
75+
uses: actions/checkout@v3
76+
- name: Cache dependencies
77+
uses: actions/cache@v3
78+
with:
79+
path: |
80+
~/.cargo
81+
target
82+
key: ${{ runner.OS }}-cargo-${{ hashFiles('**/Cargo.lock') }}
83+
restore-keys: |
84+
${{ runner.OS }}-cargo-
6385
- name: Generate, build, and run new language project
64-
run: |
65-
cargo run --bin tree-sitter-stack-graphs --features cli -- init \
66-
--language-name InitTest \
67-
--language-id init_test \
68-
--language-file-extension it \
69-
--grammar-crate-name tree-sitter-python \
70-
--grammar-crate-version 0.20.0 \
71-
--internal \
72-
--non-interactive
73-
cargo check -p tree-sitter-stack-graphs-init_test --all-features
74-
cargo test -p tree-sitter-stack-graphs-init_test
75-
cargo run -p tree-sitter-stack-graphs-init_test --features cli -- help
86+
run: script/ci-test-init
7687

7788
list-languages:
7889
runs-on: ubuntu-latest

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,8 @@ Here are a few things you can do that will increase the likelihood of your pull
3232
If you are one of the maintainers of this package, bump the version numbers in [`Cargo.toml`](Cargo.toml) and [`README.md`](README.md), then follow the typical instructions to publish a new version to [crates.io][]:
3333

3434
```
35-
$ cargo package
36-
$ cargo publish
35+
cargo package
36+
cargo publish
3737
```
3838

3939
[crates.io]: https://crates.io/stack-graphs/
@@ -43,4 +43,3 @@ $ cargo publish
4343
- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
4444
- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
4545
- [GitHub Help](https://help.github.com)
46-

‎languages/tree-sitter-stack-graphs-java/README.md‎

Lines changed: 121 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,138 @@
11
# tree-sitter-stack-graphs definition for Java
22

3-
This project defines tree-sitter-stack-graphs rules for Java using the [tree-sitter-java](https://www.npmjs.com/package/tree-sitter-java) grammar.
3+
This project defines tree-sitter-stack-graphs rules for Java using the [tree-sitter-java][] grammar.
44

5-
## Local Development
5+
[tree-sitter-java]: https://crates.io/crates/tree-sitter-java
6+
7+
- [API documentation](https://docs.rs/tree-sitter-stack-graphs-java/)
8+
- [Release notes](https://github.com/github/stack-graphs/blob/main/languages/tree-sitter-stack-graphs-java/CHANGELOG.md)
9+
10+
## Using the API
11+
12+
To use this library, add the following to your `Cargo.toml`:
13+
14+
```toml
15+
[dependencies]
16+
tree-sitter-stack-graphs-java = "0.2.0"
17+
```
18+
19+
Check out our [documentation](https://docs.rs/tree-sitter-stack-graphs-java/*/) for more details on how to use this library.
20+
21+
## Using the Command-line Program
22+
23+
The command-line program for `tree-sitter-stack-graphs-java` lets you do stack graph based analysis and lookup from the command line.
24+
25+
The CLI can be run as follows:
26+
27+
1. _(Installed)_ Install the CLI using Cargo as follows:
28+
29+
```sh
30+
cargo install --features cli tree-sitter-stack-graphs-java
31+
```
32+
33+
After this, the CLI should be available as `tree-sitter-stack-graphs-java`.
34+
35+
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-java` invocation, as follows:
36+
37+
```sh
38+
cargo run --features cli --
39+
```
40+
41+
The basic CLI workflow for the command-line program is to index source code and issue queries against the resulting database:
42+
43+
1. Index a source folder as follows:
44+
45+
```sh
46+
tree-sitter-stack-graphs-java index SOURCE_DIR
47+
```
48+
49+
_Indexing will skip any files that have already be indexed. To force a re-index, add the `-f` flag._
50+
51+
To check the status if a source folder, run:
52+
53+
```sh
54+
tree-sitter-stack-graphs-java status SOURCE_DIR
55+
```
56+
57+
To clean the database and start with a clean slate, run:
58+
59+
```sh
60+
tree-sitter-stack-graphs-java clean
61+
```
62+
63+
_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._
64+
65+
2. Run a query to find the definition(s) for a reference on a given line and column, run:
66+
67+
```sh
68+
tree-sitter-stack-graphs-java query definition SOURCE_PATH:LINE:COLUMN
69+
```
70+
71+
Resulting definitions are printed, including a source line if the source file is available.
72+
73+
Discover all available commands and flags by passing the `-h` flag to the CLI directly, or to any of the subcommands.
74+
75+
## Development
76+
77+
The project is written in Rust, and requires a recent version installed. Rust can be installed and updated using [rustup][].
78+
79+
[rustup]: https://rustup.rs/
680

781
The project is organized as follows:
882

983
- The stack graph rules are defined in `src/stack-graphs.tsg`.
84+
- Builtins sources and configuration are defined in `src/builtins.it` and `builtins.cfg` respectively.
1085
- Tests are put into the `test` directory.
1186

12-
The following commands are intended to be run from the repo root.
87+
### Running Tests
88+
89+
Run the tests as follows:
90+
91+
```sh
92+
cargo test
93+
```
94+
95+
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`.
96+
97+
Run the CLI from source as follows:
98+
99+
```sh
100+
cargo run --features cli -- ARGS
101+
```
102+
103+
Sources are formatted using the standard Rust formatted, which is applied by running:
104+
105+
```sh
106+
cargo fmt
107+
```
108+
109+
### Writing TSG
110+
111+
The stack graph rules are written in [tree-sitter-graph][]. Checkout the [examples][],
112+
which contain self-contained TSG rules for specific language features. A VSCode
113+
[extension][] is available that provides syntax highlighting for TSG files.
13114

14-
Run all tests in the project by executing the following:
115+
[tree-sitter-graph]: https://github.com/tree-sitter/tree-sitter-graph
116+
[examples]: https://github.com/github/stack-graphs/blob/main/tree-sitter-stack-graphs/examples/
117+
[extension]: https://marketplace.visualstudio.com/items?itemName=tree-sitter.tree-sitter-graph
15118

16-
cargo test -p tree-sitter-stack-graphs-java
119+
Parse and test a single file by executing the following commands:
17120

18-
Parse a single test file:
19-
`cargo run -p tree-sitter-stack-graphs-java -- parse OPTIONS FILENAME`
121+
```sh
122+
cargo run --features cli -- parse FILES...
123+
cargo run --features cli -- test TESTFILES...
124+
```
20125

21-
Test a single file:
22-
`cargo run -p tree-sitter-stack-graphs-java -- test OPTIONS FILENAME`
126+
Generate a visualization to debug failing tests by passing the `-V` flag:
23127

24-
For debugging purposes, it is useful to run the visualization tool to generate graphs for the tests being run.
128+
```sh
129+
cargo run --features cli -- test -V TESTFILES...
130+
```
25131

26-
To run a test and generate the visualization:
132+
To generate the visualization regardless of test outcome, execute:
27133

28-
`cargo run -p tree-sitter-stack-graphs-java -- test --output-mode=always -V=%r/%d/%n.html FILENAME`
134+
```sh
135+
cargo run --features cli -- test -V --output-mode=always TESTFILES...
136+
```
29137

30-
Go to https://crates.io/crates/tree-sitter-stack-graphs for links to examples and documentation.
138+
Go to <https://crates.io/crates/tree-sitter-stack-graphs> for links to examples and documentation.

‎languages/tree-sitter-stack-graphs-javascript/README.md‎

Lines changed: 71 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -4,27 +4,73 @@ This project defines tree-sitter-stack-graphs rules for JavaScript using the [tr
44

55
[tree-sitter-javascript]: https://crates.io/crates/tree-sitter-javascript
66

7-
## Usage
7+
- [API documentation](https://docs.rs/tree-sitter-stack-graphs-javascript/)
8+
- [Release notes](https://github.com/github/stack-graphs/blob/main/languages/tree-sitter-stack-graphs-javascript/CHANGELOG.md)
9+
10+
## Using the API
811

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

11-
``` toml
14+
```toml
1215
[dependencies]
13-
tree-sitter-stack-graphs-javascript = "0.0.1"
16+
tree-sitter-stack-graphs-javascript = "0.1.0"
1417
```
1518

1619
Check out our [documentation](https://docs.rs/tree-sitter-stack-graphs-javascript/*/) for more details on how to use this library.
1720

18-
## Command-line Program
21+
## Using the Command-line Program
1922

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

22-
Install the program using `cargo install` as follows:
25+
The CLI can be run as follows:
2326

24-
``` sh
25-
$ cargo install --features cli tree-sitter-stack-graphs-javascript
26-
$ tree-sitter-stack-graphs-javascript --help
27-
```
27+
1. _(Installed)_ Install the CLI using Cargo as follows:
28+
29+
```sh
30+
cargo install --features cli tree-sitter-stack-graphs-javascript
31+
```
32+
33+
After this, the CLI should be available as `tree-sitter-stack-graphs-javascript`.
34+
35+
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:
36+
37+
```sh
38+
cargo run --features cli --
39+
```
40+
41+
The basic CLI workflow for the command-line program is to index source code and issue queries against the resulting database:
42+
43+
1. Index a source folder as follows:
44+
45+
```sh
46+
tree-sitter-stack-graphs-javascript index SOURCE_DIR
47+
```
48+
49+
_Indexing will skip any files that have already be indexed. To force a re-index, add the `-f` flag._
50+
51+
To check the status if a source folder, run:
52+
53+
```sh
54+
tree-sitter-stack-graphs-javascript status SOURCE_DIR
55+
```
56+
57+
To clean the database and start with a clean slate, run:
58+
59+
```sh
60+
tree-sitter-stack-graphs-javascript clean
61+
```
62+
63+
_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._
64+
65+
2. Run a query to find the definition(s) for a reference on a given line and column, run:
66+
67+
```sh
68+
tree-sitter-stack-graphs-javascript query definition SOURCE_PATH:LINE:COLUMN
69+
```
70+
71+
Resulting definitions are printed, including a source line if the source file is available.
72+
73+
Discover all available commands and flags by passing the `-h` flag to the CLI directly, or to any of the subcommands.
2874

2975
## Development
3076

@@ -35,35 +81,29 @@ The project is written in Rust, and requires a recent version installed. Rust c
3581
The project is organized as follows:
3682

3783
- The stack graph rules are defined in `src/stack-graphs.tsg`.
38-
- Builtins sources and configuration are defined in `src/builtins.js` and `builtins.cfg` respectively.
84+
- Builtins sources and configuration are defined in `src/builtins.it` and `builtins.cfg` respectively.
3985
- Tests are put into the `test` directory.
4086

41-
### Building and Running Tests
42-
43-
Build the project by running:
44-
45-
``` sh
46-
$ cargo build
47-
```
87+
### Running Tests
4888

4989
Run the tests as follows:
5090

51-
``` sh
52-
$ cargo test
91+
```sh
92+
cargo test
5393
```
5494

5595
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`.
5696

5797
Run the CLI from source as follows:
5898

59-
``` sh
60-
$ cargo run --features cli -- ARGS
99+
```sh
100+
cargo run --features cli -- ARGS
61101
```
62102

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

65-
``` sh
66-
$ cargo fmt
105+
```sh
106+
cargo fmt
67107
```
68108

69109
### Writing TSG
@@ -78,21 +118,21 @@ which contain self-contained TSG rules for specific language features. A VSCode
78118

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

81-
``` sh
82-
$ cargo run --features cli -- parse FILES...
83-
$ cargo run --features cli -- test TESTFILES...
121+
```sh
122+
cargo run --features cli -- parse FILES...
123+
cargo run --features cli -- test TESTFILES...
84124
```
85125

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

88-
``` sh
89-
$ cargo run --features cli -- test -V TESTFILES...
128+
```sh
129+
cargo run --features cli -- test -V TESTFILES...
90130
```
91131

92132
To generate the visualization regardless of test outcome, execute:
93133

94-
``` sh
95-
$ cargo run --features cli -- test -V --output-mode=always TESTFILES...
134+
```sh
135+
cargo run --features cli -- test -V --output-mode=always TESTFILES...
96136
```
97137

98-
Go to https://crates.io/crates/tree-sitter-stack-graphs for links to examples and documentation.
138+
Go to <https://crates.io/crates/tree-sitter-stack-graphs> for links to examples and documentation.

0 commit comments

Comments
 (0)