ci: assert that a repo path quoted in a doc or build file exists - #773
Conversation
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Caution Review failedFailed to post review comments. GitHub was unavailable or timed out while CodeRabbit was posting the review. Please request a new review later if the pull request still needs one. This happened while posting 3 inline comments. Use ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (5)
Included review availability: 1 review is currently available. Based on recent review activity, included reviews refill at 2 per hour. ⏰ Context from checks skipped due to timeout. (14)
|
| Layer / File(s) | Summary |
|---|---|
Reference scanner and resolver scripts/check_references.py |
Added Git-aware file discovery, path extraction, root-relative and file-relative resolution, exclusions, reference kinds, and validation reporting. |
CI wiring and reference corrections .github/workflows/ci.yml, Bdd/Targets/FreeRtos/README.md, docs/misra-deviations.md |
The docs-build job runs scripts/check_references.py. Broken README links and the retired MISRA deviation path now reference the correct locations. |
Naming and path review guidance .coderabbit.yaml |
Tier 1 naming guidance now uses linkage. The separate outX rule was removed. Review instructions now cover repository-relative paths in CMake, make, and workflow files. |
Estimated code review effort: 3 (Moderate) | ~25 minutes
Merge Risk: 🟡 Moderate · up to d6da3
The PR adds repository-reference validation and updates naming guidance, but the current implementation can still miss stale references to root-level files, while the configuration wording and file matching scope need tightening. Merge should wait for these bounded correctness and configuration issues to be addressed.
Sequence Diagram(s)
sequenceDiagram
participant CI as docs-build
participant Validator as scripts/check_references.py
participant Repository as Git repository
CI->>Validator: Run reference validation
Validator->>Repository: Read tracked files and repository paths
Repository-->>Validator: Return path data
Validator->>Validator: Extract and resolve references
Validator-->>CI: Return success or exit status 1
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)
| Check name | Status | Explanation | Resolution |
|---|---|---|---|
| Docstring Coverage | Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%. | Write docstrings for the functions missing them to satisfy the coverage threshold. |
✅ Passed checks (4 passed)
| Check name | Status | Explanation |
|---|---|---|
| Title check | ✅ Passed | The title uses Conventional Commits format and clearly states the main change: validating repository paths in documentation and build files. |
| Description check | ✅ Passed | The description completes all required sections and provides clear purpose, implementation details, test evidence, and affected areas. |
| Linked Issues check | ✅ Passed | Check skipped because no linked issues were found for this pull request. |
| Out of Scope Changes check | ✅ Passed | Check skipped because no linked issues were found for this pull request. |
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
- Create stacked PR
- Commit on current branch
🧪 Generate unit tests (beta)
- Create PR with unit tests
- Commit unit tests in branch
ci/quoted-path-gate
Comment @coderabbitai help to get the list of available commands.
1 participant
Purpose
Two pieces of repository hygiene, no issue behind either.
.coderabbit.yamlhad drifted fromdocs/NAMING.mdin two places, so reviewswere being held to a rule the repository no longer states. And a repo-relative
path written in prose or in a build file is checked by nothing:
mkdocs build --strictresolves Markdown links between pages,docs-links.ymlresolvesexternal URLs, and neither sees a path in code font in a sentence, in a CMake
list, in a Compose mount or in a path filter. A rename leaves those green and
pointing nowhere — which is what four of them were doing.
Change Description
.coderabbit.yaml. Tier 1 is stated asdocs/NAMING.mdnow states it:decided by linkage, not by whether an integrator is meant to call the
identifier, so a library-internal class spanning two translation units from a
Core/Source/*Private.htakes the prefix. TheoutXout-parameter clause isremoved — the S23.22 audit deleted that rule from
NAMING.md, and the public APIcarries two conventions (
size_t* bytesRead,uint8_t* keyOut) with which onewins still open; naming either here would decide by config what nobody has
decided. A
path_instructionsentry now covers build files, which matched noentry at all. It includes
*.mkalongsideMakefile:solidsyslog.mkis themake integration this repository actually ships.
The gate.
scripts/check_references.pyextracts repo-relative paths fromthe tracked
*.md,*.yaml,*.yml,*.cmakeandCMakeLists.txtfiles andasserts each exists, wired into
docs-buildbesidecheck_platform_docs.py.It runs in 0.1 s.
The extraction is deliberately narrow, because a heuristic loose enough to need
a long exception list is one that gets switched off. Three rules do the work,
and each was added to kill a class of noise the previous run surfaced rather
than chosen up front:
of the repository, or
./... That drops#include <mbedtls/ssl.h>, everyURL and every
and/orwithout naming any of them. It costs a top-leveldirectory renamed wholesale.
checkout, so asserting it would be asserting that the build ran.
run:/command:/entrypoint:, isshell rather than repository text: its paths are relative to a working
directory the check cannot know. Nothing is lost, because a shell command
naming a path that does not exist fails the job it sits in — which is exactly
what a CMake list or a Compose mount does not do.
trailing slash that says it is a directory. This separates
ci/pin-action-shas(a branch),
Bdd/Targets/Common/BddTargetInteractive(a component) andCore/Platform(two directories written as one) from actual paths, at the costof a directory referred to without its slash.
Five exceptions remain, each commented with why, and all five are one thing: a
document quoting a path as some other file would write it, in order to state a
rule about how paths are written. The docstring says that past a handful the
extraction is wrong and should be tightened rather than the list grown.
Structured for #740, which is the same idea one level up — assert that a
SolidSyslogsymbol named in the docs resolves to a declared one. Same files,same extraction pass, same exception problem. It is a second
KINDSrow, not asecond script:
Kindholds how a reference is found, how it resolves, what tosay when it does not, and an
unassertablehook that is handed every referenceof its kind at once so a check needing git asks git once. #740 is deliberately
not implemented here.
Test Evidence
Run over the tree before wiring in. The first pass found 75, all but a handful
of them noise; each tightening above removed a class, ending at 8: 4 real stale
references and 4 illustrative ones. Fixed in this PR, which is the evidence the
gate works:
Bdd/Targets/FreeRtos/README.md— three links../../deep where the filesits three levels down.
Bdd/README.md,docs/containers.mdand.devcontainer/devcontainer.jsonall resolved to nothing on GitHub and in aclone. Line 64 of the same file already had it right.
docs/misra-deviations.mdD.004 — namedCore/Source/RecordStore.c, whichhas been
SolidSyslogRecordStore.csince the prefix rule this PR's firstcommit restates.
Negative test: a code span, a Markdown link and a fenced-block path, each naming
a file that does not exist, were added to
docs/bdd.mdand all three werecaught. A run outside a git checkout exits 1 rather than finding nothing and
passing.
python3 scripts/check_references.pyandpython3 scripts/check_platform_docs.pyboth green. markdownlint-cli2 v0.22.1 clean over the two changed
.mdfiles. Noproduction source changed, so no clang-format reflow and no
misra_renumber.py.Areas Affected
.coderabbit.yaml,scripts/, thedocs-buildCI lane, and two documentationfiles. No production source, no public API, no build behaviour.
Summary by CodeRabbit
New Features
Documentation
Chores