@lexbuild/fr 1.14.0 → 1.15.0

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

@@ -35,6 +35,8 @@ interface FrDocumentXmlMeta {
     rin?: string | undefined;
     /** FR document number extracted from FRDOC text */
     documentNumber?: string | undefined;
+    /** Publication date inferred from FRDOC filing date (YYYY-MM-DD) */
+    publicationDate?: string | undefined;
 }
 /**
  * Federal Register AST Builder.
@@ -274,10 +276,22 @@ declare function buildYearDir(year: string, outputRoot: string): string;
  * enriches frontmatter with JSON sidecar metadata, renders via core's
  * renderDocument, and writes structured Markdown output.
  *
- * Processes FR documents in two passes: (1) parse all files and register
- * identifiers for link resolution, (2) render and write output files.
+ * Processes FR documents in a single streaming pass: parse each XML file,
+ * render Markdown, and write output immediately. No link pre-registration
+ * since FR documents rarely cross-reference each other.
  */
 
+/** Progress info for conversion callback */
+interface FrConvertProgress {
+    /** Documents converted so far */
+    documentsConverted: number;
+    /** XML files processed so far */
+    filesProcessed: number;
+    /** Total XML files to process */
+    totalFiles: number;
+    /** Current XML file being processed */
+    currentFile: string;
+}
 /** Options for converting FR documents */
 interface FrConvertOptions {
     /** Path to input file or directory containing .xml/.json files */
@@ -294,6 +308,8 @@ interface FrConvertOptions {
     to?: string | undefined;
     /** Filter: document types */
     types?: FrDocumentType[] | undefined;
+    /** Progress callback */
+    onProgress?: ((progress: FrConvertProgress) => void) | undefined;
 }
 /** Result of a conversion operation */
 interface FrConvertResult {
@@ -339,8 +355,8 @@ interface FrDownloadOptions {
     types?: FrDocumentType[] | undefined;
     /** Maximum number of documents to download (for testing) */
     limit?: number | undefined;
-    /** Delay between XML fetches in milliseconds */
-    fetchDelayMs?: number | undefined;
+    /** Number of concurrent XML downloads (default 10) */
+    concurrency?: number | undefined;
     /** Progress callback */
     onProgress?: ((progress: FrDownloadProgress) => void) | undefined;
 }
@@ -401,7 +417,8 @@ declare function buildFrApiListUrl(from: string, to: string, page: number, types
  * Download FR documents for a date range.
  *
  * Automatically chunks large date ranges into month-sized windows to stay
- * under the API's 10,000 result cap per query.
+ * under the API's 10,000 result cap per query. Within each chunk, document
+ * XML files are downloaded concurrently (default 10 at a time).
  */
 declare function downloadFrDocuments(options: FrDownloadOptions): Promise<FrDownloadResult>;
 /**
@@ -411,4 +428,85 @@ declare function downloadFrDocuments(options: FrDownloadOptions): Promise<FrDown
  */
 declare function downloadSingleFrDocument(documentNumber: string, output: string): Promise<FrDownloadedFile>;
 
-export { FR_BLOCK_ELEMENTS, FR_CONTENT_ELEMENTS, FR_DOCUMENT_ELEMENTS, FR_DOCUMENT_TYPE_KEYS, FR_DOCUMENT_TYPE_MAP, FR_EMPHASIS_MAP, FR_HD_SOURCE_TO_DEPTH, FR_HEADING_ELEMENT, FR_IGNORE_ELEMENTS, FR_INLINE_ELEMENTS, FR_NOTE_ELEMENTS, FR_PASSTHROUGH_ELEMENTS, FR_PREAMBLE_META_ELEMENTS, FR_PREAMBLE_SECTIONS, FR_PRESIDENTIAL_SUBTYPES, FR_REGTEXT_ELEMENTS, FR_SECTION_CONTAINERS, FR_SIGNATURE_ELEMENTS, FR_SKIP_ELEMENTS, FR_TABLE_ELEMENTS, FrASTBuilder, type FrASTBuilderOptions, type FrConvertOptions, type FrConvertResult, type FrDocumentJsonMeta, type FrDocumentType, type FrDocumentXmlMeta, type FrDownloadFailure, type FrDownloadOptions, type FrDownloadProgress, type FrDownloadResult, type FrDownloadedFile, buildFrApiListUrl, buildFrDownloadJsonPath, buildFrDownloadXmlPath, buildFrFrontmatter, buildFrOutputPath, buildMonthDir, buildYearDir, convertFrDocuments, downloadFrDocuments, downloadSingleFrDocument };
+/**
+ * Federal Register govinfo bulk downloader.
+ *
+ * Downloads complete daily-issue XML files from govinfo.gov. Each file contains
+ * all FR documents published on a single day (~150 documents, ~2.4 MB average).
+ * This is dramatically faster than the per-document API for historical backfill.
+ *
+ * URL pattern: https://www.govinfo.gov/content/pkg/FR-{YYYY-MM-DD}/xml/FR-{YYYY-MM-DD}.xml
+ *
+ * The existing FrASTBuilder handles daily-issue XML natively: FEDREG root is a
+ * passthrough, section containers (RULES, NOTICES, etc.) are passthroughs, and
+ * individual document elements emit via onEmit. No splitter needed.
+ */
+/** Options for downloading FR bulk XML from govinfo */
+interface FrGovinfoBulkOptions {
+    /** Download directory (e.g., "./downloads/fr") */
+    output: string;
+    /** Start date (YYYY-MM-DD, inclusive) */
+    from: string;
+    /** End date (YYYY-MM-DD, inclusive). Defaults to today. */
+    to?: string | undefined;
+    /** Number of concurrent downloads (default 10) */
+    concurrency?: number | undefined;
+    /** Progress callback */
+    onProgress?: ((progress: FrGovinfoProgress) => void) | undefined;
+}
+/** Progress info for govinfo download callback */
+interface FrGovinfoProgress {
+    /** Files downloaded so far */
+    downloaded: number;
+    /** Total publishing days in date range */
+    totalDays: number;
+    /** Skipped days (weekends/holidays — 404) */
+    skipped: number;
+    /** Failed downloads */
+    failed: number;
+    /** Current date being downloaded */
+    currentDate: string;
+}
+/** A successfully downloaded bulk file */
+interface FrGovinfoDownloadedFile {
+    /** Absolute path to the downloaded XML file */
+    path: string;
+    /** Publication date (YYYY-MM-DD) */
+    date: string;
+    /** File size in bytes */
+    size: number;
+}
+/** Result of a govinfo bulk download */
+interface FrGovinfoResult {
+    /** Number of daily files downloaded */
+    filesDownloaded: number;
+    /** Downloaded files */
+    files: FrGovinfoDownloadedFile[];
+    /** Total bytes downloaded */
+    totalBytes: number;
+    /** Date range covered */
+    dateRange: {
+        from: string;
+        to: string;
+    };
+    /** Days skipped (no issue published — weekends/holidays) */
+    skipped: number;
+    /** Days that failed to download */
+    failed: number;
+}
+/**
+ * Build the govinfo download URL for a single day's FR issue.
+ */
+declare function buildGovinfoFrUrl(date: string): string;
+/**
+ * Build the local file path for a downloaded daily-issue XML.
+ * Stored as: {output}/bulk/{YYYY}/FR-{YYYY-MM-DD}.xml
+ */
+declare function buildGovinfoBulkPath(date: string, outputDir: string): string;
+/**
+ * Download FR daily-issue XML files from govinfo for a date range.
+ * Skips weekends/holidays (404 responses) and retries transient errors.
+ */
+declare function downloadFrBulk(options: FrGovinfoBulkOptions): Promise<FrGovinfoResult>;
+
+export { FR_BLOCK_ELEMENTS, FR_CONTENT_ELEMENTS, FR_DOCUMENT_ELEMENTS, FR_DOCUMENT_TYPE_KEYS, FR_DOCUMENT_TYPE_MAP, FR_EMPHASIS_MAP, FR_HD_SOURCE_TO_DEPTH, FR_HEADING_ELEMENT, FR_IGNORE_ELEMENTS, FR_INLINE_ELEMENTS, FR_NOTE_ELEMENTS, FR_PASSTHROUGH_ELEMENTS, FR_PREAMBLE_META_ELEMENTS, FR_PREAMBLE_SECTIONS, FR_PRESIDENTIAL_SUBTYPES, FR_REGTEXT_ELEMENTS, FR_SECTION_CONTAINERS, FR_SIGNATURE_ELEMENTS, FR_SKIP_ELEMENTS, FR_TABLE_ELEMENTS, FrASTBuilder, type FrASTBuilderOptions, type FrConvertOptions, type FrConvertProgress, type FrConvertResult, type FrDocumentJsonMeta, type FrDocumentType, type FrDocumentXmlMeta, type FrDownloadFailure, type FrDownloadOptions, type FrDownloadProgress, type FrDownloadResult, type FrDownloadedFile, type FrGovinfoBulkOptions, type FrGovinfoDownloadedFile, type FrGovinfoProgress, type FrGovinfoResult, buildFrApiListUrl, buildFrDownloadJsonPath, buildFrDownloadXmlPath, buildFrFrontmatter, buildFrOutputPath, buildGovinfoBulkPath, buildGovinfoFrUrl, buildMonthDir, buildYearDir, convertFrDocuments, downloadFrBulk, downloadFrDocuments, downloadSingleFrDocument };