dart-intellij-third-party: Skill for Claude Code

Migrating Dart Analysis Server Features to JetBrains LSP

This skill provides comprehensive architectural context, guidelines, and step-by-step instructions for converting legacy Dart Analysis Server (DAS) features (such as hover, navigation, diagnostics, code completion, etc.) over to the JetBrains LSP integration.

---

1. High-Level Architecture

The Dart IntelliJ plugin operates under a hybrid architecture during the transition from custom DAS protocols to the Language Server Protocol (LSP):

graph TD
    Client[IntelliJ IDEA / IDE Frontend]
    Legacy[Legacy Dart Providers e.g. DartDocumentationProvider]
    LspClient[JetBrains LSP Framework com.intellij.platform.dartlsp]
    BridgeMgr[DartBridgeLspServerManager]
    Bridge[DartBridgeLspServer In-Process TCP Socket]
    DAS[Dart Analysis Server External Process]

    Client -->|Experimental LSP Off| Legacy
    Legacy -->|Custom DAS API| DAS
    Client -->|Experimental LSP On| LspClient
    LspClient -->|TCP Socket| BridgeMgr
    BridgeMgr -->|Routes Requests| Bridge
    Bridge -->|lsp.handle JSON-RPC| DAS

The Bridge Server Architecture

JetBrains' native LSP client expects to connect to a socket or standard I/O stream speaking JSON-RPC 2.0. Because the Dart Analysis Server (DAS) is already running as a standalone process managed by DartAnalysisServerService, we do not launch a second LSP server process. Instead, DartBridgeLspServerManager hosts a lightweight in-process TCP socket bridge (DartBridgeLspServer). When the JetBrains LSP framework sends an LSP request (e.g., textDocument/hover), DartBridgeLspServer wraps the LSP payload into a custom DAS request named lsp.handle ({ "lspMessage": <jsonrpc payload> }), forwards it to DAS, and unpacks the returned lspResponse back to the JetBrains LSP framework.

---

2. Critical Nuances & Guidelines

[!IMPORTANT] Copied JetBrains LSP Client Sources (com.intellij.platform.dartlsp) To support IntelliJ Platform versions 2025.3 and 2026.1 before JetBrains' official Ultimate LSP client becomes open source in Community Edition, the platform LSP framework was copied into third_party/thirdPartySrc/platform-lsp/ under the namespace com.intellij.platform.dartlsp.