🕊 BIRD2 LSP Project

Modern Language Server Protocol support for BIRD2 configuration files

⚠️ Development Stage Notice

Component	Status	Warning
npm packages (@birdcc/*)	🚧 Alpha	APIs may change frequently. Evaluate carefully before production use.
VS Code extension	🧪 Beta	More stable than Alpha, but some features may still change. Evaluate before production use.

Please evaluate carefully before deploying in production environments.

English Version | 中文文档

Overview · Features · Quick Start · Packages · Architecture · Development

---

Overview

BIRD-LSP is a modern toolchain for BIRD2 (and BIRD3) configuration files, providing Language Server Protocol (LSP) support, code formatting (Formatter & Parser), and static analysis (Linter).

---

Features

Feature	Description
🎨 Syntax Highlighting	Tree-sitter based precise parsing
🔍 Real-time Diagnostics	32+ lint rules + cross-file analysis + bird -p validation
📝 Code Formatting	Dual-engine formatter (dprint + builtin) with safe mode
💡 IntelliSense	Smart completion for protocols, filters, functions
🔎 Hover Information	Type info and documentation on hover
🏗️ Symbol Navigation	Go to definition, find references (cross-file)

---

Quick Start

Install CLI

npm install -g @birdcc/cli
# or
pnpm add -g @birdcc/cli

Usage

# Lint a BIRD config file
birdcc lint bird.conf

# Format a file
birdcc fmt bird.conf --write

# Start LSP server
birdcc lsp --stdio

VS Code Extension

Search for "BIRD2 LSP" in VS Code Marketplace or install from Open VSX.

---

Packages

Package	Version	Description	Documentation
@birdcc/parser	0.1.0-alpha	Tree-sitter parser for BIRD2	README
@birdcc/core	0.1.0-alpha	Semantic analysis engine	README
@birdcc/linter	0.1.0-alpha	Pluggable lint rule system	README
@birdcc/lsp	0.1.0-alpha	LSP server implementation	README
@birdcc/formatter	0.1.0-alpha	Dual-engine code formatter	README
@birdcc/cli	0.1.0-alpha	Command-line interface	README
@birdcc/vscode	0.1.0-alpha	VS Code extension	README
@birdcc/dprint-plugin-bird	0.1.0-alpha	dprint plugin (Rust/WASM)	README

---

Architecture

Component Interaction

sequenceDiagram
    autonumber
    participant Editor as Editor (VSCode/Neovim)
    participant LSP as "@birdcc/lsp"
    participant Linter as "@birdcc/linter"
    participant Formatter as "@birdcc/formatter"
    participant Parser as "@birdcc/parser"
    participant Core as "@birdcc/core"

    rect rgb(225, 245, 254)
        Note over Editor,Core: Real-time Diagnostics Flow
        Editor->>+LSP: textDocument/didChange
        LSP->>+Parser: parseBirdConfig(source)
        Parser-->>-LSP: ParsedBirdDocument
        LSP->>+Core: buildCoreSnapshot(parsed)
        Core-->>-LSP: CoreSnapshot
        LSP->>+Linter: lintBirdConfig(context)
        Linter-->>-LSP: Diagnostics[]
        LSP-->>-Editor: textDocument/publishDiagnostics
    end

    rect rgb(255, 243, 224)
        Note over Editor,Core: Formatting Flow
        Editor->>+LSP: textDocument/formatting
        LSP->>+Formatter: formatBirdConfig(source)
        Formatter->>+Parser: parseBirdConfig(source)
        Parser-->>-Formatter: AST
        Formatter-->>-LSP: Formatted Text
        LSP-->>-Editor: TextEdit[]
    end

Loading

Package Dependency Graph

flowchart BT
    classDef infra fill:#fce4ec,stroke:#ad1457,stroke-width:2px,color:#000
    classDef core fill:#e8f5e9,stroke:#2e7d32,stroke-width:3px,color:#000
    classDef service fill:#fff3e0,stroke:#ef6c00,stroke-width:2px,color:#000
    classDef lsp fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000
    classDef user fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#000

    subgraph Infrastructure [Infrastructure Layer]
        PARSER("@birdcc/parser<br/>Tree-sitter/WASM")
        DPRINT("@birdcc/dprint-plugin-bird<br/>🦀 Rust")
    end

    subgraph CoreLayer [Core Layer]
        CORE("@birdcc/core<br/>Symbol Table & Type System")
    end

    subgraph ServiceLayer [Service Layer]
        FORMATTER("@birdcc/formatter<br/>Formatting Engine")
        LINTER("@birdcc/linter<br/>Config Static Analysis Engine")
    end

    subgraph LspLayer [LSP Adapter Layer]
        LSP_SERVER("@birdcc/lsp<br/>Language Server Protocol")
    end

    subgraph UserLayer [User Interface Layer]
        CLI("@birdcc/cli<br/>Command Line")
        VSCODE("@birdcc/vscode<br/>Editor Extension")
    end


    %% Infrastructure supports Formatter (Dprint as underlying engine)
    PARSER <--> DPRINT
    PARSER <--> CORE

    CORE --> FORMATTER
    DPRINT --> FORMATTER

    %% Core and Formatter support Linter
    CORE --> LINTER
    FORMATTER --> LINTER

    %% All services support LSP
    FORMATTER --> LSP_SERVER
    LINTER --> LSP_SERVER

    %% LSP and standalone services support user interfaces
    LSP_SERVER --> CLI
    LSP_SERVER --> VSCODE
    LINTER --> CLI
    FORMATTER --> CLI

    class PARSER,DPRINT infra
    class CORE core
    class FORMATTER,LINTER service
    class LSP_SERVER lsp
    class CLI,VSCODE user

Loading

---

Development

# Clone with submodules
git clone --recursive https://github.com/bird-chinese-community/BIRD-LSP.git
cd BIRD-LSP

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

---

📖 Documentation

• BIRD Official Documentation
• BIRD2 User Manual
• Extension Configuration Guide
• Project Config Spec (bird.config.json)
• FAQ / Troubleshooting
• GitHub Project

---

📝 License

This project is licensed under the GPL-3.0 License.

---

🙏 Acknowledgements

We gratefully acknowledge these upstream repositories for the real-world BIRD configuration examples that help validate parsing, formatting, linting, and editor support in this project:

• PoemaIX/IX-BIRD-RS-Generator
• HuJK-Data/JKNET-BIRD
• @LaunchPad-Network (private feed)
• 186526/net186-config
• SunyzNET/bird-config
• tianshome/bird-configs-output

---

_{Built with ❤️ by the BIRD Chinese Community (BIRDCC)}

🕊 GitHub · 🛒 Marketplace · 🐛 Report Issues