@lexbuild/ecfr 1.9.0 → 1.9.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,208 @@
+import { LevelType, LevelNode, EmitContext, Attributes, InlineType } from '@lexbuild/core';
+
+/**
+ * eCFR conversion orchestrator.
+ *
+ * Follows the same collect-then-write pattern as the USC converter:
+ * 1. Parse XML via SAX → feed EcfrASTBuilder
+ * 2. Collect emitted sections/parts/titles
+ * 3. Two-pass link registration (with duplicate detection)
+ * 4. Write Markdown files, _meta.json, and README.md
+ */
+/** Options for converting an eCFR XML file */
+interface EcfrConvertOptions {
+    /** Path to input eCFR XML file */
+    input: string;
+    /** Output root directory */
+    output: string;
+    /** Output granularity: section (default), part, chapter, or title */
+    granularity: "section" | "part" | "chapter" | "title";
+    /** Link style for cross-references */
+    linkStyle: "relative" | "canonical" | "plaintext";
+    /** Include source credits in output */
+    includeSourceCredits: boolean;
+    /** Include all notes */
+    includeNotes: boolean;
+    /** Selectively include editorial notes */
+    includeEditorialNotes: boolean;
+    /** Selectively include statutory/regulatory notes */
+    includeStatutoryNotes: boolean;
+    /** Selectively include amendment history */
+    includeAmendments: boolean;
+    /** Parse only, don't write files */
+    dryRun: boolean;
+}
+/** Result of an eCFR conversion */
+interface EcfrConvertResult {
+    /** Number of sections/parts/titles written */
+    sectionsWritten: number;
+    /** Paths of written files */
+    files: string[];
+    /** Title number from XML metadata */
+    titleNumber: string;
+    /** Title name from XML metadata */
+    titleName: string;
+    /** Whether this was a dry run */
+    dryRun: boolean;
+    /** Number of unique parts */
+    partCount: number;
+    /** Total estimated tokens */
+    totalTokenEstimate: number;
+    /** Peak RSS in bytes during conversion */
+    peakMemoryBytes: number;
+}
+/**
+ * Convert an eCFR XML file to structured Markdown.
+ */
+declare function convertEcfrTitle(options: EcfrConvertOptions): Promise<EcfrConvertResult>;
+
+/**
+ * eCFR bulk XML downloader.
+ *
+ * Downloads individual title XML files from govinfo.gov's bulk data repository.
+ * Unlike the USC downloader, eCFR files are plain XML (not ZIP archives).
+ */
+/** Total number of CFR titles */
+declare const ECFR_TITLE_COUNT = 50;
+/** All eCFR title numbers (1-50) */
+declare const ECFR_TITLE_NUMBERS: number[];
+/** Options for downloading eCFR titles */
+interface EcfrDownloadOptions {
+    /** Download directory */
+    output: string;
+    /** Specific titles to download (1-50), or undefined for all */
+    titles?: number[] | undefined;
+}
+/** Result of a successful download */
+interface EcfrDownloadResult {
+    /** Number of titles successfully downloaded */
+    titlesDownloaded: number;
+    /** Paths of downloaded files */
+    files: EcfrDownloadedFile[];
+    /** Total bytes downloaded */
+    totalBytes: number;
+}
+/** Metadata for a single downloaded file */
+interface EcfrDownloadedFile {
+    /** Absolute path to the downloaded file */
+    path: string;
+    /** Title number */
+    titleNumber: number;
+    /** File size in bytes */
+    size: number;
+}
+/** Error for a failed download */
+interface EcfrDownloadError {
+    /** Title number that failed */
+    titleNumber: number;
+    /** HTTP status code or error message */
+    error: string;
+}
+/**
+ * Build the download URL for an eCFR title.
+ */
+declare function buildEcfrDownloadUrl(titleNumber: number): string;
+/**
+ * Download eCFR XML files from govinfo bulk data.
+ */
+declare function downloadEcfrTitles(options: EcfrDownloadOptions): Promise<EcfrDownloadResult>;
+
+/**
+ * eCFR AST Builder — converts SAX events from GPO/SGML-derived XML into AST nodes.
+ *
+ * Follows the same stack-based, emit-at-level pattern as the USLM builder in core,
+ * but dispatches on eCFR element names (DIV1-DIV9 with TYPE attributes, HEAD, P, etc.)
+ * instead of USLM semantic element names.
+ */
+
+/** Options for configuring the eCFR AST builder */
+interface EcfrASTBuilderOptions {
+    /** 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>;
+}
+/**
+ * eCFR AST Builder. Consumes SAX events and produces LexBuild AST nodes.
+ */
+declare class EcfrASTBuilder {
+    private readonly options;
+    private readonly stack;
+    private documentMeta;
+    private readonly emitAtIndex;
+    /** Track title number from metadata header */
+    private titleNumber;
+    /** Depth inside CFRTOC or other ignored container */
+    private ignoredContainerDepth;
+    /** Part-level notes (authority/source) keyed by part identifier */
+    private readonly partNotes;
+    constructor(options: EcfrASTBuilderOptions);
+    /** Get part-level notes (authority/source) captured during parsing */
+    getPartNotes(): ReadonlyMap<string, {
+        authority?: string | undefined;
+        regulatorySource?: string | undefined;
+    }>;
+    /** Handle SAX open element */
+    onOpenElement(name: string, attrs: Attributes): void;
+    /** Handle SAX close element */
+    onCloseElement(name: string): void;
+    /** Handle SAX text content */
+    onText(text: string): void;
+    private openLevel;
+    private closeLevel;
+    private openContent;
+    private closeContent;
+    private openInline;
+    private openRef;
+    private closeInline;
+    private openNote;
+    private closeNote;
+    private closeTable;
+    private closeTableRow;
+    private closeTableCell;
+    private popFrame;
+    private findParentLevel;
+    private findParentNote;
+    private findTableFrame;
+    private extractNoteText;
+}
+
+/**
+ * eCFR GPO/SGML-derived XML element classification.
+ *
+ * The eCFR XML uses a numbered DIV system (DIV1-DIV9) where the TYPE
+ * attribute determines the semantic level, not the element name.
+ *
+ * This element vocabulary is shared by the eCFR bulk data and the
+ * annual CFR bulk data on govinfo. If a future @lexbuild/cfr package
+ * is created for the annual edition, it can import these classifications.
+ */
+
+/** Map from DIV TYPE attribute values to LexBuild level types */
+declare const ECFR_TYPE_TO_LEVEL: Readonly<Record<string, LevelType>>;
+/** DIV element names (all route to the TYPE-based level mapping) */
+declare const ECFR_DIV_ELEMENTS: Set<string>;
+/** Elements that contain text content directly */
+declare const ECFR_CONTENT_ELEMENTS: Set<string>;
+/** Elements that contain inline formatting */
+declare const ECFR_INLINE_ELEMENTS: Set<string>;
+/** Map from E element T attribute to InlineType */
+declare const ECFR_EMPHASIS_MAP: Readonly<Record<string, InlineType>>;
+/** Note-like elements */
+declare const ECFR_NOTE_ELEMENTS: Set<string>;
+/** Sub-heading elements within sections/appendices */
+declare const ECFR_HEADING_ELEMENTS: Set<string>;
+/** Block-level elements that wrap content */
+declare const ECFR_BLOCK_ELEMENTS: Set<string>;
+/** Elements to fully ignore (skip entire subtree) */
+declare const ECFR_IGNORE_ELEMENTS: Set<string>;
+/** Elements that are transparent wrappers — pass through without creating frames */
+declare const ECFR_PASSTHROUGH_ELEMENTS: Set<string>;
+/** Self-contained elements to skip (no subtree concerns) */
+declare const ECFR_SKIP_ELEMENTS: Set<string>;
+/** Cross-reference elements */
+declare const ECFR_REF_ELEMENTS: Set<string>;
+/** Table elements (HTML-style) */
+declare const ECFR_TABLE_ELEMENTS: Set<string>;
+
+export { ECFR_BLOCK_ELEMENTS, ECFR_CONTENT_ELEMENTS, ECFR_DIV_ELEMENTS, ECFR_EMPHASIS_MAP, ECFR_HEADING_ELEMENTS, ECFR_IGNORE_ELEMENTS, ECFR_INLINE_ELEMENTS, ECFR_NOTE_ELEMENTS, ECFR_PASSTHROUGH_ELEMENTS, ECFR_REF_ELEMENTS, ECFR_SKIP_ELEMENTS, ECFR_TABLE_ELEMENTS, ECFR_TITLE_COUNT, ECFR_TITLE_NUMBERS, ECFR_TYPE_TO_LEVEL, EcfrASTBuilder, type EcfrASTBuilderOptions, type EcfrConvertOptions, type EcfrConvertResult, type EcfrDownloadError, type EcfrDownloadOptions, type EcfrDownloadResult, type EcfrDownloadedFile, buildEcfrDownloadUrl, convertEcfrTitle, downloadEcfrTitles };