package consumers import ( "errors" "io" "io/fs" "path" "slices" "strings" configkit "go.maximumdirect.net/configkit" ) // ComponentSettings is a library-owned configuration type embedded by an application. type ComponentSettings struct { Name string `yaml:"name"` Resource string `yaml:"resource"` Token string `yaml:"token"` Entries []ComponentItem `yaml:"entries"` } // ComponentItem is one identified library setting. type ComponentItem struct { ID string `yaml:"id"` Resource string `yaml:"resource"` } // ComponentApplication is the application-owned root for this example. type ComponentApplication struct { Component ComponentSettings `yaml:"component"` } // ComponentResult is the small interface required by the library at handoff. type ComponentResult interface { Value(configkit.Path) (any, bool) Metadata() configkit.Metadata SourceContext(string) (configkit.ResourceContext, bool) } // ComponentRuntime contains settings and captured resource data owned by the library. type ComponentRuntime struct { Settings ComponentSettings Resource []byte } // ComponentDefinition registers library behavior through an application field selector. func ComponentDefinition[T any](selectSettings func(*T) *ComponentSettings) configkit.Definition[T] { component := configkit.Keys("component") return configkit.Definition[T]{ SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(component.Key("entries"), "id")}, Resolve: func(root *T, resolution *configkit.Resolution) error { settings := selectSettings(root) configkit.Default(resolution, component.Key("name"), &settings.Name, "default component", "use component default") configkit.Normalize(resolution, component.Key("name"), &settings.Name, strings.TrimSpace(settings.Name), "trim component name") return nil }, Validate: func(root *T, validation *configkit.Validation) { if selectSettings(root).Name == "" { validation.Error(component.Key("name"), "component name is required") } }, Sensitive: func(path configkit.Path) bool { return path.String() == "/component/token" }, } } // LoadComponentApplication assembles one application load with bundled underlay defaults. func LoadComponentApplication(source configkit.Source) (*configkit.Result[ComponentApplication], error) { return configkit.LoadLayered(configkit.Input{Source: source}, configkit.LayeredOptions[ComponentApplication]{ Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.Bytes("component defaults", []byte("component: {entries: [{id: default}]}\n"))}}}}, Definition: ComponentDefinition(func(root *ComponentApplication) *ComponentSettings { return &root.Component }), }) } // NewComponent accepts the entire result, selects library settings, and captures // a resource relative to the effective field's original source. func NewComponent(result ComponentResult) (ComponentRuntime, error) { value, ok := result.Value(configkit.Keys("component")) settings, typed := value.(ComponentSettings) if !ok || !typed { return ComponentRuntime{}, errors.New("component settings unavailable") } settings.Entries = slices.Clone(settings.Entries) info, ok := result.Metadata().Lookup(configkit.Keys("component", "resource")) if !ok || len(info.Origin.Locations) != 1 { return ComponentRuntime{}, errors.New("component resource origin unavailable") } context, ok := result.SourceContext(info.Origin.Locations[0].SourceID) if !ok { return ComponentRuntime{}, errors.New("component resource context unavailable") } data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, settings.Resource)) if err != nil { return ComponentRuntime{}, err } return ComponentRuntime{Settings: settings, Resource: data}, nil } // ComponentInspection is a library-owned facade over one selected reporting view. type ComponentInspection struct{ view configkit.Inspection } // InspectComponent selects the library's conventional reporting scope once. func InspectComponent(result interface { InspectSubtree(configkit.Path) (configkit.Inspection, bool) }) (ComponentInspection, bool) { view, ok := result.InspectSubtree(configkit.Keys("component")) return ComponentInspection{view: view}, ok } // WriteEffective renders the frozen component safely. func (i ComponentInspection) WriteEffective(output io.Writer) error { return i.view.WriteEffective(output) } // Explain forwards native application paths without changing their meaning. func (i ComponentInspection) Explain(path configkit.Path) (configkit.Explanation, bool) { return i.view.Explain(path) } // Diff compares two frozen component views. func (i ComponentInspection) Diff(other ComponentInspection) ([]configkit.Difference, error) { return i.view.Diff(other.view) }