wayfinder library

Core validation for Wayfinder knowledge bundles.

Used by the wayfinder_cli command and MCP server.

Classes

Assessed
Every rule of profile ran against the bundle.
BlockedByOkf
OKF failed, so no Profile rule ran. profile is the selection that would have been assessed, when there was one, so reports still name it.
BoundBundle
BuiltinCheck
BundleLocation
A bundle-relative path.
CatalogRule
DiagnosticLocation
EffectiveProfile
The Profile a bundle is assessed against: a chain of packages, root ancestor first, plus the project's additions. Contributors declare only their own names; the merge happens here, once.
EngineDiagnostic
NotAssessed
No Profile could be selected; an error diagnostic says why.
OkfFieldEdge
One entry of an OkfLinkField, resolved as okf resolves a source resource.
OkfLinkField
A producer frontmatter key whose value lists typed links, each a mapping with a resource target and a name under nameKey, such as relationships: [{relationship: depends-on, resource: /a.md}].
OtherRevision
"extends": {"git": ..., "ref": ..., "path": ...}: a parent resolved from its own repository and ref.
PackageParent
ProfileAssessment
What the Profile layer of a run did.
ProfileFinding
A deterministic finding of a Profile rule.
ProfilePackage
One Profile at one revision: everything wayfinder validate enforces for it. Every package, including Bitwild, is read by parse and nothing else; the engine embeds no Profile.
ProfileRuleDescriptor
Read-only metadata describing one deterministic Profile rule, mirroring okf's okfSpecRuleDescriptors.
ProfileSelection
What the resolver hands the validator: a Profile to assess, or why there is none.
ProfileSummaryEntry
Something a note rule found that the Profile permits, such as an unresolved planned link. A summary entry is not a finding, so it carries no severity and never affects the Profile state, the gate or the exit status. SARIF reports it as a result of kind informational.
ProfileValidationResult
ProfileValidator
ProjectFileLocation
The project configuration file. path is what reports print: the configured path as the caller spelled it, or the file's basename when it was discovered. file is the file actually read.
ProjectVocabulary
What a project's wayfinder.json adds for one binding: vocabulary and actors, never frontmatter keys or rules.
SameRevision
"extends": {"path": ...}: the package at path, relative to the repository root, in the same repository at the same commit as the child. A repository that hosts several Profiles releases them together.
SchemaCheck
SelectedProfile
UnselectedProfile
Vocabulary
The composed names rules see. Every list is always present, so every slot always has a value and no rule is ever skipped for want of one.
WayfinderActorMetadata
WayfinderBundleBinding
WayfinderDefinition
WayfinderProfileBinding
One profiles.<id> entry: which package, which bundles, and what the project adds. Nothing resolved lives here, and the project never wires a chain: the package names its own parent.
WayfinderProfileSource
A Profile package selected from a Git revision.
WayfinderProjectConfig

Enums

DiagnosticChannel
Where SARIF reports a diagnostic: toolConfigurationNotifications for problems with what the engine was asked to assess, and toolExecutionNotifications for problems while assessing it.
DiagnosticCode
The engine's own reports about a run, as opposed to Profile findings about the bundle. The set is closed. No catalog can declare or suppress these, and their wayfinder/ namespace is not a Profile id.
DiagnosticLevel
How severe a diagnostic is. Wire values follow SARIF notification levels.
GateState
The single outcome of a run, under okf's exit-code contract.
OkfState
ProfileState
RuleSeverity
Slot

Extension Types

ProfileId
A Profile identity in okf's finding-namespace grammar, so the id is used verbatim as the finding namespace (<id>/<rule-slug>), the lock key and the installed skill directory name. The grammar admits no /, . or _, so an id is always a safe single path segment.

Constants

okfPackageVersion → const String
The okf package this engine generates indexes with.
relationshipsLinkField → const OkfLinkField
The relationships frontmatter key (guide §5.5), the one link field the engine projects into facts and the CLI overlays on okf's graph.
supportedOkfRelease → const String
The OKF release whose bundles this engine's facts and index generator understand. An engine capability, not vocabulary.
supportedPackageFormat → const int
The package format this engine evaluates. Engine compatibility is this integer, never a Profile release. A package with another format is refused whole, never partially evaluated.

Functions

compositionFailure(ProfileId id, ProfileCompositionException error) → ({DiagnosticCode code, String message})
The failure validation reports when the chain of id does not compose.
internalErrorJson(String message) → Map<String, Object?>
The JSON of a run that stopped before it had a result: only the wayfinder/internal-error diagnostic and the gate it derives.
internalErrorSarif(String message, {required String toolVersion}) → Map<String, Object?>
The SARIF log of a run that stopped before it had a result: no results, one wayfinder/internal-error execution notification.
okfFieldEdges(OkfBundle bundle, Iterable<OkfLinkField> fields) → List<OkfFieldEdge>
Every edge fields declare in bundle, by concept, then field, then entry order. An entry draws an edge when it is a mapping whose resource is a nonblank string.
toSarif(ProfileValidationResult result, {required String bundlePath, required String toolVersion}) → Map<String, Object?>
result as a SARIF 2.1.0 log, carrying the same findings, summary entries and diagnostics as its JSON.

Exceptions / Errors

BundleBindingException
No binding applies to a bundle; diagnostic says why.
ProfileCompositionException
ProfilePackageException
A malformed package, or one this engine cannot evaluate. Load is the only step that can fail; once a package has parsed, evaluation never throws for any bundle.
WayfinderConfigException
A malformed or unsafe project configuration.