Rules
39 business rules described. A business rule is a condition the business imposes, with what it constrains and what happens when it is broken.
| Business rule | Severity | First line | Links |
|---|---|---|---|
| Accessibility | error | Every screen of the generated site gives a screen reader or keyboard user the same information as everyone else. Five guarantees hold on every page, and the build and the test suite verify them without a browser. | 74 |
| Ambiguous operation | warning | At the rung of the operation matching where a match is found, two operation notes claim the same operation imported from a contract, or one note matches several operations of its API. Nothing is attached: the finding names every candidate, the imported operation stays a separate entity with the properties of the contract only, and the other notes and operations of the API are matched as usual. The operation_id of exactly one operation in each note settles it; a note that names no API and matches several contracts of its source names its API in the api attribute. | 27 |
| Ambiguous relation | info | A link between two entities fell back to the generic relation because no section, no typed attribute and no single allowed relation decided it. It is kept at a capped confidence. The finding is raised by the relation typing step and points at the note the link was read in, on the line of its first located provenance; a link that co-occurrences alone know raises nothing, since a co-occurrence names no file and is unnamed by nature. | 51 |
| API without consumer | warning | An API has no consumer, declared or inferred: no attribute, no section, no mention in another note. | 22 |
| Broken link | error | A markdown link written in a note points to a file that does not exist in its source. The link is not recorded and the reader lands on nothing. | 59 |
| Consumer mismatch | warning | An API declares a consumer that never cites it, or a note cites an API that does not list it. One of the two is out of date. A declared consumer is an identifier, written in full or relative to the source of the API note; a note listed under the ## Consumers section of the API note is declared too; a note cites the API when a serves link between the two was read in that note, the API's own consumers attribute and ## Consumers section being declarations rather than citations. The attribute asks for the reconciliation: an API note without it is left to the API without consumer check. | 22 |
| Conversion failed | warning | An office document could not be converted to PDF: timeout, size, corruption or missing converter. The document stays downloadable, without preview or extracted text. | 59 |
| Cross-source link | warning | A markdown link leaves its source, with the <source>:<path> prefix or with a relative path that climbs above the source root into a sibling source, while inference.cross_source_links is off. The link is not recorded: the model keeps no relation between the two notes until the configuration allows links across sources, or the author links to a note of the same source. The linter in global scope reports the same finding from one repository when the link reaches a note of the published model and that model says it was built with cross-source links off; a link that leaves the source for a file that does not exist is a broken link once such links are allowed. | 34 |
| Disabled plugin | warning | A declared plugin needs a system tool that is not installed on the machine that builds: the build ran the detection command of every system dependency of the manifest, one answered nothing, and the plugin was not registered, so that none of its readers, converters, sources, inference methods, checks, projections or components took part in the build. An optional dependency yields the same finding as info and the plugin stays registered. The fix is the tool on the PATH of the build, or the plugin removed from plugins:; a project whose conversions must run raises the severity to error. | 20 |
| Document without markdown | info | A document has no markdown representation once the twin resources are reconciled: it stands as an entity of its own, or merged with other documents only. Its words are recorded from the text extracted from its PDF or its cues, but nobody wrote about it. The to-do page lists these documents; a note next to the document with the same base name, or declaring it under source, merges with it and lifts the finding. | 30 |
| Duplicate candidate | info | Two resources look like forms of the same document, with a reconciliation score between 0.5 and 0.9. They stay separate until a human decides. | 35 |
| Duplicate identifier | error | Two files resolve to the same identifier, because identifiers strip the extension and the type suffix, or because two notes declare the same id. The first in canonical order is kept. | 14 |
| Invalid encoding | error | A file is not valid UTF-8, a note saved in a single-byte encoding for instance. The file is skipped entirely: nothing of it enters the model, and every link that points to it is reported as a broken link. The linter reports it before the file is pushed, and an .editorconfig with charset = utf-8 keeps the mistake from coming back. | 17 |
| Invalid frontmatter | error | The YAML frontmatter cannot be parsed. The body is still processed; every declared attribute is lost. | 12 |
| Invalid identifier | error | A frontmatter id does not follow the identifier pattern, lowercase letters, digits and hyphens in a first segment, then at least one more segment after a slash. The declared value is ignored and the identifier derives from the source name and the file path, as if no id had been written, so that the page still exists at a predictable address; the finding says which value was refused. | 18 |
| Linter and build parity | error | The local lint says the same thing as the build. For the checks the linter computes in --scope repo, listed as LOCAL_CHECKS by the lint package (E-ENCODING, E-FM-INVALID, E-ID-DUP, E-ID-INVALID, E-LINK-BROKEN), concordance lint on a repository and concordance build on a configuration that declares it as a source produce the same findings: same check, source, path, line and entity, same severity, message and remediation. The build reports more, never less: the checks that need the whole model only exist there. | 35 |
| Missing application | warning | An entity resolves to no application: none on the source, none in a rule, none in frontmatter. | 21 |
| Operation matching | warning | An operation note attaches to the operation imported from the contract of its API on three rungs, tried in order, the first that matches winning: the operation_id of the frontmatter against the operation identifier of the contract; the method and path pair (or port and the title for a SOAP operation) against the operation's; the title of the note in comparison form, spaces and punctuation ignored, against the operation title or its identifier. The note names its API in the api attribute or through a markdown link; a note that names none is a candidate for every API of its source that declares a contract. | 44 |
| Operation unmatched | warning | An operation note that names an API with an imported contract, in its api attribute or through a markdown link, and that none of the three rungs of the operation matching attaches to an operation of that contract. One of two things is true: the operation disappeared from the contract and the note describes something that no longer exists, or the note is ahead of the contract and describes an operation the next version will declare. The build cannot tell which, so the finding says both, and the author decides: retire the note or point it at the operation that replaced its own, or keep it with the operation_id to come until the contract catches up. A note that names no API is not reported: it is a candidate for every contract of its source and may describe an API without a contract. A note taken in an ambiguity is reported by the matching rule instead. | 37 |
| Personal mention detected | info | A personal name was detected in a transcript outside the pseudonymisation dictionary. It is flagged for review before anything is published. | 13 |
20 rules of 39 — pagination by twenty. The Links column counts the related pages, which brings the most central rules of the journey to the top.