@lexbuild/core

Shared infrastructure for the LexBuild legal-XML-to-Markdown pipeline. Provides streaming XML parsing, AST definitions, Markdown rendering, YAML frontmatter generation, and cross-reference link resolution used by all source packages.

Note: This is a foundational library. Most users should install @lexbuild/cli for the command-line tool, or a source package (@lexbuild/usc, @lexbuild/ecfr, @lexbuild/fr) for programmatic access.

Install

npm install @lexbuild/core
# or
pnpm add @lexbuild/core

Quick Start

import { XMLParser, ASTBuilder, renderDocument, generateFrontmatter, createLinkResolver } from "@lexbuild/core";
import { createReadStream } from "node:fs";

// 1. Parse XML via streaming SAX
const parser = new XMLParser();
const builder = new ASTBuilder({
  emitAt: "section",
  onEmit: (node, context) => {
    // 2. Each completed section is emitted here
    const frontmatter = generateFrontmatter(/* ... */);
    const resolver = createLinkResolver("relative");
    const markdown = renderDocument(node, frontmatter, {
      linkStyle: "relative",
      resolveLink: resolver.resolve,
    });
    // 3. Write markdown to file
  },
});

parser.on("openElement", (name, attrs) => builder.onOpenElement(name, attrs));
parser.on("closeElement", (name) => builder.onCloseElement(name));
parser.on("text", (text) => builder.onText(text));

await parser.parseStream(createReadStream("usc01.xml"));

Multi-Level Emit

emitAt also accepts a ReadonlySet<LevelType>. Deeper levels fire first (sections before their containing title), and emitted nodes remain attached to their parents so a higher-level emission sees the full subtree. Attach-to-parent is gated by "any enclosing stack frame is itself an emit target" — do not reason via LEVEL_TYPES index ordering, which breaks on USLM's permissive nesting (e.g. an appendix inside a part).

const byLevel = new Map<LevelType, LevelNode[]>();

const builder = new ASTBuilder({
  emitAt: new Set(["section", "chapter", "title"]),
  onEmit: (node, context) => {
    const bucket = byLevel.get(node.levelType) ?? [];
    bucket.push(node);
    byLevel.set(node.levelType, bucket);
  },
});

This is how the @lexbuild/usc and @lexbuild/ecfr converters produce multiple output granularities from a single parse.

API Reference

XML Parsing

| Export | Description | |--------|-------------| | XMLParser | Streaming SAX parser wrapping saxes with namespace normalization. Supports USLM (namespaced) and namespace-free XML (eCFR) via the defaultNamespace option. |

AST Builder

| Export | Description | |--------|-------------| | ASTBuilder | Stack-based USLM XML-to-AST builder with configurable emit-at-level streaming. emitAt accepts LevelType (single) or ReadonlySet<LevelType> (multi-level emit). Handles the full USLM 1.0 element vocabulary. Source packages for other formats provide their own builders. |

Rendering

| Export | Description | |--------|-------------| | renderDocument() | Render a section node with frontmatter to a complete Markdown file | | renderSection() | Render a section-level node to Markdown body text | | renderNode() | Render any AST node to Markdown | | generateFrontmatter() | Generate a YAML frontmatter block from FrontmatterData | | createLinkResolver() | Create a cross-reference link resolver supporting USC, CFR, and fallback URLs |

Types

| Export | Description | |--------|-------------| | ASTNode | Union type for all AST nodes | | LevelNode | Hierarchical structural node (title, chapter, section, etc.) | | ContentNode | Text content block (content, chapeau, continuation, proviso) | | InlineNode | Inline text formatting (bold, italic, ref, footnoteRef, etc.) | | NoteNode | Note block (editorial, statutory, amendment, etc.) | | TableNode | Table with headers and rows | | SourceCreditNode | Enactment source citation | | FrontmatterData | Full frontmatter field definitions | | EmitContext | Context passed with emitted nodes (ancestors, document metadata) | | SourceType | "usc" \| "ecfr" \| "fr" | | LegalStatus | "official_legal_evidence" \| "official_prima_facie" \| "authoritative_unofficial" |

Constants

| Export | Description | |--------|-------------| | FORMAT_VERSION | Output format version ("1.1.0") | | GENERATOR | Generator string for frontmatter metadata | | LEVEL_TYPES | Ordered array of level types (title → subsubitem) | | BIG_LEVELS | Set of structural levels above section | | USLM_NS | USLM namespace URI | | XHTML_NS | XHTML namespace URI |

File System Utilities

| Export | Description | |--------|-------------| | writeFile() | Write with ENFILE/EMFILE retry and exponential backoff | | writeFileIfChanged() | Write only if content differs. Returns true if written, false if skipped (mtime preserved). Used by converters for incremental updates. | | mkdir() | Recursive mkdir with retry |

Compatibility

• Node.js >= 22
• ESM only — no CommonJS build
• TypeScript — ships .d.ts type declarations
• Zero browser dependencies — Node.js runtime only

Monorepo Context

This package is part of the LexBuild monorepo, managed with Turborepo and pnpm workspaces. All packages use changesets for lockstep versioning.

packages/
├── core/    ← you are here
├── usc/     # depends on core
├── ecfr/    # depends on core
├── fr/      # depends on core
└── cli/     # depends on core, usc, ecfr, fr

Development

pnpm turbo build --filter=@lexbuild/core   # Build
pnpm turbo test --filter=@lexbuild/core    # Run tests
pnpm turbo typecheck --filter=@lexbuild/core
pnpm turbo lint --filter=@lexbuild/core

Related Packages

| Package | Description | |---------|-------------| | @lexbuild/cli | CLI tool for downloading and converting legal XML | | @lexbuild/usc | U.S. Code (USLM XML) converter and downloader | | @lexbuild/ecfr | eCFR (Code of Federal Regulations) converter and downloader | | @lexbuild/fr | Federal Register converter and downloader |

License

MIT