okf

README

okf

A checker for OKF v0.2 bundles — directories of markdown with YAML frontmatter.

go install github.com/fairyhunter13/okf/cmd/okf@v0.2.0
okf check knowledge          # conformance errors exit 1
okf check -Werror knowledge  # warnings exit 1 too

Pin the tag, don't take @latest: this binary decides whether a consumer's CI is green, and @latest lets that verdict change with no commit in the repo it gates.

Only §11's three rules are errors: a concept needs a non-empty type, index.md carries no frontmatter (bar okf_version at the root), and log.md headings are YYYY-MM-DD. Dangling links, bundle-absolute links, stale stale_after and orphans are warnings — §11 forbids rejecting a bundle over them, and TestSeverityNeverEscalates keeps it that way.

Conformance is pinned to Google's four reference bundles in testdata/google/ rather than to a reading of the spec: whatever the checker rejects there is a bug in the checker.

Repo-local rules

An invariant the spec cannot express goes in as a Rule instead of upstream:

findings, err := okf.CheckBundle("knowledge", time.Now().UTC(), myRule)

Rules run on concepts only, never on index.md or log.md. To ship them in the CLI, call okf.Main(os.Args[1:], os.Stderr, myRule) from a local main.

An invariant over the reserved files, the link graph, or any two concepts at once needs the whole bundle, which is what BundleRule is for:

okf.MainWith(os.Args[1:], os.Stderr, okf.Rules{
	Doc:    []okf.Rule{myRule},
	Bundle: []okf.BundleRule{myBundleRule},
})

Bundle findings are appended after the per-concept ones and sorted among themselves, so adding one never moves a line the stock check already prints — TestStockCheckOutputIsByteIdentical holds that.

Fleet sweep

okf sweep --roots ~/git/github.com/fairyhunter13,~/go/src/github.com/fairyhunter13
okf sweep --roots ~/git/github.com/fairyhunter13 --memory ~/.claude/memory --json

Every directory under a root holding both .git and a knowledge/ sibling is a repo, so an eleventh is picked up the day it gets a bundle and there is no registry to drift. Per repo it reports the check verdict, field coverage, expired stale_after, unresolved [[memory:…]] references, and the gates: a hook that runs okf (directly, through a symlinked script, or through make), a workflow step, and every version literal found. A hook present but not executable is reported as such rather than as a gate — git skips it silently. More than one pin is printed as drift.

--memory is where [[memory:…]] resolves; unset, every such reference reports unresolved rather than being skipped, because the four profile homes differ and a verdict depending on which one ran would be no verdict.

Sweep exits 0 on findings. It is a report, not a gate: a red not attached to a change is the accumulating advisory the severity split exists to avoid. Exit 1 means the sweep itself did not run.

Documentation

Overview

Package okf checks OKF v0.2 bundles.

The spec is deliberately permissive: only three rules are conformance failures. That split is why findings carry a severity — everything beyond §11 is advice and must never fail a build. A repo whose graph carries an invariant the spec cannot express passes it to CheckBundle as a Rule.

Index

• func Main(args []string, w io.Writer, rules ...Rule) int
• func MainWith(args []string, w io.Writer, rules Rules) int
• func Parse(text string) (map[string]any, string, error)
• type Bundle
  • func (b Bundle) Concepts() []Doc
  • func (b Bundle) Find(rel string) (Doc, bool)
• type BundleRule
• type Doc
• type Finding
  • func CheckBundle(root string, today time.Time, rules ...Rule) ([]Finding, error)
  • func CheckBundleWith(root string, today time.Time, rules Rules) ([]Finding, error)
  • func (f Finding) String() string
• type RepoReport
  • func Sweep(roots []string, memoryDir string, today time.Time) ([]RepoReport, error)
  • func (r RepoReport) PinDrift() []string
  • func (r RepoReport) Ungated() bool
• type Rule
• type Rules
• type Severity
  • func (s Severity) String() string

