knowledge

Documentation

Index

• func Fingerprint() (string, error)
• func FingerprintDir(root string) (string, error)
• func FirstSentence(text string) string
• type Index
  • func Load(root string) (*Index, fs.FS, error)
  • func (i *Index) ApplyProfiles(ids []string) error
  • func (i *Index) Body(kind, id string) string
  • func (i *Index) Pattern(id string) (Pattern, bool)
  • func (i *Index) PatternExists(id string) bool
  • func (i *Index) Reference(id string) (Reference, bool)
  • func (i *Index) ReferenceExists(id string) bool
  • func (i *Index) Rule(id string) (Rule, bool)
  • func (i *Index) RuleExists(id string) bool
  • func (i *Index) Skill(id string) (Skill, bool)
  • func (i *Index) SkillExists(id string) bool
  • func (i *Index) SkillsOrdered() []Skill
  • func (i *Index) Summary(kind, id string) string
  • func (i *Index) Workflow(id string) (Workflow, bool)
  • func (i *Index) WorkflowExists(id string) bool
• type Pattern
• type Profile
• type Reference
• type RouterBaseline
• type RouterBaselineEntry
• type RouterDispatchRow
• type RouterOrderStep
• type RouterSpec
• type Rule
• type Skill
  • func (s Skill) Merged() bool
• type SkillOverride
• type Workflow

Functions

func Fingerprint

func Fingerprint() (string, error)

Fingerprint digests the standards this binary EMBEDS.

why: the digest travels INSIDE the binary, so it needs no record file beside it - which removes the whole class of "record missing versus unreadable" ambiguity a sidecar file would have to distinguish.

func FingerprintDir

func FingerprintDir(root string) (string, error)

FingerprintDir digests the standards tree under root on disk (root/standards), producing a value comparable to Fingerprint.

func FirstSentence

func FirstSentence(text string) string

FirstSentence returns text up to and including the first sentence-ending period, or text unchanged when it has none. A period ends a sentence only when followed by whitespace or end of string; one inside a dotted identifier (_test.go, http.DefaultClient) is always followed by more identifier characters, so it is skipped instead of mistaken for a boundary.

Types

type Index

type Index struct {
	Rules      []Rule
	Patterns   []Pattern
	Workflows  []Workflow
	Skills     []Skill
	Profiles   []Profile
	References []Reference
	Router     RouterSpec
	// contains filtered or unexported fields
}

Index is the parsed knowledge base: typed items, by-id maps for cross-reference resolution, and the markdown bodies of rules/patterns/workflows for transclusion.

func Load

func Load(root string) (*Index, fs.FS, error)

Load returns the Index and the templates filesystem. With root == "" it reads the embedded snapshot; otherwise it reads <root>/knowledge from disk, so a rule edit can be exercised without rebuilding the binary.

func (*Index) ApplyProfiles

func (i *Index) ApplyProfiles(ids []string) error

ApplyProfiles rewrites the composition lists of the skills targeted by the named profiles, in place, so a subsequent render composes the variant rules/patterns. It returns an error for an unknown profile or an override of an unknown skill; composed-id resolution is still verified at render time.

func (*Index) Body

func (i *Index) Body(kind, id string) string

Body returns the markdown body of a rule/pattern/workflow, without frontmatter.

func (*Index) Pattern

func (i *Index) Pattern(id string) (Pattern, bool)

func (*Index) PatternExists

func (i *Index) PatternExists(id string) bool

func (*Index) Reference

func (i *Index) Reference(id string) (Reference, bool)

func (*Index) ReferenceExists

func (i *Index) ReferenceExists(id string) bool

func (*Index) Rule

func (i *Index) Rule(id string) (Rule, bool)

func (*Index) RuleExists

func (i *Index) RuleExists(id string) bool

func (*Index) Skill

func (i *Index) Skill(id string) (Skill, bool)

func (*Index) SkillExists

func (i *Index) SkillExists(id string) bool

func (*Index) SkillsOrdered

func (i *Index) SkillsOrdered() []Skill

SkillsOrdered returns skills sorted by Order then ID, so the router and listings present them in composition order.

func (*Index) Summary

func (i *Index) Summary(kind, id string) string

Summary returns the distilled blockquote summary of a rule/pattern/workflow, or "" when its body carries none.

func (*Index) Workflow

func (i *Index) Workflow(id string) (Workflow, bool)

func (*Index) WorkflowExists

func (i *Index) WorkflowExists(id string) bool

type Pattern

type Pattern struct {
	ID           string   `yaml:"id"`
	Name         string   `yaml:"name"`
	Description  string   `yaml:"description"`
	Tags         []string `yaml:"tags,omitempty"`
	Dependencies []string `yaml:"dependencies,omitempty"`
	Composes     []string `yaml:"composes,omitempty"`
	References   []string `yaml:"references,omitempty"`
}

