Expand description
Opinionated bundle health checks, beyond conformance.
validate_bundle enforces only the spec’s hard
requirements and reports soft guidance as warnings. lint_bundle goes
further: it flags the hygiene issues a continuously-authored corpus drifts
into, such as orphan concepts no link or index points at, an index.md
that has fallen behind its directory, or a verification that predates the
last regeneration.
Every finding is tagged with a stable rule code so CI can pin or
silence individual checks. None of them is a conformance failure: a bundle
with lint findings is still conformant if validate_bundle says so, which
is why okf lint is a separate command rather than a stricter
okf validate.
| Code | Severity | Finding |
|---|---|---|
| L1 | warning | missing title |
| L2 | warning | missing description |
| L3 | warning | missing generated (and no legacy timestamp) |
| L4 | info | no verified events, trust tier is unverified |
| L5 | warning | legacy v0.1 timestamp present |
| L6 | warning | legacy v0.1 body # Citations list present |
| L7 | warning | body is empty |
| L8 | warning | body has no top-level # heading |
| L9 | warning | latest verified.at predates generated.at |
| L10 | warning | links to a status: deprecated concept |
| L11 | warning | past stale_after (with --today) |
| L12 | info | status: draft |
| L13 | info | self-link |
| L14 | warning | title shared with another concept |
| L15 | warning | orphan: no inbound links and not listed in any index.md |
| L16 | warning | an existing index.md is out of sync with its directory |
| L17 | warning | broken link to a concept that does not exist |
| L18 | info | frontmatter keys not in canonical preferred order |
| L19 | warning | heading hierarchy drift (heading levels skipped or multiple #) |
| L20 | warning | empty / stub section heading with no content |
| L21 | info | source declared in frontmatter but never cited with footnote |
| L22 | warning | circular concept derivation in sources graph |
| L23 | info | non-standard actor identity in generated, verified, or author |
| L24 | warning | timestamp in generated, verified, or sources is in the future |
| L25 | warning | executor, attester, or computation resource missing on disk |
| L26 | warning | # Computation code block missing language tag |
| L27 | warning | duplicate date heading in log.md |
| L28 | info | trailing whitespace or excess blank lines in markdown body |
Functions§
- lint_
bundle - Lints a loaded bundle, returning all findings.
- lint_
bundle_ at - Lints a bundle, additionally flagging concepts that are stale on
today.