@birdcc/lsp 0.0.1-alpha.0

package/src/index.ts

@@ -0,0 +1,8 @@
+export { createCompletionItemsFromParsed } from "./completion.js";
+export type { CompletionContextOptions } from "./completion.js";
+export { createDefinitionLocations } from "./definition.js";
+export { toInternalErrorDiagnostic, toLspDiagnostic } from "./diagnostic.js";
+export { createDocumentSymbolsFromParsed } from "./document-symbol.js";
+export { createHoverFromParsed } from "./hover.js";
+export { createReferenceLocations } from "./references.js";
+export { startLspServer } from "./lsp-server.js";

package/src/lsp-server.ts

@@ -0,0 +1,350 @@
+import {
+  DEFAULT_CROSS_FILE_MAX_DEPTH,
+  DEFAULT_CROSS_FILE_MAX_FILES,
+  resolveCrossFileReferences,
+  type SymbolTable,
+} from "@birdcc/core";
+import {
+  createConnection,
+  type Diagnostic,
+  type InitializeResult,
+  ProposedFeatures,
+  TextDocuments,
+  TextDocumentSyncKind,
+} from "vscode-languageserver/node.js";
+import { TextDocument } from "vscode-languageserver-textdocument";
+import type { ParsedBirdDocument } from "@birdcc/parser";
+import { parseBirdConfig } from "@birdcc/parser";
+import {
+  lintBirdConfig,
+  lintResolvedCrossFileGraph,
+  type LintResult,
+} from "@birdcc/linter";
+import { createCompletionItemsFromParsed } from "./completion.js";
+import { createDefinitionLocations } from "./definition.js";
+import { createDocumentSymbolsFromParsed } from "./document-symbol.js";
+import { toInternalErrorDiagnostic, toLspDiagnostic } from "./diagnostic.js";
+import { createHoverFromParsed } from "./hover.js";
+import { createReferenceLocations } from "./references.js";
+import { createValidationScheduler } from "./validation.js";
+
+const VALIDATION_DEBOUNCE_MS = 120;
+const INCLUDE_MAX_DEPTH = DEFAULT_CROSS_FILE_MAX_DEPTH;
+const INCLUDE_MAX_FILES = DEFAULT_CROSS_FILE_MAX_FILES;
+
+interface ParsedCacheEntry {
+  version: number;
+  parsed: ParsedBirdDocument;
+}
+
+interface GraphCacheEntry {
+  entryUri: string;
+  visitedUris: Set<string>;
+  symbolTable: SymbolTable;
+  byUri: Record<string, LintResult>;
+}
+
+const warmupParserRuntime = async (): Promise<void> => {
+  try {
+    await lintBirdConfig("");
+  } catch {
+    // Warmup is best-effort and must not block server startup.
+  }
+};
+
+const flattenAdditionalDeclarations = (
+  graph: GraphCacheEntry,
+  uri: string,
+): ParsedBirdDocument["program"]["declarations"] => {
+  const declarations: ParsedBirdDocument["program"]["declarations"] = [];
+
+  for (const [itemUri, lintResult] of Object.entries(graph.byUri)) {
+    if (itemUri === uri) {
+      continue;
+    }
+
+    declarations.push(...lintResult.parsed.program.declarations);
+  }
+
+  return declarations;
+};
+
+/** Starts the stdio LSP server with async lint validation and last-write-wins scheduling. */
+export const startLspServer = (): void => {
+  const connection = createConnection(ProposedFeatures.all);
+  const documents = new TextDocuments(TextDocument);
+  const parsedByUri = new Map<string, ParsedCacheEntry>();
+  const graphByUri = new Map<string, GraphCacheEntry>();
+  const publishedUrisByEntry = new Map<string, Set<string>>();
+  let hasShutdownBeenRequested = false;
+
+  void warmupParserRuntime();
+
+  const clearEntryTracking = (entryUri: string): void => {
+    const publishedUris = publishedUrisByEntry.get(entryUri);
+    if (publishedUris) {
+      for (const uri of publishedUris) {
+        connection.sendDiagnostics({ uri, diagnostics: [] });
+      }
+      publishedUrisByEntry.delete(entryUri);
+    }
+
+    for (const [uri, graph] of graphByUri.entries()) {
+      if (graph.entryUri === entryUri) {
+        graphByUri.delete(uri);
+      }
+    }
+  };
+
+  const analyzeDocument = async (
+    document: TextDocument,
+    options: { publishRelatedDiagnostics: boolean },
+  ): Promise<{ entryDiagnostics: Diagnostic[]; graph: GraphCacheEntry }> => {
+    const openDocuments = documents.all().map((item) => ({
+      uri: item.uri,
+      text: item.getText(),
+    }));
+
+    const crossFile = await resolveCrossFileReferences({
+      entryUri: document.uri,
+      documents: openDocuments,
+      loadFromFileSystem: true,
+      maxDepth: INCLUDE_MAX_DEPTH,
+      maxFiles: INCLUDE_MAX_FILES,
+    });
+
+    const lintGraph = await lintResolvedCrossFileGraph(crossFile);
+    const visitedUris = new Set(
+      crossFile.visitedUris.length > 0 ? crossFile.visitedUris : [document.uri],
+    );
+
+    const graph: GraphCacheEntry = {
+      entryUri: document.uri,
+      visitedUris,
+      symbolTable: crossFile.symbolTable,
+      byUri: lintGraph.byUri,
+    };
+
+    for (const [uri, lintResult] of Object.entries(lintGraph.byUri)) {
+      const liveDocument = documents.get(uri);
+      parsedByUri.set(uri, {
+        version: liveDocument?.version ?? -1,
+        parsed: lintResult.parsed,
+      });
+      graphByUri.set(uri, graph);
+    }
+
+    const diagnosticsByUri = new Map<string, Diagnostic[]>();
+    for (const uri of visitedUris) {
+      const lintResult = lintGraph.byUri[uri];
+      diagnosticsByUri.set(
+        uri,
+        (lintResult?.diagnostics ?? []).map(toLspDiagnostic),
+      );
+    }
+
+    const entryDiagnostics = diagnosticsByUri.get(document.uri) ?? [];
+    if (options.publishRelatedDiagnostics) {
+      const previousUris =
+        publishedUrisByEntry.get(document.uri) ?? new Set<string>();
+
+      for (const uri of previousUris) {
+        if (visitedUris.has(uri)) {
+          continue;
+        }
+
+        connection.sendDiagnostics({ uri, diagnostics: [] });
+      }
+
+      for (const [uri, diagnostics] of diagnosticsByUri) {
+        if (uri === document.uri) {
+          continue;
+        }
+
+        connection.sendDiagnostics({
+          uri,
+          version: documents.get(uri)?.version,
+          diagnostics,
+        });
+      }
+
+      publishedUrisByEntry.set(document.uri, visitedUris);
+    }
+
+    return { entryDiagnostics, graph };
+  };
+
+  const getGraphForDocument = async (
+    document: TextDocument,
+  ): Promise<GraphCacheEntry> => {
+    const cached = graphByUri.get(document.uri);
+    if (cached) {
+      return cached;
+    }
+
+    const analyzed = await analyzeDocument(document, {
+      publishRelatedDiagnostics: false,
+    });
+    return analyzed.graph;
+  };
+
+  connection.onInitialize(
+    (): InitializeResult => ({
+      capabilities: {
+        textDocumentSync: TextDocumentSyncKind.Incremental,
+        documentSymbolProvider: true,
+        hoverProvider: true,
+        definitionProvider: true,
+        referencesProvider: true,
+        completionProvider: {
+          resolveProvider: false,
+          triggerCharacters: [" ", "."],
+        },
+      },
+    }),
+  );
+
+  const scheduler = createValidationScheduler<TextDocument, Diagnostic>({
+    debounceMs: VALIDATION_DEBOUNCE_MS,
+    validate: async (textDocument): Promise<Diagnostic[]> => {
+      try {
+        const analyzed = await analyzeDocument(textDocument, {
+          publishRelatedDiagnostics: true,
+        });
+        return analyzed.entryDiagnostics;
+      } catch (error) {
+        return [toInternalErrorDiagnostic(error)];
+      }
+    },
+    publish: (payload) => {
+      connection.sendDiagnostics(payload);
+    },
+  });
+
+  documents.onDidOpen((event) => {
+    scheduler.schedule(event.document);
+  });
+
+  documents.onDidChangeContent((event) => {
+    scheduler.schedule(event.document);
+  });
+
+  documents.onDidClose((event) => {
+    parsedByUri.delete(event.document.uri);
+    clearEntryTracking(event.document.uri);
+    scheduler.close(event.document.uri);
+  });
+
+  const getParsedDocument = async (
+    document: TextDocument,
+  ): Promise<ParsedBirdDocument> => {
+    const cached = parsedByUri.get(document.uri);
+    if (cached && cached.version === document.version) {
+      return cached.parsed;
+    }
+
+    const parsed = await parseBirdConfig(document.getText());
+    parsedByUri.set(document.uri, {
+      version: document.version,
+      parsed,
+    });
+    return parsed;
+  };
+
+  connection.onDocumentSymbol(async (params) => {
+    const document = documents.get(params.textDocument.uri);
+    if (!document) {
+      return [];
+    }
+
+    const parsed = await getParsedDocument(document);
+    return createDocumentSymbolsFromParsed(parsed);
+  });
+
+  connection.onHover(async (params) => {
+    const document = documents.get(params.textDocument.uri);
+    if (!document) {
+      return null;
+    }
+
+    const parsed = await getParsedDocument(document);
+    return createHoverFromParsed(parsed, document, params.position);
+  });
+
+  connection.onDefinition(async (params) => {
+    const document = documents.get(params.textDocument.uri);
+    if (!document) {
+      return [];
+    }
+
+    try {
+      const graph = await getGraphForDocument(document);
+      return createDefinitionLocations(
+        graph.symbolTable,
+        document.uri,
+        params.position,
+        document.getText(),
+      );
+    } catch {
+      return [];
+    }
+  });
+
+  connection.onReferences(async (params) => {
+    const document = documents.get(params.textDocument.uri);
+    if (!document) {
+      return [];
+    }
+
+    try {
+      const graph = await getGraphForDocument(document);
+      return createReferenceLocations(
+        graph.symbolTable,
+        document.uri,
+        params.position,
+        document.getText(),
+      );
+    } catch {
+      return [];
+    }
+  });
+
+  connection.onCompletion(async (params) => {
+    const document = documents.get(params.textDocument.uri);
+    if (!document) {
+      return [];
+    }
+
+    const parsed = await getParsedDocument(document);
+    const linePrefix = document.getText({
+      start: { line: params.position.line, character: 0 },
+      end: params.position,
+    });
+
+    try {
+      const graph = await getGraphForDocument(document);
+      return createCompletionItemsFromParsed(parsed, {
+        linePrefix,
+        additionalDeclarations: flattenAdditionalDeclarations(
+          graph,
+          document.uri,
+        ),
+      });
+    } catch {
+      return createCompletionItemsFromParsed(parsed, { linePrefix });
+    }
+  });
+
+  connection.onShutdown(() => {
+    hasShutdownBeenRequested = true;
+  });
+
+  connection.onExit(() => {
+    if (!hasShutdownBeenRequested) {
+      process.exitCode = 1;
+    }
+  });
+
+  documents.listen(connection);
+  connection.listen();
+};