Pattern is an implementation recipe that shows how to apply the rules.

type Profile

type Profile struct {
	ID          string                   `yaml:"id"`
	Axis        string                   `yaml:"axis"`
	Description string                   `yaml:"description"`
	Overrides   map[string]SkillOverride `yaml:"overrides,omitempty"`
}

Profile is an install-time customization (e.g. a code-layout variant) that overrides what selected skills compose, so one knowledge base serves several project shapes.

type Reference

type Reference struct {
	ID    string `yaml:"id"`
	Title string `yaml:"title"`
	URL   string `yaml:"url"`
	Note  string `yaml:"note,omitempty"`
}

Reference is an external canonical source a rule or pattern can cite; the renderer surfaces cited references under "## References" in a generated skill.

type RouterBaseline

type RouterBaseline struct {
	Always      []RouterBaselineEntry `yaml:"always"`
	CommitLast  []RouterBaselineEntry `yaml:"commit_last"`
	Conditional []RouterBaselineEntry `yaml:"conditional"`
}

RouterBaseline groups the router's always-load baseline skills, the commit-last skills, and the conditionally-loaded ones.

type RouterBaselineEntry

type RouterBaselineEntry struct {
	Skill string `yaml:"skill"`
	Note  string `yaml:"note"`
}

RouterBaselineEntry is one always-load or conditionally-loaded baseline skill with the short reason the router prints next to it.

type RouterDispatchRow

type RouterDispatchRow struct {
	Signal string   `yaml:"signal"`
	Skills []string `yaml:"skills"`
	Note   string   `yaml:"note,omitempty"`
}

RouterDispatchRow maps a task signal to the skills it should load, with an optional parenthetical note for the conditional nuance.

type RouterOrderStep

type RouterOrderStep struct {
	Skills []string `yaml:"skills"`
	Note   string   `yaml:"note"`
}

RouterOrderStep is one layer of the composition order: the skills applied at that layer and the reason they come there.

type RouterSpec

type RouterSpec struct {
	Baseline RouterBaseline      `yaml:"baseline"`
	Dispatch []RouterDispatchRow `yaml:"dispatch"`
	Order    []RouterOrderStep   `yaml:"order"`
}

RouterSpec is the data behind the project-router skill's baseline, dispatch table, and composition order, so the rendered router can be filtered to only the skills actually being installed.

type Rule

type Rule struct {
	ID           string   `yaml:"id"`
	Name         string   `yaml:"name"`
	Description  string   `yaml:"description"`
	Tags         []string `yaml:"tags,omitempty"`
	Dependencies []string `yaml:"dependencies,omitempty"`
	Linters      []string `yaml:"linters,omitempty"`
	// Analyzers lists the ids of this repo's own analyzers (registered under
	// internal/analysis) that enforce this rule, as opposed to Linters, which
	// names external golangci-lint linters. A rule with neither carries no
	// machine-checked enforcement.
	Analyzers  []string `yaml:"analyzers,omitempty"`
	References []string `yaml:"references,omitempty"`
}

Rule is a mandatory, enforceable engineering rule.

type Skill

type Skill struct {
	ID               string   `yaml:"id"`
	Name             string   `yaml:"name"`
	Description      string   `yaml:"description"`
	Triggers         []string `yaml:"triggers,omitempty"`
	AlwaysLoad       bool     `yaml:"always_load"`
	Order            int      `yaml:"order"`
	ComposeRules     []string `yaml:"compose_rules,omitempty"`
	ComposePatterns  []string `yaml:"compose_patterns,omitempty"`
	ComposeWorkflows []string `yaml:"compose_workflows,omitempty"`
	ComposeSkills    []string `yaml:"compose_skills,omitempty"`
	// NoMerge renders composed rules/patterns per source instead of merging
	// them section-by-section. The zero value keeps the merging default, so
	// the field states the departure rather than the norm.
	NoMerge bool `yaml:"no_merge,omitempty"`
}

Skill is a generated capability that composes rules, patterns, and workflows.

func (Skill) Merged

func (s Skill) Merged() bool

type SkillOverride

type SkillOverride struct {
	ComposeRules    []string `yaml:"compose_rules,omitempty"`
	ComposePatterns []string `yaml:"compose_patterns,omitempty"`
}

SkillOverride is a profile's replacement of a skill's composition lists. An empty list leaves that dimension unchanged.

type Workflow

type Workflow struct {
	ID               string   `yaml:"id"`
	Name             string   `yaml:"name"`
	Description      string   `yaml:"description"`
	Tags             []string `yaml:"tags,omitempty"`
	Steps            []string `yaml:"steps,omitempty"`
	ComposesRules    []string `yaml:"composes_rules,omitempty"`
	ComposesPatterns []string `yaml:"composes_patterns,omitempty"`
}

Workflow is an ordered sequence that composes rules and patterns for a task.