v0.17.1: embedded, queryable docs with a coverage invariant (REQ-DOCS-001) - #43
Merged
Conversation
…Q-DOCS-001) Modelled on `rivet docs`: varve's documentation ships INSIDE the binary (include_str! — no files, no network, air-gapped) and is queryable. `varve docs` lists topics; `varve docs <topic>` shows one (21 subcommands + 6 concepts: pins, realms, layers, trust-roots, payload-kinds, air-gap); `varve docs --grep` searches. Coverage is a MECHANICAL INVARIANT: `varve docs check --coverage` walks the clap subcommand tree, `--strict` exits non-zero on any undocumented command — a CI gate (rust job) + a unit test, so a new subcommand cannot ship undocumented. Documentation-as-invariant, the same "mechanical not prose" spine as review-check/claim-check. REQ-DOCS-001 verified; 10 test suites, clippy/fmt clean, --locked synced, rivet validate + verification-evidence (116) + claim-check (13) green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019TNtfRjLNhEz82G2ggeeNu
…Q-DOCS-001) Clean-room review of `varve docs` returned PASS but found one real overclaim: REQ-DOCS-001 promised a machine-readable `--format json` that did not exist (requirement-vs-implementation drift — the honesty thesis exists to catch this). Fixed before release rather than struck, since "directly query them" was the point (rivet-docs parity): - `--format json` (TDD, RED first): docs::render_json emits the topic list (slug+title) or a single topic with its full body; two new tests (topic_list_renders_as_machine_readable_json, single_topic_renders_as_json_with_body); wired into the Docs command + handler, exercised end to end; bad format rejected. - Narrowed the "walks the clap subcommand tree" wording (requirement + module doc) to "top-level subcommands", matching the non-recursive coverage check. VER-REVIEW-v0.17.1 records the verdict as a first-class rivet artifact (DD-019). rivet validate PASS; verification-evidence 118 steps; claim-check 13; review-check 6 verdicts, no advisory warning; fmt/clippy/test all green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019TNtfRjLNhEz82G2ggeeNu
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
1 participant
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.
What
varve docs— varve's own documentation, embedded in the binary and queryable, modelled onrivet docs. Closes #28.include_str!'d into the binary — no files, no network. 21 top-level subcommands + 6 concepts (pins, realms, layers, trust-roots, payload-kinds, air-gap).varve docslists;varve docs <topic>shows one;varve docs --grep <q>searches bodies;varve docs --format jsonemits the same content for machine queries (rivet-docs parity).varve docs check --coverageenumerates the CLI's top-level subcommands and reports any without a topic;--strictexits non-zero. Wired as a CI gate (rust job, both OSes) and a unit test, so a new subcommand cannot ship undocumented — the same "mechanical, not prose" spine as review-check / claim-check.Traceability
--format jsonthat did not exist — fixed before release (implemented via TDD, not struck), plus a wording narrowing ("top-level subcommands", matching the non-recursive check).Gate (local, verified exit codes)
rivet validatePASS ·rivet check verification-evidence118 steps · claim-check 13 · review-check 6 verdicts, no advisory warningFalsification
Adding a new
varvesubcommand without a matchingdocstopic makesvarve docs check --coverage --strictexit non-zero and failsevery_cli_subcommand_has_a_documented_topic. If both stay green after such a change, the invariant is broken.🤖 Generated with Claude Code