ru-handbook-check¶
Check a repository against the Kokeb Labs handbook rules that a script can decide, and report every finding by rule ID.
The declaration¶
Each repository says what it is in .kokeb/handbook.yml:
---
handbook: "1.0" # the handbook release it follows
kind: driver # driver, library, hal, firmware, tooling, docs or template
level: high # standard, high or safety
waivers: # optional
- rule: KB-DOC-004
reason: Doxygen comments for the v2 register API land with #41.
approved_by: "@N3b3x"
until: 2027-01-31
A rule applies when the repository's kind is in the rule's scope and its level is at or above the rule's lowest level.
What it checks¶
| Rule | Check |
|---|---|
| KB-REPO-002 | The declaration exists and names a handbook release, a kind and a level |
| KB-REPO-003 | Every waiver names a handbook rule, a reason, an approver and a date that has not passed |
| KB-REPO-005 | The root of a driver holds only the committed entries ADR-0011 allows |
| KB-REPO-018 | driver.yml has name, version, bus, mcus, peripheral and kb_core_min, matching cmake/<chip>_build_settings.cmake |
| KB-CPP-001 | The library requires C++20 and compiler extensions are not turned on |
| KB-BLD-002 | No file(GLOB) in CMake outside tests/ and examples/ |
| KB-CPP-002 | No throw, try, catch, typeid or dynamic_cast in inc/ and src/ |
| KB-CPP-003 | No new, delete, malloc and friends, or heap-owning smart pointers in inc/ and src/ |
| KB-ARCH-011 | No virtual in a driver (ADR-0016) |
| KB-CPP-012 | Driver headers include only the target library subset; other target code includes no allocating, throwing or OS header (ADR-0017) |
| KB-REPO-016 | No generated sdkconfig is committed (ADR-0018) |
| KB-DOC-035 | No PDF is committed under docs/ (ADR-0019) |
Code checks read only committed files, with comments and string literals blanked out first, so a word in a
comment or a message never counts. = delete and placement new are not heap use.
How a finding counts¶
- Error (fails the job): the rule is active, or its
enforce_fromdate has passed. - Warning: the rule is still proposed and its
enforce_fromdate is ahead, or it is a should rule. - Notice: a valid waiver covers the rule; the notice quotes the waiver.
Each finding is an annotation on its file and line with the rule's ID, title and a link to its page, and the run summary has the full table.
Where the rules come from¶
The checker and rules.json, a snapshot of the handbook's rules exported by the handbook's own tooling, live in
tools/handbook_check/ in this repository. The workflow checks them out at its own commit, so a caller on @v1
always gets a checker and a rule set that belong together.
Caller¶
jobs:
handbook:
uses: kokeb-labs/ci-tools/.github/workflows/ru-handbook-check.yml@v1
permissions:
contents: read
Add the job to the CI gate's needs.