Update documentation and remove unnecessary files#10
Conversation
chris-c-thomas
added
docs
|
Caution Review failedThe pull request is closed. ℹ️ Recent review infoConfiguration used: Organization UI Review profile: CHILL Plan: Free 📒 Files selected for processing (13)
📝 WalkthroughWalkthroughThis pull request performs repository cleanup and documentation expansion. It bumps package versions from 0.7.0 to 0.8.0 across the monorepo, removes the context7 MCP server integration, and updates .gitignore to ignore the MCP configuration file. Documentation is substantially expanded across multiple files to clarify build processes, architectural decisions, CLI usage, and project structure. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 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 primarily updates project documentation and onboarding materials for the law2md monorepo, while also removing obsolete MCP config and bumping package versions/changelogs.
Changes:
- Expanded/rewrote key docs (
README.md,CONTRIBUTING.md,CLAUDE.md,.github/copilot-instructions.md) to clarify architecture, conventions, workflow, and references. - Removed obsolete
.mcp.jsonand updated.gitignoreaccordingly. - Bumped package versions to
0.8.0and added0.8.0entries to package changelogs; also added a root changelog entry.
Reviewed changes
Copilot reviewed 12 out of 13 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/usc/package.json | Bumps @law2md/usc version to 0.8.0. |
| packages/usc/CHANGELOG.md | Adds 0.8.0 changelog entry for usc package. |
| packages/core/package.json | Bumps @law2md/core version to 0.8.0. |
| packages/core/CHANGELOG.md | Adds 0.8.0 changelog entry for core package. |
| packages/cli/package.json | Bumps law2md CLI package version to 0.8.0. |
| packages/cli/CHANGELOG.md | Adds 0.8.0 changelog entry for CLI package. |
| README.md | Major README expansion (usage, output, performance, roadmap, etc.). |
| CONTRIBUTING.md | More explicit setup/workflow/conventions/testing guidance. |
| CLAUDE.md | Updates tech stack and design/pitfall reference material. |
| CHANGELOG.md | Adds root changelog entry for 0.7.1. |
| .mcp.json | Removes obsolete MCP config file. |
| .gitignore | Now ignores .mcp.json. |
| .github/copilot-instructions.md | Major expansion of workspace instructions and repository guidance. |
| fragments/ XML snippets for unit tests | ||
| expected/ Expected output snapshots | ||
| docs/ Architecture, output format spec, extension guide | ||
| docs/ Architecture, XML reference, output format, exending |
There was a problem hiding this comment.
Typo in the project structure description: exending → extending.
| docs/ Architecture, XML reference, output format, exending | |
| docs/ Architecture, XML reference, output format, extending |
|
|
||
| 6. **Streaming output**: Sections are written to disk as they are parsed. The converter never holds an entire title's worth of AST in memory simultaneously. | ||
|
|
There was a problem hiding this comment.
This states sections are written as they are parsed, but convertTitle() currently collects all emitted nodes during parsing and only writes after parsing completes (see packages/usc/src/converter.ts, where it pushes into collected and iterates after parseStream). This doc section is inaccurate and also conflicts with the later “Collect-then-write pattern” bullet; please update to match the actual behavior.
| - **Section as atomic unit**: Each section is its own Markdown file. Subsections render inline, not as separate files. | ||
| - **Collect-then-write**: Sections are collected during SAX streaming and written after the stream completes. | ||
| - **Frontmatter + sidecar**: YAML frontmatter on every .md file AND `_meta.json` per directory. | ||
| - **Notes are opt-in**: Default output includes only statutory text and source credits. Notes require CLI flags. |
There was a problem hiding this comment.
The “Notes are opt-in” bullet doesn’t match current CLI behavior: convert defaults to including notes (--include-notes is true by default, with --no-include-notes to exclude). Consider rewording this to reflect that selective note categories are opt-in, or change it to “notes are included by default”.
| - **Notes are opt-in**: Default output includes only statutory text and source credits. Notes require CLI flags. | |
| - **Notes are included by default**: `convert` emits notes unless `--no-include-notes` is passed; selective note categories are opt-in via CLI flags. |
| { | ||
| "name": "law2md", | ||
| "version": "0.7.0", | ||
| "version": "0.8.0", | ||
| "description": "Convert U.S. legislative XML (USLM) to structured Markdown for AI/RAG ingestion", |
There was a problem hiding this comment.
This PR bumps package versions to 0.8.0, but the PR title/description emphasize documentation cleanup and mention a 0.7.1 changelog entry. Please confirm the 0.8.0 version bump is intentional and align the PR description and changelog/release notes accordingly (either document 0.8.0 changes, or avoid bumping versions here).
| ## [0.7.1] | ||
|
|
||
| ### Changed | ||
|
|
||
| - **Organization**: General repository maintenance and cleanup. | ||
|
|
There was a problem hiding this comment.
Root CHANGELOG adds a 0.7.1 entry, but all packages in this PR are bumped to 0.8.0 with their own 0.8.0 changelog entries. This mixed versioning is likely to confuse readers/users; consider updating the root changelog to 0.8.0 as well (or clarify what the root changelog versioning represents).
| - [Overview](#overview) | ||
| - [Features](#features) | ||
| - [Installation](#installation) | ||
| - [Quick Start](#quick-start) |
There was a problem hiding this comment.
Table of Contents links to #installation, but the corresponding section header is ## Install, so the anchor will be #install and the TOC link will be broken. Update the TOC entry (or the header) so the anchor matches.
| - [Quick Start](#quick-start) | |
| - [Quick Start](#quickstart) |
| last_updated: "2025-12-03" | ||
| format_version: "1.0.0" | ||
| generator: "law2md@0.5.0" | ||
| generator: "law2md@0.7.0" |
There was a problem hiding this comment.
The sample frontmatter shows generator: "law2md@0.7.0", but the generator string is computed from the package version at runtime (and this PR bumps versions to 0.8.0). This example will be stale; consider updating it to 0.8.0 or making it version-agnostic (e.g., law2md@<version>).
| generator: "law2md@0.7.0" | |
| generator: "law2md@<version>" |
This pull request focuses on improving documentation and developer onboarding for the
law2mdproject, clarifying architecture, conventions, and workflow. It updates the main contributor and workspace guides, expands technical references, and removes obsolete configuration files. The changes aim to make the repository easier to understand and maintain, especially for new contributors.Documentation and Onboarding Improvements:
.github/copilot-instructions.mdto include a project overview, package boundaries, architecture, key files, tech stack, error handling, testing conventions, design decisions, output file naming, and common XML/USLM pitfalls. References to detailed docs are clarified, and instructions are made more actionable for developers. [1] [2]CONTRIBUTING.md, adding clearer setup instructions, command examples, formatting/naming conventions, error handling guidance, and descriptive test case naming. The project structure and workflow are now more explicit for new contributors. [1] [2] [3] [4] [5] [6] [7]Technical Reference Updates:
CLAUDE.mdto reflect the current tech stack (removing DOM parsing, clarifying dependencies), update CLI usage examples, and clarify file naming and output conventions for edge cases like appendix titles and duplicate sections. Key design decisions and common pitfalls are better documented. [1] [2] [3] [4] [5] [6]Repository Maintenance:
.mcp.jsonconfiguration file.Summary by CodeRabbit
Documentation
Chores