okfrules

README

okfrules

The invariants every OKF bundle in this fleet keeps and the spec deliberately does not. §11 forbids rejecting a bundle over an unknown type, a missing key or a broken link, so a local vocabulary is only a rule while something asserts it — two bundles drifted before anything did.

okf.MainWith(os.Args[1:], os.Stderr, okfrules.Standard())

A repo that is not Go installs the binary instead of building a checker:

go install github.com/fairyhunter13/okfrules/cmd/okfrules@v0.2.0
okfrules check -Werror knowledge
okfrules -strict check -Werror knowledge

Rule	Refuses
ResourceResolves	a resource: naming a path that is gone
TypeVocabulary	a type outside the skills' table
VerifiedWellFormed	a verified: stamp not naming a human:, or older than generated.at
StaleAfterHasAReason	a stale_after with no sources: naming what expires
IndexHeadingsAreSingularTypes	## Decisions where the table says Decision
LogFrontmatter	a log.md missing type: Log or its title
NoIntraBundleWikilinks	[[name]] inside a bundle — link with markdown, or name the home
LogVerbs	a log entry led by something outside the four verbs

Standard() is the first seven. NoIntraBundleWikilinks joined it in v0.2.1, when the conversion it was waiting on finished and all ten bundles measured zero; before that it would have been enforced only in the two repos that build their own checker, which is the half of the fleet least likely to drift.

Strict() adds LogVerbs alone, and that one is opt-in for a different reason: two logs lead 47 entries with a sentence, and rewriting dated history to satisfy a closed vocabulary falsifies the record. It is not staging for a conversion that will happen.

Everything is okf.Error. These are not the spec's advisory half: each one says a concept is describing something that is not there, or is filed where nothing will find it.

Documentation

Overview

Package okfrules holds the invariants every bundle in this fleet keeps but the OKF spec deliberately does not: §11 forbids rejecting a bundle over an unknown type, a missing key or a broken link, so a local vocabulary is only a rule while something asserts it. Two bundles drifted before anything did.

Index

• Variables
• func IndexHeadingsAreSingularTypes(types []string) okf.BundleRule
• func LogFrontmatter(b okf.Bundle) []okf.Finding
• func LogVerbs(verbs []string) okf.BundleRule
• func NoIntraBundleWikilinks(b okf.Bundle) []okf.Finding
• func ResourceResolves(d okf.Doc) []okf.Finding
• func StaleAfterHasAReason(d okf.Doc) []okf.Finding
• func Standard() okf.Rules
• func Strict() okf.Rules
• func TypeVocabulary(types []string) okf.Rule
• func VerifiedWellFormed(d okf.Doc) []okf.Finding

Variables

var (
	DefaultTypes = []string{
		"Decision", "Component", "Interface", "Constraint", "Policy", "Runbook",
		"Skill", "Glossary Term", "Attested Computation", "Scenario", "Defect",
	}
	DefaultLogVerbs = []string{"Creation", "Update", "Deprecation", "Remove", "Verified"}
)

The vocabularies the okf-knowledge-bundle and okf-bootstrap skills tabulate.

Functions

func IndexHeadingsAreSingularTypes

func IndexHeadingsAreSingularTypes(types []string) okf.BundleRule

IndexHeadingsAreSingularTypes keeps the index's groups joinable across bundles. The level is free — an index may open with a title and an orienting paragraph — but "Decisions" is a group nothing else can join.

func LogFrontmatter

func LogFrontmatter(b okf.Bundle) []okf.Finding

LogFrontmatter: `title` is what the bootstrap template prescribes and what the two newest bundles dropped. Nothing noticed, because nothing looked.

func LogVerbs

func LogVerbs(verbs []string) okf.BundleRule

LogVerbs holds the log to its four verbs. The log is the bundle's history and a free-text verb makes it unreadable as a series.

func NoIntraBundleWikilinks

func NoIntraBundleWikilinks(b okf.Bundle) []okf.Finding

NoIntraBundleWikilinks refuses `[[name]]` inside a bundle. OKF's graph is ordinary markdown links, which okf resolves and reports on; a wikilink is invisible to it, so a target that stops existing goes quiet instead of warning. A reference into another home keeps the syntax with its home named — `[[memory:some-note]]` — which is the half no checker running in CI can resolve anyway.

func ResourceResolves

func ResourceResolves(d okf.Doc) []okf.Finding

ResourceResolves refuses a concept whose `resource:` names a path that is gone. A concept describing something that no longer exists is the one kind of rot a checker can prove, and the fix is always cheaper than the bypass: repoint it, mark the concept deprecated, or drop the key, which is optional.

func StaleAfterHasAReason

func StaleAfterHasAReason(d okf.Doc) []okf.Finding

StaleAfterHasAReason keeps the date for genuine shelf life — a vendor EOL, a certificate — by requiring the external thing that expires to be named. A date set because a concept felt old is a re-verification treadmill nobody asked for, and two of 242 concepts carry one at all.

func Standard

func Standard() okf.Rules

Standard is what a bundle can adopt today without a bulk edit first. Measured over all ten fleet bundles, these fire twice in total, and both are real. A repo with a local rule appends to the returned lists rather than rebuilding them.

func Strict

func Strict() okf.Rules

Strict adds the one rule two bundles cannot take: their logs lead 47 entries with a sentence, and rewriting dated history to satisfy a closed vocabulary falsifies the record. It stays opt-in for that reason rather than as a staging area — a rule no bundle can ever adopt is not waiting for anything.

func TypeVocabulary

func TypeVocabulary(types []string) okf.Rule

TypeVocabulary refuses a `type` outside the fleet's table. `type: Constraints` is the drift this catches: a group nothing joins up across bundles.

func VerifiedWellFormed

func VerifiedWellFormed(d okf.Doc) []okf.Finding

VerifiedWellFormed refuses a stamp an agent could have written. v0.2 splits provenance from trust: `generated:` says who wrote a concept and `verified:` who confirmed it, so a stamp naming a model, or naming nobody, is the whole key defeated.