help

type BookI ¶

type BookI interface {
	// AppId returns the app this book belongs to. Stable across the
	// book's lifetime.
	AppId() (id app.AppIdT)
	// Docs returns the indexed documents in path-sorted order. Triggers
	// a one-shot walk + parse on first call.
	Docs() (docs []DocInfo)
	// Doc returns the parsed markdown document and its DocInfo for the
	// given FS-relative path minus the `.md` suffix (e.g. `"overview"`
	// or `"howto/replay"`). ok=false when the path is not indexed.
	Doc(docPath string) (doc *markdown.Doc, info DocInfo, ok bool)
	// Source returns the raw markdown bytes the doc was parsed from.
	// Consumers that want to display a "view source" toggle (such as
	// the HelpHost app) read from here and feed the bytes through
	// codeview.PrepareMarkdown for syntax-highlighted rendering. The
	// returned slice is owned by the book and MUST NOT be mutated.
	// ok=false when the path is not indexed.
	Source(docPath string) (src []byte, ok bool)
	// HasSection reports whether the document at docPath contains a
	// heading whose slug matches section. ok=false when the doc is
	// absent or the section is unknown. Used by [RefT] consumers to
	// validate cross-document links at write time.
	HasSection(docPath string, section string) (ok bool)
	// Validate reports documentation-standard front-matter conformance
	// problems across every indexed document, in path-sorted order (empty
	// when the book conforms). Operator-facing, so `type: adr` is rejected;
	// see [ValidateDocInfo] for the per-document check. Triggers the
	// one-shot walk on first call, like the other index methods.
	Validate() (problems []Problem)
}

BookI is the parsed help corpus for one app. Implementations are lazy: the first call to BookI.Docs, BookI.Doc, or BookI.HasSection walks the fs.FS, parses every .md file, and caches the result for the book's lifetime. Subsequent calls hit the cache.

Failures during the walk (missing FS entries, parse errors) are logged at Warn but do not poison the cache — the affected file is simply absent from BookI.Docs. Callers that need hard-fail semantics should use the NewBook error return on construction (a nil fs.FS) and treat per-file gaps as drift to be fixed in CI.

func Book(id app.AppIdT) (b BookI, ok bool)

func Books() (books []BookI)

func NewBook(id app.AppIdT, fsys fs.FS) (b BookI, err error)

type DocInfo ¶

type DocInfo struct {
	Path     string
	Title    string
	Type     string
	Status   string
	Sections []SectionInfo
}

DocInfo is the static metadata of one help document. Populated at first-parse time and cached on the BookI for the book's lifetime.

Title resolution order: frontmatter `title:` → first H1 → filename leaf. Type and Status come from the Diátaxis-mandated frontmatter keys ([CLAUDE.md]); empty strings when the doc omits them. Sections is the in-document heading list in document order, suitable as a TOC sidebar source.

type FSImageResolver ¶

type FSImageResolver struct {
	resolver.NoopResolver
	// contains filtered or unexported fields
}

FSImageResolver decodes inline image references in help docs against a backing fs.FS. URL resolution for wikilinks and embeds is delegated to resolver.NoopResolver; only image bytes are served from the FS.

Image refs in markdown — both CommonMark `` and Obsidian `![[file.png]]` — arrive as path strings rooted at the FS root. A leading `/` is stripped so `` and `` resolve to the same FS entry; otherwise paths are interpreted verbatim against fs.ReadFile, which handles nested directories (`assets/diag.png`) naturally.

Relative paths (`../assets/`) are intentionally not supported in M1 — every doc inside one BookI shares the same FS root, so vault-rooted refs are the unambiguous form. Future work can layer per-doc base-path resolution on top if authors want relative refs.

func NewFSImageResolver(fsys fs.FS) (r FSImageResolver)

func (inst FSImageResolver) LoadImage(ref string) (pixels []uint32, widthPx uint32, heightPx uint32, ok bool)

type LibraryI ¶

type LibraryI interface {
	// Book returns the book registered for id, or ok=false when absent.
	// Triggers a one-shot SyncFromRegistry on first call.
	Book(id app.AppIdT) (b BookI, ok bool)
	// Books returns every registered book in AppId-sorted order.
	// Triggers a one-shot SyncFromRegistry on first call.
	Books() (books []BookI)
	// Register inserts an explicitly-built book. Returns an error on
	// nil book or on duplicate AppId (first registration wins).
	Register(b BookI) (err error)
	// SyncFromRegistry walks app.DefaultRegistry and registers a fresh
	// Book for every Manifest with a non-nil Help fs.FS that isn't
	// already registered. Returns the number of books added. Safe to
	// call repeatedly; idempotent past the first call.
	SyncFromRegistry() (added int)
}

LibraryI is the registry of BookI values keyed by app.AppIdT. Implementations auto-sync from app.DefaultRegistry on first read — every registered app.Manifest with a non-nil Help fs.FS becomes a book on first access — so the typical app does not need to call LibraryI.Register explicitly.

Manual registration is supported for tests, special-purpose libraries built around a [Registry] other than DefaultRegistry, and runtime-injected docs (e.g. bundled "About Keelson" content that isn't owned by any single app).

var DefaultLibrary LibraryI = NewLibrary()

func NewLibrary() (l LibraryI)

type Problem ¶

type Problem struct {
	// DocPath is the FS-relative path (minus the `.md` suffix) of the
	// offending document — the same key [BookI.Doc] takes.
	DocPath string
	// Field is the offending front-matter key: "type" or "status".
	Field string
	// Value is the offending value, or "" when the field is absent.
	Value string
	// Message is a self-contained, human-readable description of the breach.
	Message string
}

Problem is one documentation-standard front-matter conformance issue for a single help document, as surfaced by ValidateDocInfo and BookI.Validate. It carries the doc path so a caller iterating a whole book can attribute the breach; field, value, and message come straight from the shared docstd.Violation.

func ValidateDocInfo(info DocInfo) (problems []Problem)

type RefT ¶

type RefT struct {
	AppId   app.AppIdT
	Doc     string
	Section string
}

RefT references one help location: a book (selected by app.AppIdT), a document inside that book (FS-relative path minus the .md suffix, e.g. `"overview"` or `"howto/replay"`), and an optional heading slug inside that document (matches markdown.SlugHeading).

RefT is a plain value: it will round-trip through CBOR on the bus (once the bus subject lands) and across Go function boundaries today. The String form is for debug and log output, not a wire format.

func (inst RefT) IsZero() (zero bool)

func (inst RefT) String() (s string)

type SectionInfo ¶

type SectionInfo struct {
	Slug       string
	Text       string
	Level      uint8
	ByteOffset int
}

SectionInfo describes one top-level heading inside a help document. Slug matches markdown.SlugHeading so RefT.Section values resolve to the same key the markdown widget consumes for in-doc anchors.

ByteOffset mirrors markdown.HeadingInfo.ByteOffset: the heading text's offset within the bytes BookI.Source returns, -1 when the heading has no text. It is what lets a search index (ADR-0164) slice that source into per-section regions without re-parsing.