knowledge

package
v1.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 2, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Add 

func Add(root, id string, input NewConcept, force bool) (string, error)

func CanonicalID 

func CanonicalID(value string) (string, error)

func IsSingleBundleRoot 

func IsSingleBundleRoot(root string) (bool, error)

IsSingleBundleRoot reports whether root uses the single-bundle mode.

func Move 

func Move(root, oldID, newID string) (int, error)

func UpdateIndexes 

func UpdateIndexes(root string, checkOnly bool) ([]string, error)

Types 

type Backlink struct {
	Concept *Concept
	Link    Link
}

type Bundle 

type Bundle struct {
	Root     string
	Title    string
	Concepts []*Concept
	ByID     map[string]*Concept
	Markdown map[string]string
}

func Load 

func Load(root string) (*Bundle, error)
func (b *Bundle) Backlinks(id string) ([]Backlink, error)

func (*Bundle) ConceptPath 

func (b *Bundle) ConceptPath(id string) (string, string, error)

func (*Bundle) ConceptsUnder 

func (b *Bundle) ConceptsUnder(prefix string, recursive bool) []*Concept

ConceptsUnder returns concepts in a directory, optionally including nested directories.

func (*Bundle) Get 

func (b *Bundle) Get(id string) (*Concept, error)

func (*Bundle) Graph 

func (b *Bundle) Graph(id string, maxDepth int) ([]GraphNode, error)

func (*Bundle) Outgoing 

func (b *Bundle) Outgoing(id string) ([]Link, error)

type BundleValidationStats 

type BundleValidationStats struct {
	Name                  string
	Root                  string
	MarkdownFiles         int
	ReservedFiles         int
	ConceptFiles          int
	LoadedConcepts        int
	InvalidConceptFiles   int
	LinksChecked          int
	BrokenLinks           int
	StaleGeneratedIndexes int
}

type Concept 

type Concept struct {
	ID          string
	RelPath     string
	AbsPath     string
	Metadata    map[string]any
	Type        string
	Title       string
	Description string
	Tags        []string
	Body        string
	Links       []Link
}

type ConceptRef 

type ConceptRef struct {
	BundleName string
	Bundle     *Bundle
	Concept    *Concept
}

ConceptRef identifies a concept together with the bundle that owns it.

type Confidence added in v1.3.0 

type Confidence int

Confidence is the semantic confidence tier of a match, ordered from strongest to weakest. The enum value is the tier; String returns its stable wire name for rendered JSON. 

const (
	// ConfidenceHigh covers exact and phrase matches.
	ConfidenceHigh Confidence = iota
	// ConfidenceMedium covers structured metadata matches.
	ConfidenceMedium
	// ConfidenceLow covers weak lexical matches.
	ConfidenceLow
)

func (Confidence) String added in v1.3.0 

func (c Confidence) String() string

String returns the stable machine-readable wire name of the tier.

type GraphNode 

type GraphNode struct {
	Concept *Concept
	Depth   int
}

type Issue 

type Issue struct {
	Path    string `json:"path"`
	Message string `json:"message"`
}
type Link struct {
	Label      string
	RawTarget  string
	TargetPath string
	TargetID   string
	External   bool
	Broken     bool
}

type Match added in v1.3.0 

type Match struct {
	MatchedFields []string
	MatchedTerms  []string
	Rank          ScoreRank
	Coverage      float64
}

Match records why a concept matched a query. It is the search evidence exposed in rendered JSON as matched_fields, matched_terms, and matched_rank. Coverage is the fraction of query tokens that matched (0..1) and feeds the confidence tier, so a single tag hit on a three-token query is not medium.

type NewConcept 

type NewConcept struct {
	Type        string
	Title       string
	Description string
	Tags        []string
}

type ScoreRank added in v1.3.0 

type ScoreRank int

ScoreRank is the semantic class of a match, ordered from strongest to weakest. The enum value is the rank; Weight returns its fixed score contribution. Ranks are ordinal, so comparisons like "stronger than a description match" are expressed as rank comparisons instead of magic numbers. 

const (
	// RankExactID is a direct concept-ID lookup, the highest-confidence path.
	RankExactID ScoreRank = iota
	// RankTitlePhrase is the normalized query appearing verbatim in the title.
	RankTitlePhrase
	// RankDescriptionPhrase is the normalized query appearing verbatim in the
	// description.
	RankDescriptionPhrase
	// RankTitle is a token match in the title.
	RankTitle
	// RankTag is a token match in the tags.
	RankTag
	// RankDescription is a token match in the description.
	RankDescription
	// RankID is a token match in the concept ID path.
	RankID
	// RankBody is a token match in the body.
	RankBody
)

func (ScoreRank) Confidence added in v1.3.0 

