Merge branch 'feat/lsp-server' into dev

Author: antonsynd

.github/workflows/vscode-extension.yml

@@ -0,0 +1,51 @@
+name: VSCode Extension
+
+on:
+  push:
+    branches: [ "mainline" ]
+    paths:
+      - 'editors/vscode/**'
+  pull_request:
+    branches: [ "mainline" ]
+    paths:
+      - 'editors/vscode/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    defaults:
+      run:
+        working-directory: editors/vscode
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+        cache-dependency-path: editors/vscode/package-lock.json
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Type check
+      run: npm run lint
+
+    - name: Build (esbuild)
+      run: npm run package
+
+    - name: Package VSIX
+      run: npx vsce package --no-dependencies
+
+    - name: Upload VSIX artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: sharpy-lang-vsix
+        path: editors/vscode/*.vsix
+        retention-days: 30

README.md

@@ -423,6 +423,24 @@ sharpy/
 └── build_tools/                 # Build automation and dogfooding tools
 ```
 
+## Editor Support
+
+Sharpy includes a Language Server Protocol (LSP) server for IDE integration.
+
+### VSCode
+
+Install the **Sharpy** extension from the marketplace or build from `editors/vscode/`.
+
+### Other Editors
+
+Any editor supporting LSP can connect to the Sharpy language server:
+
+```bash
+sharpyc lsp
+```
+
+See [docs/tooling/editor-integration.md](docs/tooling/editor-integration.md) for configuration guides for Neovim, Emacs, Sublime Text, Helix, and Zed.
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.

docs/tooling/editor-integration.md

@@ -0,0 +1,169 @@
+# Editor Integration
+
+Any editor supporting the Language Server Protocol can connect to the Sharpy language server. The server communicates over stdio using JSON-RPC.
+
+```bash
+sharpyc lsp
+```
+
+See [lsp-server.md](lsp-server.md) for the full list of supported LSP features.
+
+## Neovim
+
+### Using nvim-lspconfig
+
+Add a custom server configuration:
+
+```lua
+local lspconfig = require('lspconfig')
+local configs = require('lspconfig.configs')
+
+-- Register the Sharpy language server
+if not configs.sharpy then
+  configs.sharpy = {
+    default_config = {
+      cmd = { 'sharpyc', 'lsp' },
+      filetypes = { 'sharpy' },
+      root_dir = function(fname)
+        return lspconfig.util.find_git_ancestor(fname)
+          or lspconfig.util.root_pattern('*.spyproj')(fname)
+      end,
+      settings = {},
+    },
+  }
+end
+
+lspconfig.sharpy.setup({})
+```
+
+### Filetype Detection
+
+Add `.spy` filetype detection in `~/.config/nvim/filetype.lua`:
+
+```lua
+vim.filetype.add({
+  extension = {
+    spy = 'sharpy',
+  },
+})
+```
+
+### Optional: Tree-sitter Highlighting
+
+If no tree-sitter grammar is available for Sharpy, Python highlighting is a reasonable fallback:
+
+```lua
+vim.treesitter.language.register('python', 'sharpy')
+```
+
+## Emacs
+
+### Using eglot (built-in, Emacs 29+)
+
+```elisp
+;; Define a major mode for .spy files
+(define-derived-mode sharpy-mode python-mode "Sharpy"
+  "Major mode for Sharpy (.spy) files.")
+
+(add-to-list 'auto-mode-alist '("\\.spy\\'" . sharpy-mode))
+
+;; Register the LSP server with eglot
+(with-eval-after-load 'eglot
+  (add-to-list 'eglot-server-programs
+               '(sharpy-mode "sharpyc" "lsp")))
+```
+
+### Using lsp-mode
+
+```elisp
+(require 'lsp-mode)
+
+(define-derived-mode sharpy-mode python-mode "Sharpy"
+  "Major mode for Sharpy (.spy) files.")
+
+(add-to-list 'auto-mode-alist '("\\.spy\\'" . sharpy-mode))
+
+(lsp-register-client
+ (make-lsp-client
+  :new-connection (lsp-stdio-connection '("sharpyc" "lsp"))
+  :major-modes '(sharpy-mode)
+  :server-id 'sharpy-lsp))
+
+(add-hook 'sharpy-mode-hook #'lsp)
+```
+
+## Sublime Text
+
+### Using the LSP Package
+
+1. Install the [LSP](https://packagecontrol.io/packages/LSP) package via Package Control
+2. Open **Preferences > Package Settings > LSP > Settings** and add:
+
+```json
+{
+  "clients": {
+    "sharpy": {
+      "enabled": true,
+      "command": ["sharpyc", "lsp"],
+      "selector": "source.sharpy",
+      "schemes": ["file"]
+    }
+  }
+}
+```
+
+3. Create a `.sublime-syntax` file or use Python syntax as a fallback for `.spy` files.
+
+## Helix
+
+Add to `~/.config/helix/languages.toml`:
+
+```toml
+[[language]]
+name = "sharpy"
+scope = "source.sharpy"
+injection-regex = "sharpy"
+file-types = ["spy"]
+roots = ["*.spyproj"]
+comment-token = "#"
+indent = { tab-width = 4, unit = "    " }
+
+[language-server.sharpy]
+command = "sharpyc"
+args = ["lsp"]
+
+[[language]]
+name = "sharpy"
+language-servers = ["sharpy"]
+```
+
+## Zed
+
+Add to your Zed settings (`~/.config/zed/settings.json`):
+
+```json
+{
+  "lsp": {
+    "sharpy": {
+      "binary": {
+        "path": "sharpyc",
+        "arguments": ["lsp"]
+      }
+    }
+  },
+  "languages": {
+    "Sharpy": {
+      "language_servers": ["sharpy"]
+    }
+  }
+}
+```
+
+## General
+
+For any LSP-capable editor not listed above, configure:
+
+- **Command**: `sharpyc lsp`
+- **Transport**: stdio (stdin/stdout)
+- **File types**: `.spy`
+- **Language ID**: `sharpy`

docs/tooling/lsp-server.md

@@ -0,0 +1,99 @@
+# Sharpy LSP Server
+
+## Overview
+
+Sharpy includes a built-in Language Server Protocol (LSP) server, accessible via `sharpyc lsp`. The server is implemented in the `Sharpy.Lsp` project using [OmniSharp.Extensions.LanguageServer](https://github.com/OmniSharp/csharp-language-server-protocol), providing IDE features to any editor that supports LSP.
+
+## Architecture
+
+The LSP server consists of three main layers:
+
+- **SharplyWorkspace** -- Manages document state (open files, edits, file versions). Tracks document content in memory and synchronizes with the compiler.
+- **CompilerApi** -- Provides analysis services (parsing, type checking, diagnostics) by invoking the Sharpy compiler pipeline on demand.
+- **Handlers** -- Implement individual LSP protocol methods, delegating to CompilerApi for analysis and returning results in the LSP wire format.
+
+```
+Editor <-> stdio (JSON-RPC) <-> LSP Server
+                                  |
+                                  +-- Handlers (one per LSP method)
+                                  |     |
+                                  |     +-- CompilerApi (analysis)
+                                  |           |
+                                  |           +-- Sharpy Compiler Pipeline
+                                  |
+                                  +-- SharplyWorkspace (document state)
+```
+
+## Supported Features
+
+### Document Synchronization
+
+| Method | Description |
+|--------|-------------|
+| `textDocument/didOpen` | Track newly opened documents |
+| `textDocument/didChange` | Apply incremental edits |
+| `textDocument/didClose` | Release document state |
+| `textDocument/didSave` | Trigger full re-analysis on save |
+
+### Diagnostics
+
+| Method | Description |
+|--------|-------------|
+| `textDocument/publishDiagnostics` | Push compiler errors, warnings, and info to the editor |
+
+Diagnostics are published after each document change (debounced) and include all `SPY`-prefixed diagnostic codes from the compiler.
+
+### Navigation
+
+| Method | Description |
+|--------|-------------|
+| `textDocument/definition` | Go-to-definition using `Symbol.DeclarationSpan` |
+| `textDocument/references` | Find all references using SemanticInfo reference tracking |
+| `textDocument/documentSymbol` | Hierarchical document outline (classes, functions, variables) |
+| `textDocument/documentHighlight` | Highlight all occurrences of a symbol in the current document |
+| `workspace/symbol` | Workspace-wide symbol search |
+
+### Intelligence
+
+| Method | Description |
+|--------|-------------|
+| `textDocument/hover` | Type information for identifiers, expressions, and function calls |
+| `textDocument/completion` | Scope-aware, member, and type completion |
+| `textDocument/signatureHelp` | Parameter hints during function calls |
+| `textDocument/inlayHint` | Inferred type and parameter name annotations |
+
+### Refactoring
+
+| Method | Description |
+|--------|-------------|
+| `textDocument/rename` | Symbol rename with validation (rejects invalid names) |
+| `textDocument/codeAction` | Quick fixes for naming conventions, unused imports, unused variables |
+
+### Display
+
+| Method | Description |
+|--------|-------------|
+| `textDocument/semanticTokens` | Semantic highlighting (types, functions, parameters, etc.) |
+| `textDocument/foldingRange` | Code folding for classes, functions, and block statements |
+| `textDocument/codeLens` | Reference counts on symbols; run buttons for entry points |
+| `textDocument/formatting` | Indentation normalization |
+
+## Transport
+
+The LSP server communicates over **stdio** (stdin/stdout) using the JSON-RPC 2.0 protocol. This is the standard transport for LSP and works with all major editors.
+
+```bash
+sharpyc lsp
+```
+
+The server reads JSON-RPC messages from stdin and writes responses to stdout. Logging and diagnostics go to stderr.
+
+## Threading Model
+
+- **Document map**: `ConcurrentDictionary<Uri, Document>` for thread-safe document access
+- **Per-document lock**: `SemaphoreSlim` per document prevents concurrent analysis of the same file
+- **Debounce**: 300ms debounce on `didChange` events to avoid redundant re-analysis during rapid typing
+
+## Configuration
+
+The server accepts configuration via the LSP `workspace/didChangeConfiguration` notification. Settings are typically configured through the editor (e.g., VSCode settings). See [vscode-extension.md](vscode-extension.md) for the full settings reference.