Implement multi-granularity conversion and update documentation

[chris-c-thomas]

This pull request updates documentation across the monorepo to introduce and explain the new single-pass multi-granularity conversion feature. The new feature allows the CLI and core libraries to emit multiple output granularities (such as section, chapter, title, and part) from a single parse of the source XML, resulting in significant performance improvements and a simpler workflow. All relevant docs, including READMEs, CLI reference, guides, and internal documentation, have been refreshed to describe the new --granularities flag, related output options, and the updated usage patterns for scripts and libraries. No code changes are included—this is a documentation-only release to accompany the feature rollout.

Multi-Granularity Conversion Documentation:

• All CLI, core, and builder documentation now describes the new --granularities flag, which enables emitting multiple granularities (e.g., section, chapter, title, part) in a single parse, and the corresponding --output-<granularity> flags for specifying output directories. Examples and usage notes are provided for both USC and eCFR sources. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14]

• The builder's API documentation now covers the new ReadonlySet<LevelType> form for the emitAt option, explaining how multiple levels are emitted in a single pass, and how this improves performance and output consistency. [1] [2]

Workflow and Script Updates:

• Update scripts (update-usc.sh, update-ecfr.sh) and their documentation now use the new multi-granularity mode, so conversion is performed once per title instead of once per granularity, reducing wall-clock time by ~40–50% for multi-granularity runs. [1] [2] [3] [4]

Reference and Guide Enhancements:

• All relevant guides, CLI references, and architecture docs have been updated with new examples, option tables, and notes on the mutual exclusivity of --granularities and -g/--granularity, as well as performance benefits and migration guidance. [1] [2] [3] [4] [5] [6] [7] [8]

Internal and Meta Documentation:

• Internal docs and meta notes have been updated to reflect changes in output file metadata (e.g., wall-clock timestamps in _meta.json/README.md), which are relevant for testing and output comparison. [1] [2]

Release Notes:

• Changeset files have been added to ensure the documentation refresh is published to npm and to summarize the new feature and its back-compatibility with the old single-granularity mode. [1] [2]

[Copilot]

Pull request overview

This PR rolls out single-pass multi-granularity conversion across the LexBuild toolchain (core AST builder → USC/eCFR converters → CLI/scripts), and updates monorepo documentation to reflect the new --granularities / per-granularity output workflow.

Changes:

• Add multi-level emit support (emitAt as ReadonlySet<LevelType>) to the core USLM builder and the eCFR builder, enabling one parse to feed multiple output granularities.
• Update USC/eCFR converters and CLI commands to support multi-granularity conversion with mutually exclusive single- vs multi-mode options, plus parity/validation tests.
• Refresh docs, READMEs, and update scripts to use the new single-pass multi-granularity workflow; add Changesets for release notes/versioning.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
scripts/update-usc.sh	Switch USC pipeline conversion step to one-call multi-granularity CLI invocation.
scripts/update-ecfr.sh	Switch eCFR pipeline conversion step to one-call multi-granularity CLI invocation.
packages/usc/src/snapshot.test.ts	Update test types to new single-granularity option type.
packages/usc/src/index.ts	Export new converter option/result/granularity types.
packages/usc/src/converter.ts	Implement single-pass multi-granularity conversion + updated result shape.
packages/usc/src/converter.test.ts	Add multi-granularity parity + runtime validation tests.
packages/usc/README.md	Document multi-granularity usage and new exported types.
packages/ecfr/src/index.ts	Export new converter option/result/granularity types.
packages/ecfr/src/ecfr-builder.ts	Allow multi-level emits via emitAt set; adjust attachment rules accordingly.
packages/ecfr/src/ecfr-builder.test.ts	Add tests for set-based multi-emits and appendix nesting behavior.
packages/ecfr/src/converter.ts	Implement single-pass multi-granularity conversion + updated result shape.
packages/ecfr/src/converter.test.ts	New byte-parity integration tests for multi vs repeated single conversions.
packages/ecfr/README.md	Document multi-granularity usage and new exported types.
packages/core/src/ast/uslm-builder.ts	Support emitAt as set; implement stack-based attach rule for multi-emits.
packages/core/src/ast/uslm-builder.test.ts	Add tests validating multi-level emit ordering, ancestry, and reference identity.
packages/core/README.md	Document multi-level emit API and correct attach-to-parent semantics.
packages/core/CLAUDE.md	Update internal guidance for multi-level emit behavior and invariants.
packages/cli/src/commands/convert-usc.ts	Add --granularities parsing, per-granularity outputs, and summary output changes.
packages/cli/src/commands/convert-usc.test.ts	Add unit tests for --granularities parsing and validation.
packages/cli/src/commands/convert-ecfr.ts	Add --granularities parsing, per-granularity outputs, and summary output changes.
packages/cli/src/commands/convert-ecfr.test.ts	Add unit tests for eCFR --granularities parsing and validation.
packages/cli/README.md	Document --granularities and per-granularity output flags.
packages/cli/CLAUDE.md	Document Commander flag-source detection pattern for mutex validation.
apps/astro/src/content/docs/reference/cli-reference.md	Update CLI reference with multi-granularity flags, examples, and guidance.
apps/astro/src/content/docs/guides/rag-pipeline.md	Update RAG pipeline guide to use single-pass multi-granularity examples.
apps/astro/src/content/docs/guides/bulk-download.md	Add single-pass “all granularities” examples and guidance.
apps/astro/src/content/docs/cli/sources/us-code.md	Add USC single-pass multi-granularity section.
apps/astro/src/content/docs/cli/sources/ecfr.md	Add eCFR single-pass multi-granularity section.
apps/astro/src/content/docs/cli/commands.md	Document shared CLI flags and multi-granularity workflow.
apps/astro/src/content/docs/architecture/conversion-pipeline.md	Document multi-level emit model and collect-then-write implications.
apps/astro/README.md	Update app setup instructions to generate all granularities via single-pass mode.
README.md	Update root README with multi-granularity CLI usage and script behavior.
CLAUDE.md	Note generated_at timestamps in outputs and implications for byte-parity tests.
.changeset/multi-granularity-converter.md	Release notes for the new multi-granularity converter feature.
.changeset/docs-multi-granularity.md	Release notes for documentation refresh around multi-granularity conversion.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sonarqubecloud]

Quality Gate failed

Failed conditions
7.4% Duplication on New Code (required ≤ 3%)
D Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE