Crate leekscript_rs 

leekscript-rs

A LeekScript parser and analysis library implemented with sipha.

Architecture

The crate is layered as follows (dependencies flow downward):

• Core: syntax, types — token/node kinds, type system.
• Parse: grammar, parser, preprocess — grammar, parsing, include handling.
• Analysis: analysis — scope, validation, type checking.
• Orchestration: document, doc_comment — document-level API and doc comments.
• Tooling: formatter, visitor, tree_display, [transform] — formatting, visiting, display.
• LSP: [lsp] (and [utf16] when enabled) — language server and UTF-16 utilities.

See ARCHITECTURE.md in the repository root for layer details and where to add new features (new syntax, LSP features, etc.).

Utilities from sipha

The syntax tree (sipha::red::SyntaxNode) supports node_at_offset, token_at_offset, first_token, last_token, and find_ancestor. Use parse_to_doc for a single handle (source, root, line index, and those helpers).

UTF-16 (optional feature)

Enable the utf16 feature for LSP and editor integration: ParsedDoc then provides offset_to_line_col_utf16, offset_to_line_col_utf16_1based, and span_to_utf16_range.

Modules

analysis

doc_comment

document

formatter

grammar

parser

preprocess

signatures

Loading of signature files (.sig) for stdlib and API definitions.

syntax

tree_display

types

visitor

Structs

AnalysisResult

Result of running scope building and validation.

AnalyzeOptions

Options for running analysis (single entry point for program or document).

DocComment

Structured documentation parsed from a Doxygen-style comment.

DocumentAnalysis

Result of document-level analysis: source, AST, diagnostics, scope, types, definition map, doc maps, class hierarchy.

DocumentAnalysisOptions

Options for building a DocumentAnalysis.

FormatDriver

Driver that writes the syntax tree to a string by visiting tokens. You can use [format] directly, or build a custom flow with walk(root, &mut driver, &opts).

FormatterOptions

Options for printing the syntax tree.

IncludeTree

One file in the include tree: path, source, parsed root, and parsed included files in order.

LineIndex

Maps byte offsets to line and column.

ParsedDoc

A successfully parsed document: source buffer, line index, and syntax root.

RecoverMultiResult

Result of parsing in multi-error recovery mode: partial output and all collected errors.

ScopeId

Identifies a scope in the scope store (used for parent chain).

ScopeStore

Store for all scopes; root is at index 0.

SemanticDiagnostic

A single diagnostic from semantic analysis or validation (e.g. undefined variable, type error).

TextEdit

A text edit: replace old_source[start..end] with new_text.

TreeDisplayOptions

Options for formatting the syntax tree.

WalkOptions

Options that control how the tree is traversed.

Enums

AnalysisError

Error codes for semantic validation (mirroring leekscript-java Error enum).

CastType

Cast compatibility between types (matches Java CastType).

IncludeError

Error from the include preprocessor.

ResolvedSymbol

RootSymbolKind

Kind of root-level symbol for definition map (matches scope seeding order).

Severity

Severity for analysis/validation diagnostics (errors, warnings, etc.).

Type

Primitive and built-in types matching leekscript-java’s Type constants.

Constants

KEYWORDS

LeekScript keywords (for completion and tooling). Sorted for display.

Traits

Visitor

Trait for visiting a sipha syntax tree.

Functions

all_files

Flatten the tree into (path, source) for all files (root first, then includes depth-first).

analyze

Build scope from the tree and run validation. Returns diagnostics and the scope store.

analyze_with_include_tree

Analyze the main file of an include tree: seed scope from included files and signatures, then analyze the main AST.

analyze_with_options

Run analysis with the given options. Dispatches to analyze, analyze_with_signatures, or analyze_with_include_tree as appropriate.

analyze_with_signatures

Analyze the program with the root scope pre-seeded from signature files (e.g. stdlib constants and functions). This allows references to global constants and built-in functions to resolve without errors. Also seeds built-in type/class names (e.g. Class, bool) so that common LeekScript code validates.

build_class_super

Build map class_name -> superclass_name from the AST (for visibility: subclass can see protected).

build_definition_map

Build (name, kind) -> (path, start, end) for root-level symbols (includes first, then main).

build_doc_map

Build a map from declaration (start_byte, end_byte) to parsed documentation.

build_grammar

Build the LeekScript grammar (Phase 1: token stream).

build_include_tree

Build the include tree: parse source as the main file, resolve each include("path"), load and parse those files (with circular include detection), and return the tree.

build_scope_extents

Build list of (ScopeId, extent) where extent is (start_byte, end_byte). Root scope (ScopeId(0)) is always first with extent (0, source_len). Remaining entries are in walk order, matching scope_id_sequence.

build_signature_grammar

Build the signature file grammar. Start rule: start → sig_ws sig_file sig_ws eof.

decl_span_for_name_span

Find the declaration node span (for doc_map lookup) that contains the given name span.

format

Print the syntax tree to a string. When canonical_format, parenthesize_expressions, or annotate_types is set, runs a custom walk; otherwise uses sipha’s emit API for round-trip.

format_syntax_tree

Format a syntax tree starting at root as a multi-line string.

is_valid_identifier

Returns true if name is a valid LeekScript identifier (non-empty, starts with letter or underscore, rest alphanumeric or underscore). Used e.g. for rename validation in LSP.

parse

Parse source as a program (Phase 3/4: list of statements).

parse_doc_comment

Parse one or more raw comment strings (e.g. from multiple preceding trivia tokens). If the combined text contains a block comment (/** ... */), only that block is used so that a preceding line comment (e.g. // Comment) does not corrupt the doc block.

parse_error_to_diagnostics

Convert a parse error into semantic diagnostics for LSP or other tooling.

parse_error_to_miette

Convert a parse error into a miette::Report with source snippet and resolved literals.

parse_expression

Parse source as a single expression (Phase 2).

parse_recovering

Parse in recovering mode: on failure, returns the partial output and the error.

parse_recovering_multi

Parse in multi-error recovery mode: on statement failures, skip to the next sync point (e.g. ;, }, or statement-start keyword) and continue, collecting up to max_errors errors.

parse_signatures

Parse source as a signature file (function/class/global declarations only).

parse_to_doc

Parse source and return a ParsedDoc: source bytes, line index, and syntax root.

parse_tokens

Parse source as a token stream (Phase 1 lexer).

print_syntax_tree

Print the syntax tree to stdout.

program_literals

Literal table for the program grammar (used for parsing full programs).

reparse

Reparse after a text edit, reusing unchanged parts of the tree.

reparse_or_parse

Apply a text edit and reparse incrementally, or fall back to full parse.

scope_at_offset

Find the innermost scope containing the given byte offset. When extents is empty (e.g. partial state), returns root scope ID so the LSP never panics.

seed_scope_from_signatures

Seed the root scope from parsed signature file(s). Each element of signature_roots should be the root node returned by parse_signatures() (may be a wrapper or NodeSigFile).

walk

Walks the tree starting at root with the given visitor and options.

Type Aliases

WalkResult

Result of a visitor callback: continue walking or stop.