@lexbuild/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,525 @@
+import { Readable } from 'node:stream';
+
+/**
+ * Streaming XML parser wrapping saxes with typed events and namespace normalization.
+ */
+
+/** Normalized attributes: a flat record of name → value */
+type Attributes = Record<string, string>;
+/** Events emitted by the XML parser */
+interface ParserEvents {
+    /** An element was opened */
+    openElement: (name: string, attrs: Attributes, ns: string) => void;
+    /** An element was closed */
+    closeElement: (name: string, ns: string) => void;
+    /** Text content was encountered */
+    text: (content: string) => void;
+    /** An error occurred during parsing */
+    error: (err: Error) => void;
+    /** Parsing is complete */
+    end: () => void;
+}
+/** Configuration for the XML parser */
+interface XMLParserOptions {
+    /** Namespace URI to treat as default (elements in this NS emit bare names) */
+    defaultNamespace?: string | undefined;
+    /** Additional namespace prefix mappings beyond the built-in ones */
+    namespacePrefixes?: Readonly<Record<string, string>> | undefined;
+}
+type EventName = keyof ParserEvents;
+type EventHandler<K extends EventName> = ParserEvents[K];
+/**
+ * Streaming XML parser that normalizes namespace-prefixed element names.
+ *
+ * Elements in the default namespace emit bare names (e.g., "section").
+ * Elements in other recognized namespaces emit prefixed names (e.g., "xhtml:table").
+ * Elements in unrecognized namespaces emit the full URI-prefixed name.
+ */
+declare class XMLParser {
+    private readonly saxParser;
+    private readonly defaultNs;
+    private readonly prefixMap;
+    private readonly listeners;
+    constructor(options?: XMLParserOptions);
+    /**
+     * Register an event listener.
+     */
+    on<K extends EventName>(event: K, handler: EventHandler<K>): this;
+    /**
+     * Parse a complete XML string.
+     */
+    parseString(xml: string): void;
+    /**
+     * Parse from a readable stream (e.g., fs.createReadStream).
+     * Returns a promise that resolves when parsing is complete.
+     */
+    parseStream(stream: Readable): Promise<void>;
+    /**
+     * Normalize an element name based on its namespace.
+     * Default namespace elements get bare names; others get prefixed.
+     */
+    private normalizeName;
+    /**
+     * Normalize saxes namespace-aware attributes to a flat record.
+     * Strips namespace prefixes from attribute names for simplicity,
+     * except for xmlns declarations which are dropped entirely.
+     */
+    private normalizeAttributes;
+    /**
+     * Emit an event to all registered listeners.
+     */
+    private emit;
+}
+
+/**
+ * USLM XML namespace constants and element classification utilities.
+ */
+/** USLM 1.0 default namespace */
+declare const USLM_NS = "http://xml.house.gov/schemas/uslm/1.0";
+/** XHTML namespace (used for tables) */
+declare const XHTML_NS = "http://www.w3.org/1999/xhtml";
+/** Dublin Core elements namespace */
+declare const DC_NS = "http://purl.org/dc/elements/1.1/";
+/** Dublin Core terms namespace */
+declare const DCTERMS_NS = "http://purl.org/dc/terms/";
+/** XML Schema Instance namespace */
+declare const XSI_NS = "http://www.w3.org/2001/XMLSchema-instance";
+/**
+ * Prefix map for recognized non-default namespaces.
+ * Elements in these namespaces will be emitted with the prefix (e.g., "dc:title").
+ */
+declare const NAMESPACE_PREFIXES: Readonly<Record<string, string>>;
+/** USLM elements that represent hierarchical levels */
+declare const LEVEL_ELEMENTS: Set<string>;
+/** USLM elements that represent content blocks */
+declare const CONTENT_ELEMENTS: Set<string>;
+/** USLM elements that represent inline formatting */
+declare const INLINE_ELEMENTS: Set<string>;
+/** USLM note-related elements */
+declare const NOTE_ELEMENTS: Set<string>;
+/** USLM elements that act as levels in appendix contexts */
+declare const APPENDIX_LEVEL_ELEMENTS: Set<string>;
+/** USLM metadata elements inside <meta> */
+declare const META_ELEMENTS: Set<string>;
+/** Structural container elements (no direct content) */
+declare const CONTAINER_ELEMENTS: Set<string>;
+
+/**
+ * @lexbuild/core AST node types
+ *
+ * The intermediate AST is a semantic representation of parsed USLM XML.
+ * It is NOT a 1:1 mapping — it has been partially interpreted to simplify rendering.
+ */
+/** All hierarchical levels in the USLM schema, ordered big → small */
+declare const LEVEL_TYPES: readonly ["title", "appendix", "subtitle", "chapter", "subchapter", "compiledAct", "reorganizationPlans", "reorganizationPlan", "courtRules", "courtRule", "article", "subarticle", "part", "subpart", "division", "subdivision", "preliminary", "section", "subsection", "paragraph", "subparagraph", "clause", "subclause", "item", "subitem", "subsubitem"];
+/** A USLM hierarchical level type */
+type LevelType = (typeof LEVEL_TYPES)[number];
+/** Big levels: above section in the hierarchy */
+declare const BIG_LEVELS: Set<"title" | "subtitle" | "chapter" | "subchapter" | "article" | "subarticle" | "part" | "subpart" | "division" | "subdivision" | "preliminary" | "section" | "subsection" | "paragraph" | "subparagraph" | "clause" | "subclause" | "item" | "subitem" | "subsubitem" | "appendix" | "compiledAct" | "reorganizationPlans" | "reorganizationPlan" | "courtRules" | "courtRule">;
+/** Small levels: below section in the hierarchy */
+declare const SMALL_LEVELS: Set<"title" | "subtitle" | "chapter" | "subchapter" | "article" | "subarticle" | "part" | "subpart" | "division" | "subdivision" | "preliminary" | "section" | "subsection" | "paragraph" | "subparagraph" | "clause" | "subclause" | "item" | "subitem" | "subsubitem" | "appendix" | "compiledAct" | "reorganizationPlans" | "reorganizationPlan" | "courtRules" | "courtRule">;
+/** Base node all AST nodes extend */
+interface BaseNode {
+    /** Discriminator for the node type */
+    readonly type: string;
+    /** USLM identifier if present (e.g., "/us/usc/t1/s1") */
+    identifier?: string | undefined;
+    /** Source XML element name for debugging */
+    sourceElement?: string | undefined;
+}
+/** A hierarchical level (title, chapter, section, subsection, etc.) */
+interface LevelNode extends BaseNode {
+    readonly type: "level";
+    /** Which level in the USLM hierarchy */
+    levelType: LevelType;
+    /** Display text of the number (e.g., "§ 1.", "(a)", "CHAPTER 1—") */
+    num?: string | undefined;
+    /** Normalized value of the number (e.g., "1", "a") */
+    numValue?: string | undefined;
+    /** Heading text (e.g., "Words denoting number, gender, and so forth") */
+    heading?: string | undefined;
+    /** Legal status of this element (e.g., "repealed", "transferred") */
+    status?: string | undefined;
+    /** Child nodes */
+    children: ASTNode[];
+}
+/** Variant of a content block */
+type ContentVariant = "content" | "chapeau" | "continuation" | "proviso";
+/** A block of text content */
+interface ContentNode extends BaseNode {
+    readonly type: "content";
+    /** What kind of content block this is */
+    variant: ContentVariant;
+    /** Inline children (text, formatting, refs) */
+    children: InlineNode[];
+}
+/** Discriminator for inline node types */
+type InlineType = "text" | "bold" | "italic" | "ref" | "date" | "term" | "quoted" | "sup" | "sub" | "footnoteRef";
+/** Inline text or formatting */
+interface InlineNode extends BaseNode {
+    readonly type: "inline";
+    /** What kind of inline this is */
+    inlineType: InlineType;
+    /** Text content (for leaf text nodes) */
+    text?: string | undefined;
+    /** Link target (for ref nodes) */
+    href?: string | undefined;
+    /** Footnote target ID (for footnoteRef nodes) */
+    idref?: string | undefined;
+    /** Nested inline children */
+    children?: InlineNode[] | undefined;
+}
+/** A note (editorial, statutory, amendment, etc.) */
+interface NoteNode extends BaseNode {
+    readonly type: "note";
+    /** Semantic category (e.g., "amendments", "codification") */
+    topic?: string | undefined;
+    /** Role refinement (e.g., "crossHeading") */
+    role?: string | undefined;
+    /** Note placement type (e.g., "uscNote", "footnote") */
+    noteType?: string | undefined;
+    /** Heading text of the note */
+    heading?: string | undefined;
+    /** Child nodes */
+    children: ASTNode[];
+}
+/** Source credit annotation */
+interface SourceCreditNode extends BaseNode {
+    readonly type: "sourceCredit";
+    /** The full source credit text, including inline formatting */
+    children: InlineNode[];
+}
+/** Table (either XHTML or USLM layout-based) */
+interface TableNode extends BaseNode {
+    readonly type: "table";
+    /** Which table model */
+    variant: "xhtml" | "layout";
+    /** Header rows (each row is an array of cell strings) */
+    headers: string[][];
+    /** Body rows */
+    rows: string[][];
+    /** Raw HTML for complex tables that can't be simplified to rows/columns */
+    rawHtml?: string | undefined;
+}
+/** A single TOC entry */
+interface TOCItemNode extends BaseNode {
+    readonly type: "tocItem";
+    /** Section/chapter number */
+    number?: string | undefined;
+    /** Title or heading text */
+    title?: string | undefined;
+    /** Link target identifier */
+    href?: string | undefined;
+}
+/** Table of contents */
+interface TOCNode extends BaseNode {
+    readonly type: "toc";
+    /** TOC entries */
+    items: TOCItemNode[];
+}
+/** Container for notes (wraps <notes type="uscNote">) */
+interface NotesContainerNode extends BaseNode {
+    readonly type: "notesContainer";
+    /** The notes type attribute (e.g., "uscNote") */
+    notesType?: string | undefined;
+    /** Child note nodes */
+    children: (NoteNode | ASTNode)[];
+}
+/** Quoted content (blockquote) */
+interface QuotedContentNode extends BaseNode {
+    readonly type: "quotedContent";
+    /** Where the quote originates from */
+    origin?: string | undefined;
+    /** Content of the quotation */
+    children: ASTNode[];
+}
+/** Union of all AST node types */
+type ASTNode = LevelNode | ContentNode | InlineNode | NoteNode | SourceCreditNode | TableNode | TOCNode | TOCItemNode | NotesContainerNode | QuotedContentNode;
+/** Info about an ancestor level in the hierarchy */
+interface AncestorInfo {
+    /** The level type (e.g., "title", "chapter") */
+    levelType: LevelType;
+    /** Normalized number value */
+    numValue?: string | undefined;
+    /** Heading text */
+    heading?: string | undefined;
+    /** USLM identifier */
+    identifier?: string | undefined;
+}
+/** Document-level metadata extracted from the <meta> block */
+interface DocumentMeta {
+    /** dc:title — display title (e.g., "Title 1") */
+    dcTitle?: string | undefined;
+    /** dc:type — document type (e.g., "USCTitle") */
+    dcType?: string | undefined;
+    /** docNumber — numeric designation (e.g., "1") */
+    docNumber?: string | undefined;
+    /** docPublicationName — publication name */
+    docPublicationName?: string | undefined;
+    /** Release point identifier (e.g., "119-73") */
+    releasePoint?: string | undefined;
+    /** Whether this is positive law */
+    positivelaw?: boolean | undefined;
+    /** dc:publisher */
+    publisher?: string | undefined;
+    /** dcterms:created — ISO timestamp */
+    created?: string | undefined;
+    /** dc:creator — generator tool name */
+    creator?: string | undefined;
+    /** The root document identifier (e.g., "/us/usc/t1") */
+    identifier?: string | undefined;
+}
+/** Context provided when a completed section/chapter is emitted */
+interface EmitContext {
+    /** Ancestor chain from document root to the emitted node's parent */
+    ancestors: AncestorInfo[];
+    /** Document-level metadata from the <meta> block */
+    documentMeta: DocumentMeta;
+}
+/** Data used to generate YAML frontmatter for a section file */
+interface FrontmatterData {
+    /** USLM canonical identifier (e.g., "/us/usc/t1/s1") */
+    identifier: string;
+    /** Human-readable display title (e.g., "1 USC § 1 - Words denoting...") */
+    title: string;
+    /** Title number (integer) */
+    title_number: number;
+    /** Title name (e.g., "General Provisions") */
+    title_name: string;
+    /** Chapter number (integer, omitted if not applicable) */
+    chapter_number?: number | undefined;
+    /** Chapter name */
+    chapter_name?: string | undefined;
+    /** Subchapter identifier (often Roman numerals) */
+    subchapter_number?: string | undefined;
+    /** Subchapter name */
+    subchapter_name?: string | undefined;
+    /** Part identifier */
+    part_number?: string | undefined;
+    /** Part name */
+    part_name?: string | undefined;
+    /** Section number (string — can be alphanumeric like "7801") */
+    section_number: string;
+    /** Section name */
+    section_name: string;
+    /** Whether this title is positive law */
+    positive_law: boolean;
+    /** Full source credit text */
+    source_credit?: string | undefined;
+    /** Release point identifier (e.g., "119-73") */
+    currency: string;
+    /** ISO date from XML generation timestamp */
+    last_updated: string;
+    /** Section status (e.g., "repealed", "transferred") */
+    status?: string | undefined;
+}
+
+/**
+ * AST Builder — converts XML parser events into an AST tree.
+ *
+ * Implements the section-emit pattern: when a section (or other configured level)
+ * close tag is encountered, the completed LevelNode is emitted via callback
+ * and its subtree is released from memory.
+ */
+
+/** Options for configuring the AST builder */
+interface ASTBuilderOptions {
+    /** Emit completed nodes at this level instead of accumulating */
+    emitAt: LevelType;
+    /** Callback when a completed node is ready */
+    onEmit: (node: LevelNode, context: EmitContext) => void | Promise<void>;
+}
+/**
+ * Builds an AST from XML parser events, emitting completed subtrees at the configured level.
+ */
+declare class ASTBuilder {
+    private readonly options;
+    private readonly stack;
+    private readonly ancestors;
+    private readonly documentMeta;
+    /** Whether we are currently inside the <meta> block */
+    private inMeta;
+    /** Nesting depth inside <quotedContent> — levels inside quotes are not emitted */
+    private quotedContentDepth;
+    /** Active XHTML table collector (null when not inside a table) */
+    private tableCollector;
+    /** Active USLM layout collector (null when not inside a layout) */
+    private layoutCollector;
+    /** Nesting depth inside <toc> — elements inside toc are handled by layout collector only */
+    private tocDepth;
+    /** Current meta field being collected (e.g., "dc:title", "docNumber") */
+    private metaField;
+    /** Attributes of the current meta property element */
+    private metaPropertyAttrs;
+    constructor(options: ASTBuilderOptions);
+    /** Returns the document metadata collected so far */
+    getDocumentMeta(): DocumentMeta;
+    /**
+     * Handle an openElement event from the parser.
+     */
+    onOpenElement(name: string, attrs: Attributes): void;
+    /**
+     * Handle a closeElement event from the parser.
+     */
+    onCloseElement(name: string): void;
+    /**
+     * Handle a text event from the parser.
+     */
+    onText(text: string): void;
+    private handleMetaOpen;
+    private handleMetaClose;
+    private openLevel;
+    private closeLevel;
+    private openContent;
+    private closeContent;
+    private openInline;
+    private closeInline;
+    private openNotesContainer;
+    private closeNotesContainer;
+    private openNote;
+    private closeNote;
+    private openSourceCredit;
+    private closeSourceCredit;
+    private openQuotedContent;
+    private closeQuotedContent;
+    private handleNumOrHeadingClose;
+    private handlePClose;
+    /**
+     * Bubble text content up to the nearest heading/num ignore frame on the stack.
+     * This handles patterns like <heading><b>Editorial Notes</b></heading>
+     * where the text is inside an inline child but needs to be collected by the heading frame.
+     */
+    private handleTableOpen;
+    private handleTableClose;
+    private finishTable;
+    private handleLayoutOpen;
+    private handleLayoutClose;
+    private finishLayout;
+    private bubbleTextToCollector;
+    private peekFrame;
+    private peekFrameAbove;
+    private popFrame;
+    private findParentFrame;
+    /**
+     * Add a block-level AST node to the nearest parent that accepts children.
+     */
+    private addToParent;
+    /**
+     * Add an inline AST node to the nearest parent that accepts inline children.
+     */
+    private addInlineToParent;
+    /**
+     * Extract plain text from a node tree (for flattening quotedContent).
+     */
+    private extractText;
+    private extractInlineText;
+}
+
+/**
+ * Markdown renderer — converts AST nodes to Markdown strings.
+ *
+ * Stateless and pure: no side effects, no file I/O.
+ */
+
+/** Notes filtering configuration */
+interface NotesFilter {
+    /** Include editorial notes (codification, dispositionOfSections, etc.) */
+    editorial: boolean;
+    /** Include statutory notes (changeOfName, regulations, miscellaneous, repeals, etc.) */
+    statutory: boolean;
+    /** Include amendment history (amendments, effectiveDateOfAmendment) */
+    amendments: boolean;
+}
+/** Options for controlling Markdown rendering */
+interface RenderOptions {
+    /** Heading level offset (0 = section is H1, 1 = section is H2) */
+    headingOffset: number;
+    /** How to render cross-references */
+    linkStyle: "relative" | "canonical" | "plaintext";
+    /** Function to resolve a USLM identifier to a relative file path (for linkStyle "relative") */
+    resolveLink?: ((identifier: string) => string | null) | undefined;
+    /** Notes filtering. Undefined = include all notes. */
+    notesFilter?: NotesFilter | undefined;
+}
+/**
+ * Render a complete section document: frontmatter + Markdown content.
+ */
+declare function renderDocument(sectionNode: LevelNode, frontmatter: FrontmatterData, options?: RenderOptions): string;
+/**
+ * Render a section-level node to Markdown.
+ */
+declare function renderSection(node: LevelNode, options?: RenderOptions): string;
+/**
+ * Render any AST node to Markdown.
+ */
+declare function renderNode(node: ASTNode, options?: RenderOptions): string;
+
+/**
+ * YAML frontmatter generator for section Markdown files.
+ */
+
+/** Output format version */
+declare const FORMAT_VERSION = "1.0.0";
+/** Generator identifier (reads version from package.json) */
+declare const GENERATOR: string;
+/**
+ * Generate a YAML frontmatter string from section metadata.
+ *
+ * Returns a complete frontmatter block including the `---` delimiters.
+ */
+declare function generateFrontmatter(data: FrontmatterData): string;
+
+/**
+ * Cross-reference link resolver.
+ *
+ * Resolves USLM identifier URIs to relative Markdown file paths within
+ * the output tree, or falls back to OLRC website URLs.
+ */
+/** Parsed components of a USLM identifier */
+interface ParsedIdentifier {
+    /** Jurisdiction (e.g., "us") */
+    jurisdiction: string;
+    /** Code (e.g., "usc") */
+    code: string;
+    /** Title number (e.g., "1", "26") */
+    titleNum?: string | undefined;
+    /** Section number (e.g., "1", "7801", "106a") */
+    sectionNum?: string | undefined;
+    /** Subsection path (e.g., "a/2") */
+    subPath?: string | undefined;
+}
+/**
+ * Parse a USLM identifier into its components.
+ *
+ * Handles: /us/usc/t{N}, /us/usc/t{N}/s{N}, /us/usc/t{N}/s{N}/{sub}
+ * Returns null for non-USC identifiers (stat, pl, act).
+ */
+declare function parseIdentifier(identifier: string): ParsedIdentifier | null;
+/**
+ * Resolve a USLM identifier to an expected output file path.
+ *
+ * Given a section identifier like "/us/usc/t2/s285b", returns a path like
+ * "usc/title-02/section-285b.md". The chapter is unknown without a registry,
+ * so this returns null unless the identifier is registered.
+ */
+interface LinkResolver {
+    /**
+     * Given a USLM identifier and the current file's path in the output tree,
+     * return a relative Markdown link path or null if unresolvable.
+     */
+    resolve(identifier: string, fromFile: string): string | null;
+    /**
+     * Register a converted file so future cross-references can resolve to it.
+     */
+    register(identifier: string, filePath: string): void;
+    /**
+     * Build the fallback OLRC website URL for identifiers not in the output corpus.
+     */
+    fallbackUrl(identifier: string): string | null;
+}
+/**
+ * Create a new LinkResolver instance.
+ */
+declare function createLinkResolver(): LinkResolver;
+
+export { APPENDIX_LEVEL_ELEMENTS, ASTBuilder, type ASTBuilderOptions, type ASTNode, type AncestorInfo, type Attributes, BIG_LEVELS, CONTAINER_ELEMENTS, CONTENT_ELEMENTS, type ContentNode, type ContentVariant, DCTERMS_NS, DC_NS, type DocumentMeta, type EmitContext, FORMAT_VERSION, type FrontmatterData, GENERATOR, INLINE_ELEMENTS, type InlineNode, type InlineType, LEVEL_ELEMENTS, LEVEL_TYPES, type LevelNode, type LevelType, type LinkResolver, META_ELEMENTS, NAMESPACE_PREFIXES, NOTE_ELEMENTS, type NoteNode, type NotesContainerNode, type NotesFilter, type ParsedIdentifier, type ParserEvents, type QuotedContentNode, type RenderOptions, SMALL_LEVELS, type SourceCreditNode, type TOCItemNode, type TOCNode, type TableNode, USLM_NS, XHTML_NS, XMLParser, type XMLParserOptions, XSI_NS, createLinkResolver, generateFrontmatter, parseIdentifier, renderDocument, renderNode, renderSection };