sysml-v2-lsp 0.1.6 → 0.2.0

package/CHANGELOG.md

@@ -1,101 +1,37 @@
 # Changelog
 
-## [0.1.6]
-
-### Fixed
-
-- Fix keyword validator silently ignoring extreme typos (e.g., `pasddsafart def Vehicle`) — identifiers in keyword positions are now flagged even when no close keyword match exists (Levenshtein distance > 2), with a generic "Unexpected identifier" message instead of requiring a "Did you mean?" suggestion
-- Fix `flagUnknownIdentifiers` incorrectly skipping identifiers followed by `def` — valid keywords before `def` (`part`, `action`, etc.) have their own token types, so an IDENTIFIER before `def` is always invalid
-- Fix Python LSP client missing diagnostics on first run — `drain_notifications` used a fixed 2-second timeout, but DFA warm-up on first server start takes ~15-20s. Added `drain_until_diagnostics()` which waits up to 30s and stops as soon as diagnostics arrive
-
-## [0.1.5]
+## [0.2.0]
 
 ### Added
 
-- Python LSP client example in `clients/python/` — zero-dependency script demonstrating how to drive the SysML v2 language server from Python over JSON-RPC/stdio, using the same server as VS Code
-- `sysml.inlayHints.enabled` VS Code setting — allows users to toggle inlay hints on/off (default: true). Server-side gating returns empty results when disabled
-- Extension Development Host settings (`examples/.vscode/settings.json`) — disables inlay hints during F5 testing
-- Code completion provider tests — ensures keyword completions, snippet insert text, and resolve are covered
-- Call hierarchy typed-usage detection — `action x : TypeDef`, `state x : TypeDef`, and `calc x : TypeDef` composition patterns are now recognised as outgoing/incoming calls, not just explicit `perform`/`include`/`accept` keywords
+- Custom LSP request (`sysml/model`): full semantic model with scoped queries
+- MCP server (`sysml-mcp` CLI): 7 tools, 3 resources, 3 prompts for AI-assisted modelling
+- Standard library: 94 bundled SysML v2 / KerML files from OMG release repo
+- Inlay hints: ghost text for inferred types and supertypes
+- Call hierarchy: action call graph navigation
+- Type hierarchy: specialization chain navigation
+- Signature help: parameter tooltips for action/calc invocations
+- Code lens: reference counts above definitions
+- Document links: clickable `import` statements
+- Workspace symbols: cross-document symbol search
+- Linked editing ranges: simultaneous rename of all occurrences
+- Selection ranges: smart expand/shrink selection
+- Code actions: quick-fix actions for diagnostics
+- Formatting: document and range formatting
+- Keyword validation: typo detection with "did you mean?" suggestions
+- npm package: `sysml-v2-lsp` distributable for third-party extensions
+- Python LSP client: reference JSON-RPC/stdio client
+- Parse worker: background ANTLR parsing with DFA warm-up
+- `make update-library`: fetch latest standard library from upstream
+- `make package-server` / `make test-package`: npm tarball build and validation
 
 ### Changed
 
