stack-graphs

The repository includes several examples demonstrating different name binding patterns. Each example directory contains a stack-graphs.tsg file describing the implemented behavior and a tests directory showcasing that behavior. Note that while these examples use Python syntax, they may not strictly implement Python semantics.

Available examples:

• nested-scope/: Demonstrates nested scoping.
• sequential-definitions/: Demonstrates sequential definitions.
• modules/: Demonstrates modules and imports.

The languages/ directory contains stack graphs definitions for specific programming languages. Each definition is packaged following a naming convention that combines the target tool and the language name.

For example, tree-sitter-stack-graphs-typescript is the definition for TypeScript intended for use with tree-sitter-stack-graphs.

Stack graphs definitions are versioned independently of the underlying grammar versions. They use an adapted semantic versioning (MAJOR.MINOR.PATCH) scheme based on the compatibility of the resulting resolutions:

• MAJOR: Increment if the new stack graphs are incompatible with previous versions (i.e., some existing resolutions are missing when replacing old graphs with new ones).
• MINOR: Increment if the new stack graphs are compatible with previous versions (i.e., all pre-existing resolutions remain, though new resolutions may be added).
• PATCH: Increment for bug fixes.

Note for 0.x.y versions: Increment the MINOR version for changes that are incompatible with the previous version.

Dependency Rule: Versioned releases of stack graphs should only depend on versioned releases of the grammars they use.

Stack graph rules are written using the tree-sitter-graph syntax.

• Rule Location: In this project, rules are defined in src/stack-graphs.tsg.
• Builtins: Sources and configuration are in src/builtins.it and builtins.cfg.
• Tooling: A VSCode extension is available for TSG syntax highlighting.
• Examples: Refer to the stack-graphs examples for self-contained rules for specific language features.

The lsp-positions crate solves the problem of interoperating with the Language Server Protocol (LSP) when working with Rust source code.

Rust strings are UTF-8 encoded and indexed by bytes, whereas LSP specifies character locations using UTF-16 code units. To bridge this gap, lsp-positions tracks each source code position using two distinct units:

1. UTF-8 byte position: Used for indexing into standard Rust str and [u8] data.
2. UTF-16 code unit position: Used within a line to generate Position values compatible with LSP specifications.

This dual tracking ensures that tools analyzing source code can accurately map internal byte offsets to the character-based locations required by LSP clients and servers.

If you are contributing to the project or running it without installation, use the following commands. Note that the CLI features are gated behind the cli feature flag.

• Run CLI from source: cargo run --features cli -- ARGS
• Build: cargo build (use --features cli to include CLI binaries)
• Test: cargo test (use --features cli to include CLI tests)
• Format: cargo fmt

# Run CLI with arguments
cargo run --features cli -- <ARGS>

# Build with CLI features
cargo build --features cli

You can install the command-line tool using Cargo. Once installed, the CLI is available via the tree-sitter-stack-graphs-java command.

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

To start developing stack graph definitions for a new language, use the init command. This will launch an interactive prompt to collect information about the language, its grammar dependency, and the project structure, then generate a scaffold in the specified directory.

tree-sitter-stack-graphs init PROJECT_DIR

To use the TypeScript stack graph definitions in your Rust application, add the tree-sitter-stack-graphs-typescript crate to your Cargo.toml dependencies.

[dependencies]
tree-sitter-stack-graphs-typescript = "0.4"

To use the JavaScript stack graph definitions as a library in your Rust project, add the following dependency to your Cargo.toml file:

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

You can install the command-line program using cargo install. Ensure you include the cli feature to enable the binary.

After installation, the CLI is available via the tree-sitter-stack-graphs-typescript command.

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