SysML v2 语言服务器

SysML v2 Language Server

A Language Server Protocol (LSP) implementation for SysML v2.

Features

Quick Start

Unicode and unrestricted names

Use single quotes for names outside the ASCII basic-name syntax, for example attribute 'temperature Ω' : Real;. Names may contain Unicode characters, combining marks, spaces and escaped quotes or backslashes. Their spelling is preserved without Unicode normalization (SysML 7.2.2; KerML 8.2.2.3).

Navigation, hover, references, rename and completions handle the whole quoted name. Rename updates resolved workspace references, not comments, string literals, usage names or unrelated same-named declarations. Completion and rename insert the required quotes and escapes automatically; editor positions use UTF-16, including after characters outside the Basic Multilingual Plane.

Experimental text validation

sysml/validateText checks proposed document texts against the current workspace, including unsaved documents, without opening documents or publishing diagnostics. It is disabled by default. Enable sysml.experimental.validateText.enabled to use it. Requests contain documents, an array of { uri, text } entries. The response contains each requested URI and its diagnostics, in request order.

The default limits are 5 documents, 200 lines per document, 8,192 characters per document, and 16,384 characters across the request. Characters are UTF-16 code units, so an emoji outside the Basic Multilingual Plane counts as two. The corresponding settings are maxDocuments, maxLines, maxCharacters and maxTotalCharacters under sysml.experimental.validateText. Oversized requests fail with InvalidParams before parsing or changing cached documents. Disabled requests fail with MethodNotFound.

Only requested documents are checked. Include an affected existing document with its current text to check it too. Results use the server's existing diagnostic checks; they do not certify complete SysML conformance. Input limits reduce work but do not guarantee a fixed response time.

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. The TypeScript project and build scripts use clients/vscode/ as the canonical extension source directory.

Release packaging downloads the pinned VS Code packaging CLI on demand, keeping its dependency tree out of normal development and CI installs:

npm run package

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)
make bench            # Run all benchmark suites (SUITE="parse" to select)
make bench-baseline   # Save a baseline from the stable suites
make bench-compare    # Compare two runs (BASE=<file|dir> HEAD=<file|dir>)
make bench-history    # Stable historical benchmark trends

Benchmarks

A built-in benchmark suite measures parser, symbol table, LSP provider, memory, throughput, folder-load, and sysml/validateText performance. Results are written as both JSON and Markdown to benchmarks/results/.

Running Benchmarks

npm run bench                                        # run all suites
npm run bench -- --suite parse --suite symbolTable   # specific suites
npm run bench -- --runs 10 --warmup 3                # custom iterations
npm run bench -- --output ./my-results               # custom output directory
npm run bench:compare -- --base <a> --head <b>       # compare two runs (used by CI)
npm run bench:history                                # stable historical trends

Suites

Regression Detection

Save a baseline, then compare future runs against it:

make bench-baseline                                            # save a baseline
npm run bench -- --suite symbolTable --suite folderLoad --compare   # compare, exit 1 on regression

Run the same suites for the baseline and comparison: suites share a process, so earlier suites slow later ones. The comparison uses the same stable metrics, verdicts, and thresholds as the pull request check: it warns above 15% and fails above 35%. Override the failure threshold with --threshold <n>. Baselines must come from the same Node version and platform.

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

Generate a historical report from saved JSON results with:

npm run bench:history

The history report tracks the stable metrics used by the pull request check, combining runs of the same commit and environment. Prefer medians and repeated runs for trend decisions; with the default five measured runs, p95 is indicative rather than statistically robust.

Pull Request Performance Check

The CI performance job benchmarks the PR base and head on the same runner using the PR's benchmark harness, then compares the stable metrics:

npm run bench:compare -- --base <base.json|dir> --head <head.json|dir> --warn 15 --fail 35

Results appear in the job summary as a table, slowdowns above 15% raise warning annotations, regressions above 35% fail the job, and the raw JSON/Markdown reports are uploaded as the benchmark-reports artifact.

If the base cannot be benchmarked (for example, when a PR changes server APIs the harness calls), the comparison is skipped with a warning and the job passes; check the job summary before relying on a green result.

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

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