package/src/references.ts

@@ -0,0 +1,107 @@
+import type {
+  SymbolDefinition,
+  SymbolReference,
+  SymbolTable,
+} from "@birdcc/core";
+import type { Location, Position } from "vscode-languageserver/node.js";
+import {
+  containsPosition,
+  createSymbolLookupIndex,
+  dedupeLocations,
+  extractWordAtPosition,
+  toLocation,
+} from "./symbol-utils.js";
+
+interface SymbolTarget {
+  kind?: SymbolDefinition["kind"] | SymbolReference["kind"];
+  name: string;
+}
+
+const findTargetSymbol = (
+  symbolTable: SymbolTable,
+  index: ReturnType<typeof createSymbolLookupIndex>,
+  uri: string,
+  position: Position,
+  sourceText: string,
+): SymbolTarget | null => {
+  const definition = symbolTable.definitions.find(
+    (item) => item.uri === uri && containsPosition(item, position),
+  );
+  if (definition) {
+    return { kind: definition.kind, name: definition.name };
+  }
+
+  const reference = symbolTable.references.find(
+    (item) => item.uri === uri && containsPosition(item, position),
+  );
+  if (reference) {
+    return { kind: reference.kind, name: reference.name };
+  }
+
+  const name = extractWordAtPosition(sourceText, position);
+  if (!name) {
+    return null;
+  }
+
+  const lowerName = name.toLowerCase();
+
+  const matchedDefinition = (index.definitionsByName.get(lowerName) ?? [])[0];
+  if (matchedDefinition) {
+    return { kind: matchedDefinition.kind, name: matchedDefinition.name };
+  }
+
+  const matchedReference = (index.referencesByName.get(lowerName) ?? [])[0];
+  if (matchedReference) {
+    return { kind: matchedReference.kind, name: matchedReference.name };
+  }
+
+  return { name };
+};
+
+/** Resolves cross-file symbol references from a merged symbol table. */
+export const createReferenceLocations = (
+  symbolTable: SymbolTable,
+  uri: string,
+  position: Position,
+  sourceText: string,
+): Location[] => {
+  const index = createSymbolLookupIndex(
+    symbolTable.definitions,
+    symbolTable.references,
+  );
+  const target = findTargetSymbol(
+    symbolTable,
+    index,
+    uri,
+    position,
+    sourceText,
+  );
+  if (!target) {
+    return [];
+  }
+
+  const lowerName = target.name.toLowerCase();
+  const definitionMatches = (
+    index.definitionsByName.get(lowerName) ?? []
+  ).filter((item) => {
+    if (!target.kind) {
+      return true;
+    }
+
+    return item.kind === target.kind;
+  });
+
+  const referenceMatches = (index.referencesByName.get(lowerName) ?? []).filter(
+    (item) => {
+      if (!target.kind) {
+        return true;
+      }
+
+      return item.kind === target.kind;
+    },
+  );
+
+  return dedupeLocations(
+    [...definitionMatches, ...referenceMatches].map(toLocation),
+  );
+};

