Enhance CLI UI and add multi-select Title options for downloads#6
Enhance CLI UI and add multi-select Title options for downloads#6chris-c-thomas merged 6 commits intomainfrom
Conversation
Replace --title <n> (single title) with --titles <spec> supporting ranges, comma-separated lists, and mixed formats (e.g. 1-5,8,11). Make convert <input> optional and add --titles + --input-dir flags for multi-title conversion with per-title summaries and aggregate footer.
chris-c-thomas
added
docs
|
Caution Review failedThe pull request is closed. ℹ️ Recent review infoConfiguration used: Organization UI Review profile: CHILL Plan: Free ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (19)
📝 WalkthroughWalkthroughThe PR introduces version 0.5.0 with multi-title selection support via a new Changes
Sequence DiagramsequenceDiagram
actor User
participant CLI
participant Parser as Title Parser<br/>(parseTitles)
participant Handler as Command Handler<br/>(download/convert)
participant UI as UI Module<br/>(spinner, tables)
participant FS as File System
participant Converter as Converter/<br/>Downloader
User->>CLI: Enter command with --titles spec
CLI->>Parser: parseTitles(spec)
Parser->>Parser: Parse ranges, lists,<br/>deduplicate, validate
Parser-->>CLI: number[] of titles
CLI->>Handler: Process titles array
loop For each title
Handler->>UI: createSpinner(title label)
UI-->>Handler: spinner instance
Handler->>FS: Resolve title file path
FS-->>Handler: file path
Handler->>Converter: Process single title
Converter->>FS: Read/Write files
FS-->>Converter: Success/Error
Converter-->>Handler: Result + stats
Handler->>UI: Update spinner + log
UI-->>Handler: Output rendered
end
Handler->>UI: summaryBlock(aggregated stats)
UI->>UI: Format table with<br/>totals, duration, size
UI-->>Handler: Summary rendered
Handler-->>CLI: Complete with results
CLI-->>User: Display formatted output
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Note 🎁 Summarized by CodeRabbit FreeYour organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login. Comment |
There was a problem hiding this comment.
Pull request overview
This PR upgrades law2md CLI UX for batch workflows by adding multi-title selection for download/convert, a configurable XML input directory for multi-title conversion, and more polished terminal output. It also updates default paths/documentation and bumps versions to 0.5.0.
Changes:
- Add
--titles <spec>parsing (ranges/lists) and apply it todownloadandconvert(including multi-title convert mode with aggregate stats). - Introduce shared terminal UI helpers (spinner, tables, formatting) and adopt
chalk/ora/cli-table3. - Update defaults/docs/ignores to the new
./downloads/usc/xmllayout and bump package versions/changelogs.
Reviewed changes
Copilot reviewed 18 out of 20 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| pnpm-lock.yaml | Locks new CLI UI dependencies (chalk, ora, cli-table3) and transitive deps. |
| packages/usc/package.json | Bumps @law2md/usc version to 0.5.0. |
| packages/usc/CHANGELOG.md | Adds release notes for @law2md/usc (currently includes CLI-oriented notes). |
| packages/core/package.json | Bumps @law2md/core version to 0.5.0. |
| packages/core/CHANGELOG.md | Adds release notes for @law2md/core (currently includes CLI-oriented notes). |
| packages/cli/src/ui.ts | Adds shared CLI UI utilities (spinner, formatting, tables). |
| packages/cli/src/parse-titles.ts | Implements --titles spec parsing with validation/dedup/sort. |
| packages/cli/src/parse-titles.test.ts | Adds unit tests for parseTitles(). |
| packages/cli/src/index.test.ts | Updates CLI help expectations for --titles / --input-dir. |
| packages/cli/src/commands/download.ts | Replaces --title with --titles and adds formatted summary/table output. |
| packages/cli/src/commands/convert.ts | Makes [input] optional; adds --titles + --input-dir multi-title conversion path and summaries. |
| packages/cli/package.json | Bumps CLI version and adds new UI dependencies. |
| packages/cli/CHANGELOG.md | Updates CLI changelog for 0.5.0 with multi-title selection. |
| docs/output-format.md | Updates generator version strings to 0.5.0. |
| README.md | Updates examples/docs to --titles and new default downloads path. |
| CONTRIBUTING.md | Updates contributor docs/examples for new CLI options and downloads path. |
| CLAUDE.md | Updates repo layout + dev commands to reflect downloads/usc/xml and multi-title usage. |
| CHANGELOG.md | Adds project-level 0.5.0 release notes and related prior entries. |
| .prettierignore | Adds downloads/ to ignored paths. |
| .gitignore | Updates ignored download locations and documents legacy paths. |
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| const mins = Math.floor(secs / 60); | ||
| const remainSecs = Math.round(secs % 60); |
There was a problem hiding this comment.
formatDuration() can produce invalid strings like "1m 60s" because remainSecs uses Math.round(secs % 60), which can round up to 60. Consider using Math.floor for the seconds component (or carrying the extra second into minutes) to keep the 0–59 invariant.
| const mins = Math.floor(secs / 60); | |
| const remainSecs = Math.round(secs % 60); | |
| const totalSecs = Math.round(secs); | |
| const mins = Math.floor(totalSecs / 60); | |
| const remainSecs = totalSecs % 60; |
| // Validate: must specify --titles or --all | ||
| if (!options.titles && !options.all) { | ||
| console.error(error("Specify --titles <spec> or --all (e.g. --titles 1-5,8,11)")); | ||
| process.exit(1); | ||
| } |
There was a problem hiding this comment.
The CLI currently allows --titles and --all to be provided together; in that case --all is silently ignored because titles is passed to downloadTitles(). It’d be clearer to treat these flags as mutually exclusive and exit with an error when both are present.
| if (result.errors.length > 0) { | ||
| console.log(""); | ||
| for (const err of result.errors) { | ||
| console.error(` Error (Title ${err.titleNumber}): ${err.message}`); | ||
| console.log(` ${error(`Title ${err.titleNumber}: ${err.message}`)}`); | ||
| } |
There was a problem hiding this comment.
Download errors are printed with console.log(...) (stdout). For scripting/piping, error reporting should generally go to stderr (e.g., console.error(...)) while the success tables remain on stdout.
|
|
||
| ### Minor Changes | ||
|
|
||
| - 3a29a8e: Add `--titles` multi-select option to download and convert commands. Supports ranges (`1-5`), comma-separated lists |
There was a problem hiding this comment.
This package changelog entry describes CLI flags (--titles on download/convert). Those options are implemented in packages/cli, not in @law2md/core, so the 0.5.0 notes here look inaccurate/misleading. Suggest updating this entry to describe actual @law2md/core changes (or omit it if there were no functional changes).
| - 3a29a8e: Add `--titles` multi-select option to download and convert commands. Supports ranges (`1-5`), comma-separated lists | |
| - 3a29a8e: No functional changes to `@law2md/core` in this release; version bump to keep in sync with other packages. |
|
|
||
| ### Patch Changes | ||
|
|
||
| - Add chalk, ora, and cli-table3 for polished terminal output with spinners and formatted |
There was a problem hiding this comment.
The 0.4.1 patch notes mention adding chalk, ora, and cli-table3, but those dependencies are in the CLI package (and packages/cli/src/ui.ts), not @law2md/core. This changelog entry should reflect changes shipped in @law2md/core only.
| - Add chalk, ora, and cli-table3 for polished terminal output with spinners and formatted | |
| - Internal maintenance release for @law2md/core (no public API changes). |
|
|
||
| ### Minor Changes | ||
|
|
||
| - 3a29a8e: Add `--titles` multi-select option to download and convert commands. Supports ranges (`1-5`), comma-separated lists |
There was a problem hiding this comment.
This @law2md/usc changelog entry calls out the CLI --titles option on the download/convert commands. That flag parsing lives in packages/cli; @law2md/usc exposes downloadTitles()/convertTitle() and doesn’t implement CLI options itself. Recommend rewriting the 0.5.0 notes to reflect actual library/API changes (or remove if this release is just a version bump).
| - 3a29a8e: Add `--titles` multi-select option to download and convert commands. Supports ranges (`1-5`), comma-separated lists | |
| - 3a29a8e: Add multi-title helpers (`downloadTitles()`, `convertTitle()`) to support downloading and converting multiple titles. Supports ranges (`1-5`) and comma-separated lists. |
|
|
||
| ### Patch Changes | ||
|
|
||
| - Add chalk, ora, and cli-table3 for polished terminal output with spinners and formatted |
There was a problem hiding this comment.
The 0.4.1 notes mention adding chalk, ora, and cli-table3 for terminal output, but those dependencies/utilities are in the CLI package rather than @law2md/usc. This entry is likely misplaced and should be corrected to avoid misleading package consumers.
| - Add chalk, ora, and cli-table3 for polished terminal output with spinners and formatted | |
| - Internal maintenance; terminal output improvements (chalk, ora, cli-table3) are part of the CLI package, not `@law2md/usc`. |
This pull request introduces a major update (v0.5.0) to the
law2mdCLI and documentation, focused on supporting multi-title selection for both download and convert commands, updating default paths, and improving terminal output. The changes provide a more flexible and user-friendly workflow for working with U.S. Code XML files, including new options for specifying multiple titles and enhanced summary reporting.Multi-title selection and CLI enhancements
--titles <spec>option to bothdownloadandconvertcommands, supporting single numbers, comma-separated lists, ranges, and mixed formats; replaces the old--title <n>option and allows batch processing of titles. [1] [2] [3] [4] [5]convertcommand to accept either a file path or--titles, with per-title summary tables and an aggregate footer showing conversion stats. [1] [2] [3]--input-dir <dir>option to specify the XML directory for conversion (default:./downloads/usc/xml). [1] [2] [3] [4]Documentation and path updates
downloads/usc/xml/instead ofxml/, reflecting the new workflow and options. [1] [2] [3] [4] [5] [6].prettierignoreto includedownloadsdirectory, aligning with the new file structure.Terminal output and UI improvements
chalk,ora, andcli-table3for polished CLI output, including spinners, formatted summary blocks, and data tables for download and convert commands. [1] [2] [3]Version and metadata updates
0.5.0inpackage.json, output metadata, and documentation. [1] [2] [3] [4]These changes collectively make the CLI more powerful and easier to use for batch operations and improve the clarity of both documentation and output.
Summary by CodeRabbit
New Features
--titlesflag supporting ranges (e.g., 1-5), comma-separated values, and mixed formats for download and convert commands--input-dirparameter for convert commandDocumentation
--titlessyntax and default download locationTests
Chores