@birdcc/core 0.0.1-alpha.0 → 0.0.1-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@birdcc/core",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1-alpha.1",
   "private": false,
   "type": "module",
   "license": "GPL-3.0-only",
@@ -9,17 +9,24 @@
     "email": "npm-dev@birdcc.link",
     "url": "https://github.com/bird-chinese-community/"
   },
+  "description": "Semantic analysis core for BIRD2 configuration files.",
   "main": "./dist/index.js",
-  "types": "./src/index.ts",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     }
   },
+  "sideEffects": false,
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE"
+  ],
   "dependencies": {
     "fast-cidr-tools": "^0.3.4",
-    "@birdcc/parser": "0.0.1-alpha.0"
+    "@birdcc/parser": "0.0.1-alpha.1"
   },
   "devDependencies": {
     "mitata": "^1.0.34"

package/.oxfmtrc.json

@@ -1,16 +0,0 @@
-{
-  "$schema": "../../../node_modules/oxfmt/configuration_schema.json",
-  "ignorePatterns": [
-    "node_modules/*",
-    "package.json",
-    "dist/*",
-    ".turbo/*",
-    "target/*",
-    "*.lock",
-    "pnpm-*.yaml",
-    "*-lock.json"
-  ],
-  "printWidth": 80,
-  "tabWidth": 2,
-  "useTabs": false
-}

package/scripts/benchmark-node-vs-regex.js

@@ -1,86 +0,0 @@
-// Run: pnpm --filter @birdcc/core bench:ip-check
-
-import { bench, run, summary, barplot } from "mitata";
-import { isIP } from "node:net";
-
-// --- regex implementations ---
-// Validates each octet: 0-255, no leading zeros
-const IPv4_RE =
-  /^(25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)(\.(25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)){3}$/;
-
-// Covers all RFC 4291 compressed forms (::, ::1, 1::, fe80::1, etc.)
-// Zone ID (fe80::1%eth0) intentionally excluded — match node:net behavior = include it
-const IPv6_RE =
-  /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]+|::(ffff(:0{1,4})?:)?((25[0-5]|(2[0-4]|1?\d)?\d)\.){3}(25[0-5]|(2[0-4]|1?\d)?\d)|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1?\d)?\d)\.){3}(25[0-5]|(2[0-4]|1?\d)?\d))$/;
-
-/** Returns 4 | 6 | 0 — same contract as node:net isIP */
-const isIP_regex = (input) => {
-  if (IPv4_RE.test(input)) return 4;
-  if (IPv6_RE.test(input)) return 6;
-  return 0;
-};
-
-// --- test fixtures: mix of ipv4 / ipv6 / invalid ---
-const samples = [
-  "127.0.0.1", // valid ipv4
-  "192.168.1.255", // valid ipv4
-  "0.0.0.0", // valid ipv4
-  "255.255.255.255", // valid ipv4
-  "::1", // valid ipv6 loopback
-  "2001:db8::1", // valid ipv6
-  "fe80::1%eth0", // ipv6 with zone id  (isIP → 0, regex → 0)
-  "not-an-ip", // invalid
-  "127.000.000.001", // invalid (leading zeros)
-  "999.999.999.999", // invalid (out of range)
-];
-
-const parseSampleSize = (value) => {
-  const parsed = Number.parseInt(value ?? "", 10);
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    return 100000;
-  }
-  return parsed;
-};
-
-const sampleSize = parseSampleSize(process.env.BENCH_SAMPLE_SIZE);
-const samplePool = Array.from({ length: sampleSize }, (_, index) => {
-  return samples[index % samples.length];
-});
-
-// Sanity-check: both implementations must agree on every sample
-for (const s of samples) {
-  const r = isIP_regex(s);
-  const n = isIP(s);
-  if (r !== n) {
-    throw new Error(`[mismatch] "${s}" regex=${r} node=${n}`);
-  }
-}
-
-// --- benchmarks ---
-summary(() => {
-  barplot(() => {
-    bench("regex  · single sample (127.0.0.1)", () => isIP_regex("127.0.0.1"));
-    bench("node   · single sample (127.0.0.1)", () => isIP("127.0.0.1"));
-
-    bench("regex  · single sample (::1)", () => isIP_regex("::1"));
-    bench("node   · single sample (::1)", () => isIP("::1"));
-
-    bench("regex  · single sample (invalid)", () => isIP_regex("not-an-ip"));
-    bench("node   · single sample (invalid)", () => isIP("not-an-ip"));
-
-    bench("regex  · 10-sample mixed loop", () => {
-      for (const s of samples) isIP_regex(s);
-    });
-    bench("node   · 10-sample mixed loop", () => {
-      for (const s of samples) isIP(s);
-    });
-    bench(`regex  · ${sampleSize}-sample deterministic loop`, () => {
-      for (const s of samplePool) isIP_regex(s);
-    });
-    bench(`node   · ${sampleSize}-sample deterministic loop`, () => {
-      for (const s of samplePool) isIP(s);
-    });
-  });
-});
-
-await run();

