🕊 BIRD Config Parser (@birdcc/parser)

⚠️ 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 · API Reference · Building

Overview

@birdcc/parser is a Tree-sitter based parser for BIRD2 configuration files, delivering high-performance syntax analysis and declaration extraction capabilities.

Core Highlights

| Feature | Description | | ------------------------- | --------------------------------------------------------------------------------- | | 🌲 Tree-sitter Grammar | Complete BIRD2 grammar definition with error recovery support | | ⚡ WASM Runtime | WebAssembly runtime powered by web-tree-sitter for cross-platform compatibility | | 🔌 Async API | Asynchronous parsing interface optimized for server and CLI environments | | 📦 Declaration Extraction | Extract top-level declarations and protocol statements for semantic analysis | | 🩺 Error Diagnostics | Automatic syntax error detection with precise source location information |

Features

Declaration Extraction

• include — File inclusion statements
• define — Macro definitions
• router id — Router identifier configuration
• table — Routing table definitions (ipv4/ipv6/vpn4/vpn6/roa4/roa6/flow4/flow6)

Protocols & Templates

• protocol — Protocol definitions supporting types like bgp/ospf/static/direct
• template — Protocol template definitions
• Template Inheritance — Support for template inheritance via the from clause

Protocol Statements

• local as — Local AS number configuration
• neighbor ... as ... — BGP neighbor definition
• import — Import rules (all/none/filter/where)
• export — Export rules (all/none/filter/where)

Channel Statements

• Types — ipv4/ipv6/vpn4/vpn6/roa4/roa6/flow4/flow6/mpls
• table — Associated routing table
• import/export — Channel-level import/export rules
• import limit / receive limit — Route limit configuration
• debug — Debug configuration
• import keep filtered — Retain filtered routes

Filter & Function Skeleton

• Control Flow — if / case conditional statements
• Actions — accept / reject / return routing decisions
• Literal Extraction — ip / prefix literals for semantic validation
• Match Expressions — Pattern matching with the ~ operator

Error Diagnostics

• ERROR Nodes — Tree-sitter syntax errors with complete source ranges
• MISSING Nodes — Missing symbol detection (e.g., missing semicolons)
• Brace Balancing — Automatic detection of unbalanced braces

Installation

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

# Using npm
npm install @birdcc/parser

# Using yarn
yarn add @birdcc/parser

Prerequisites

• Node.js >= 18
• TypeScript >= 5.0 (if using TypeScript)

Usage

Basic Parsing

import { parseBirdConfig } from "@birdcc/parser";

const source = `
protocol bgp edge {
  local as 65001;
  neighbor 192.0.2.1 as 65002;
  import all;
  export filter policy_out;
  
  ipv4 {
    table bgp_v4;
    import limit 1000 action restart;
  };
}
`;

const result = await parseBirdConfig(source);

// View extracted declarations
console.log(result.program.declarations);

// View diagnostic issues
console.log(result.issues);

Handling Errors

import { parseBirdConfig } from "@birdcc/parser";

const result = await parseBirdConfig(source);

if (result.issues.length > 0) {
  for (const issue of result.issues) {
    console.error(
      `[${issue.code}] Line ${issue.line}:${issue.column} - ${issue.message}`,
    );
  }
}

// Even with errors, the result contains processable declarations
console.log(`Found ${result.program.declarations.length} declarations`);

Extract Protocol Details

import { parseBirdConfig } from "@birdcc/parser";

const result = await parseBirdConfig(source);

for (const decl of result.program.declarations) {
  if (decl.kind === "protocol") {
    console.log(`Protocol: ${decl.name} (${decl.protocolType})`);

    for (const stmt of decl.statements) {
      if (stmt.kind === "local-as") {
        console.log(`  Local AS: ${stmt.asn}`);
      }
      if (stmt.kind === "neighbor") {
        console.log(`  Neighbor: ${stmt.address} AS ${stmt.asn}`);
      }
    }
  }
}

API Reference

Main Function

function parseBirdConfig(input: string): Promise<ParsedBirdDocument>;

Parses BIRD configuration content and returns the parsing result along with diagnostic information.

Parameters:

• input: string — Configuration file content

Returns: Promise<ParsedBirdDocument> — Parsing result object

Core Types

ParsedBirdDocument

interface ParsedBirdDocument {
  program: BirdProgram; // Parsed program structure
  issues: ParseIssue[]; // Diagnostic issues
}

BirdDeclaration

Union type of declaration kinds:

| Type | Description | | --------------------- | --------------------------- | | IncludeDeclaration | include "file.conf"; | | DefineDeclaration | define MACRO = value; | | RouterIdDeclaration | router id 192.0.2.1; | | TableDeclaration | table bgp_v4; | | ProtocolDeclaration | protocol bgp name { ... } | | TemplateDeclaration | template bgp base { ... } | | FilterDeclaration | filter name { ... } | | FunctionDeclaration | function name() { ... } |

ParseIssue

interface ParseIssue {
  code:
    | "syntax/missing-semicolon"
    | "syntax/unbalanced-brace"
    | "parser/missing-symbol"
    | "parser/syntax-error"
    | "parser/runtime-error";
  message: string;
  line: number; // Start line (1-based)
  column: number; // Start column (1-based)
  endLine: number; // End line
  endColumn: number; // End column
}

Building

Development Build

# Install dependencies
pnpm install

# Build TypeScript
pnpm --filter @birdcc/parser run build

# Run tests
pnpm --filter @birdcc/parser run test

# Type check
pnpm --filter @birdcc/parser run typecheck

WASM Build

# Regenerate grammar files
pnpm --filter @birdcc/parser run build:grammar

# Build WASM runtime (requires Emscripten or Docker)
pnpm --filter @birdcc/parser run build:wasm

File Structure

Tracked Files (in Git):

| File | Description | | ----------------------------- | ------------------------------ | | grammar.js | Tree-sitter grammar definition | | src/tree-sitter-birdcc.wasm | WASM runtime binary | | src/*.ts | TypeScript source files |

Generated Files (not tracked):

| File | Description | | --------------------- | --------------------- | | src/parser.c | Generated C parser | | src/grammar.json | Serialized grammar | | src/node-types.json | Node type definitions |

Related Packages

| Package | Description | | ------------------------------------------ | --------------------------------------- | | @birdcc/core | AST, symbol table, and type checker | | @birdcc/linter | 32+ lint rules and diagnostics | | @birdcc/lsp | Language Server Protocol implementation | | @birdcc/formatter | Code formatter | | @birdcc/cli | Command-line interface |

📖 Documentation

• BIRD Official Documentation
• BIRD2 User Manual
• Extension Configuration Guide
• GitHub Project

📝 License

This project is licensed under the GPL-3.0 License.