func (r ScoreRank) Confidence(coverage float64) Confidence

Confidence returns the semantic confidence tier of a match: high for exact and phrase matches and full-coverage metadata matches; medium for metadata matches covering more than half of the query tokens and description matches covering all of them; low for weak lexical matches and sparse hits. Coverage-aware tiers prevent a single tag or title hit on a multi-token query from masquerading as a confident match.

func (ScoreRank) String added in v1.3.0 

func (r ScoreRank) String() string

String returns the stable machine-readable name of the rank.

func (ScoreRank) Weight added in v1.3.0 

func (r ScoreRank) Weight() float64

Weight returns the fixed score contribution of the rank.

type SearchOptions 

type SearchOptions struct {
	Tag   string
	Type  string
	Path  string
	Limit int
}

type SearchResult 

type SearchResult struct {
	Concept    *Concept
	Score      float64
	Match      Match
	BundleName string
}
func Search(bundle *Bundle, query string, options SearchOptions) []SearchResult

Search ranks concepts by lexical relevance. An exact concept-ID query short-circuits with a perfect match; otherwise scoring uses normalized tokens with boundary matching, a phrase bonus, and per-field weights.

type SearchResultRef 

type SearchResultRef struct {
	BundleName string
	Concept    *Concept
	Score      float64
	Match      Match
}

SearchResultRef is a workspace-qualified search result.

type ValidationReport 

type ValidationReport struct {
	Errors   []Issue
	Warnings []Issue
	Stats    ValidationStats
	Bundles  []BundleValidationStats
}

func Validate 

func Validate(root string, strict bool) (ValidationReport, error)

func ValidateWorkspaceRoot 

func ValidateWorkspaceRoot(root string, strict bool) (ValidationReport, error)

ValidateWorkspaceRoot validates a single bundle or all direct child bundles without loading concepts into the in-memory Bundle model first.

func (*ValidationReport) AddError 

func (r *ValidationReport) AddError(path, message string)

func (*ValidationReport) AddWarning 

func (r *ValidationReport) AddWarning(path, message string)

func (ValidationReport) Sort 

func (r ValidationReport) Sort()

func (ValidationReport) Valid 

func (r ValidationReport) Valid() bool

type ValidationStats 

type ValidationStats struct {
	Root                  string
	Mode                  string
	Bundles               int
	MarkdownFiles         int
	ReservedFiles         int
	ConceptFiles          int
	LoadedConcepts        int
	InvalidConceptFiles   int
	LinksChecked          int
	BrokenLinks           int
	StaleGeneratedIndexes int
}

type Workspace 

type Workspace struct {
	Root       string
	SingleRoot bool
	Bundles    []*Bundle
	ByName     map[string]*Bundle
}

Workspace coordinates one bundle or a directory containing direct child bundles.

func LoadWorkspace 

func LoadWorkspace(root string) (*Workspace, error)

LoadWorkspace loads root as one bundle or discovers its direct child bundles.

func (*Workspace) Mode added in v1.3.0 

func (w *Workspace) Mode() WorkspaceMode

Mode reports how this workspace interprets its root.

func (*Workspace) QualifyID 

func (w *Workspace) QualifyID(bundleName, localID string) string

QualifyID converts a bundle-local ID to the CLI ID for this workspace.

func (*Workspace) ResolveConcept 

func (w *Workspace) ResolveConcept(value string) (*ConceptRef, error)

ResolveConcept resolves a local ID in a single bundle or a qualified ID in a workspace.

func (*Workspace) ResolveDirectory 

func (w *Workspace) ResolveDirectory(value string) (*Bundle, string, string, error)

ResolveDirectory resolves a workspace directory path to its owning bundle and local prefix. An empty prefix in workspace mode refers to the workspace itself and returns a nil bundle.

func (*Workspace) Search 

func (w *Workspace) Search(query string, options SearchOptions) ([]SearchResultRef, error)

Search searches all bundles, applying a qualified path filter when supplied.

func (*Workspace) Validate 

func (w *Workspace) Validate(strict bool) (ValidationReport, error)

ValidateWorkspace validates each bundle and prefixes issues with its workspace path.

type WorkspaceMode added in v1.3.0 

type WorkspaceMode int

WorkspaceMode describes how a workspace root is interpreted: as one bundle or as a directory of child bundles. The enum value is the mode; String returns its stable wire name for rendered JSON. 

const (
	// ModeWorkspace treats the root as a directory of child bundles.
	ModeWorkspace WorkspaceMode = iota
	// ModeSingle treats the root as one bundle.
	ModeSingle
)

func (WorkspaceMode) String added in v1.3.0 

func (m WorkspaceMode) String() string

String returns the stable machine-readable wire name of the mode.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.