ForgeLSP

High-performance Language Server Protocol implementation for ForgeScript

---

✨ Features

🔍 Language Intelligence

• Hover Documentation: Rich markdown tooltips with function signatures, descriptions, and examples
• Auto-Completion: Context-aware suggestions triggered by $ or .
• Signature Help: Real-time parameter hints with active parameter highlighting
• Semantic Tokens: Syntax highlighting for functions, strings, numbers, and keywords
• Diagnostics: Real-time error detection with helpful messages

⚡ Performance

• Trie-based Lookup: O(k) function name matching for instant completions
• Async I/O: Non-blocking operations using Tokio runtime
• Smart Caching: Metadata caching with network fallback
• Incremental Parsing: Efficient document re-parsing on changes

🌐 Flexible Configuration

• GitHub Shorthand: Use github:owner/repo#branch syntax for metadata URLs
• Multi-Source Support: Load function metadata from multiple URLs
• Workspace Config: Configure per-project via forgeconfig.json

---

📁 Project Structure

forgelsp/
├── src/
│   ├── main.rs          # Entry point, LSP service initialization
│   ├── server.rs        # LanguageServer trait implementation
│   ├── hover.rs         # Hover provider logic
│   ├── parser.rs        # ForgeScript parser with diagnostics
│   ├── metadata.rs      # Metadata fetching, caching, and Trie
│   ├── diagnostics.rs   # Diagnostic publishing utilities
│   ├── semantic.rs      # Semantic token extraction
│   └── utils.rs         # Helper functions and config loading
├── docs/                # Comprehensive module documentation
│   ├── main.md          # Entry point documentation
│   ├── server.md        # LSP server documentation
│   ├── hover.md         # Hover feature documentation
│   ├── parser.md        # Parser implementation details
│   ├── metadata.md      # Metadata management guide
│   ├── diagnostics.md   # Diagnostics system overview
│   ├── semantic.md      # Semantic highlighting details
│   └── utils.md         # Utility functions reference
├── .github/
│   └── workflows/       # CI/CD pipelines
├── Cargo.toml           # Rust dependencies
└── Cargo.lock           # Dependency lockfile

---

📦 Source Files

main.rs

Entry point for the LSP server. Initializes the metadata manager, loads configuration from forgeconfig.json, and starts the Tower LSP service over stdio.

server.rs

Implements the LanguageServer trait from Tower LSP:

• initialize: Registers capabilities (hover, completion, signature help, semantic tokens)
• did_open/did_change: Processes document changes and triggers diagnostics
• hover: Delegates to hover handler
• completion: Returns function suggestions based on cursor context
• signature_help: Provides parameter hints for function calls
• semantic_tokens_full: Returns semantic highlighting data

hover.rs

Handles hover requests by:

1. Locating the token under the cursor
2. Looking up function metadata in the Trie
3. Generating markdown documentation with signatures, descriptions, and examples

parser.rs

Custom ForgeScript parser that:

• Tokenizes $functionName[args] syntax
• Supports nested function calls
• Validates argument counts against metadata
• Reports diagnostics for unknown functions and syntax errors

metadata.rs

Manages function metadata with three key components:

Component	Purpose
Fetcher	HTTP client with file-based caching
FunctionTrie	Prefix-tree for O(k) function lookup
MetadataManager	Coordinates fetching and indexing

diagnostics.rs

Converts parser diagnostics to LSP format and publishes them to the client.

semantic.rs

Extracts semantic tokens from code blocks using regex patterns:

• Functions ($name)
• Strings (single/double quoted)
• Numbers (integers/floats)
• Keywords (true, false)

utils.rs

Utility functions:

• load_forge_config: Parses forgeconfig.json
• resolve_github_shorthand: Expands github:owner/repo to raw URLs
• spawn_log: Async logging helper

---

📚 Documentation

Comprehensive documentation for each module is available in the docs/ directory:

• main.md - Entry point initialization flow
• server.md - LSP server implementation details
• hover.md - Hover provider logic
• parser.md - Parser implementation and escape handling
• metadata.md - Metadata management and Trie algorithm
• diagnostics.md - Diagnostic system overview
• semantic.md - Semantic token extraction
• utils.md - Utility functions reference

---

🔧 Dependencies

Crate	Version	Purpose
tower-lsp	0.20.0	LSP framework
tokio	1.x	Async runtime
reqwest	0.12	HTTP client
serde	1.x	Serialization
serde_json	1.x	JSON parsing
nom	8.0.0	Parser combinators
regex	1.12.2	Pattern matching
smallvec	1.15.1	Stack-allocated vectors
anyhow	1.x	Error handling
base64	0.22.1	URL-safe cache keys
futures	0.3.31	Async utilities
tracing-subscriber	0.3.22	Structured logging

---

🚀 Building

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run directly
cargo run

Release Profile Optimizations

[profile.release]
opt-level = 3      # Maximum optimization
lto = "fat"        # Link-time optimization
codegen-units = 1  # Single codegen unit for better optimization
panic = "abort"    # Smaller binary size
strip = true       # Remove debug symbols

---

📊 LSP Capabilities

Capability	Status	Description
Text Document Sync	✅ Full	Complete document sync on each change
Hover	✅	Function documentation on hover
Completion	✅	Triggered by $ and .
Signature Help	✅	Triggered by $, [, ;
Semantic Tokens	✅ Full	Full document semantic highlighting
Diagnostics	✅	Real-time error reporting

---

🔗 Related Projects

• ForgeLSP VS Code Extension - The VS Code client for this LSP
• ForgeScript - The ForgeScript language

---

Contributors

• Striatp (@striatp): Helping me with the github build scripts to build the lsp for all devices

---

📄 License

GPL-3 License - See LICENSE for details.