🕊 BIRD Config LSP (@birdcc/lsp)

⚠️ Alpha Stage: This package is in early development. APIs may change frequently, and unexpected issues may occur. Please evaluate carefully before deploying in production environments.

Overview · Features · Installation · Usage · Editor Integration · API Reference · Architecture

Overview

@birdcc/lsp is the Language Server Protocol implementation for BIRD2 configuration files, delivering real-time diagnostics, intelligent code completion, hover tooltips, and more for editor integration.

| Package | Version | Description | | ------------- | ------- | ---------------------------------------------------- | | @birdcc/lsp | 0.1.0 | LSP server implementation with real-time diagnostics |

Features

LSP Capabilities

• Incremental Synchronization — TextDocumentSyncKind.Incremental for efficient handling of large files
• Real-time Diagnostics — Automatic validation on document open and modification
• Code Completion — Auto-completion for keywords, symbols, and snippets
• Hover Information — Type information and documentation on hover
• Go to Definition — Navigate to symbol definitions
• Find References — Find all references to a symbol
• Document Symbols — Outline view for quick navigation

Protocol Features

• Standard LSP — Full protocol support powered by vscode-languageserver
• Diagnostic Push — Server-initiated diagnostic updates
• Workspace Folders — Multi-root workspace support

Installation

# Using pnpm (recommended)
pnpm add @birdcc/lsp

# Using npm
npm install @birdcc/lsp

# Using yarn
yarn add @birdcc/lsp

Usage

Start LSP Server

# stdio mode (for editor integration)
npx birdcc lsp --stdio

Programmatic Usage

import { startLspServer, toLspDiagnostic } from "@birdcc/lsp";
import type { BirdDiagnostic } from "@birdcc/core";

// Start the LSP server
startLspServer();

// Convert internal diagnostic to LSP format
const lspDiagnostic = toLspDiagnostic(birdDiagnostic);

Editor Integration

Visual Studio Code

// settings.json
{
  "bird-lsp.enable": true,
  "bird-lsp.path": "./node_modules/.bin/birdcc",
  "bird-lsp.validateWithBird": true
}

Neovim

-- init.lua with nvim-lspconfig
local lspconfig = require("lspconfig")
local configs = require("lspconfig.configs")

if not configs.birdcc then
  configs.birdcc = {
    default_config = {
      cmd = { "npx", "birdcc", "lsp", "--stdio" },
      filetypes = { "bird", "conf" },
      root_dir = lspconfig.util.root_pattern(".git", "bird.conf"),
      single_file_support = true,
    },
  }
end

lspconfig.birdcc.setup({})

Helix

# ~/.config/helix/languages.toml
[[language]]
name = "bird"
file-types = ["conf"]
roots = [".git", "bird.conf"]
language-servers = ["birdcc"]

[language-server.birdcc]
command = "npx"
args = ["birdcc", "lsp", "--stdio"]

API Reference

Exports

import { startLspServer, toLspDiagnostic, createConnection } from "@birdcc/lsp";

startLspServer(): void

Start the LSP server with stdio transport.

toLspDiagnostic(diagnostic: BirdDiagnostic): Diagnostic

Convert a BIRD diagnostic to LSP Diagnostic format.

Types

interface LspOptions {
  connection?: Connection;
  documents?: TextDocuments<TextDocument>;
}

Architecture

System Overview

flowchart TB
    subgraph "Editor Layer"
        E1[VS Code]
        E2[Neovim]
        E3[Vim]
        E4[Helix]
    end

    subgraph "LSP Protocol"
        LSP[LSP Protocol<br/>JSON-RPC]
    end

    subgraph "LSP Server"
        S[@birdcc/lsp<br/>LSP Server]
        SYNC[Document Sync<br/>Incremental]
        DIAG[Diagnostics Handler]
        COMP[Completion Provider]
        HOVER[Hover Provider]
        DEF[Definition Provider]
    end

    subgraph "Service Layer"
        LINTER[@birdcc/linter<br/>32+ Rules]
        FORMATTER[@birdcc/formatter<br/>dprint/builtin]
    end

    subgraph "Core Layer"
        CORE[@birdcc/core<br/>Symbol Table]
    end

    subgraph "Parser Layer"
        PARSER[@birdcc/parser<br/>Tree-sitter]
    end

    E1 --> LSP
    E2 --> LSP
    E3 --> LSP
    E4 --> LSP
    LSP --> S
    S --> SYNC
    S --> DIAG
    S --> COMP
    S --> HOVER
    S --> DEF
    DIAG --> LINTER
    COMP --> CORE
    HOVER --> CORE
    DEF --> CORE
    LINTER --> CORE
    FORMATTER --> PARSER
    CORE --> PARSER

    style S fill:#e3f2fd
    style LSP fill:#f3e5f5

Request Handling Flow

sequenceDiagram
    participant Editor as Editor
    participant LSP as LSP Connection
    participant Server as @birdcc/lsp
    participant Services as Services
    participant Core as @birdcc/core

    Editor->>LSP: Initialize Request
    LSP->>Server: onInitialize()
    Server-->>LSP: ServerCapabilities
    LSP-->>Editor: Initialize Result

    Editor->>LSP: textDocument/didOpen
    LSP->>Server: onDidOpen()
    Server->>Services: validate(document)
    Services->>Core: buildCoreSnapshot()
    Core-->>Services: snapshot
    Services-->>Server: diagnostics
    Server->>LSP: publishDiagnostics
    LSP->>Editor: Diagnostics

    Editor->>LSP: textDocument/completion
    LSP->>Server: onCompletion()
    Server->>Core: getSymbols()
    Core-->>Server: symbols[]
    Server-->>LSP: CompletionItem[]
    LSP-->>Editor: Completions

    Editor->>LSP: textDocument/hover
    LSP->>Server: onHover()
    Server->>Core: resolveSymbol()
    Core-->>Server: symbol info
    Server-->>LSP: Hover
    LSP-->>Editor: Tooltip

Document Synchronization

flowchart LR
    subgraph "Editor"
        E[Document Changes]
    end

    subgraph "LSP Server"
        S[Text Documents Manager]
        AST[AST Cache]
        SYM[Symbol Cache]
    end

    subgraph "Validation"
        V[Validator]
        D[Diagnostics Engine]
    end

    E -->|didChange| S
    E -->|didOpen| S
    E -->|didClose| S
    S -->|parse| AST
    AST -->|analyze| SYM
    SYM -->|validate| V
    V -->|report| D
    D -->|publish| E

    style S fill:#e3f2fd
    style AST fill:#e8f5e9
    style SYM fill:#fff3e0

Server Capabilities

| Capability | Status | | ------------------------ | ----------- | | textDocumentSync | Incremental | | documentSymbolProvider | ✅ | | hoverProvider | ✅ | | definitionProvider | ✅ | | referencesProvider | ✅ | | completionProvider | ✅ |

Related Packages

| Package | Description | | ---------------------------------- | ------------------------------ | | @birdcc/parser | Tree-sitter grammar and parser | | @birdcc/core | Semantic analysis engine | | @birdcc/linter | 32+ lint rules | | @birdcc/formatter | Code formatting engine | | @birdcc/cli | Command-line interface |

📖 Documentation

• BIRD Official Documentation
• BIRD2 User Manual
• LSP Specification
• GitHub Project

📝 License

This project is licensed under the GPL-3.0 License.