fix(docs-check): tighten --coverage rule 3 + add --warn-only mode (#248)#250
Merged
fix(docs-check): tighten --coverage rule 3 + add --warn-only mode (#248)#250
Conversation
Two fixes to `rivet docs check --coverage` (the gate from #241): * B5 — rule 4 (umbrella mapping via `COVERAGE_TOPIC_MAP`) now requires the parent topic body to mention the child subcommand by name as a whole word, case-insensitive. A catch-all `cli` mapping that doesn't reference the family is no coverage at all. With the current TOPICS registry this surfaces `lsp` and `batch` as additional gaps (was 48/81 covered; now 46/81). * B6 — replace the implicit two-state warn/strict pattern with three explicit modes: --coverage print, exit 0, no annotations (local use) --coverage --warn-only print + emit ::warning::file=…::… GitHub Actions annotations per gap, exit 0 (CI rollout — surface gaps inline on PRs without failing the build) --coverage --strict print, exit 1 on any uncovered (enforcing CI) `--warn-only` and `--strict` are mutually exclusive (clap-enforced). CI workflow now uses `--warn-only` explicitly so the contract is legible at the call site rather than relying on the previous default warn-on-failure semantics. The `rivet docs docs-coverage` topic and the docs::TOPICS body are updated to describe the three modes and the rule-4 body-mention check. Tests: * 6 new unit tests for the body-mention rule (positive/negative, case-insensitive, whole-word, plus a direct test of the `topic_body_mentions` helper). * Integration: `coverage_warn_only_emits_github_annotations` asserts at least one `::warning file=…::` line is printed and exit is 0. * Integration: `coverage_strict_currently_fails_on_main` pins exit 1 behaviour while the inventory has gaps. * Integration: `coverage_warn_only_and_strict_are_mutually_exclusive` pins clap conflict-rejection. * Integration: existing `coverage_default_exits_zero_no_annotations` asserts no `::warning::` lines in the default mode. Closes #248. Implements: REQ-007
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
⚠️ Performance Alert ⚠️
Possible performance regression was detected for benchmark 'Rivet Criterion Benchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.
| Benchmark suite | Current: ec1e8a4 | Previous: b7a17be | Ratio |
|---|---|---|---|
store_insert/10000 |
15885926 ns/iter (± 1427903) |
10641021 ns/iter (± 264093) |
1.49 |
link_graph_build/10000 |
35895303 ns/iter (± 4115915) |
22660622 ns/iter (± 884929) |
1.58 |
validate/10000 |
16841744 ns/iter (± 4432787) |
12248917 ns/iter (± 180828) |
1.37 |
This comment was automatically generated by workflow using github-action-benchmark.
📐 Rivet artifact deltaNo artifact changes in this PR. Code-only changes (renderer, CLI wiring, tests) don't touch the artifact graph. |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
3 tasks
avrabe
added a commit
that referenced
this pull request
May 2, 2026
* chore(release): v0.8.0 — dogfood follow-ups Workspace, vscode-rivet, and npm root package versions bumped to 0.8.0. Platform packages stay on the release-npm.yml override path. What's in 0.8.0: - fix(docs): stale literals + extend rivet docs check (#252, closes #247). Six embedded-doc literals fixed, plus three new invariants (EmbeddedVersionLiterals, EmbeddedFlagReferences, EmbeddedTodoMarkers) to prevent the class of drift from re-shipping. - feat(docs-check): tighten --coverage rule 4 + --warn-only (#250, closes #248). Rule 4 now requires child name to appear in parent body (catches false-positives on lsp + batch). New three-mode semantics: default silent / --warn-only with annotations / --strict fail. - feat(cli): cited-source --strict, --strict-cited-source-stale, schema migrate --list (#251, closes #249). Read-only audit gate for cited-source drift; promotable stale severity; recipe discovery. Trace: skip * ci: ignore RUSTSEC-2026-0114 (wasmtime 42.x table-allocation panic) New wasmtime advisory published 2026-04-30, blocking 0.8.0 CI. Rivet's wasmtime usage is behind an optional wasm feature gate and doesn't allocate large wasmtime tables, so the panic case isn't reachable. Follow-up issue will track upgrading to wasmtime >=43.0.2. Trace: skip
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.
Closes #248.
Summary
Two fixes to
rivet docs check --coverage(the gate from #241):B5 — Rule 3 too generous. The
COVERAGE_TOPIC_MAPumbrella ruleused to be "if the parent has a topic, the child is covered." That
marked
lsp,batch, etc. as covered viaclieven though theclitopic body doesn't actually mention them. The rule now alsorequires the parent topic body to contain the child subcommand name
as a whole word, case-insensitive (
\b<name>\b). A catch-allumbrella that doesn't reference the family is no coverage at all.
B6 —
--coveragehad no GitHub-annotation surface. Theprevious default warn-on-failure pattern ran the gate but exited 0
silently, with no way to surface gaps inline on PRs. Replaced with
three explicit modes:
--coverage--coverage --warn-only::warning file=…::…per gap--coverage --strict--warn-onlyand--strictare clap-enforced mutually exclusive.The CI workflow now uses
--warn-onlyexplicitly so the contract islegible at the call site.
Before / after coverage on main
Coverage: 48/81 (59%), 33 uncovered.Coverage: 46/81 (56%), 35 uncovered —lspandbatchsurface as gaps now that the umbrella rule no longer hides them
(rule 3 tightening increases the uncovered count, as expected).
Test plan
cargo check— cleancargo clippy --workspace --all-targets -- -D warnings— cleancargo fmt --all— cleancargo test -p rivet-cli— all tests pass (12 new unit + 8integration tests, including 6 new rule-3 unit tests and 3 new
integration tests for
--warn-onlyand clap mutual-exclusion)rivet docs check --coverage— prints, exits 0, no annotationsrivet docs check --coverage --warn-only— prints + 35::warning::annotations, exits 0rivet docs check --coverage --strict— prints, exits 1rivet docs check --coverage --warn-only --strict— clap rejectswith conflict error, exits 2
rivet docs check(no flags) — unchanged, doc-check PASSRelated
rivet docs docs-coveragetopic now describes the three modesand the rule 3 body-mention check.
🤖 Generated with Claude Code