Functions

func Main

func Main(args []string, w io.Writer, rules ...Rule) int

Main runs the `okf check` CLI and returns the process exit code. A repo with its own rules wires them in here rather than forking the command.

func MainWith

func MainWith(args []string, w io.Writer, rules Rules) int

MainWith is Main with bundle-wide rules as well.

func Parse

func Parse(text string) (map[string]any, string, error)

Parse splits an OKF document into its YAML frontmatter and body. A document with no frontmatter block yields a nil map and no error; whether that is a violation depends on the filename, which Parse does not know.

Types

type Bundle

type Bundle struct {
	Root string
	Docs []Doc // walk order, which is lexical by path
}

Bundle is every parsed document in one root, index.md and log.md included.

func (Bundle) Concepts

func (b Bundle) Concepts() []Doc

Concepts returns the documents that are not index.md or log.md.

func (Bundle) Find

func (b Bundle) Find(rel string) (Doc, bool)

Find returns the document at this bundle-relative path, or false.

type BundleRule

type BundleRule func(Bundle) []Finding

BundleRule is a caller-supplied check over a whole bundle. A Rule runs per concept and so cannot see the reserved files, the link graph, or any pair of concepts at once.

type Doc

type Doc struct {
	Root string         // bundle root, as given to CheckBundle
	Rel  string         // bundle-relative path, slash-separated
	FM   map[string]any // frontmatter
	Body string
}

Doc is one parsed concept, handed to a Rule.

type Finding

type Finding struct {
	Path string
	Sev  Severity
	Msg  string
}

func CheckBundle

func CheckBundle(root string, today time.Time, rules ...Rule) ([]Finding, error)

CheckBundle walks a bundle root and reports conformance errors (§11) and advisory warnings, plus whatever the caller's rules report.

func CheckBundleWith

func CheckBundleWith(root string, today time.Time, rules Rules) ([]Finding, error)

CheckBundleWith is CheckBundle with bundle-wide rules as well. Their findings are appended after the per-concept ones and sorted among themselves, so adding one cannot move a line the stock check already prints.

func (Finding) String

func (f Finding) String() string

type RepoReport

type RepoReport struct {
	Path     string         `json:"path"`
	Bundle   string         `json:"bundle"`
	Concepts int            `json:"concepts"`
	Errors   int            `json:"errors"`
	Warnings int            `json:"warnings"`
	Findings []string       `json:"findings,omitempty"`
	Gates    []string       `json:"gates,omitempty"`
	Pins     []string       `json:"pins,omitempty"`
	Stale    []string       `json:"stale,omitempty"`
	Memory   []string       `json:"unresolved_memory,omitempty"`
	Coverage map[string]int `json:"coverage,omitempty"`
}

func Sweep

func Sweep(roots []string, memoryDir string, today time.Time) ([]RepoReport, error)

Sweep reports every bundle under roots. It runs the stock check only: the shared rules live in a module that imports this one, so grading them here would be a cycle.

func (RepoReport) PinDrift

func (r RepoReport) PinDrift() []string

PinDrift names each module this repo pins at more than one version. Two pins are not drift once a repo runs both okf and okfrules; two versions of one module are, whichever files they came from.

func (RepoReport) Ungated

func (r RepoReport) Ungated() bool

Ungated is the finding the sweep exists for: a bundle nothing checks is not a clean bundle, it is an unmeasured one.

type Rule

type Rule func(Doc) []Finding

Rule is a caller-supplied check over one concept. It runs on concepts only, never on the reserved index.md and log.md. A Finding with an empty Path is stamped with the concept's.

type Rules

type Rules struct {
	Doc    []Rule
	Bundle []BundleRule
}

Rules is what a caller passes to CheckBundleWith and MainWith.

type Severity

type Severity int

const (
	Warning Severity = iota
	Error
)

func (Severity) String

func (s Severity) String() string