ci: make doc-lint output actionable, and reseed the baseline - #385
Merged
mvandeberg merged 1 commit intoAug 25, 2026
Merged
Conversation
The gate printed its comparison as JSON -- ~250 lines of which 8 mattered, none carrying a line number or a quote, so you still had to grep the corpus to find what broke. It now prints one block per finding: severity, file:line, rule, and an excerpt. --show-baseline adds the grandfathered findings still present, as warnings; --json restores the old dump. Under Actions each gated finding is also a ::warning annotation on the diff. Line numbers cannot live in the fingerprint -- keying on them once renamed 27 grandfathered findings from a comment-only insertion (df68f9b) -- so baseline.mjs gains --details, a sidecar the comparator requests and the reseed does not. Fingerprints are byte-identical either way. Docstring findings resolve back to the .hpp through a line map from extract-docstrings.mjs, then narrow within the block by locating the excerpt, since a doc comment can be 100 lines long. The gate is report-only by maintainer decision. Attention keys on --gate and failure on --strict, so restoring the block is one word. The Vale steps treat exit 1 (alerts found, the steady state) as success and propagate exit 2, so an annotation from them now means Vale actually broke. selftest.mjs runs in CI, non-blocking -- it is the only thing between a silent linter regression and a green run. Step names are standardised on "Docs:", "Lint:" and "Reseed:"; the reseed locates its --gate spec by matching the gate step's name, so that anchor moves too. Stops linting detail/ prose, which mrdocs.yml marks implementation-defined: 11 of 73 extracted files, plus 33 doc comments in `namespace detail` blocks inside public headers. The extractor now clears its output directory -- it never did, so a header that stopped producing output left its last .adoc linted forever. Vale vocabulary gains the domain prose it was missing and the coroutine keywords. The keyword split is the point: io_result has a reference page, so bare in prose it is a missing cpp: link and B1 says fix it; co_await has no page, so that alert can never be actioned. One real misspelling is fixed rather than whitelisted, and STYLE_GUIDE E4's a11y carve-out is extended to the three rule classes it did not name. Reseeds doc/lint/baseline.json from CI: retires 3845 stale fingerprints, adds 107. Eight match the gate spec and are PR cppalliance#383's, accepted as backlog rather than blocking an already-merged PR. The one-shot reseed blockquote is removed as it instructed.
|
An automated preview of the documentation is available at https://385.capy.prtest3.cppalliance.org/index.html If more commits are pushed to the pull request, the docs will rebuild at the same URL. 2026-08-25 21:43:18 UTC |
|
GCOVR code coverage report https://385.capy.prtest3.cppalliance.org/gcovr/index.html Build time: 2026-08-25 21:57:15 UTC |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #385 +/- ##
========================================
Coverage 98.09% 98.09%
========================================
Files 130 130
Lines 6291 6291
========================================
Hits 6171 6171
Misses 120 120
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
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
2 participants
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.
The gate printed its comparison as JSON -- ~250 lines of which 8 mattered, none carrying a line number or a quote, so you still had to grep the corpus to find what broke. It now prints one block per finding: severity, file:line, rule, and an excerpt. --show-baseline adds the grandfathered findings still present, as warnings; --json restores the old dump. Under Actions each gated finding is also a ::warning annotation on the diff.
Line numbers cannot live in the fingerprint -- keying on them once renamed 27 grandfathered findings from a comment-only insertion (df68f9b) -- so baseline.mjs gains --details, a sidecar the comparator requests and the reseed does not. Fingerprints are byte-identical either way. Docstring findings resolve back to the .hpp through a line map from extract-docstrings.mjs, then narrow within the block by locating the excerpt, since a doc comment can be 100 lines long.
The gate is report-only by maintainer decision. Attention keys on --gate and failure on --strict, so restoring the block is one word. The Vale steps treat exit 1 (alerts found, the steady state) as success and propagate exit 2, so an annotation from them now means Vale actually broke. selftest.mjs runs in CI, non-blocking -- it is the only thing between a silent linter regression and a green run. Step names are standardised on "Docs:", "Lint:" and "Reseed:"; the reseed locates its --gate spec by matching the gate step's name, so that anchor moves too.
Stops linting detail/ prose, which mrdocs.yml marks implementation-defined: 11 of 73 extracted files, plus 33 doc comments in
namespace detailblocks inside public headers. The extractor now clears its output directory -- it never did, so a header that stopped producing output left its last .adoc linted forever.Vale vocabulary gains the domain prose it was missing and the coroutine keywords. The keyword split is the point: io_result has a reference page, so bare in prose it is a missing cpp: link and B1 says fix it; co_await has no page, so that alert can never be actioned. One real misspelling is fixed rather than whitelisted, and STYLE_GUIDE E4's a11y carve-out is extended to the three rule classes it did not name.
Reseeds doc/lint/baseline.json from CI: retires 3845 stale fingerprints, adds
107. Eight match the gate spec and are PR #383's, accepted as backlog rather than blocking an already-merged PR. The one-shot reseed blockquote is removed as it instructed.