package/src/cross-file.ts

@@ -1,412 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { dirname, isAbsolute, normalize, relative, resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import type { ParsedBirdDocument, SourceRange } from "@birdcc/parser";
-import { parseBirdConfig } from "@birdcc/parser";
-import type {
-  BirdDiagnostic,
-  CoreSnapshot,
-  CrossFileResolveOptions,
-  CrossFileResolutionResult,
-  CrossFileResolutionStats,
-  SymbolTable,
-} from "./types.js";
-import { buildCoreSnapshotFromParsed } from "./snapshot.js";
-import {
-  mergeSymbolTables,
-  pushSymbolTableDiagnostics,
-} from "./symbol-table.js";
-import { collectCircularTemplateDiagnostics } from "./template-cycles.js";
-
-export const DEFAULT_CROSS_FILE_MAX_DEPTH = 16;
-export const DEFAULT_CROSS_FILE_MAX_FILES = 256;
-
-const PARSED_DOCUMENT_CACHE_LIMIT = 512;
-const parsedDocumentCache = new Map<
-  string,
-  { text: string; parsed: ParsedBirdDocument }
->();
-
-const DEFAULT_RANGE = {
-  line: 1,
-  column: 1,
-  endLine: 1,
-  endColumn: 1,
-} as const;
-
-const isFileUri = (uri: string): boolean => uri.startsWith("file://");
-
-const toFilePath = (uri: string): string | null => {
-  if (isFileUri(uri)) {
-    return fileURLToPath(uri);
-  }
-
-  if (uri.startsWith("/")) {
-    return uri;
-  }
-
-  return null;
-};
-
-const normalizeUriForPrefixMatch = (uri: string): string =>
-  uri.replace(/\/+$/, "");
-
-const toDefaultWorkspaceRootUri = (entryUri: string): string => {
-  const entryPath = toFilePath(entryUri);
-  if (entryPath) {
-    return pathToFileURL(dirname(entryPath)).toString();
-  }
-
-  return normalize(dirname(entryUri));
-};
-
-const isWithinWorkspaceRoot = (
-  candidateUri: string,
-  workspaceRootUri: string,
-): boolean => {
-  const candidatePath = toFilePath(candidateUri);
-  const workspaceRootPath = toFilePath(workspaceRootUri);
-
-  if (candidatePath && workspaceRootPath) {
-    const resolvedRoot = normalize(workspaceRootPath);
-    const resolvedCandidate = normalize(candidatePath);
-    const relPath = relative(resolvedRoot, resolvedCandidate);
-
-    return (
-      relPath.length === 0 ||
-      (!relPath.startsWith("..") && !isAbsolute(relPath))
-    );
-  }
-
-  const normalizedRoot = normalizeUriForPrefixMatch(
-    normalize(workspaceRootUri),
-  );
-  const normalizedCandidate = normalizeUriForPrefixMatch(
-    normalize(candidateUri),
-  );
-  return (
-    normalizedCandidate === normalizedRoot ||
-    normalizedCandidate.startsWith(`${normalizedRoot}/`)
-  );
-};
-
-const defaultReadFileText = async (uri: string): Promise<string> => {
-  const filePath = toFilePath(uri);
-  if (!filePath) {
-    throw new Error(`Unsupported non-file URI '${uri}'`);
-  }
-
-  return readFile(filePath, "utf8");
-};
-
-const resolveIncludeUri = (baseUri: string, includePath: string): string => {
-  if (includePath.startsWith("file://")) {
-    return pathToFileURL(normalize(fileURLToPath(includePath))).toString();
-  }
-
-  if (isFileUri(baseUri)) {
-    const basePath = fileURLToPath(baseUri);
-    const resolvedPath = resolve(dirname(basePath), includePath);
-    return pathToFileURL(resolvedPath).toString();
-  }
-
-  return normalize(resolve(dirname(baseUri), includePath));
-};
-
-const includeDiagnostic = (
-  uri: string,
-  message: string,
-  range: SourceRange = DEFAULT_RANGE,
-): BirdDiagnostic => ({
-  code: "semantic/missing-include",
-  message,
-  severity: "warning",
-  source: "core",
-  uri,
-  range: {
-    line: range.line,
-    column: range.column,
-    endLine: range.endLine,
-    endColumn: range.endColumn,
-  },
-});
-
-const dedupeDiagnostics = (diagnostics: BirdDiagnostic[]): BirdDiagnostic[] => {
-  const seen = new Set<string>();
-  const output: BirdDiagnostic[] = [];
-
-  for (const diagnostic of diagnostics) {
-    const key = [
-      diagnostic.code,
-      diagnostic.message,
-      diagnostic.uri ?? "",
-      diagnostic.range.line,
-      diagnostic.range.column,
-      diagnostic.range.endLine,
-      diagnostic.range.endColumn,
-    ].join(":");
-
-    if (seen.has(key)) {
-      continue;
-    }
-
-    seen.add(key);
-    output.push(diagnostic);
-  }
-
-  return output;
-};
-
-const parseDocumentWithCache = async (
-  uri: string,
-  text: string,
-  stats: CrossFileResolutionStats,
-): Promise<ParsedBirdDocument> => {
-  const cached = parsedDocumentCache.get(uri);
-  if (cached && cached.text === text) {
-    stats.parsedCacheHits += 1;
-    return cached.parsed;
-  }
-
-  stats.parsedCacheMisses += 1;
-  const parsed = await parseBirdConfig(text);
-
-  if (parsedDocumentCache.size >= PARSED_DOCUMENT_CACHE_LIMIT) {
-    const oldestKey = parsedDocumentCache.keys().next().value;
-    if (oldestKey) {
-      parsedDocumentCache.delete(oldestKey);
-    }
-  }
-
-  parsedDocumentCache.set(uri, { text, parsed });
-  return parsed;
-};
-
-interface QueueItem {
-  uri: string;
-  depth: number;
-}
-
-export const resolveCrossFileReferences = async (
-  options: CrossFileResolveOptions,
-): Promise<CrossFileResolutionResult> => {
-  const maxDepth = options.maxDepth ?? DEFAULT_CROSS_FILE_MAX_DEPTH;
-  const maxFiles = options.maxFiles ?? DEFAULT_CROSS_FILE_MAX_FILES;
-  const loadFromFileSystem = options.loadFromFileSystem ?? true;
-  const readFileText = options.readFileText ?? defaultReadFileText;
-  const workspaceRootUri =
-    options.workspaceRootUri ?? toDefaultWorkspaceRootUri(options.entryUri);
-  const allowIncludeOutsideWorkspace =
-    options.allowIncludeOutsideWorkspace ?? false;
-
-  const stats: CrossFileResolutionStats = {
-    loadedFromMemory: options.documents?.length ?? 0,
-    loadedFromFileSystem: 0,
-    skippedByDepth: 0,
-    skippedByFileLimit: 0,
-    missingIncludes: 0,
-    parsedCacheHits: 0,
-    parsedCacheMisses: 0,
-  };
-
-  const documentMap = new Map(
-    (options.documents ?? []).map((document) => [
-      document.uri,
-      { uri: document.uri, text: document.text },
-    ]),
-  );
-  const parsedDocuments = new Map<string, ParsedBirdDocument>();
-  const snapshots: Record<string, CoreSnapshot> = {};
-  const queue: QueueItem[] = [{ uri: options.entryUri, depth: 0 }];
-  const queued = new Set<string>([options.entryUri]);
-  const visited = new Set<string>();
-  const diagnostics: BirdDiagnostic[] = [];
-
-  const ensureDocument = async (uri: string): Promise<boolean> => {
-    if (documentMap.has(uri)) {
-      return true;
-    }
-
-    if (!loadFromFileSystem) {
-      return false;
-    }
-
-    try {
-      const text = await readFileText(uri);
-      documentMap.set(uri, { uri, text });
-      stats.loadedFromFileSystem += 1;
-      return true;
-    } catch {
-      return false;
-    }
-  };
-
-  if (!(await ensureDocument(options.entryUri))) {
-    return {
-      entryUri: options.entryUri,
-      visitedUris: [],
-      symbolTable: { definitions: [], references: [] },
-      snapshots: {},
-      documents: {},
-      diagnostics: [
-        includeDiagnostic(
-          options.entryUri,
-          `Entry file not found or not readable: '${options.entryUri}'`,
-        ),
-      ],
-      stats,
-    };
-  }
-
-  while (queue.length > 0) {
-    const current = queue.shift();
-    if (!current) {
-      break;
-    }
-
-    if (visited.has(current.uri)) {
-      continue;
-    }
-
-    if (current.depth > maxDepth) {
-      stats.skippedByDepth += 1;
-      continue;
-    }
-
-    if (visited.size >= maxFiles) {
-      stats.skippedByFileLimit += 1;
-      diagnostics.push(
-        includeDiagnostic(
-          current.uri,
-          `Cross-file analysis stopped after reaching max files limit (${maxFiles})`,
-        ),
-      );
-      break;
-    }
-
-    visited.add(current.uri);
-
-    const document = documentMap.get(current.uri);
-    if (!document) {
-      continue;
-    }
-
-    const parsed = await parseDocumentWithCache(
-      current.uri,
-      document.text,
-      stats,
-    );
-    parsedDocuments.set(current.uri, parsed);
-    snapshots[current.uri] = buildCoreSnapshotFromParsed(parsed, {
-      uri: current.uri,
-      typeCheck: options.typeCheck,
-    });
-
-    for (const declaration of parsed.program.declarations) {
-      if (declaration.kind !== "include" || declaration.path.length === 0) {
-        continue;
-      }
-
-      const includeUri = resolveIncludeUri(current.uri, declaration.path);
-      const includeRange = declaration.pathRange;
-
-      if (
-        !allowIncludeOutsideWorkspace &&
-        !isWithinWorkspaceRoot(includeUri, workspaceRootUri)
-      ) {
-        diagnostics.push(
-          includeDiagnostic(
-            current.uri,
-            `Include skipped outside workspace root '${workspaceRootUri}': '${declaration.path}'`,
-            includeRange,
-          ),
-        );
-        continue;
-      }
-
-      if (visited.has(includeUri) || queued.has(includeUri)) {
-        continue;
-      }
-
-      if (current.depth + 1 > maxDepth) {
-        stats.skippedByDepth += 1;
-        diagnostics.push(
-          includeDiagnostic(
-            current.uri,
-            `Include skipped due to max depth (${maxDepth}): '${declaration.path}'`,
-            includeRange,
-          ),
-        );
-        continue;
-      }
-
-      if (visited.size + queue.length >= maxFiles) {
-        stats.skippedByFileLimit += 1;
-        diagnostics.push(
-          includeDiagnostic(
-            current.uri,
-            `Include skipped due to max files limit (${maxFiles}): '${declaration.path}'`,
-            includeRange,
-          ),
-        );
-        continue;
-      }
-
-      const loaded = await ensureDocument(includeUri);
-      if (!loaded) {
-        stats.missingIncludes += 1;
-        diagnostics.push(
-          includeDiagnostic(
-            current.uri,
-            `Included file not found in workspace: '${declaration.path}'`,
-            includeRange,
-          ),
-        );
-        continue;
-      }
-
-      queue.push({ uri: includeUri, depth: current.depth + 1 });
-      queued.add(includeUri);
-    }
-  }
-
-  const mergedSymbolTable: SymbolTable = mergeSymbolTables(
-    Object.values(snapshots).map((snapshot) => snapshot.symbolTable),
-  );
-  pushSymbolTableDiagnostics(mergedSymbolTable, diagnostics);
-
-  for (const [uri, snapshot] of Object.entries(snapshots)) {
-    for (const diagnostic of snapshot.diagnostics) {
-      if (
-        diagnostic.code === "semantic/duplicate-definition" ||
-        diagnostic.code === "semantic/undefined-reference" ||
-        diagnostic.code === "semantic/circular-template"
-      ) {
-        continue;
-      }
-
-      diagnostics.push({
-        ...diagnostic,
-        uri,
-      });
-    }
-  }
-
-  diagnostics.push(
-    ...collectCircularTemplateDiagnostics(
-      [...parsedDocuments.entries()].map(([uri, parsed]) => ({ uri, parsed })),
-    ),
-  );
-
-  return {
-    entryUri: options.entryUri,
-    visitedUris: [...visited],
-    symbolTable: mergedSymbolTable,
-    snapshots,
-    documents: Object.fromEntries(
-      [...documentMap.entries()].map(([uri, document]) => [uri, document.text]),
-    ),
-    diagnostics: dedupeDiagnostics(diagnostics),
-    stats,
-  };
-};

package/src/index.ts

@@ -1,42 +0,0 @@
-import { parseBirdConfig } from "@birdcc/parser";
-import { resolveCrossFileReferences } from "./cross-file.js";
-import { buildCoreSnapshotFromParsed } from "./snapshot.js";
-
-export type {
-  BirdDiagnostic,
-  BirdDiagnosticSeverity,
-  BirdRange,
-  BirdSymbolKind,
-  CoreSnapshot,
-  CrossFileDocumentInput,
-  CrossFileResolveOptions,
-  CrossFileResolutionResult,
-  CrossFileResolutionStats,
-  SymbolDefinition,
-  SymbolReference,
-  SymbolTable,
-  TypeCheckOptions,
-  TypeValue,
-} from "./types.js";
-
-export { checkTypes } from "./type-checker.js";
-export {
-  DEFAULT_DOCUMENT_URI,
-  buildSymbolTableFromParsed,
-  mergeSymbolTables,
-  pushSymbolTableDiagnostics,
-} from "./symbol-table.js";
-export { buildCoreSnapshotFromParsed } from "./snapshot.js";
-export {
-  DEFAULT_CROSS_FILE_MAX_DEPTH,
-  DEFAULT_CROSS_FILE_MAX_FILES,
-  resolveCrossFileReferences,
-} from "./cross-file.js";
-
-/** Parses and builds semantic snapshot in one async call. */
-export const buildCoreSnapshot = async (text: string) => {
-  const parsed = await parseBirdConfig(text);
-  return buildCoreSnapshotFromParsed(parsed);
-};
-
-export type ResolveCrossFileReferences = typeof resolveCrossFileReferences;

package/src/prefix.ts

@@ -1,94 +0,0 @@
-import { isIP } from "node:net";
-import { parse as parseCidr } from "fast-cidr-tools";
-
-const parsePrefixRange = (
-  suffix: string,
-): { min: number; max: number } | null => {
-  if (!suffix.startsWith("{") || !suffix.endsWith("}")) {
-    return null;
-  }
-
-  const inner = suffix.slice(1, -1);
-  const commaIndex = inner.indexOf(",");
-  if (commaIndex <= 0 || commaIndex >= inner.length - 1) {
-    return null;
-  }
-
-  const min = Number(inner.slice(0, commaIndex));
-  const max = Number(inner.slice(commaIndex + 1));
-
-  if (!Number.isInteger(min) || !Number.isInteger(max)) {
-    return null;
-  }
-
-  return { min, max };
-};
-
-export const isValidPrefixLiteral = (literal: string): boolean => {
-  let value = literal.trim();
-  if (value.length === 0) {
-    return false;
-  }
-
-  let range: { min: number; max: number } | null = null;
-
-  if (value.endsWith("+")) {
-    value = value.slice(0, -1);
-  } else if (value.endsWith("-")) {
-    value = value.slice(0, -1);
-  } else if (value.endsWith("}")) {
-    const braceStart = value.lastIndexOf("{");
-    if (braceStart === -1) {
-      return false;
-    }
-
-    range = parsePrefixRange(value.slice(braceStart));
-    if (!range) {
-      return false;
-    }
-
-    value = value.slice(0, braceStart);
-  }
-
-  const slashIndex = value.lastIndexOf("/");
-  if (slashIndex <= 0 || slashIndex >= value.length - 1) {
-    return false;
-  }
-
-  const ipPart = value.slice(0, slashIndex);
-  const prefixPart = value.slice(slashIndex + 1);
-  const prefix = Number(prefixPart);
-
-  if (!Number.isInteger(prefix)) {
-    return false;
-  }
-
-  const version = isIP(ipPart);
-  if (version === 0) {
-    return false;
-  }
-
-  const maxBits = version === 4 ? 32 : 128;
-  if (prefix < 0 || prefix > maxBits) {
-    return false;
-  }
-
-  if (range) {
-    if (
-      range.min < prefix ||
-      range.min > maxBits ||
-      range.max < range.min ||
-      range.max > maxBits
-    ) {
-      return false;
-    }
-  }
-
-  try {
-    void parseCidr(value);
-  } catch {
-    return false;
-  }
-
-  return true;
-};

package/src/range.ts

@@ -1,12 +0,0 @@
-import type { BirdRange } from "./types.js";
-
-export const createRange = (
-  line: number,
-  column: number,
-  nameLength = 1,
-): BirdRange => ({
-  line,
-  column,
-  endLine: line,
-  endColumn: column + Math.max(nameLength, 1),
-});