Skip to content

feat: spec coverage map, held to the spec by tests - #21

Merged
imjohnbo merged 1 commit into
catchup/07-account-purchasesfrom
catchup/08-coverage-map
Aug 20, 2026
Merged

feat: spec coverage map, held to the spec by tests#21
imjohnbo merged 1 commit into
catchup/07-account-purchasesfrom
catchup/08-coverage-map

Conversation

@imjohnbo

@imjohnbo imjohnbo commented Aug 20, 2026

Copy link
Copy Markdown
Owner

Part 8 of 8. Base: #20. This is the branch that stops these issues from recurring.

The problem

The api-spec-change workflow 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.js records the answer. 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. It asserts three things.

  1. Every spec operation appears in the map.
  2. No entry names an operation that the spec dropped.
  3. Every command that the map names exists in the command tree.

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.js into src/program.js. bin/kit.js now 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:

  1. Run npm test.
  2. Read the failure. It names each added or removed endpoint.
  3. Add a command, or add a NOT_EXPOSED entry with a reason.

The stack

Merge from the top down. Each part builds on the one above it.

PR Contents
1 #14 Client query support and shared helpers
2 #15 Sequence CRUD and sequence emails
3 #16 Posts and snippets
4 #17 Broadcast filters, account-wide stats, link clicks
5 #18 Subscriber slim listing, warnings, filter
6 #19 Tag rename, remove-by-email, bulk delete
7 #20 Account endpoints and purchase create
8 #21 (this one) Spec coverage map and its tests

Base branch: main for part 1, the previous part's branch for the rest.
GitHub retargets each base to main as the part below it merges.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant