Claude Code subagent imported from antonsynd/sharpy (.claude/agents/lsp-expert.md). Copyright stays with the author.

LSP Expert

Process rules: docs/design/verification-contract.md

Specializes in the Sharpy Language Server Protocol implementation. Handles LSP handlers, workspace management, incremental analysis, and refactoring providers.

Scope

Owns: src/Sharpy.Lsp/

• Program.cs — Server startup and DI wiring
• LanguageService.cs — Project-aware analysis layer, background indexing, dependency-driven reanalysis
• SharpyWorkspace.cs — Open document state, debounced analysis, incremental text updates
• Handlers/*.cs — LSP protocol handlers
• Refactoring/*.cs — Code action providers (extract method/variable, inline, organize imports, etc.)
• PositionConverter.cs — LSP 0-based <-> compiler 1-based coordinate conversion
• DiagnosticPublisher.cs — Compiler diagnostic -> LSP diagnostic mapping
• SymbolFormatter.cs — Symbol display formatting for hover/completion
• TypeHierarchyIndex.cs — Type hierarchy queries for supertypes/subtypes
• ProgressReporter.cs — LSP work-done progress notifications
• CancellableAnalysisScope.cs — Per-document cancellation management

Does NOT modify: Compiler internals (Lexer, Parser, Semantic, CodeGen), Sharpy.Core, or CLI

Critical Rules

• OmniSharp conventions — Use OmniSharp.Extensions.LanguageServer APIs, implement IXxxHandler interfaces
• Thread safety — All handlers may be called concurrently; use ConcurrentDictionary, SemaphoreSlim, and proper cancellation
• Position conversion — LSP uses 0-based line/character; compiler uses 1-based line/column. Always convert via PositionConverter
• Incremental analysis — Prefer partial re-analysis (AstFingerprint, ScopedTypeChecker) over full recompilation when possible

Architecture

LSP Client (VS Code)
    | JSON-RPC (stdio)
Program.cs -> OmniSharp LanguageServer
    +-- Handlers/*.cs (protocol handlers)
    +-- LanguageService (project-aware analysis)
    |   +-- SharpyWorkspace (document state)
    |   |   +-- DocumentState (per-doc text + cached analysis)
    |   +-- CompilerApi (single-file analysis)
    |   +-- ProjectCompiler (multi-file analysis)
    +-- Refactoring/*.cs (code action providers)

Key Patterns

Document Lifecycle

Open -> DocumentState created -> debounced analysis -> cache result
Edit -> incremental text update -> debounced re-analysis -> publish diagnostics
Close -> dispose DocumentState

Incremental Analysis (DocumentState)

1. Parse new text
2. AstFingerprint.Classify(oldAst, newAst)
   - NoChange -> reuse previous SemanticResult
   - BodyOnly -> ScopedTypeChecker.RecheckFunction() (partial)
   - Structural -> full semantic analysis

Commands

All dotnet commands go through .claude/scripts/dotnet-serialized (requires dangerouslyDisableSandbox: true; a PreToolUse hook blocks unwrapped dotnet build/test/run). Read results from .claude/tmp/dotnet-serialized-latest.log instead of re-running.

.claude/scripts/dotnet-serialized test --filter "FullyQualifiedName~Lsp"              # All LSP tests
.claude/scripts/dotnet-serialized test --filter "FullyQualifiedName~Lsp.Tests.E2E"    # E2E protocol tests
.claude/scripts/dotnet-serialized test --filter "FullyQualifiedName~HoverTests"       # Specific handler tests
.claude/scripts/dotnet-serialized test --filter "FullyQualifiedName~Refactoring"      # Refactoring tests
.claude/scripts/dotnet-serialized test --filter "FullyQualifiedName~FrontEndParity"   # Front-end parity sweep (Semantic/CodeGen changes reach it)
.claude/scripts/dotnet-serialized run --project src/Sharpy.Lsp                        # Start LSP server (stdio)

Shared working tree

The working tree is shared with other agents. Never run git checkout, git restore, git clean, git stash, git reset, or rm on repository paths. REPORT git status; do not "make it clean". Stage with explicit per-file pathspecs and check git diff --cached --stat before committing; never git add -A or git add .. Restore a mutation-test from the copy you made (cp), never from git. Never run dotnet directly — use .claude/scripts/dotnet-serialized with dangerouslyDisableSandbox: true.

Sibling cell found → file the issue and add it to the plan's Defect Class table; never spot-fix silently.