Validation¶

kac validate checks every record in a corpus against the schema its type declares, and kac checks lists every check that run can report. A corpus is one repository of knowledge records kept in git, and a record is one Markdown document in it. This page lists what validation is built to do, and the scenario proving each behaviour. validate, checks and Checks own the full statement of each one.

What it does¶

It checks the schema before any record, and reports each finding against the schema file that declares it. What the schema is held to
It passes a corpus with no fault, a record in a sub-folder of its type folder included. from: sub-path
It checks each type is both a page and a folder, or neither. The shape on disk
It checks a type's template without counting it as a record. What discovery excludes
It checks every file generate writes into still has both markers of each block, and checks its links. Generated block markers
It checks a record's filename, id, H1, identity line and sections against its type. The three id styles
It refuses a field the type derives from the folder when an author writes it, in a record or a template. A derived field
It checks each frontmatter value against its field: enum, list, pattern, floor, date and timestamp. A type's own rules
It reports frontmatter that does not parse as one finding, and checks nothing else in that record. Which check reports a fault
It checks each id is used once, each reference resolves to a record of the type its field names, and each reciprocal field agrees. Faults nothing else would catch
It checks a field mirroring a section, or the lines carrying a label, agrees with that section or those lines. Referring to an id
It checks the parts a type keeps: a clause table's shape, ids and modals, a term's heading and the words under it, and a rule's id and bullets. Referring to an id
It holds each citation of a part to the part it names, in a code span, a link, or beside a link. Referring to an id
It reports one fault once, under the check that owns it. Which check reports a fault
It warns, without failing, on an unused link definition, a list out of order, a Y-statement outside its bounds and a value below its floor. A run that finds faults
It reports a warning a record names in accepts: as info, with the reason, and warns on an entry matching no warning on its record. The accepts field
With --since, it compares each record with its state at that revision, paired by id. It fails a change in substance to a decided ADR or a published postmortem, and a clause id or a rule id gone from an active policy or standard. It warns on a record deleted while in force. Comparing with a base revision
kac checks lists each check with its severity and what it proves, read from the corpus's own .schema/, a type the corpus declares itself included. checks
kac checks lists a C# rule under the check it emits, and leaves out a rule with no severity. checks
kac checks opens no record. checks

What it refuses¶

kac checks exits 1 where the checks table on a type page disagrees with the catalogue: a check with no row, a row for a check kept off the page, or a row for a check the schema does not declare. checks
validate refuses an accepts: entry naming acceptance-stale, a check that reports errors or only info, or an id no check reports. The accepts field
validate --since exits 1 where git cannot resolve the ref, and names it. Comparing with a base revision

Specified by¶

Schema.feature:

A schema that promises what the tool cannot deliver is reported against the file that says so
A part line naming a list field is reported against the type, not the record filling it

Clean.feature:

The clean baseline validates with no findings
A record filed in a sub-folder validates, at one level and at two

Shape.feature:

A type is stood up as both a page and a folder, or as neither
Every file carrying a generated block is checked for its markers, and for its links
A type's template is checked without being counted as a record

Structure.feature:

A document with no H1 is an error, and its missing Y-statement is a warning
An id disagreeing with its filename is flagged on the id alone
An empty section is reported, and the wording follows what the author can do about it
A mnemonic id is checked for shape, case and agreement with the filename
A slug id is checked for its alphabet and for agreement with the whole filename
An identity line is required beneath the H1, and is reported once when malformed
Each half of the identity line is held to the frontmatter separately
A status is checked for agreement first, then for being upper-case
The mnemonic prefix is excluded from the slug-length measurement
A mis-cased id label is flagged wherever a reader meets it
A label the style admits is held against the document it leads to
A field the type derives from the folder is not the author's to write
A template carrying a derived field is reported, not only a record
The whole corpus produces exactly these findings and nothing else

ValueChecks.feature:

An out-of-range, capitalised enum trips both enum checks
A scalar where a list is declared trips the list check
Unparseable frontmatter short-circuits to a single finding
A field pattern applies to each list entry, not to the list as a whole
A list shorter than its declared floor is reported against the field
A well-formed date that names no day is reported
A field pattern on a scalar field applies to its value
An actor field without its prefix is refused
A timestamp is held to its shape and then to the calendar
The corpus as a whole produces exactly these findings and nothing else

Graph.feature:

A duplicated id is reported against the later document
A reference to an id nothing carries is reported once, whether or not the field reciprocates
A reference that resolves to a document of the wrong type is reported, and reported once
A reciprocated supersede chain reports nothing at either end
A field reconciles against the section it names, whichever section that is
A field reconciles against the lines carrying its label, whichever label that is
A field naming a part refuses the record named whole
The whole graph produces exactly these findings and nothing else

Parts.feature:

The section must hold a table, headed as the columns are read, with rows in it
An empty clause section is reported by the check that can say what belongs there
A clause id is a code span, matches the type's pattern, and is used once
A clause opens with a modal, and the binding levels are the bold ones
Disorder is reported once, against the row that breaks the grouping
A second modal in one row is two obligations sharing an id
A citation is held to the clause it names, and to the document that carries it
A part id written beside a link is resolved as a citation
A citation separated by a colon is told the form to write
A signpost in a clause reaches the clause it names
Two clauses sharing an id signpost each other
A clause id repeated in another policy with no signpost is reported once for the two
Terms are addressed by the anchor their heading slugs to
A term declared by a heading is held to carrying something under it
Every bullet under a rule heading is held to a modal in bold capitals
A list written inside a rule's bullet is refused
A rule heading opening with no id is refused
A parts section holding no headings is told what belongs there
The whole corpus produces exactly these findings and nothing else

Warnings.feature:

An unused link definition and a verdict-less alternative both warn
A list out of alphabetical order warns once, naming the entry that belongs earlier
Numbers in a list entry compare as numbers, not as text
A Y-statement past the ceiling its type declares warns, naming the count and the limit
A Y-statement short of its moves warns, naming each move that is absent
A value below its field's floor is reported against each record carrying it
The corpus as a whole warns eight times and errors not at all

Accepts.feature:

An accepted warning is reported as info, with its reason
An entry matching no warning on its record is stale
A stale entry accepts the warning once its record raises it again
An entry naming anything but a check that warns is refused
An entry with no reason, or a blank one, accepts nothing

Checks.feature:

The catalogue lists each check with the severity it reports at and what it proves
A type the corpus declares itself has its checks in the catalogue
A rule implemented in C# is listed under the check it emits
A rule with no severity is not in the catalogue
The catalogue opens no record and reports no fault in one
A check declared for the type page with no row in the checks table fails the run
A check kept off the type page that has a row in the checks table fails the run
A row in the checks table for a check the schema does not declare fails the run

Unspecified¶

Eight validate fixtures with no scenario: frontmatter that breaks, values: $corpus.x in its three forms, the descriptor's targets, expression rules, shortcodes, and type adoption. Imports specifies imports and import-versions. #247
Most rules a type declares for itself, and core checks such as key-order, are tripped by a golden fixture and named in no scenario. kac checks lists them, and the golden suite's coverage gate fails a check no fixture trips.
The checks --since runs. The history fixture trips each of them, HistoryTests and SubstanceTests pin what a change in substance is, and CommandsTests pins the exit code for a ref git cannot resolve.
validate exiting 1 exactly when it finds an error. The scenarios call the validator and not the command, so the golden suite is where the exit code is asserted.
How validate groups its findings, and the shape of --json. Both are printed only.
How kac checks prints the catalogue, as a grid or as --json. Both are printed only.

Where to go next¶

Checks says where each check comes from, and how to add one.