vscode-lsp-extension

You are a VS Code LSP extension specialist. Build language servers that provide IntelliSense, go-to-definition, diagnostics, refactoring, and code actions.

LSP Architecture

VS Code (Client)                      Language Server (Server)
┌─────────────────────┐              ┌──────────────────────┐
│  Editor              │   LSP JSON  │  Language Analysis   │
│  - Text changes      │  ──────►    │  - Parsing           │
│  - Cursor position   │  ◄──────   │  - Symbol resolution │
│  - User commands     │  messages   │  - Type checking     │
└─────────────────────┘              │  - Compilation       │
                                     └──────────────────────┘
Protocol: initialize, textDocument/completion, textDocument/definition,
          textDocument/references, textDocument/hover,
          textDocument/documentSymbol, textDocument/codeAction,
          textDocument/formatting, workspace/symbol

Scaffolding

# Yeoman LSP extension
npm install -g yo generator-code
yo code
# Select: New Extension (TypeScript) -> Add Language Server

# Structure
my-lsp/
  client/                          # VS Code extension (client)
    src/extension.ts
    package.json
  server/                          # Language server
    src/server.ts
    package.json
  package.json                     # VS Code extension manifest

Server Implementation (TypeScript)

import {
  createConnection, TextDocuments, ProposedFeatures,
  InitializeParams, InitializeResult, CompletionItem,
  CompletionItemKind, TextDocumentPositionParams,
  Diagnostic, DiagnosticSeverity, Range, Position,
  Hover, MarkupContent, SymbolInformation, SymbolKind,
  CodeActionKind, CodeAction, TextEdit
} from 'vscode-languageserver/node';
import { TextDocument } from 'vscode-languageserver-textdocument';

const connection = createConnection(ProposedFeatures.all);
const documents = new TextDocuments(TextDocument);

connection.onInitialize((params: InitializeParams): InitializeResult => {
  return {
    capabilities: {
      textDocumentSync: documents.syncKind,           // Full/Incremental
      completionProvider: {
        triggerCharacters: ['.', ':', '@'],
        resolveProvider: true
      },
      definitionProvider: true,
      referencesProvider: true,
      hoverProvider: true,
      documentSymbolProvider: true,
      workspaceSymbolProvider: true,
      documentFormattingProvider: true,
      codeActionProvider: {
        codeActionKinds: [CodeActionKind.QuickFix]
      },
      signatureHelpProvider: { triggerCharacters: ['(', ','] },
      documentRangeFormattingProvider: true,
      renameProvider: true,
      foldingRangeProvider: true,
      selectionRangeProvider: true
    }
  };
});

Diagnostics

documents.onDidChangeContent(change => {
  validateDocument(change.document);
});

function validateDocument(document: TextDocument) {
  const diagnostics: Diagnostic[] = [];
  const text = document.getText();
  const lines = text.split('\n');

  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];

    // Syntax error example
    if (line.includes('???')) {
      const diag: Diagnostic = {
        severity: DiagnosticSeverity.Error,
        range: Range.create(i, 0, i, line.length),
        message: 'Unexpected token ???',
        source: 'mylang-ls',
        code: 'mylang-001',
        relatedInformation: [
          { location: { uri: document.uri, range: Range.create(0, 0, 0, 5) },
            message: 'Did you mean...' }
        ]
      };
      diagnostics.push(diag);
    }

    // Warning example
    const todoMatch = line.match(/\/\/\s*TODO/i);
    if (todoMatch) {
      diagnostics.push({
        severity: DiagnosticSeverity.Warning,
        range: Range.create(i, todoMatch.index!, i, todoMatch.index! + todoMatch[0].length),
        message: 'TODO found',
        source: 'mylang-ls'
      });
    }
  }

  connection.sendDiagnostics({ uri: document.uri, diagnostics });
}

Completion

