@lexbuild/usc 1.0.0 → 1.0.1
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.
- package/README.md +121 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
# @lexbuild/usc
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@lexbuild/usc)
|
|
4
|
+
[](https://github.com/chris-c-thomas/lexbuild/blob/main/LICENSE)
|
|
5
|
+
|
|
6
|
+
This package is part of the [LexBuild](https://github.com/chris-c-thomas/lexbuild) monorepo, a tool that converts U.S. legislative 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 official [USLM](https://uscode.house.gov/download/resources/USLM-User-Guide.pdf) XML from the [Office of the Law Revision Counsel](https://uscode.house.gov/) (OLRC) into structured Markdown. It also provides a downloader for fetching the XML directly from OLRC.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
npm install @lexbuild/usc
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Usage
|
|
17
|
+
|
|
18
|
+
### Convert a Title
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
import { convertTitle } from "@lexbuild/usc";
|
|
22
|
+
|
|
23
|
+
const result = await convertTitle({
|
|
24
|
+
input: "./downloads/usc/xml/usc01.xml",
|
|
25
|
+
output: "./output",
|
|
26
|
+
granularity: "section",
|
|
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(`Chapters: ${result.chapterCount}`);
|
|
38
|
+
console.log(`Estimated tokens: ${result.totalTokenEstimate}`);
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Download Titles from OLRC
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
import { downloadTitles } from "@lexbuild/usc";
|
|
45
|
+
|
|
46
|
+
// Download specific titles
|
|
47
|
+
const result = await downloadTitles({
|
|
48
|
+
outputDir: "./downloads/usc/xml",
|
|
49
|
+
titles: [1, 5, 26],
|
|
50
|
+
});
|
|
51
|
+
|
|
52
|
+
// Download all 54 titles (uses a single bulk zip)
|
|
53
|
+
const all = await downloadTitles({
|
|
54
|
+
outputDir: "./downloads/usc/xml",
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
console.log(`Downloaded ${result.files.length} files`);
|
|
58
|
+
console.log(`Release point: ${result.releasePoint}`);
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## API Reference
|
|
62
|
+
|
|
63
|
+
### Functions
|
|
64
|
+
|
|
65
|
+
| Export | Description |
|
|
66
|
+
|--------|-------------|
|
|
67
|
+
| `convertTitle(options)` | Convert a USC XML file to section-level Markdown |
|
|
68
|
+
| `downloadTitles(options)` | Download USC XML from OLRC |
|
|
69
|
+
| `buildDownloadUrl(titleNumber, releasePoint)` | Build URL for a single title zip |
|
|
70
|
+
| `buildAllTitlesUrl(releasePoint)` | Build URL for the bulk zip |
|
|
71
|
+
| `releasePointToPath(releasePoint)` | Convert release point to URL path segment |
|
|
72
|
+
| `isAllTitles(titles)` | Check if a title list covers all 54 titles |
|
|
73
|
+
|
|
74
|
+
### Types
|
|
75
|
+
|
|
76
|
+
| Export | Description |
|
|
77
|
+
|--------|-------------|
|
|
78
|
+
| `ConvertOptions` | Options for `convertTitle()` |
|
|
79
|
+
| `ConvertResult` | Result of a conversion (sections, chapters, tokens, files) |
|
|
80
|
+
| `DownloadOptions` | Options for `downloadTitles()` |
|
|
81
|
+
| `DownloadResult` | Result of a download (files, errors, release point) |
|
|
82
|
+
| `DownloadedFile` | Info about a downloaded file (title, path, size) |
|
|
83
|
+
| `DownloadError` | Info about a failed download |
|
|
84
|
+
|
|
85
|
+
### Constants
|
|
86
|
+
|
|
87
|
+
| Export | Description |
|
|
88
|
+
|--------|-------------|
|
|
89
|
+
| `CURRENT_RELEASE_POINT` | Current OLRC release point (e.g., `"119-73not60"`) |
|
|
90
|
+
| `USC_TITLE_NUMBERS` | Array of valid title numbers (1-54) |
|
|
91
|
+
|
|
92
|
+
## Output
|
|
93
|
+
|
|
94
|
+
Each title produces a directory tree of Markdown files with YAML frontmatter and JSON metadata indexes:
|
|
95
|
+
|
|
96
|
+
```
|
|
97
|
+
output/usc/title-01/
|
|
98
|
+
README.md
|
|
99
|
+
_meta.json
|
|
100
|
+
chapter-01/
|
|
101
|
+
_meta.json
|
|
102
|
+
section-1.md
|
|
103
|
+
section-2.md
|
|
104
|
+
chapter-02/
|
|
105
|
+
_meta.json
|
|
106
|
+
section-101.md
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
See the [output format specification](https://github.com/chris-c-thomas/lexbuild/blob/main/docs/output-format.md) for details.
|
|
110
|
+
|
|
111
|
+
## Documentation
|
|
112
|
+
|
|
113
|
+
- [Monorepo README](https://github.com/chris-c-thomas/lexbuild#readme)
|
|
114
|
+
- [Architecture](https://github.com/chris-c-thomas/lexbuild/blob/main/docs/architecture.md)
|
|
115
|
+
- [Output Format](https://github.com/chris-c-thomas/lexbuild/blob/main/docs/output-format.md)
|
|
116
|
+
- [XML Element Reference](https://github.com/chris-c-thomas/lexbuild/blob/main/docs/xml-element-reference.md)
|
|
117
|
+
- [Extending](https://github.com/chris-c-thomas/lexbuild/blob/main/docs/extending.md)
|
|
118
|
+
|
|
119
|
+
## License
|
|
120
|
+
|
|
121
|
+
[MIT](https://github.com/chris-c-thomas/lexbuild/blob/main/LICENSE)
|