How kotlin/kotlin-lsp works
Project Type and Purpose
• This is a language-server implementation for Kotlin (kotlin-lsp) plus a VS Code extension (kotlin-vscode) and related modules (API definitions, feature plugins, project import).
• It implements the Language Server Protocol (LSP) to provide diagnostics, completion, navigation, code actions, etc., and ships both a standalone LSP server and a VS Code client.
High-Level Module Structure
• api.core: Core LSP API interfaces (LSServer, LSWorkspace, LSDocuments, utilities).
• api.features: Definitions of language-server features (completion, hover, diagnostics, symbols, commands).
• features-impl: Concrete implementations of those features in two flavors:
• common: generic implementations (syntax errors, quick-fixes, basic completion, hover).
• kotlin: Kotlin-specific implementations (compiler diagnostics, Kotlin AST-based completion, organize imports, semantic tokens).
• workspace-import: Project-import subsystem (Gradle importers, JSON importer, services).
• kotlin-lsp: The actual server binary wiring: starts LSP over stdio or sockets, hooks into IntelliJ platform.
• kotlin-vscode: VS Code extension (TypeScript) acting as LSP client.
• scripts: Launch wrappers for other editors (neovim, Emacs, Zed).
Core Components and Interactions
• LSP Client (VS Code extension / any editor)
↕ JSON-RPC over stdio or sockets
• LSP Server (kotlin-lsp module)
• Uses engine wiring to load modules: api.core + api.features + features-impl/common + features-impl/kotlin + workspace-import
• Receives initialize/file events, dispatches to API interfaces -> feature providers -> implementation.
• Project Import Subsystem
• Called at initialization: workspace-import chooses appropriate importer (Gradle, JSON, JPS) to build an in-memory model.
• Provides project model for diagnostics, completion, symbols.
• IntelliJ Platform & Kotlin Plugin
• Underlying engine for parsing, type-checking, analysis.
• Invoked indirectly by feature-impl/kotlin for deep analysis.
Architectural Patterns & Principles
• Plugin Architecture: clear separation between API definitions (api.core, api.features) and implementations (features-impl).
• Dependency Injection / Service Locator: implementations are discovered via META-INF XML descriptors.
• Modular Build with Bazel: each module has its own BUILD.bazel and strict dependencies.
• Layered Design:
• Transport Layer (JSON-RPC, stdio)
• Protocol Layer (api.core)
• Feature Layer (api.features + implementations)
• Language Engine Layer (IntelliJ + Kotlin compiler internals)
• Project Model Layer (workspace-import)