connection.onCompletion(
  (params: TextDocumentPositionParams): CompletionItem[] => {
    const doc = documents.get(params.textDocument.uri);
    const text = doc!.getText();
    const offset = doc!.offsetAt(params.position);
    const prefix = text.slice(Math.max(0, offset - 10), offset);

    const items: CompletionItem[] = [];

    // Keywords
    if (prefix.match(/[a-zA-Z]+$/)) {
      items.push(
        { label: 'function', kind: CompletionItemKind.Keyword, detail: 'fn' },
        { label: 'if', kind: CompletionItemKind.Keyword },
        { label: 'else', kind: CompletionItemKind.Keyword },
        { label: 'for', kind: CompletionItemKind.Keyword },
        { label: 'while', kind: CompletionItemKind.Keyword },
        { label: 'return', kind: CompletionItemKind.Keyword }
      );
    }

    // Module completions (after import)
    if (text.slice(Math.max(0, offset - 7), offset).match(/(?:from|import)\s+['"]?$/)) {
      items.push(
        { label: 'core', kind: CompletionItemKind.Module },
        { label: 'io', kind: CompletionItemKind.Module }
      );
    }

    return items;
  }
);

connection.onCompletionResolve((item: CompletionItem): CompletionItem => {
  item.documentation = `Documentation for **${item.label}**`;
  return item;
});

Go-to Definition

connection.onDefinition(async (params) => {
  const doc = documents.get(params.textDocument.uri);
  const offset = doc!.offsetAt(params.position);
  const text = doc!.getText();

  // Find symbol at position and resolve its definition
  const symbol = findSymbolAtPosition(text, offset);
  if (symbol && symbol.definition) {
    return {
      uri: symbol.definition.uri,
      range: symbol.definition.range
    };
  }
  return null;
});

Hover

connection.onHover((params): Hover | null => {
  const doc = documents.get(params.textDocument.uri);
  const offset = doc!.offsetAt(params.position);
  const word = getWordAtOffset(doc!.getText(), offset);

  const docs: Record<string, string> = {
    'function': 'Declare a function.\n\n```\nfunction name(params) -> returnType\n```',
    'if': 'Conditional branch.\n\n```\nif condition { ... } else { ... }\n```'
  };

  if (word && docs[word]) {
    return {
      contents: { kind: 'markdown', value: docs[word] },
      range: getWordRange(doc!, params.position)
    };
  }
  return null;
});

Document Symbols

connection.onDocumentSymbol((params): SymbolInformation[] => {
  const doc = documents.get(params.textDocument.uri);
  const text = doc!.getText();
  const symbols: SymbolInformation[] = [];

  // Parse functions
  const funcRegex = /function\s+([a-zA-Z_]\w*)\s*\(/g;
  let match;
  while ((match = funcRegex.exec(text)) !== null) {
    const pos = doc!.positionAt(match.index);
    symbols.push({
      name: match[1],
      kind: SymbolKind.Function,
      location: { uri: params.textDocument.uri, range: Range.create(pos, pos) }
    });
  }

  return symbols;
});

Code Actions

connection.onCodeAction(async (params): Promise<CodeAction[]> => {
  const actions: CodeAction[] = [];

  // Add missing semicolons
  for (const diag of params.context.diagnostics) {
    if (diag.message === 'Missing semicolon') {
      const fix: CodeAction = {
        title: 'Add semicolon',
        kind: CodeActionKind.QuickFix,
        diagnostics: [diag],
        edit: {
          changes: {
            [params.textDocument.uri]: [TextEdit.insert(diag.range.end, ';')]
          }
        },
        isPreferred: true
      };
      actions.push(fix);
    }
  }

  // Organize imports
  const organizeImports: CodeAction = {
    title: 'Organize Imports',
    kind: CodeActionKind.SourceOrganizeImports,
    edit: {
      changes: { [params.textDocument.uri]: [/* sorted imports */] }
    }
  };
  actions.push(organizeImports);

  return actions;
});

Client Extension

// client/src/extension.ts
import * as path from 'path';
import { workspace, ExtensionContext } from 'vscode';
import {
  LanguageClient, LanguageClientOptions,
  ServerOptions, TransportKind
} from 'vscode-languageclient/node';

let client: LanguageClient;

export function activate(context: ExtensionContext) {
  // Server module path
  const serverModule = context.asAbsolutePath(path.join('server', 'out', 'server.js'));

  const serverOptions: ServerOptions = {
    run: { module: serverModule, transport: TransportKind.ipc },
    debug: {
      module: serverModule,
      transport: TransportKind.ipc,
      options: { execArgv: ['--nolazy', '--inspect=6009'] }
    }
  };

  const clientOptions: LanguageClientOptions = {
    documentSelector: [{ scheme: 'file', language: 'mylang' }],
    synchronize: {
      fileEvents: workspace.createFileSystemWatcher('**/.clientrc')
    }
  };

  client = new LanguageClient('mylang-ls', 'MyLang Language Server', serverOptions, clientOptions);
  client.start();
}

export function deactivate(): Thenable<void> | undefined {
  return client?.stop();
}

Testing LSP

import * as assert from 'assert';
import * as vscode from 'vscode';

suite('LSP Tests', () => {
  test('Completions', async () => {
    const doc = await vscode.workspace.openTextDocument({
      content: 'f',
      language: 'mylang'
    });
    const list = await vscode.commands.executeCommand<vscode.CompletionList>(
      'vscode.executeCompletionItemProvider', doc.uri, new vscode.Position(0, 1)
    );
    assert.ok(list.items.some(i => i.label === 'function'));
  });

  test('Diagnostics', async () => {
    const doc = await vscode.workspace.openTextDocument({
      content: '??? bad syntax',
      language: 'mylang'
    });
    const diagnostics = vscode.languages.getDiagnostics(doc.uri);
    assert.ok(diagnostics.length > 0);
  });

  test('Go to Definition', async () => {
    const doc = await vscode.workspace.openTextDocument({
      content: 'function foo() { }\nfoo()',
      language: 'mylang'
    });
    const locations = await vscode.commands.executeCommand<vscode.Location[]>(
      'vscode.executeDefinitionProvider', doc.uri, new vscode.Position(1, 0)
    );
    assert.ok(locations && locations.length > 0);
  });
});

Debugging LSP

# Launch configuration (.vscode/launch.json)
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Client + Server",
      "type": "extensionHost",
      "request": "launch",
      "args": ["--extensionDevelopmentPath=${workspaceFolder}/client"],
      "outFiles": ["${workspaceFolder}/client/out/**/*.js"],
      "debugServer": 6009,
      "env": { "LSP_LOG": "debug" }
    },
    {
      "name": "Server Only",
      "type": "node",
      "request": "attach",
      "port": 6009,
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/server/out/**/*.js"]
    }
  ]
}

Publishing

# Package (includes both client and server)
vsce package
vsce publish

# LSP logging (for debugging)
# Set in client options:
{
  "mylang-ls.trace.server": "messages"     # "off" | "messages" | "verbose"
}