sysmledgraph 0.7.0

package/docs/TOOLS.md

@@ -0,0 +1,317 @@
+# Tools reference (all MCP tools)
+
+Single reference for every MCP tool available in this workspace. Use when you need exact parameters, return shapes, or which server exposes which tool.
+
+---
+
+## 1. sysmledgraph MCP (this project)
+
+Server: run `node dist/mcp/index.js` or `sysmledgraph-mcp`. Add to `.cursor/mcp.json` to use from Cursor.
+
+Graph: one `Node` table (`id`, `name`, `path`, `label`); rel tables per edge type (`IN_DOCUMENT`, `IN_PACKAGE`, `PARENT`, `TYPES`, `REFERENCES`, `IMPORTS`, etc.). Labels: Document, Package, PartDef, PartUsage, ConnectionDef, ConnectionUsage, PortDef, Port, RequirementDef, Block, ValueType, Action, StateMachine.
+
+| Tool | Description |
+|------|-------------|
+| **indexDbGraph** | Build the knowledge graph from path(s). |
+| **list_indexed** | List indexed path(s). |
+| **clean_index** | Remove index for path or all. |
+| **cypher** | Run a Cypher query on the graph (uses first indexed path). |
+| **query** | Concept search over symbols (by name/label). |
+| **context** | 360° view for one symbol (node + edges). |
+| **impact** | Blast radius: what uses this element or what it uses. |
+| **rename** | Multi-file rename preview (dry_run only in v1). |
+| **generate_map** | Generate Markdown from the graph (interconnection view). |
+
+### indexDbGraph
+
+Build the graph from one or more directory paths. Relative paths are resolved against `process.cwd()`.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | string | no* | Single path to index. |
+| `paths` | string[] | no* | Multiple paths to index. |
+
+*At least one of `path` or `paths` is required.
+
+**Returns:** `{ ok: true, filesProcessed: number }` or `{ ok: false, error: string }`
+
+---
+
+### list_indexed
+
+List all paths currently registered in the index.
+
+**Parameters:** None.
+
+**Returns:** `{ ok: true, paths: string[] }` or `{ ok: false, error: string }`
+
+---
+
+### clean_index
+
+Remove index data for a path or for all indexed paths.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | string | no | Path to clean; omit to clean all. |
+
+**Returns:** `{ ok: true, removed: string[] }` or `{ ok: false, error: string }`
+
+---
+
+### cypher
+
+Run a Cypher query against the graph. Uses the first indexed path to resolve the DB.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | string | yes | Cypher query string. |
+
+**Returns:** `{ ok: true, rows: unknown[] }` or `{ ok: false, error: string }`
+
+**Example:** `MATCH (n:Node) WHERE n.label = 'PartDef' RETURN n.id, n.name, n.path LIMIT 50`
+
+---
+
+### query
+
+Concept search over symbols: matches `query` against node names/labels (case-insensitive). Optional filter by node label.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | string | yes | Search string. |
+| `kind` | string | no | Filter by node label (e.g. `PartDef`, `Document`). |
+
+**Returns:** `{ ok: true, nodes: unknown[] }` or `{ ok: false, error: string }`
+
+---
+
+### context
+
+Return one node and its edges (incoming and outgoing) for a symbol by name or id.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | string | yes | Symbol name or id. |
+
+**Returns:** `{ ok: true, node: unknown, edges: unknown[] }` or `{ ok: false, error: string }`
+
+---
+
+### impact
+
+Blast radius: list nodes that reference the target (upstream) or that the target references (downstream).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `target` | string | yes | Symbol name or id. |
+| `direction` | `'upstream'` \| `'downstream'` | no | `upstream` = what references this; `downstream` = what this references. |
+
+**Returns:** `{ ok: true, nodes: unknown[] }` or `{ ok: false, error: string }`
+
+---
+
+### rename
+
+Multi-file rename preview. In v1, only dry-run is implemented; no edits are applied.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `symbol` | string | yes | Symbol to rename. |
+| `newName` | string | yes | New name. |
+| `dry_run` | boolean | no | If true, only return preview (default: true). |
+
+**Returns:** `{ ok: true, preview: { path: string, count: number }[], message?: string }` or `{ ok: false, error: string }`
+
+---
+
+### generate_map
+
+Generate Markdown from the graph (documents, nodes by label, edges). Uses first indexed path. Fails if no indexed path or empty graph.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `output_path` | string | no | Optional path to write the .md file (if server can write). |
+
+**Returns:** `{ ok: true, markdown: string }` or `{ ok: false, error: string }`
+
+---
+
+### Resources (sysmledgraph)
+
+| URI | Description |
+|-----|-------------|
+| `sysmledgraph://context` | Index stats and indexed paths (markdown). |
+| `sysmledgraph://context/{path}` | Context for a specific indexed path. |
+| `sysmledgraph://schema` | Graph node/edge schema (markdown). |
+| `sysmledgraph://schema/{path}` | Schema for a specific indexed path. |
+
+---
+
+## 2. GitNexus MCP
+
+Server: `npx -y gitnexus@latest mcp` (configured in `.cursor/mcp.json` as `gitnexus`).
+
+Index: run `npx gitnexus analyze` from project root first. Read `gitnexus://repo/{name}/context` for overview and staleness; read `gitnexus://repo/{name}/schema` before using `cypher`.
+
+| Tool | Description |
+|------|-------------|
+| **query** | Process-grouped code intelligence — execution flows related to a concept. |
+| **context** | 360° symbol view — categorized refs, processes it participates in. |
+| **impact** | Symbol blast radius — depth 1/2/3 with confidence. |
+| **detect_changes** | Git-diff impact — what do current changes affect. |
+| **rename** | Multi-file coordinated rename with confidence-tagged edits. |
+| **cypher** | Raw graph queries (read schema resource first). |
+| **list_repos** | Discover indexed repos. |
+
+### query (GitNexus)
+
+Find execution flows and symbols related to a concept.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | string | yes | Concept or search text (e.g. "payment processing", "auth"). |
+
+**Returns:** Process-grouped results; symbols and file locations per flow.
+
+---
+
+### context (GitNexus)
+
+Full context for one symbol: incoming/outgoing calls, processes, file.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | string | yes | Symbol name (e.g. function, class). |
+
+**Returns:** Incoming calls, outgoing calls, processes the symbol participates in.
+
+---
+
+### impact (GitNexus)
+
+Blast radius with depth and confidence. Use before changing code.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `target` | string | yes | Symbol name. |
+| `direction` | `'upstream'` \| `'downstream'` | no | `upstream` = what depends on this. |
+| `minConfidence` | number | no | e.g. 0.8. |
+| `maxDepth` | number | no | e.g. 3 (d=1 direct, d=2/3 transitive). |
+
+**Returns:** Nodes by depth (d=1 WILL BREAK, d=2 LIKELY AFFECTED, d=3 MAY NEED TESTING).
+
+---
+
+### detect_changes (GitNexus)
+
+Map current git changes to affected symbols and processes.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `scope` | `'staged'` \| `'all'` | no | Staged changes only or all working-tree changes. |
+
+**Returns:** Changed symbols, affected processes, risk level.
+
+---
+
+### rename (GitNexus)
+
+Multi-file rename with graph + AST search; supports dry_run then apply.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `symbol_name` | string | yes | Current symbol name. |
+| `new_name` | string | yes | New name. |
+| `dry_run` | boolean | no | If true, preview only (default: true). |
+
+**Returns:** List of edits (file_path, line, old_text, new_text, confidence); graph edits high confidence, ast_search edits need review.
+
+---
+
+### cypher (GitNexus)
+
+Run Cypher on the GitNexus graph. Read `gitnexus://repo/{name}/schema` first.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `query` | string | yes | Cypher query. |
+
+**Returns:** Query result rows.
+
+**Example:** `MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"}) RETURN caller.name, caller.filePath`
+
+---
+
+### list_repos (GitNexus)
+
+List all repos registered in the GitNexus registry.
+
+**Parameters:** None.
+
+**Returns:** Indexed repo names/paths (same as `npx gitnexus list`).
+
+---
+
+### Resources (GitNexus)
+
+| URI | Description |
+|-----|-------------|
+| `gitnexus://repo/{name}/context` | Stats, staleness check. |
+| `gitnexus://repo/{name}/clusters` | Functional areas with cohesion scores. |
+| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members. |
+| `gitnexus://repo/{name}/processes` | All execution flows. |
+| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace. |
+| `gitnexus://repo/{name}/schema` | Graph schema for Cypher. |
+
+---
+
+## 3. Other MCP servers (this workspace)
+
+| Server | Purpose | Tools |
+|--------|---------|--------|
+| **sysml-v2** | SysML v2 LSP MCP | See `node_modules/sysml-v2-lsp` for tool list. |
+| **context7** | Context7 MCP | See `@upstash/context7-mcp` for tool list. |
+
+---
+
+## Quick pick: which tool for what
+
+| Goal | Prefer |
+|------|--------|
+| Index SysML/models in this project | sysmledgraph **indexDbGraph** |
+| Search SysML symbols / graph query | sysmledgraph **query**, **cypher**, **context** |
+| “What uses this?” (sysmledgraph) | sysmledgraph **impact** |
+| Understand or explore a codebase (TS/JS etc.) | GitNexus **query**, **context**; resources **process**, **clusters** |
+| “What breaks if I change this?” (code) | GitNexus **impact**, **detect_changes** |
+| Rename symbol across files (code) | GitNexus **rename** (dry_run first) |
+| Rename symbol (SysML graph only) | sysmledgraph **rename** (preview only in v1) |
+| List what’s indexed | sysmledgraph **list_indexed**; GitNexus **list_repos** |

