okf

Documentation

Overview

Package okf — parser/serializer for the YAML subset used in OKF frontmatter. Parsing and serialization are implemented using Go's standard library only.

Package okf implements the Open Knowledge Format primitives for the Agentic Wiki. Handles concept IDs, raw frontmatter, section extraction, and normalized content-hash.

Index

• Variables
• func ContentHash(content string) string
• func ExtractSection(body string, heading string) (string, bool)
• func IDToPath(id ConceptID) string
• func IsReserved(name string) bool
• func SectionHashes(content string) map[string]string
• func SplitFrontmatter(content string) (frontmatterRaw string, body string, hasFrontmatter bool)
• type ConceptID
  • func PathToID(relPath string) (ConceptID, error)
• type Frontmatter
  • func ParseFrontmatter(raw string) (*Frontmatter, error)
  • func (fm *Frontmatter) CanonicalString() string
  • func (fm *Frontmatter) Delete(key string)
  • func (fm *Frontmatter) Get(key string) (interface{}, bool)
  • func (fm *Frontmatter) Keys() []string
  • func (fm *Frontmatter) Serialize() string
  • func (fm *Frontmatter) Set(key string, value interface{})
  • func (fm *Frontmatter) Type() string
• type Heading
  • func ListHeadings(body string) []Heading

Variables

var (
	ErrNotFound       = errors.New("concept not found")
	ErrStaleWrite     = errors.New("stale write: content-hash mismatch")
	ErrInvalidPath    = errors.New("invalid path")
	ErrInvalidConcept = errors.New("invalid concept")
)

Exported errors used by other packages.

Functions

func ContentHash

func ContentHash(content string) string

ContentHash computes the sha256 (hex) of the content normalized per OKF rules:

• CRLF -> LF
• trailing spaces/tabs stripped per line
• trailing blank lines removed
• frontmatter: canonical key ordering (via ParseFrontmatter/CanonicalString), falling back to raw frontmatter text if parsing fails
• frontmatter: "timestamp:" line always removed to avoid spurious stale_write errors

func ExtractSection

func ExtractSection(body string, heading string) (string, bool)

ExtractSection extracts the content under a markdown heading (matched by exact text) up to the next heading of equal or higher level. Returns the extracted content and true if found.

func IDToPath

func IDToPath(id ConceptID) string

IDToPath converts a ConceptID to the relative path of the corresponding .md file.

func IsReserved

func IsReserved(name string) bool

IsReserved returns true if the file name is reserved (index.md, log.md, _map.md, _archive.md, AGENTS.md).

func SectionHashes

func SectionHashes(content string) map[string]string

SectionHashes computes sha256 hashes (hex) for each heading section of the body. Returns a map of heading_text → hash. Also includes "_full" for the hash of the entire content. Only first- and second-level sections (# and ##) are considered.

func SplitFrontmatter

func SplitFrontmatter(content string) (frontmatterRaw string, body string, hasFrontmatter bool)

SplitFrontmatter separates the raw YAML frontmatter block from the markdown body. The frontmatter is delimited by "---" lines (first and second occurrence). The frontmatter is returned as RAW text without YAML parsing.

Types

type ConceptID

type ConceptID string

ConceptID identifies a concept as a path relative to the KB root without the .md extension.

func PathToID

func PathToID(relPath string) (ConceptID, error)

PathToID converts a relative path (e.g. "maintenance/cert-rotation.md") to the corresponding ConceptID (e.g. "maintenance/cert-rotation"). Returns ErrInvalidPath if the path contains non-kebab-case segments.

type Frontmatter

type Frontmatter struct {
	// contains filtered or unexported fields
}

Frontmatter is an ordered map representing an OKF frontmatter block. Preserves key order and the position of original comments. Supported values: string, []string, nil.

func ParseFrontmatter

func ParseFrontmatter(raw string) (*Frontmatter, error)

ParseFrontmatter parses the raw frontmatter text (without --- delimiters) and returns a structured *Frontmatter.

func (*Frontmatter) CanonicalString

func (fm *Frontmatter) CanonicalString() string

CanonicalString generates YAML text with keys sorted alphabetically and without comments. Used for deterministic content-hash computation.

func (*Frontmatter) Delete

func (fm *Frontmatter) Delete(key string)

Delete removes the key from the frontmatter. It is a no-op if the key does not exist.

func (*Frontmatter) Get

func (fm *Frontmatter) Get(key string) (interface{}, bool)

Get returns the value associated with the key, and true if the key exists.

func (*Frontmatter) Keys

func (fm *Frontmatter) Keys() []string

Keys returns the keys in insertion order (excludes comments).

func (*Frontmatter) Serialize

func (fm *Frontmatter) Serialize() string

Serialize generates the YAML text of the frontmatter in insertion order, preserving original comments. Does not include the --- delimiters. []string values are always serialized as flow lists [a, b, c].

func (*Frontmatter) Set

func (fm *Frontmatter) Set(key string, value interface{})

Set sets the value for a key. If the key already exists, updates the value in place preserving the original position; otherwise appends the key at the end.

func (*Frontmatter) Type

func (fm *Frontmatter) Type() string

Type is a shortcut to retrieve the "type" field as a string. Returns "" if the field is absent or the value is not a string.

type Heading

type Heading struct {
	Level int
	Title string
	Bytes int
}

Heading describes one markdown heading found by ListHeadings, along with the byte size of the section it introduces.

func ListHeadings

func ListHeadings(body string) []Heading

ListHeadings returns every heading in body, in document order, with the byte size of each section — from the heading (excluded) up to the next heading of equal or higher level, or the end of the body. Same section boundary semantics as ExtractSection.