-- Reorganise folder structure: `client/` → `clients/vscode/`, Python client at `clients/python/`
-- Call hierarchy provider no longer depends on `TextDocuments` — uses `DocumentManager` for all text access, simplifying the architecture
-- `DocumentManager.getUris()` now returns all open documents (from `TextDocuments.all()`), not just cached ones — fixes providers that scan across documents (call hierarchy, references, code lens)
-- Suppress esbuild size warnings — custom build summary replaces default output to avoid misleading ⚠️ indicators on the expected 1.4 MB ANTLR parser bundle
-
-### Fixed
-
-- Fix `end` keyword in connection/interface definitions causing false positive diagnostics — identifiers after `end` (e.g., `end source : PowerPort;`) were incorrectly flagged as keyword typos
-- Fix `in`/`out`/`inout` direction keywords causing false positive diagnostics — identifiers after `in`, `out`, `inout` (e.g., `out arrived : Boolean`) were incorrectly flagged as keyword typos
-- Fix Find References only returning declarations — added text-based reference scanning (`findTextReferences`) across all open documents to find usage-site references (e.g., `action adjustWheels : AdjustWheelAngle`)
-- Fix CodeLens reference counts only counting declarations — now uses text-based scanning consistent with Find References
-- Remove redundant `activationEvents` from `package.json` — VS Code auto-generates from `contributes.languages`
-- Remove unnecessary `sysml.inlayHints.enabled` from dev workspace settings (only needed in Extension Development Host)
-
-## [0.1.4]
-
-### Added
-
-- Extract MCP resource and prompt handler logic into testable `mcpCore.ts` module — 3 resource handlers (element kinds, keywords, grammar overview) and 3 prompt handlers (review SysML, explain element, generate SysML)
-- `constraint` grammar rules: `ConstraintDefinition`, `ConstraintUsage`, `RequirementConstraintMember`, `assert constraint`
-- 9 new unit tests for MCP resources and prompts (101 total tests, up from 92)
-- Constraint-related unit tests
-
-### Fixed
-
-- Fix false positive diagnostics on qualified names with `::` (e.g., `toaster::maxTemp`) — add `COLON_COLON` to next-token skip list in `parseWorker.ts`
-- Fix identifiers after `actor`, `stakeholder`, `subject`, `variant`, `ref`, `snapshot`, `timeslice` incorrectly flagged as keyword typos — add to `NAME_PRECEDING_KEYWORDS` in both validators
-- Fix false positive keyword typo diagnostics on dot-chain and expression-position identifiers (e.g., `transportPassenger.driver`) — skip identifiers preceded by `.`, `=`, `:`, `::`, `:>`, `:>>`
-- Remove unused `parseAndBuild` import in `mcpServer.ts` after refactoring
-
-### Changed
-
-- Slim VS Code dev extension to lightweight harness — move TextMate grammar and snippets to separate `VSCode_SysML_Extension` repo
-- Simplify `language-configuration.json` to minimal comments and brackets for dev use
-
-## [0.1.3]
-
-### Added
-
-- `make test-package` target to test npm package in a simulated consumer project
-- README badges: npm version, license, Socket.dev supply chain security
-
-### Fixed
-
-- Fix `constructor.name` minification breaking code lens and symbol resolution — `getRuleName()` now uses ANTLR4 `ruleIndex` + `ruleNames[]` instead of `constructor.name` which is mangled by esbuild
-- Rename ESM bundles from `.js` to `.mjs` for Node 20 compatibility — `child_process.fork()` now correctly treats server and worker as ESM
-- Move `@modelcontextprotocol/sdk` and `zod` from `dependencies` to `devDependencies` — they are fully bundled by esbuild and not needed at runtime
-- Guard `postinstall` script with `[ -f tsconfig.json ]` so it only runs in dev checkout, not in consumer installs
-
-## [0.1.2]
-
-### Added
-
-- Release checklist (`.github/RELEASE_CHECKLIST.md`)
-
-### Fixed
-
-- Remove unused `antlr4-c3` dependency from server package
-- Fix client extension server path to use bundled `dist/` output (VSIX was broken)
-- Fix `postinstall` script silently swallowing server install failures
-- Sync versions across `server/package.json`, `client/package.json`, and MCP server to `0.1.1`
-- Align Node engine requirement to `>=20` in `server/package.json` (was `>=18`)
-- Update esbuild target from `node18` to `node20`
-- Add `*.tgz` to `.gitignore` to prevent accidental commits
-- Add explicit `require`/`default` conditions to `exports` field
-- Remove redundant `activationEvents` (auto-generated from `contributes.languages`)
-
-## [0.1.1]
-
-### Fixed
-
-- Update postinstall script to handle missing `client` directory gracefully
-- Add npm trusted publishing (OIDC) support and normalize repository URL
-- Remove accidentally committed `.tgz` archive
-- Skip `npm version` in release workflow when git tag already matches `package.json`
-- Drop Node 18 from CI matrix (Vite 7 requires Node 20+)
+- Go-to-definition falls back to standard library for unresolved symbols
+- Recursive type name extraction in symbol table
+- Synthetic `start`/`done` nodes in activity diagram flows
+- Element kind enum expanded to 55 kinds
+- esbuild bundles four targets: server, worker, MCP server, VS Code client
 
 ## [0.1.0]
 