package/lsp/README.md

@@ -0,0 +1,41 @@
+# LSP server (dedicated init)
+
+This folder is a **separate npm install** for the SysML LSP server. This is the **only** LSP used by sysmledgraph when present; root `node_modules` is fallback. Use it so the server runs with its own `cwd` and dependencies.
+
+## Setup
+
+```bash
+cd lsp
+npm install
+```
+
+## What this does
+
+- **Isolated install**: `sysml-v2-lsp` lives in `lsp/node_modules/`, not the repo root. The server starts with **process cwd = `lsp/`**, which can help it find config or libraries relative to this directory.
+- **Clear boundary**: The main project points at this LSP when you set:
+  - `SYSMLLSP_SERVER_PATH` to the **absolute** path to:
+    - `lsp/node_modules/sysml-v2-lsp/dist/server/server.js` (LSP)
+    - or `lsp/node_modules/sysml-v2-lsp/dist/server/mcpServer.js` (MCP)
+  - and the spawn **cwd** to `lsp/` (or the parent that contains `lsp/`) so the server’s working directory is correct.
+
+## Running the server
+
+- **stdio (for our indexer)**: The main app spawns the server; it doesn’t run “standalone” here. Use this folder’s path in `SYSMLLSP_SERVER_PATH` and set the spawn cwd to `lsp` when starting the process.
+- **Manual run** (e.g. to see stdout/stderr):
+  ```bash
+  cd lsp && npm start
+  ```
+  The process will wait for LSP messages on stdin; useful for debugging.
+
+## Main project
+
+From repo root, after `cd lsp && npm install`:
+
+- **LSP (analyze/index)**  
+  Point `SYSMLLSP_SERVER_PATH` at:
+  - `lsp/node_modules/sysml-v2-lsp/dist/server/server.js`  
+  (use absolute path or resolve from repo root.)
+- **Spawn cwd**  
+  When the main project spawns this server, set **cwd** to the **`lsp`** directory (absolute path) so the LSP server’s init and file resolution use this folder.
+
+If the main app already resolves cwd from the server path (e.g. “dirname of server.js → dist/server → cwd = package root”), then with the server path under `lsp/node_modules/...`, that cwd would be `lsp/`. That is what we want.

