fix: re-sync vendored v0.4 schema; correct docs that contradict shipped behavior - #16
Merged
Conversation
…adict shipped behavior The vendored schema copy had drifted from its declared source of truth: `npm run check:sync` was RED on main (verified in a clean checkout of origin/main, not just locally) because dspack 0.4.3 added the `requiredCategories` / `required-composition` rule branch and the byte copy was never re-synced. `dspack-export validate` therefore validated against a schema the canonical one had moved past. Re-synced with the repo's own `scripts/check-sync.mjs --write`; check:sync green, 139 tests pass. Documentation corrected where it stated the opposite of what ships: - docs/handbook.md claimed "Status: experimental (0.2.0-alpha.0). Not on npm" — it is 0.5.0 and published — and that it emits **dspack v0.2** when SPEC_VERSION has been '0.4' since 0.3.0. - docs/handbook.md told users "regeneration overwrites the output file — keep hand edits in a separate copy". The opposite is true and has been since 0.4.0: `generate` REFUSES when the output carries human-authored content, with deliberately no force override. That claim invited a defensive workaround against data loss that cannot happen. - CONTRIBUTING.md listed the merge workflow as deferred roadmap; it shipped in 0.4.0 as `regenerateSections()` (library API; no CLI flag yet — stated). - README now documents `init --force`, implemented and previously in no doc. - docs/alpha-decision.md marked as a point-in-time record with its two superseded claims named, rather than rewriting a dated decision log. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR re-syncs the vendored dspack v0.4 JSON Schema to match the upstream schema (fixing check:sync drift) and updates documentation to accurately reflect the currently shipped/published behavior of dspack-export.
Changes:
- Re-synced
src/emit/schema/dspack.v0.4.schema.jsonto include the latest v0.4 rule/schema updates (notably therequiredCategoriesbranch underrequired-composition). - Updated docs to reflect that the tool ships on npm at
0.5.0, emits dspack v0.4, and that regeneration refuses to overwrite hand-authored content (withregenerateSections()as the library API path). - Documented
init --forcein the README (matches existing CLI behavior).
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| src/emit/schema/dspack.v0.4.schema.json | Updates the vendored v0.4 schema to align validation with the upstream dspack spec (fixes committed drift). |
| README.md | Documents dspack-export init --force usage in the quickstart snippet. |
| docs/handbook.md | Corrects handbook claims about publication/version/spec output and clarifies regeneration/refusal behavior and merge workflow. |
| docs/alpha-decision.md | Adds a “historical record” note to prevent outdated alpha-era claims from being read as current behavior. |
| CONTRIBUTING.md | Updates references to emitted dspack version and notes shipped regenerateSections() workflow (library API only). |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Found during an ecosystem-wide documentation audit.
Implementation defect (not just docs).
npm run check:syncis RED onmain— verified in a clean checkout oforigin/main, so this is committed drift, not a local artifact. dspack 0.4.3 added therequiredCategories/required-compositionbranch and the vendored byte copy was never re-synced, sodspack-export validatevalidated against a schema the canonical one had moved past. Re-synced with the repo's ownscripts/check-sync.mjs --write. check:sync green, 139 tests pass.Docs that stated the opposite of what ships:
docs/handbook.md: "Status: experimental (0.2.0-alpha.0). Not on npm" → it is 0.5.0 and published; and "generates a dspack v0.2 snapshot" →SPEC_VERSIONhas been'0.4'since 0.3.0.docs/handbook.md: "regeneration overwrites the output file — keep hand edits in a separate copy". The opposite is true since 0.4.0:generaterefuses when the output carries human-authored content, with deliberately no force override. The old text invited a defensive workaround against data loss that cannot happen.CONTRIBUTING.md: the merge workflow listed as deferred roadmap → shipped in 0.4.0 asregenerateSections()(library API; no CLI flag yet, stated honestly).README.md: documentsinit --force, which is implemented and appeared in no document.docs/alpha-decision.md: marked as a point-in-time record naming its two superseded claims, rather than rewriting a dated decision log.Not touched: the
types/exportsgap (documented library types aren't resolvable from the package entry) — a packaging change, filed separately rather than folded into a docs PR.🤖 Generated with Claude Code