Module okf 

Open Knowledge Format (OKF) support shared across the suite.

OKF v0.1 is a minimal standard for knowledge corpora: a directory tree of Markdown concept files, each carrying a leading YAML frontmatter block (one required field, type; recommended title/description/resource/tags/ timestamp), plus reserved index.md (a directory listing) and log.md (a change history). Cross-links are ordinary Markdown links, either bundle-relative (/tables/customers.md) or document-relative.

This module is the single home for the format: frontmatter detection and field extraction (parse), reserved-file recognition (is_reserved), cross-link extraction (links), bundle conformance (conformance) and broken-link detection (broken_links). It is reused by ct-okf, by the OKF-awareness added to ct-search/ct-tree/ct-view/ct-outline, and by the okf built-in check (check).

Conformance is deliberately permissive (per the spec): a non-reserved .md conforms when it has parseable frontmatter carrying a non-empty type; unknown keys, unknown types, and broken links are tolerated, never fatal.

Structs

Finding

A per-file conformance finding for a bundle.

Frontmatter

The recognised frontmatter fields, extracted from a concept’s YAML block. Unknown keys are preserved in extra, as the spec requires consumers to tolerate and round-trip them.

Link

A Markdown cross-link found in a concept body.

Parsed

A concept’s parsed frontmatter and where it sits in the file.

Constants

RESERVED

Reserved file names with defined structural roles; never concept documents.

Functions

broken_links

Find bundle cross-links whose target file is missing. Bundle-relative (/…) targets resolve against base; document-relative targets resolve against the linking file’s directory. Any fragment (#…) is dropped before resolution. External URLs are ignored by links and never appear here.

build_concept

Build a new concept’s file text: a frontmatter block (a non-empty type is required by OKF) followed by the body, defaulting to a single # title heading when no body is given.

check

Run an okf built-in check: walk the bundle under root/--base and assert every non-reserved .md conforms (parseable frontmatter with a non-empty type); with --strict, also assert no broken bundle cross-links. Returns the probe outcome, a one-line reason, and a violation report. Argument and walk errors are ProbeOutcome::Broken.

check_grammar

The okf check’s introspected grammar (see [crate::deps::grammar]).

conformance

Walk a bundle and judge each .md file’s conformance.

fm_to_json

Render a Frontmatter as a JSON object — only fields that are present appear; unknown keys from extra are included verbatim. Shared so ct-okf and the OKF-aware tools emit metadata the same way.

is_reserved

Whether file_name is an OKF reserved file (index.md / log.md).

links

Extract Markdown [text](target) cross-links from body, skipping external URLs (http(s)://, mailto:) and bare anchors (#…). The kind of relationship is conveyed by prose, not syntax, so links are untyped edges.

log_entry

Prepend a dated, labelled entry to a log.md’s existing text, merging into the same-day section when it is already on top (newest first).

md_selector

Build a .md-restricted walk::Selector under base, optionally narrowed by a name pattern set. Shared by the tool and the built-in check so they select concepts identically.

parse

Parse a concept’s leading frontmatter, or None when the text does not open with a --- fence (the only frontmatter form OKF defines).

render_index

Render an index.md body from (file, title, description) entries.

set_field

Set or update a top-level scalar frontmatter field on a concept’s text, preserving every other byte. Returns the new text and whether an existing key was replaced (false means a new key was appended before the closing fence). Errors when the text has no frontmatter to edit.

today_utc

Today’s date as YYYY-MM-DD (UTC), via Howard Hinnant’s civil-from-days. Shared so log.md entries and timestamps are stamped consistently.

yaml_scalar

Quote a frontmatter scalar value if it would not be a safe bare YAML scalar. Shared by the authoring verbs and the --script engine so a value written by either path round-trips identically.