services/lsp/ — Language Server Protocol Service

Contents

Architecture

flowchart TD
  MGR["manager.ts\nSingleton Lifecycle"] -->|creates| SM["LSPServerManager\n(createLSPServerManager)"]
  CFG["config.ts\nPlugin Config Loader"] -->|server configs| SM
  SM -->|per-language| SI["LSPServerInstance\n(createLSPServerInstance)"]
  SI -->|spawns| CL["LSPClient\n(createLSPClient)"]
  CL -->|JSON-RPC| LS["Language Server\n(external process)"]
  LS -->|publishDiagnostics| PF["passiveFeedback.ts\nNotification Handler"]
  PF -->|registers| DR["LSPDiagnosticRegistry\nDedup & Volume Limit"]
  SM -->|extension routing| EM["Extension Map\next → server name"]
  SM -->|file sync| OF["Open Files Map\nfileUri → serverName"]

Server Instance State Machine

stateDiagram-v2
  [*] --> stopped
  stopped --> starting : start()
  starting --> running : initialize OK
  starting --> error : init failed
  error --> starting : restart (count < maxRestarts)
  error --> stopped : max restarts exceeded
  running --> stopping : stop()
  running --> error : crash detected
  stopping --> stopped : cleanup complete
  stopped --> [*]

Key Classes & Functions

Data Structures

Interactions

Configuration

Directory Map

lsp/
├── LSPClient.ts               ← JSON-RPC client wrapper (448 lines)
├── LSPDiagnosticRegistry.ts   ← Diagnostic dedup & volume limiting (387 lines)
├── LSPServerInstance.ts       ← Single server lifecycle & state machine (512 lines)
├── LSPServerManager.ts        ← Multi-server orchestration & file routing (421 lines)
├── config.ts                  ← Plugin-based config loading (80 lines)
├── manager.ts                 ← Singleton lifecycle & initialization (290 lines)
└── passiveFeedback.ts         ← Diagnostic notification handlers (329 lines)

Deep-Dive Highlights

Core mechanisms from this sub-module have been extracted into dedicated focus areas. Each topic covers one protocol flow, subsystem, or algorithm in detail.

Deep-Dive Pages

Capabilities Negotiated

During the LSP initialize handshake, the client advertises these capabilities to each language server:

Diagnostic Severity Mapping

LSP numeric severity values are mapped to human-readable strings for Claude's consumption:

// passiveFeedback.ts — mapLSPSeverity()
function mapLSPSeverity(lspSeverity: number | undefined): string {
  switch (lspSeverity) {
    case 1: return 'Error';     // DiagnosticSeverity.Error
    case 2: return 'Warning';   // DiagnosticSeverity.Warning
    case 3: return 'Info';      // DiagnosticSeverity.Information
    case 4: return 'Hint';      // DiagnosticSeverity.Hint
    default: return 'Error';    // Unknown → treat as Error
  }
}
// Diagnostics sorted by severity so Errors are delivered first
// when volume limits truncate results

Code Examples

Example 1: Server Instance with Transient Error Retry

import { createLSPServerInstance } from './LSPServerInstance';

const instance = createLSPServerInstance('typescript', {
  command: 'typescript-language-server',
  args: ['--stdio'],
  extensionToLanguage: { '.ts': 'typescript', '.tsx': 'typescriptreact' },
  maxRestarts: 3,
});

await instance.start();

// Requests automatically retry on ContentModified (-32801) errors
// with exponential backoff: 500ms, 1000ms, 2000ms
try {
  const result = await instance.sendRequest('textDocument/definition', {
    textDocument: { uri: 'file:///project/src/index.ts' },
    position: { line: 42, character: 10 },
  });
  console.log('Definition at:', result);
} catch (error) {
  // After MAX_RETRIES_FOR_TRANSIENT_ERRORS (3), throws with full context
  console.error(`LSP request failed: ${error.message}`);
}

Example 2: File Synchronization Protocol

import { createLSPServerManager } from './LSPServerManager';

const manager = createLSPServerManager();
await manager.initialize();

// Open a file — auto-routes to the right server via extensionMap
// Sends textDocument/didOpen with languageId from extensionToLanguage
await manager.openFile('src/app.ts', fileContent);

// After editing — sends textDocument/didChange (full content replacement)
// If file wasn't previously opened, auto-promotes to didOpen
await manager.changeFile('src/app.ts', updatedContent);

// After saving — sends textDocument/didSave
await manager.saveFile('src/app.ts');

// Check if file is tracked
console.log(manager.isFileOpen('src/app.ts')); // true

// Close — sends textDocument/didClose and removes from tracking
await manager.closeFile('src/app.ts');

Example 3: Diagnostic Collection with Deduplication

import { registerLSPNotificationHandlers } from './passiveFeedback';
import {
  checkForLSPDiagnostics,
  registerPendingLSPDiagnostic,
} from './LSPDiagnosticRegistry';

// Register handlers on all running servers
const result = registerLSPNotificationHandlers(manager);
console.log(`Registered on ${result.successCount}/${result.totalServers} servers`);

// Diagnostics arrive asynchronously via textDocument/publishDiagnostics
// and are queued in the registry. To retrieve them:

const diagnostics = checkForLSPDiagnostics();
// Returns deduplicated results:
//   - Within-batch dedup (same file + range + message)
//   - Cross-turn dedup via LRU cache (won't re-report same error)
//   - Sorted by severity: Error < Warning < Info < Hint
//   - Capped: 10 per file, 30 total across all files

for (const file of diagnostics) {
  console.log(`${file.uri}: ${file.diagnostics.length} issues`);
  for (const d of file.diagnostics) {
    console.log(`  [${d.severity}] L${d.range.start.line}: ${d.message}`);
  }
}