package/lsp/node_modules/.bin/sysml-mcp

@@ -0,0 +1,12 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+exec "$basedir/../sysml-v2-lsp/dist/server/mcpServer.js"   "$@"

package/lsp/node_modules/.bin/sysml-mcp.cmd

@@ -0,0 +1,9 @@
+@ECHO off
+GOTO start
+:find_dp0
+SET dp0=%~dp0
+EXIT /b
+:start
+SETLOCAL
+CALL :find_dp0
+"%dp0%\..\sysml-v2-lsp\dist\server\mcpServer.js"   %*

package/lsp/node_modules/.bin/sysml-mcp.ps1

@@ -0,0 +1,16 @@
+#!/usr/bin/env pwsh
+$basedir=Split-Path $MyInvocation.MyCommand.Definition -Parent
+
+$exe=""
+if ($PSVersionTable.PSVersion -lt "6.0" -or $IsWindows) {
+  # Fix case when both the Windows and Linux builds of Node
+  # are installed in the same directory
+  $exe=".exe"
+}
+# Support pipeline input
+if ($MyInvocation.ExpectingInput) {
+  $input | & "$basedir/../sysml-v2-lsp/dist/server/mcpServer.js"   $args
+} else {
+  & "$basedir/../sysml-v2-lsp/dist/server/mcpServer.js"   $args
+}
+exit $LASTEXITCODE