package/README.md

@@ -1,288 +1,99 @@
 # SysML v2 Language Server
 
-[![npm version](https://img.shields.io/npm/v/sysml-v2-lsp)](https://www.npmjs.com/package/sysml-v2-lsp)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Socket Badge](https://socket.dev/api/badge/npm/package/sysml-v2-lsp)](https://socket.dev/npm/package/sysml-v2-lsp)
+A [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) implementation for [SysML v2](https://www.omgsysml.org/SysML-2.htm), powered by the ANTLR4 grammar from [daltskin/sysml-v2-grammar](https://github.com/daltskin/sysml-v2-grammar).
 
-A [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/) with [Model Context Protocol](https://modelcontextprotocol.io/) implementation for [SysML v2](https://www.omgsysml.org/SysML-2.htm), providing rich editing, navigation, and code intelligence for LSP-compatible editors.
+## Features
 
-Powered by the ANTLR4 grammar from [daltskin/sysml-v2-grammar](https://github.com/daltskin/sysml-v2-grammar).
+| 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 |
 
-> **Works with:** VS Code, Neovim, Emacs, Sublime Text, Helix, and any editor that supports the Language Server Protocol.
+## Quick Start
 
----
+### Dev Container (recommended)
 
-## Language Server Features
+Open in GitHub Codespaces or VS Code Dev Containers — everything is pre-installed.
 
-The language server runs as a separate process and communicates over LSP — these features are available in **any** compatible editor.
-
-### Editing & Navigation
-
-| Feature              | Description                                                            |
-| -------------------- | ---------------------------------------------------------------------- |
-| **Diagnostics**      | Syntax errors, unknown identifiers, keyword typos with severity levels |
-| **Code Completion**  | Keywords, snippets, and symbol suggestions with documentation          |
-| **Signature Help**   | Parameter tooltips when invoking `action def` / `calc def`             |
-| **Hover**            | Element kind, type, qualified name, and documentation                  |
-| **Go to Definition** | Jump to a symbol's declaration                                         |
-| **Find References**  | Find all usages of a symbol across open files                          |
-| **Rename Symbol**    | Rename a symbol and update all references                              |
-| **Linked Editing**   | Edit a name and all same-scope occurrences update simultaneously       |
-| **Document Links**   | Clickable `import` paths — jump to the imported namespace              |
-
-### Code Intelligence
-
-| Feature               | Description                                                              |
-| --------------------- | ------------------------------------------------------------------------ |
-| **CodeLens**          | Reference counts shown above each definition                             |
-| **Inlay Hints**       | Ghost text showing inferred types (`: Type`) and supertypes (`:> Super`) |
-| **Type Hierarchy**    | Navigate specialization chains — supertypes and subtypes                 |
-| **Call Hierarchy**    | Navigate `perform`/`include` chains between actions                      |
-| **Workspace Symbols** | Fuzzy search for any definition across all open files                    |
-
-### Presentation & Formatting
-
-| Feature              | Description                                                                    |
-| -------------------- | ------------------------------------------------------------------------------ |
-| **Semantic Tokens**  | Rich, context-aware syntax highlighting (definitions, usages, keywords, types) |
-| **Document Symbols** | Outline / breadcrumbs showing SysML model structure                            |
-| **Folding Ranges**   | Collapsible `{ }` blocks and comment regions                                   |
-| **Selection Ranges** | Smart expand/shrink selection (word → line → block → enclosing block)          |
-| **Quick Fix**        | Fix keyword typos (e.g., `paart` → `part`)                                     |
-| **Formatting**       | Auto-indent, normalize braces, trim trailing whitespace                        |
-
-### Parser
-
-- ANTLR4-based parser via [antlr4ng](https://github.com/mike-lischke/antlr4ng)
-- SLL/LL dual-mode strategy — fast path with automatic fallback
-- DFA warm-up for near-instant first-parse performance
-- Worker thread architecture for non-blocking document processing
-- Symbol table with qualified name resolution and cross-file references
-
----
-
-## MCP Server (AI Integration)
-
-A standalone [Model Context Protocol](https://modelcontextprotocol.io/) server that lets AI assistants parse, validate, and query SysML v2 models. Runs independently of any editor.
-
-### Tools
-
-| Tool              | Description                                            |
-| ----------------- | ------------------------------------------------------ |
-| `parse`           | Parse SysML source, build symbol table, return summary |
-| `validate`        | Check syntax and return errors                         |
-| `getSymbols`      | List symbols (filter by kind, URI, definitions/usages) |
-| `getDefinition`   | Look up a symbol by name or qualified name             |
-| `getReferences`   | Find all references to a symbol                        |
-| `getHierarchy`    | Get parent–child containment structure                 |
-| `getModelSummary` | Counts, kinds, and loaded documents                    |
-
-### Resources
-
-| URI                        | Description                  |
-| -------------------------- | ---------------------------- |
-| `sysml://element-kinds`    | All recognised element kinds |
-| `sysml://keywords`         | Complete keyword list        |
-| `sysml://grammar-overview` | Language structure reference |
-
-### Prompts
-
-| Prompt            | Description                          |
-| ----------------- | ------------------------------------ |
-| `review-sysml`    | Review a SysML model for correctness |
-| `explain-element` | Explain a SysML element kind         |
-| `generate-sysml`  | Generate SysML from a description    |
-
-### MCP Setup
-
-**VS Code / GitHub Copilot** — The workspace includes `.vscode/mcp.json`, so the MCP server is automatically available after building.
-
-**Claude Desktop** — Add to `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "sysml-v2": {
-      "command": "node",
-      "args": ["/path/to/sysml-v2-lsp/dist/server/mcpServer.mjs"]
-    }
-  }
-}
-```
-
-**Any MCP client** — Run the server directly via stdio:
-
-```bash
-npx sysml-v2-lsp   # after npm install -g sysml-v2-lsp
-# or
-node dist/server/mcpServer.mjs
-```
-
-### Quick Test Examples
-
-Once the MCP server is connected, try these prompts:
-
-> Parse this: `package Demo { part def Vehicle { attribute speed : Real; } part car : Vehicle; }`
-
-> Validate this: `part def Broken { attribute x :`
-
-> What symbols are in the model?
-
-> Find the definition of Vehicle
-
-> Show the hierarchy of car
-
----
-
-## VS Code Dev Extension
-
-A lightweight VS Code extension is included for **development and debugging** of the language server. It registers the `sysml` language ID, starts the LSP client, and provides a restart command — nothing more.
-
-For the full VS Code experience (TextMate grammar, snippets, language configuration, visualization), see [daltskin/VSCode_SysML_Extension](https://github.com/daltskin/VSCode_SysML_Extension).
-
-| Feature                  | Description                                                                    |
-| ------------------------ | ------------------------------------------------------------------------------ |
-| **Language Registration**| Registers `.sysml` / `.kerml` file types                                       |
-| **LSP Client**           | Starts and manages the language server process                                 |
-| **Restart Command**      | `SysML: Restart Language Server` command                                       |
-| **Dev Container**        | Open in GitHub Codespaces or VS Code Dev Containers — everything pre-installed |
-| **Debug Configurations** | "Client + Server" compound launch for simultaneous debugging                   |
-| **Example Files**        | `examples/` folder with camera, toaster, and vehicle models                    |
-
----
-
-## Getting Started
-
-### Using the VS Code Extension
-
-Open in GitHub Codespaces or Dev Containers (recommended), or manually:
+### Manual Setup
 
 ```bash
+# Install dependencies
 npm install
-npm run build
-# Press F5 to launch the Extension Development Host
-```
-
-### Using the LSP with Other Editors
 
-Build the server, then point your editor's LSP client at it:
+# Generate TypeScript parser from ANTLR4 grammar
+npm run generate
 
-```bash
-npm install && npm run build
-# Server binary: dist/server/server.mjs
-# Start with: node dist/server/server.mjs --stdio
-```
-
-**Neovim** (via [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig)):
-
-```lua
-vim.lsp.start({
-  name = 'sysml',
-  cmd = { 'node', '/path/to/sysml-v2-lsp/dist/server/server.mjs', '--stdio' },
-  filetypes = { 'sysml' },
-})
-```
-
-**Emacs** (via [lsp-mode](https://github.com/emacs-lsp/lsp-mode)):
+# Build
+npm run build
 
-```elisp
-(lsp-register-client
-  (make-lsp-client
-    :new-connection (lsp-stdio-connection
-                     '("node" "/path/to/sysml-v2-lsp/dist/server/server.mjs" "--stdio"))
-    :activation-fn (lsp-activate-on "sysml")
-    :server-id 'sysml-lsp))
+# Run tests
+npm test
 ```
 
-**Python** — A zero-dependency Python LSP client is included in [`clients/python/`](clients/python/):
+### Development
 
 ```bash
-cd clients/python
-python3 sysml_lsp_client.py                       # analyse all example files
-python3 sysml_lsp_client.py ../../examples/vehicle-model.sysml  # specific file
-```
-
-This demonstrates that the same LSP server used by VS Code can be driven from
-any language — see the [Python client README](clients/python/README.md) for details.
-
-### Using the MCP Server
+# Watch mode — recompiles on file changes
+npm run watch
 
-```bash
-npm install && npm run build
-node dist/server/mcpServer.mjs   # stdio transport
+# Then press F5 in VS Code to launch the extension + server
 ```
 
----
+Use the **"Client + Server"** compound debug configuration to debug both sides simultaneously.
 
 ## Architecture
 
 ```
-┌──────────────────────────────────────────────────────────────────┐
-│                     Language Server (Node.js)                    │
-│                                                                  │
-│  ┌──────────────┐  ┌──────────────────┐  ┌───────────────────┐   │
-│  │ ANTLR4 Parser│  │   Symbol Table   │  │   21 Providers    │   │
-│  │ (worker thr.)│──│ scopes, q-names  │──│ completion, hover │   │
-│  │ SLL/LL dual  │  │ cross-file refs  │  │ def, refs, rename │   │
-│  └──────────────┘  └──────────────────┘  │ hierarchy, format │   │
-│                                          │ tokens, lens, ... │   │
-│                                          └───────────────────┘   │
-└──────────────────────┬───────────────────────────┬───────────────┘
-                       │ LSP (stdio/IPC)           │
-          ┌────────────┴────────────┐              │
-          │      Any Editor         │              │
-          │  VS Code, Neovim,       │              │
-          │  Emacs, Sublime, ...    │              │
-          └─────────────────────────┘              │
-                                                   │
-┌──────────────────────────────────────────────────┴──────────────┐
-│                     MCP Server (standalone)                     │
-│  7 tools · 3 resources · 3 prompts · stdio transport            │
-│                                                                 │
-│  ┌─────────────────┐  ┌──────────────────┐ ┌──────────────────┐ │
-│  │  Claude, Copilot│  │  Cursor, Windsurf│ │  Any MCP Client  │ │
-│  └─────────────────┘  └──────────────────┘ └──────────────────┘ │
-└─────────────────────────────────────────────────────────────────┘
+┌──────────────────────┐     IPC     ┌──────────────────────────┐
+│   VS Code Extension  │ ◄─────────► │    Language Server        │
+│   (Language Client)   │             │    (Separate Process)     │
+├──────────────────────┤             ├──────────────────────────┤
+│ • Starts server       │             │ • ANTLR4 parser           │
+│ • Registers language  │             │ • Diagnostics             │
+│                       │             │ • Completion (keywords)   │
+│                       │             │ • Symbols / hover         │
+│                       │             │ • Go-to-def / references  │
+│                       │             │ • Semantic tokens         │
+│                       │             │ • Rename / folding        │
+└──────────────────────┘             └──────────────────────────┘
 ```
 
 ### Project Structure
 
 ```
 sysml-v2-lsp/
-├── server/                 # Language Server + MCP Server
+├── client/                 # VS Code Language Client extension
+│   └── src/extension.ts    # Starts LanguageClient, connects to server
+├── server/                 # Language Server (runs in separate process)
 │   └── src/
-│       ├── server.ts           # LSP connection, capability registration
-│       ├── mcpServer.ts        # MCP server entry point (stdio)
-│       ├── mcpCore.ts          # MCP handler logic (testable)
+│       ├── server.ts       # LSP connection, capability registration
 │       ├── documentManager.ts  # Parse cache, document lifecycle
-│       ├── parser/             # ANTLR4 parse pipeline + worker thread
-│       ├── symbols/            # Symbol table, scopes, element types
-│       └── providers/          # 21 LSP feature implementations
-├── clients/                # LSP client implementations
-│   ├── vscode/                 # VS Code Language Client extension
-│   │   └── src/extension.ts        # Starts LanguageClient, registers language
-│   └── python/                 # Python LSP client demo (zero dependencies)
-│       └── sysml_lsp_client.py
+│       ├── parser/         # ANTLR4 parse pipeline
+│       ├── symbols/        # Symbol table, scopes, element types
+│       └── providers/      # LSP feature implementations
 ├── grammar/                # ANTLR4 grammar files (.g4)
-├── examples/               # Sample SysML models
-├── test/                   # Unit tests (vitest)
+├── test/                   # Unit tests (vitest) + E2E tests
 └── package.json            # Extension manifest + monorepo scripts
 ```
 
----
+## Grammar Updates
 
-## Development
+The grammar files in `grammar/` are sourced from [daltskin/sysml-v2-grammar](https://github.com/daltskin/sysml-v2-grammar). To pull the latest version:
 
 ```bash
-npm install                 # Install all dependencies
-npm run generate            # Generate TypeScript parser from ANTLR4 grammar
-npm run build               # Compile + bundle (esbuild)
-npm run watch               # Watch mode — recompiles on changes
-npm test                    # Run 88 unit tests (vitest)
-npm run lint                # ESLint
+npm run update-grammar
+npm run generate
 ```
 
-Or use the Makefile:
+## Available Commands
 
 ```bash
 make install          # Install all dependencies
@@ -292,33 +103,21 @@ make watch            # Watch mode
 make test             # Run unit tests
 make lint             # ESLint
 make package          # Build .vsix
-make package-server   # Build npm tarball
 make update-grammar   # Pull latest grammar from upstream
 make ci               # Full CI pipeline
 ```
 
-### Grammar Updates
-
-The grammar files in `grammar/` are sourced from [daltskin/sysml-v2-grammar](https://github.com/daltskin/sysml-v2-grammar). To pull the latest:
-
-```bash
-npm run update-grammar && npm run generate
-```
-
----
-
 ## Technology Stack
 
-| Component | Technology                                                                          |
-| --------- | ----------------------------------------------------------------------------------- |
-| Language  | TypeScript (strict mode)                                                            |
-| Runtime   | Node.js ≥ 20                                                                        |
-| Parser    | ANTLR4 via [antlr4ng](https://github.com/mike-lischke/antlr4ng)                     |
-| Generator | [antlr-ng](https://github.com/nicklockwood/antlr-ng)                                |
-| LSP       | [vscode-languageserver](https://github.com/microsoft/vscode-languageserver-node)    |
-| MCP       | [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) |
-| Bundler   | esbuild                                                                             |
-| Tests     | vitest                                                                              |
+| Component | Technology |
+|-----------|-----------|
+| Language | TypeScript (strict mode) |
+| Runtime | Node.js ≥ 18 |
+| Parser | ANTLR4 via [antlr4ng](https://github.com/mike-lischke/antlr4ng) |
+| Generator | [antlr-ng](https://github.com/nicklockwood/antlr-ng) |
+| LSP | [vscode-languageserver](https://github.com/microsoft/vscode-languageserver-node) |
+| Bundler | esbuild |
+| Tests | vitest |
 
 ## Related Projects