Documentation
¶
Overview ¶
Package facts is StageFreight's single fact-resolution dispatch.
Every templated surface — badge values, scribe bodies, notification text — resolves its {tokens} through one Registry instead of each surface keeping a private pass list. A Registry holds a set of Resolvers; each Resolver owns one or more fact families (the token prefixes it resolves) and declares the families it DEPENDS ON. The Registry applies them in topological order, so a fact whose value expands into another fact (e.g. {path.dockerhub} → a registry default_path → {org.handle}) is fully resolved in one Resolve call rather than left half-expanded.
This package is the orchestrator: it may import the data packages (gitver, config, cistate). The dependency direction is one-way — surfaces import facts, facts imports the data packages, and the data packages import neither. In particular gitver never imports config; config-sourced inputs reach a resolver only through Context.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ResolveInventoryTemplates ¶
func ResolveInventoryTemplates(ctx context.Context, values []string, appCfg *config.Config, rootDir string) []string
ResolveInventoryTemplates resolves {inventory.<cluster>.count} tokens across the given badge values.
The count comes from the same sweep the k8s-inventory region renders (k8s.Sweep), so the badge and the page are one reading whichever is rendered first. Where the cluster is unreachable from this runner, the committed manifest's active entries stand in. An unknown cluster with no manifest leaves the token unresolved and the badge layer renders "n/a".
func ResolveRegistryTemplates ¶
ResolveRegistryTemplates resolves every {registry.<id>...} token across the given values, fetching each referenced registry's metadata exactly once (dispatched by the registry's provider), and returns the resolved values in the same order. Values with no such token pass through untouched; an unknown id or a tag with no metadata resolves to empty, which the badge layer renders as "n/a".
Types ¶
type Context ¶
type Context struct {
// Ctx scopes network calls made by live-data resolvers (registry/inventory).
Ctx context.Context
// Version and RootDir feed the gitver leaf families ({version}, {sha}, {commit.*},
// {project.*}, scoped versions). RootDir "" disables git-dependent families.
Version *gitver.VersionInfo
RootDir string
// Vars backs {var:name}; Description backs {project.description} (config-sourced,
// injected explicitly rather than via any package global).
Vars map[string]string
Description string
// Config backs the identity/coordinate families and the registry/inventory
// resolvers; State backs cistate run-identity and subsystem facts. Either may be nil.
Config *config.Config
State *cistate.State
}
Context carries every input a resolver might read. A resolver reads only the fields its families need; the zero value is valid — a family whose inputs are absent resolves to empty or passes the token through, matching pre-registry behavior.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry applies its Resolvers in dependency order.
func BadgeRegistry ¶
func BadgeRegistry() *Registry
BadgeRegistry returns the standard registry for resolving badge values: the gitver leaf pass (version/vars/commit/project/…), then the {registry.*} and {inventory.*} batch resolvers. This is the single assembly point for the badge fact set — the order (leaf → registry → inventory) matches the pre-registry pipeline and, since these families are independent, is fixed by registration order.
Identity families resolve at config NORMALIZATION (load time) — they are pure functions of the config, so no runtime resolver exists for them.
func ScribeRegistry ¶
func ScribeRegistry() *Registry
ScribeRegistry returns the registry for resolving narration/scribe text: the gitver leaf pass only. Narration bodies deliberately do NOT resolve {registry.*}/{inventory.*} — those are badge-only and would turn prose tokens into live network fetches — so those resolvers are absent here.
func (*Registry) Add ¶
Add registers a resolver. Registration order is the deterministic tiebreaker when two resolvers are not ordered by a dependency. Returns the registry for chaining.
func (*Registry) Resolve ¶
Resolve applies every resolver to the value set in dependency order and returns the fully-expanded set (same length as values).
func (*Registry) ResolveOne ¶
ResolveOne is the single-value convenience: resolve one string through the registry. Surfaces that render one body at a time (scribe) use this; batch surfaces (badges) call Resolve with the whole set so fetch-once resolvers work across it.
type Resolver ¶
type Resolver interface {
// Name identifies the resolver in diagnostics and ordering errors.
Name() string
// Provides lists the fact families this resolver resolves (token prefixes, e.g.
// "path", "registry"; or the sentinel families a monolithic resolver owns).
Provides() []string
// DependsOn lists families that must be resolved before this resolver runs. A
// family not provided by any registered resolver is treated as externally supplied
// and imposes no ordering constraint.
DependsOn() []string
// Resolve returns values with this resolver's families expanded (same length).
Resolve(values []string, c *Context) []string
}
Resolver rewrites a SET of templated values, resolving the fact families it owns. Operating on []string (rather than one string) is what lets batch resolvers — registry/inventory, which fetch each remote once across all values — sit behind the same interface as per-value resolvers, which simply map over the set. Resolve must be a pure function of (values, c) modulo idempotent live fetches, returning a slice the same length as its input, and must not mutate shared package state.
func GitverLeaf ¶
func GitverLeaf() Resolver
GitverLeaf returns the resolver for gitver's leaf template families.
func InventoryResolver ¶
func InventoryResolver() Resolver
InventoryResolver returns the resolver for the {inventory.*} family.
func RegistryResolver ¶
func RegistryResolver() Resolver
RegistryResolver returns the resolver for the {registry.*} family.
Source Files