Documentation
¶
Overview ¶
Package okf implements the Open Knowledge Format (OKF) v0.1 conformance check (ADR 0023). Given a frozen corpus it returns a Report: the three §9 normative rules and a bundle-level verdict. It is pure domain — it imports only the standard library and the sibling corpus/identity packages (ADR 0004) and does no I/O and no YAML parsing of its own (the parser already recorded whether each document's frontmatter was present and whether it parsed).
The three conformance rules (OKF v0.1 §9, verbatim in docs/research/okf-spec-pinned.md):
R1. Every non-reserved `.md` file contains a PARSEABLE YAML frontmatter block. R2. Every such frontmatter block contains a non-empty `type` field. R3. Every reserved file (index.md, log.md) follows its §6/§7 structure.
Reserved filenames are EXACTLY index.md and log.md (case-insensitive); every other `.md` — README.md included — is a concept document. Conformance is the WHOLE of the verdict: broken links, orphans, and the rest of matlatl's health signals are deliberately NOT part of it (OKF §9 says consumers MUST NOT reject a bundle for a broken link), so they live entirely outside this package.
Index ¶
Constants ¶
const ( // FrontMatterAbsent means the document had no frontmatter fence block at all. FrontMatterAbsent = "absent" // FrontMatterUnparseable means a frontmatter block was present but did not // decode (malformed YAML, or stripped by the oversized-frontmatter guard). FrontMatterUnparseable = "unparseable" )
Frontmatter-state values for a rule-R1 violation, carried on Violation.State.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Report ¶
type Report struct {
Conformant bool
DetectedVersion string
// The three §9 rule buckets, each sorted by (Doc, Line) for determinism.
MissingFrontmatter []Violation // R1
MissingType []Violation // R2
ReservedStructure []Violation // R3
}
Report is the result of an OKF conformance check. Conformant is set by Check: true iff all three violation lists are empty (the zero-value Report has Conformant=false, which is why callers must run Check rather than rely on the zero value). DetectedVersion is the okf_version declared in the bundle-root index.md frontmatter (OKF §11), or "" when none is present.
type Violation ¶
type Violation struct {
Doc identity.DocumentID
Line int
State string // R1 only: FrontMatterAbsent | FrontMatterUnparseable
Reason string // R2/R3 only: human-readable cause
}
Violation is one OKF conformance failure, pinned to a document and (when meaningful) a source line. For a rule-R1 (missing-frontmatter) violation the State field carries "absent" or "unparseable"; for R2 (missing-type) and R3 (reserved-file-structure) the Reason field carries a human-readable cause. The unused field is "" for its rule.
Source Files