package/lsp/node_modules/.package-lock.json

@@ -0,0 +1,22 @@
+{
+  "name": "sysmledgraph-lsp-server",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "node_modules/sysml-v2-lsp": {
+      "version": "0.7.0",
+      "resolved": "https://registry.npmjs.org/sysml-v2-lsp/-/sysml-v2-lsp-0.7.0.tgz",
+      "integrity": "sha512-cJ2JINpe7Ez1gyMO020gEokoTLmqRFv+KTcNqGq+10PI3mE0q74anHLxFzbrjIx2wRDeoacQcMg3v9XVkvuWHw==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "sysml-mcp": "dist/server/mcpServer.js"
+      },
+      "engines": {
+        "node": ">=20",
+        "vscode": "^1.85.0"
+      }
+    }
+  }
+}

package/lsp/node_modules/sysml-v2-lsp/CHANGELOG.md

@@ -0,0 +1,188 @@
+# Changelog
+
+## [0.7.0]
+
+### Added
+
+- Workspace-wide semantic validation with cross-file symbol indexes (byName, byParent, byQualifiedName, definitionsByName, portsByName)
+- Three new validation rules: redefinition multiplicity, port type compatibility, constraint body references
+- Quick-fix code actions for all three new rules (align multiplicity, switch port endpoint, suggest nearest member)
+- Context-aware completions: port endpoints in `connect` blocks, type annotation filtering, workspace definition symbols
+- Semantic feedback in hover tooltips — shows diagnostics and repair hints at the hovered position
+- Cached semantic diagnostics per document version to avoid redundant revalidation
+- MCP preview tool falls back to cached/loaded documents when `code` parameter is omitted
+
+### Changed
+
+- Unused-definition rule narrowed to PartDef/ActionDef, excludes types with base types, promoted from Hint to Warning, now workspace-scoped
+- Grammar updated to OMG "2026-02 - SysML v2 Release" — removed local `end <keyword>` patch in favour of upstream `endFeatureUsage` rule
+- MCP non-visual tools annotated with explicit "NOT Visualization" routing guidance
+- MCP preview response stripped to minimal render data (mermaidMarkup + title)
+- MCP tool routing guidance and aliases expanded for diagnostics, validation, and file-focused preview requests
+
+### Fixed
+
+- Semantic validator signal quality: reduced specialization false positives and downgraded low-value unused-definition reports to warnings
+- Document-close diagnostics race: pending validation timers are cancelled and diagnostics publishing is guarded for closed documents
+
+## [0.6.0]
+
+### Added
+
+- Shared utilities: `identUtils.ts` for identifier handling, `symbolKindMapping.ts` for LSP SymbolKind mapping
+- Keywords now derived from ANTLR grammar at runtime — no manual list to maintain
+- Grammar support for `end` keyword syntax in interface/connection definitions
+- DFA snapshot infrastructure for parser serialisation
+
+### Changed
+
+- Code actions use structured diagnostic data instead of message parsing
+- Semantic tokens provider integrates lexer token types for operators/punctuation
+- Library indexing supports qualified name resolution
+- Parser retries with cleared DFA on error
+- Refactored providers to use shared utility modules
+
+### Removed
+
+- Hand-maintained keyword list (replaced by grammar-derived extraction)
+
+## [0.5.1]
+
+### Changed
+
+- Semantic validator: library type and feature reference checks
+- Symbol table: improved keyword and redefinition pattern handling
+
+## [0.5.0]
+
+### Changed
+
+- Symbol table uses `ruleIndex` instead of `constructor.name` for minification safety
+- Removed committed dist/ build artefacts from repository
+
+## [0.4.1]
+
+### Fixed
+
+- Web client graceful shutdown
+- Release pipeline fix
+
+## [0.4.0]
+
+### Added
+
+- Web client: browser-based SysML editor (`clients/web/`)
+- Python LSP client: Jupyter notebook demo
+
+### Changed
+
+- Library index, MCP server, and symbol table improvements
+
+## [0.3.1]
+
+### Fixed
+
+- esbuild: added `keepNames` for debugging
+- Removed committed dist/ build artefacts
+
+## [0.3.0]
+
+### Added
+
+- Mermaid diagram preview with 6 diagram types, focus mode, and diff mode
+- Complexity analyser: structural metrics with composite 0–100 index
+- Semantic validator: unresolved types, invalid multiplicity, duplicate definitions
+- MCP tools: `preview`, `getDiagnostics`, `getComplexity`
+- Code action quick-fixes: naming conventions, doc stubs, empty enum placeholders
+- Library type-level indexing with Go-to-Definition into standard library
+- Multiplicity and documentation extraction from parse tree
+- LSP `sysml/serverStats`, `sysml/clearCache`, `sysml/status` requests
+
+### Changed
+
+- MCP `validate` response: `syntaxErrors` + `semanticIssues` (was `errors` + `errorCount`)
+- Symbol `typeName` → `typeNames` (array)
+- Diagnostics computed synchronously (removed background worker)
+- Parser simplified to single-pass (removed SLL/LL fallback)
+- esbuild output changed from ESM to CJS
+
+### Removed
+
+- Background parse worker thread and DFA warm-up
+- Text-scanning reference finder (replaced by symbol-table lookups)
+
+## [0.2.0]
+
+### Added
+
+- Custom LSP request `sysml/model` for full semantic model with scoped queries
+- MCP server (`sysml-mcp` CLI): 7 tools, 3 resources, 3 prompts
+- Standard library: 94 bundled SysML v2 / KerML files
+- LSP providers: inlay hints, call/type hierarchy, signature help, code lens, document links, workspace symbols, linked editing, selection ranges, code actions, formatting
+- Keyword validation with "did you mean?" suggestions
+- npm package, Python LSP client, background parse worker
+- `make update-library`, `make package-server`, `make test-package`
+
+### Changed
+
+- Go-to-definition falls back to standard library
+- Element kind enum expanded to 55 kinds
+
+## [0.1.7]
+
+### Changed
+
+- Keyword validator: expanded SysML element coverage
+- New parser, symbol table, and provider tests
+
+## [0.1.6]
+
+### Fixed
+
+- Keyword validation diagnostic messages
+- Python LSP client diagnostics handling
+
+## [0.1.5]
+
+### Added
+
+- Inlay hints, call hierarchy improvements
+- Python LSP client with README
+- Client restructured under `clients/vscode/`
+
+## [0.1.4]
+
+### Added
+
+- MCP core module extracted from MCP server
+- Constraint parsing tests, grammar refinements
+
+## [0.1.3]
+
+### Fixed
+
+- `constructor.name` minification breaking code lens
+- ESM bundles renamed to `.mjs` for Node 20 compatibility
+- Bundled deps moved to devDependencies (zero runtime deps)
+
+## [0.1.2]
+
+### Fixed
+
+- Removed unused `antlr4-c3` dependency
+
+## [0.1.1]
+
+### Fixed
+
+- Dropped Node 18 from CI (Vite 7 requires Node 20+)
+- Release pipeline and trusted publishing fixes
+
+## [0.1.0]
+
+### Added
+
+- Initial LSP server with ANTLR4-based SysML v2 parser
+- LSP providers: diagnostics, document symbols, hover, go-to-definition, find references, completion, semantic tokens, folding, rename
+- VS Code Language Client extension
+- vitest unit tests, GitHub Actions CI/CD, Dev Container

package/lsp/node_modules/sysml-v2-lsp/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamie Dalton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.