feat: spec coverage map, held to the spec by tests - #21
Merged
Conversation
The api-spec-change workflow opens an issue every time the Kit spec moves. Triaging it means answering one question per changed endpoint: does the CLI cover this? Ten open issues asked that question and there was nowhere to record the answer, so the same review happened again each time. spec/coverage.js records it. Every operation in spec/v4.json maps to the command that reaches it, or to a NOT_EXPOSED entry with a reason. scripts/spec-coverage.test.js keeps the map honest: - every spec operation appears in the map - no entry names an operation the spec dropped - every command named in the map exists in the command tree A spec change that adds or removes an endpoint now fails the suite and names it, rather than waiting for someone to notice. The map covers all 73 operations, with no gaps. To make the third check possible, command tree construction moved out of bin/kit.js into src/program.js. bin/kit.js builds and parses. Tests can now walk the whole tree, which also gets checks for missing descriptions and duplicate sibling names. README and the Claude Code skill document every new command.
This was referenced Aug 20, 2026
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.
Part 8 of 8. Base: #20. This is the branch that stops these issues from recurring.
The problem
The
api-spec-changeworkflow opens an issue every time the Kit spec moves. Triage means answering one question per changed endpoint: does the CLI cover this?Three of the ten open issues were almost entirely description changes. Issue #12 listed 30 endpoints. Issue #13 listed 5. Issue #7 listed 15. Together they carried 38 endpoints with no code change to make, only a review to repeat. There was nowhere to record the answer, so the review started from scratch each time.
What this adds
spec/coverage.jsrecords the answer. Every operation inspec/v4.jsonmaps to the command that reaches it, or to aNOT_EXPOSEDentry with a reason.scripts/spec-coverage.test.jskeeps the map honest. It asserts three things.A spec change that adds or removes an endpoint now fails the suite and names the endpoint. A renamed command fails check 3. The map cannot drift.
The map covers all 73 operations, with no gaps. Writing it is what found the missing snippets, posts, and account commands in the earlier parts of this stack.
Refactor
Check 3 needs the command tree without parsing argv. Tree construction moved out of
bin/kit.jsintosrc/program.js.bin/kit.jsnow builds the tree and parses it, in five lines.This also allowed three checks on the whole tree: no missing descriptions, no duplicate sibling names, and a valid version string.
Docs
The README and the Claude Code skill document every command that this stack added.
Review notes
Tests: 368 before, 378 after.
Suggested triage for the next spec-change issue:
npm test.NOT_EXPOSEDentry with a reason.The stack
Merge from the top down. Each part builds on the one above it.
Base branch:
mainfor part 1, the previous part's branch for the rest.GitHub retargets each base to
mainas the part below it merges.