SysML v2 Language Server
April 20, 2026 · View on GitHub
A Language Server Protocol (LSP) implementation for SysML v2.
Features
| Feature | Status | Description |
|---|---|---|
| Diagnostics | ✅ | Syntax error reporting with red squiggles |
| Document Symbols | ✅ | Outline panel with SysML model structure |
| Hover | ✅ | Element kind, type, and documentation on hover |
| Go to Definition | ✅ | Ctrl+Click navigation to declarations |
| Find References | ✅ | Find all usages of a symbol |
| Code Completion | ✅ | Keywords, snippets, and symbol suggestions |
| Semantic Tokens | ✅ | Rich, context-aware syntax highlighting |
| Folding Ranges | ✅ | Collapsible { } blocks and comments |
| Rename | ✅ | Rename symbol and all references |
| Semantic Validation | ✅ | Unresolved types, invalid multiplicity, duplicates |
| Code Actions | ✅ | Quick-fixes: naming, doc stubs, empty enums, unused defs |
| Complexity Analysis | ✅ | Structural metrics, composite index, hotspot detection |
| Mermaid Preview | ✅ | 6 diagram types with auto-detect, focus, and diff modes |
| MCP Server | ✅ | AI-assisted modelling via sysml-mcp CLI |
Quick Start
Install from Marketplace
Install via the VS Code extension from the VS Code Marketplace.
Dev Container (recommended)
Open in GitHub Codespaces or VS Code Dev Containers — everything is pre-installed, including Python 3.13, Jupyter, and Node.js 22.
Manual Setup
npm install && npm run build && npm test
Development
npm run watch # recompiles on file changes
# Then press F5 in VS Code to launch the extension + server
Use the "Client + Server" compound debug configuration to debug both sides simultaneously.
Client Examples
The LSP server is language-agnostic. Three client implementations are included to demonstrate different integration patterns:
VS Code Extension (clients/vscode/)
The primary client — a full VS Code extension using vscode-languageclient, communicating over IPC. Provides diagnostics, completions, hover, go-to-definition, semantic tokens, and all other LSP features directly in the editor.
Web Client (clients/web/)
A browser-based SysML explorer with a Node.js HTTP bridge to the LSP server. Features a live editor with auto-analyse, diagnostics panel, symbol outline, and Mermaid diagram generation with zoom/pan.
make web # build + start on http://localhost:3000
Python Client (clients/python/)
A zero-dependency Python script and Jupyter notebook that drives the LSP over stdio — the same JSON-RPC protocol VS Code uses, with no framework overhead.
python3 clients/python/sysml_lsp_client.py # analyse all examples
python3 clients/python/sysml_lsp_client.py examples/bike.sysml # analyse a specific file
The Jupyter notebook (sysml_lsp_demo.ipynb) provides an interactive walkthrough of every LSP feature.
Architecture
┌───────────────────────────┐
│ Language Server │
│ (Node.js process) │
├───────────────────────────┤
│ • ANTLR4 parser │
│ • Diagnostics │
│ • Symbols / hover │
│ • Completions / rename │
│ • Semantic tokens │
│ • Go-to-def / references │
└────────┬──────────────────┘
│ LSP (JSON-RPC)
┌───────────────────┼────────────────────┐
│ │ │
┌────────┴───────┐ ┌────────┴───────┐ ┌─────────┴──────┐
│ VS Code (IPC) │ │ Web (HTTP) │ │ Python (stdio)│
│ Extension │ │ Browser SPA │ │ Script/Jupyter│
└────────────────┘ └────────────────┘ └────────────────┘
Project Structure
sysml-v2-lsp/
├── clients/
│ ├── vscode/ # VS Code extension (TypeScript)
│ ├── web/ # Browser SPA + Node.js HTTP bridge
│ └── python/ # Zero-dep Python client + Jupyter notebook
├── server/src/ # Language Server
│ ├── server.ts # LSP connection, capability registration
│ ├── documentManager.ts # Parse cache, document lifecycle
│ ├── parser/ # Parse pipeline
│ ├── symbols/ # Symbol table, scopes, element types
│ ├── providers/ # LSP feature implementations
│ ├── analysis/ # Complexity analyzer
│ └── mcp/ # Mermaid diagram generator
├── grammar/ # ANTLR4 grammar files (.g4)
├── sysml.library/ # SysML v2 standard library
├── benchmarks/ # Performance benchmark suite
│ ├── src/ # Runner, suites, reporters, utilities
│ ├── baselines/ # Saved baseline for regression detection
│ ├── results/ # JSON + Markdown output per run
│ └── fixtures/ # Synthetic .sysml files for benchmarking
├── examples/ # Example .sysml models
├── test/ # Unit tests (vitest)
└── package.json # Extension manifest + monorepo scripts
Available Commands
make help # Show all targets
make install # Install all dependencies
make build # Generate parser + compile + bundle
make watch # Watch mode
make test # Run unit tests
make lint # ESLint
make package # Build .vsix
make package-server # Build server tarball for npm
make web # Launch web client (http://localhost:3000)
make update-grammar # Pull latest grammar, rebuild parser + DFA snapshot
make update-library # Pull latest SysML v2 standard library
make dfa # Regenerate DFA snapshot (after any grammar change)
make ci # Full CI pipeline (lint + build + test)
npm run bench # Run all benchmark suites
npm run bench:baseline # Save benchmark baseline
npm run bench:regression # Compare against baseline
Benchmarks
A built-in benchmark suite measures parser, symbol table, LSP provider, memory, throughput, and folder-load performance. Results are written as both JSON and Markdown to benchmarks/results/.
Running Benchmarks
npm run bench # run all suites
npm run bench:parse # parse suite only
npm run bench:providers # LSP providers suite only
Or use the runner directly for full control:
npx tsx benchmarks/src/runner.ts --suite parse --suite symbolTable
npx tsx benchmarks/src/runner.ts --runs 10 --warmup 3
npx tsx benchmarks/src/runner.ts --output ./my-results
Suites
| Suite | What it measures |
|---|---|
parse | ANTLR4 parse time — cold (no DFA) vs warm (DFA snapshot pre-loaded) |
symbolTable | Symbol table build and lookup latency |
providers | LSP features: diagnostics, hover, completion, references, rename, etc. |
memory | Heap allocation per file and scaling behaviour |
throughput | End-to-end lines/sec and tokens/sec across all example files |
folderLoad | Full folder parse + symbol build (examples, standard library, all) |
Regression Detection
Save a baseline, then compare future runs against it:
npm run bench:baseline # save current results as baseline
npm run bench:regression # compare against baseline, exit 1 on regression
The default regression threshold is 20%. Override with --threshold <n>.
Viewing Results
Each run produces a JSON file and a Markdown report in benchmarks/results/. To convert an existing JSON result to Markdown:
npx tsx benchmarks/src/reporters/markdownReporter.ts benchmarks/results/<file>.json
Grammar Updates
The grammar files in grammar/ are sourced from daltskin/sysml-v2-grammar. To pull the latest version, rebuild the parser, and regenerate the DFA snapshot:
make update-grammar
This fetches the .g4 files, runs npm run build, and regenerates the DFA snapshot that eliminates the ANTLR4 cold-start penalty. If you edit grammar files manually, run make dfa afterwards.
Technology Stack
| Component | Technology |
|---|---|
| Language | TypeScript (strict mode) |
| Runtime | Node.js ≥ 18 |
| Parser | antlr4ng |
| Generator | antlr-ng |
| LSP | vscode-languageserver |
| Bundler | esbuild |
| Tests | vitest |
Related Projects
- daltskin/sysml-v2-grammar — Grammar for SysML v2
- daltskin/VSCode_SysML_Extension — VS Code extension with visualization
- OMG SysML v2 Specification
License
MIT