@lexbuild/ecfr 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +136 -0
  2. package/package.json +68 -0
package/README.md ADDED
@@ -0,0 +1,136 @@
1
+ # @lexbuild/ecfr
2
+
3
+ [![npm](https://img.shields.io/npm/v/%40lexbuild%2Fecfr?style=for-the-badge)](https://www.npmjs.com/package/@lexbuild/ecfr)
4
+ [![license](https://img.shields.io/github/license/chris-c-thomas/LexBuild?style=for-the-badge)](https://github.com/chris-c-thomas/LexBuild)
5
+
6
+ This package is part of the [LexBuild](https://github.com/chris-c-thomas/LexBuild) monorepo, a tool that converts U.S. legal XML into structured Markdown optimized for AI, RAG pipelines, and semantic search. See the monorepo for full documentation, architecture details, and contribution guidelines.
7
+
8
+ It converts [eCFR](https://www.ecfr.gov/) (Electronic Code of Federal Regulations) bulk XML from [govinfo.gov](https://www.govinfo.gov/bulkdata/ECFR) into structured Markdown and is built on [`@lexbuild/core`](https://www.npmjs.com/package/@lexbuild/core) for shared parsing and rendering infrastructure. It also provides a downloader for fetching the XML directly from govinfo. End users typically interact with this package through [`@lexbuild/cli`](https://www.npmjs.com/package/@lexbuild/cli).
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ npm install @lexbuild/ecfr
14
+ ```
15
+
16
+ ## Usage
17
+
18
+ ### Convert a Title
19
+
20
+ ```ts
21
+ import { convertEcfrTitle } from "@lexbuild/ecfr";
22
+
23
+ const result = await convertEcfrTitle({
24
+ input: "./downloads/ecfr/xml/ECFR-title17.xml",
25
+ output: "./output",
26
+ granularity: "section", // or "part", "chapter", or "title"
27
+ linkStyle: "plaintext",
28
+ includeSourceCredits: true,
29
+ includeNotes: true,
30
+ includeEditorialNotes: false,
31
+ includeStatutoryNotes: false,
32
+ includeAmendments: false,
33
+ dryRun: false,
34
+ });
35
+
36
+ console.log(`Wrote ${result.sectionsWritten} sections`);
37
+ console.log(`Parts: ${result.partCount}`);
38
+ console.log(`Estimated tokens: ${result.totalTokenEstimate}`);
39
+ ```
40
+
41
+ ### Download Titles from govinfo
42
+
43
+ ```ts
44
+ import { downloadEcfrTitles } from "@lexbuild/ecfr";
45
+
46
+ // Download specific titles
47
+ const result = await downloadEcfrTitles({
48
+ output: "./downloads/ecfr/xml",
49
+ titles: [1, 17, 26],
50
+ });
51
+
52
+ // Download all 50 titles
53
+ const all = await downloadEcfrTitles({
54
+ output: "./downloads/ecfr/xml",
55
+ });
56
+
57
+ console.log(`Downloaded ${result.titlesDownloaded} files`);
58
+ console.log(`Total size: ${result.totalBytes} bytes`);
59
+ ```
60
+
61
+ ## API Reference
62
+
63
+ ### Functions
64
+
65
+ | Export | Description |
66
+ |--------|-------------|
67
+ | `convertEcfrTitle(options)` | Convert an eCFR XML file to section-level Markdown |
68
+ | `downloadEcfrTitles(options)` | Download eCFR XML from govinfo |
69
+ | `buildEcfrDownloadUrl(titleNumber)` | Build URL for a single title XML file |
70
+
71
+ ### Types
72
+
73
+ | Export | Description |
74
+ |--------|-------------|
75
+ | `EcfrConvertOptions` | Options for `convertEcfrTitle()` |
76
+ | `EcfrConvertResult` | Result of a conversion (sections, parts, tokens, files) |
77
+ | `EcfrDownloadOptions` | Options for `downloadEcfrTitles()` |
78
+ | `EcfrDownloadResult` | Result of a download (files, bytes) |
79
+ | `EcfrDownloadedFile` | Info about a downloaded file (title, path, size) |
80
+ | `EcfrDownloadError` | Info about a failed download |
81
+
82
+ ### Classes
83
+
84
+ | Export | Description |
85
+ |--------|-------------|
86
+ | `EcfrASTBuilder` | SAX→AST builder for eCFR GPO/SGML XML |
87
+
88
+ ### Constants
89
+
90
+ | Export | Description |
91
+ |--------|-------------|
92
+ | `ECFR_TITLE_COUNT` | Total number of eCFR titles (`50`) |
93
+ | `ECFR_TITLE_NUMBERS` | Array of valid title numbers (1–50) |
94
+ | `ECFR_TYPE_TO_LEVEL` | Map from DIV TYPE attributes to LexBuild level types |
95
+ | `ECFR_EMPHASIS_MAP` | Map from E element T attribute to inline types |
96
+
97
+ ## Output
98
+
99
+ Each title produces Markdown files with YAML frontmatter. The output structure depends on the granularity setting:
100
+
101
+ | Granularity | Output | Metadata |
102
+ |---|---|---|
103
+ | `section` (default) | `ecfr/title-NN/chapter-X/part-N/section-N.N.md` | `_meta.json` per part + title, `README.md` per title |
104
+ | `part` | `ecfr/title-NN/chapter-X/part-N.md` | — |
105
+ | `chapter` | `ecfr/title-NN/chapter-X/chapter-X.md` | — |
106
+ | `title` | `ecfr/title-NN.md` | — |
107
+
108
+ ### Frontmatter
109
+
110
+ eCFR sections include standard LexBuild frontmatter fields plus source-specific metadata:
111
+
112
+ ```yaml
113
+ ---
114
+ identifier: "/us/cfr/t17/s240.10b-5"
115
+ source: "ecfr"
116
+ legal_status: "authoritative_unofficial"
117
+ title: "17 CFR § 240.10b-5 - Employment of manipulative and deceptive devices"
118
+ title_number: 17
119
+ title_name: "Commodity and Securities Exchanges"
120
+ section_number: "240.10b-5"
121
+ section_name: "Employment of manipulative and deceptive devices"
122
+ part_number: "240"
123
+ part_name: "GENERAL RULES AND REGULATIONS, SECURITIES EXCHANGE ACT OF 1934"
124
+ positive_law: false
125
+ currency: "2025-03-13"
126
+ last_updated: "2025-03-13"
127
+ format_version: "1.1.0"
128
+ generator: "lexbuild@1.8.0"
129
+ authority: "15 U.S.C. 78a et seq., ..."
130
+ cfr_part: "240"
131
+ ---
132
+ ```
133
+
134
+ ## License
135
+
136
+ [MIT](https://github.com/chris-c-thomas/LexBuild/blob/main/LICENSE)
package/package.json ADDED
@@ -0,0 +1,68 @@
1
+ {
2
+ "name": "@lexbuild/ecfr",
3
+ "version": "1.9.0",
4
+ "description": "Electronic Code of Federal Regulations (eCFR) to Markdown converter for LexBuild",
5
+ "author": "Chris Thomas",
6
+ "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "https://github.com/chris-c-thomas/LexBuild.git",
10
+ "directory": "packages/ecfr"
11
+ },
12
+ "homepage": "https://github.com/chris-c-thomas/LexBuild/tree/main/packages/ecfr",
13
+ "bugs": {
14
+ "url": "https://github.com/chris-c-thomas/LexBuild/issues"
15
+ },
16
+ "keywords": [
17
+ "lexbuild",
18
+ "legal-tech",
19
+ "law",
20
+ "rag",
21
+ "llm",
22
+ "xml",
23
+ "parser",
24
+ "cfr",
25
+ "ecfr",
26
+ "regulations",
27
+ "federal-regulations",
28
+ "govinfo",
29
+ "typescript"
30
+ ],
31
+ "type": "module",
32
+ "main": "./dist/index.js",
33
+ "types": "./dist/index.d.ts",
34
+ "exports": {
35
+ ".": {
36
+ "types": "./dist/index.d.ts",
37
+ "import": "./dist/index.js"
38
+ }
39
+ },
40
+ "sideEffects": false,
41
+ "files": [
42
+ "dist"
43
+ ],
44
+ "scripts": {
45
+ "build": "tsup",
46
+ "dev": "tsup --watch",
47
+ "typecheck": "tsc --noEmit",
48
+ "test": "vitest run --passWithNoTests",
49
+ "test:watch": "vitest",
50
+ "lint": "eslint src",
51
+ "lint:fix": "eslint src --fix"
52
+ },
53
+ "dependencies": {
54
+ "@lexbuild/core": "workspace:*"
55
+ },
56
+ "devDependencies": {
57
+ "@types/node": "^25.3.2",
58
+ "tsup": "^8",
59
+ "typescript": "^5.8",
60
+ "vitest": "^3"
61
+ },
62
+ "engines": {
63
+ "node": ">=22"
64
+ },
65
+ "publishConfig": {
66
+ "access": "public"
67
+ }
68
+ }