package/src/server.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { startLspServer } from "./index.js";
+
+startLspServer();

package/src/shared.ts

@@ -0,0 +1,182 @@
+import {
+  CompletionItemKind,
+  SymbolKind,
+  type Range,
+  type Position,
+} from "vscode-languageserver/node.js";
+import type { BirdDeclaration, SourceRange } from "@birdcc/parser";
+import { HOVER_KEYWORD_DOCS } from "./hover-docs.js";
+
+const BASE_KEYWORD_DOCS: Record<string, string> = {
+  protocol: "Define a protocol instance. Example: `protocol bgp edge { ... }`.",
+  template: "Define a reusable protocol template.",
+  filter: "Define route filtering logic.",
+  function: "Define reusable logic callable from filters.",
+  define: "Define a reusable constant. Example: `define ASN = 65001;`.",
+  include: "Include another configuration file.",
+  table: "Define a routing table resource for protocol/channel usage.",
+  import: "Control import policy for routes.",
+  export: "Control export policy for routes.",
+  neighbor: "Configure protocol neighbor endpoint and ASN.",
+  "local as": "Configure local ASN via `local as <asn>;`.",
+  "router id": "Set explicit router ID or select from runtime source.",
+  ipv4: "IPv4 address family/channel/table scope keyword.",
+  ipv6: "IPv6 address family/channel/table scope keyword.",
+};
+
+export const KEYWORD_DOCS: Record<string, string> = {
+  ...BASE_KEYWORD_DOCS,
+  ...HOVER_KEYWORD_DOCS,
+};
+
+export interface LspDeclarationMetadata {
+  symbolName: string;
+  selectionRange: SourceRange;
+  symbolKind: SymbolKind;
+  detail: string;
+  hoverMarkdown: string;
+  completionLabel?: string;
+  completionKind?: CompletionItemKind;
+  completionDetail?: string;
+}
+
+export const toLspRange = (range: SourceRange): Range => ({
+  start: {
+    line: Math.max(range.line - 1, 0),
+    character: Math.max(range.column - 1, 0),
+  },
+  end: {
+    line: Math.max(range.endLine - 1, 0),
+    character: Math.max(range.endColumn - 1, 0),
+  },
+});
+
+export const isPositionInRange = (
+  position: Position,
+  range: SourceRange,
+): boolean => {
+  const line = position.line + 1;
+  const character = position.character + 1;
+
+  if (line < range.line || line > range.endLine) {
+    return false;
+  }
+
+  if (line === range.line && character < range.column) {
+    return false;
+  }
+
+  if (line === range.endLine && character > range.endColumn) {
+    return false;
+  }
+
+  return true;
+};
+
+export const declarationMetadata = (
+  declaration: BirdDeclaration,
+): LspDeclarationMetadata | null => {
+  const escapeMarkdownCode = (text: string): string =>
+    text.replaceAll("\\", "\\\\").replaceAll("`", "\\`");
+
+  switch (declaration.kind) {
+    case "protocol": {
+      const fromTemplate = declaration.fromTemplate
+        ? ` from \`${escapeMarkdownCode(declaration.fromTemplate)}\``
+        : "";
+      return {
+        symbolName: declaration.name,
+        selectionRange: declaration.nameRange,
+        symbolKind: SymbolKind.Module,
+        detail: `protocol ${declaration.protocolType}`,
+        hoverMarkdown: `**protocol** \`${escapeMarkdownCode(declaration.name)}\`\n\nType: \`${escapeMarkdownCode(declaration.protocolType)}\`${fromTemplate}`,
+        completionLabel: declaration.name,
+        completionKind: CompletionItemKind.Reference,
+        completionDetail: `protocol ${declaration.protocolType}`,
+      };
+    }
+    case "template":
+      return {
+        symbolName: declaration.name,
+        selectionRange: declaration.nameRange,
+        symbolKind: SymbolKind.Class,
+        detail: `template ${declaration.templateType}`,
+        hoverMarkdown: `**template** \`${escapeMarkdownCode(declaration.name)}\`\n\nType: \`${escapeMarkdownCode(declaration.templateType)}\``,
+        completionLabel: declaration.name,
+        completionKind: CompletionItemKind.Reference,
+        completionDetail: `template ${declaration.templateType}`,
+      };
+    case "filter":
+      return {
+        symbolName: declaration.name,
+        selectionRange: declaration.nameRange,
+        symbolKind: SymbolKind.Method,
+        detail: "filter",
+        hoverMarkdown: `**filter** \`${escapeMarkdownCode(declaration.name)}\``,
+        completionLabel: declaration.name,
+        completionKind: CompletionItemKind.Reference,
+        completionDetail: "filter",
+      };
+    case "function":
+      return {
+        symbolName: declaration.name,
+        selectionRange: declaration.nameRange,
+        symbolKind: SymbolKind.Function,
+        detail: "function",
+        hoverMarkdown: `**function** \`${escapeMarkdownCode(declaration.name)}\``,
+        completionLabel: declaration.name,
+        completionKind: CompletionItemKind.Reference,
+        completionDetail: "function",
+      };
+    case "define":
+      return {
+        symbolName: declaration.name,
+        selectionRange: declaration.nameRange,
+        symbolKind: SymbolKind.Constant,
+        detail: "define",
+        hoverMarkdown: `**define** \`${escapeMarkdownCode(declaration.name)}\``,
+        completionLabel: declaration.name,
+        completionKind: CompletionItemKind.Constant,
+        completionDetail: "define",
+      };
+    case "table":
+      return {
+        symbolName: declaration.name,
+        selectionRange: declaration.nameRange,
+        symbolKind: SymbolKind.Object,
+        detail: `table ${declaration.tableType}`,
+        hoverMarkdown: `**table** \`${escapeMarkdownCode(declaration.name)}\`\n\nType: \`${escapeMarkdownCode(declaration.tableType)}\``,
+        completionLabel: declaration.name,
+        completionKind: CompletionItemKind.Variable,
+        completionDetail: `table ${declaration.tableType}`,
+      };
+    case "include":
+      return {
+        symbolName: declaration.path,
+        selectionRange: declaration.pathRange,
+        symbolKind: SymbolKind.File,
+        detail: "include",
+        hoverMarkdown: `**include** \`${escapeMarkdownCode(declaration.path)}\``,
+        completionLabel: declaration.path,
+        completionKind: CompletionItemKind.File,
+        completionDetail: "include path",
+      };
+    case "router-id": {
+      const fromSource = declaration.fromSource
+        ? ` (${declaration.fromSource})`
+        : "";
+      return {
+        symbolName: `router id ${declaration.value}`,
+        selectionRange: declaration.valueRange,
+        symbolKind: SymbolKind.Property,
+        detail: `router-id ${declaration.valueKind}`,
+        hoverMarkdown: `**router id** \`${escapeMarkdownCode(declaration.value)}\`${fromSource}`,
+        completionLabel: `router id ${declaration.value}`,
+        completionKind: CompletionItemKind.Property,
+        completionDetail: `router id ${declaration.valueKind}`,
+      };
+    }
+    default:
+      return null;
+  }
+};