diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 8668159..b7e28d5 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,6 +1,6 @@ # Implementation plan: typed result values and focused inspection -Status: implementation in progress; Stages 1–7 complete. +Status: implementation in progress; Stages 1–8 complete. ## Scope and working instructions @@ -290,6 +290,8 @@ ConfigKit registration API or a second library-specific load. ## Stage 8 — Demonstrate two-library composition +**Complete.** + Extend the example with a second small consumer using the same application result and a smaller consumer-owned interface where sufficient. Compose existing application and library callbacks with explicit ordering and authoritative diff --git a/examples/consumers/result_component.go b/examples/consumers/result_component.go index 581ac01..b5af827 100644 --- a/examples/consumers/result_component.go +++ b/examples/consumers/result_component.go @@ -21,7 +21,8 @@ type ComponentSettings struct { // ComponentItem is one identified library setting. type ComponentItem struct { - ID string `yaml:"id"` + ID string `yaml:"id"` + Resource string `yaml:"resource"` } // ComponentApplication is the application-owned root for this example. diff --git a/examples/consumers/result_composition.go b/examples/consumers/result_composition.go new file mode 100644 index 0000000..16f2ff0 --- /dev/null +++ b/examples/consumers/result_composition.go @@ -0,0 +1,86 @@ +package consumers + +import ( + "errors" + "strings" + + configkit "go.maximumdirect.net/configkit" +) + +// AuditSettings is a second library's independent configuration type. +type AuditSettings struct { + Enabled bool `yaml:"enabled"` + Rules []AuditRule `yaml:"rules"` +} + +// AuditRule has an identity used by the application's assembly policy. +type AuditRule struct { + ID string `yaml:"id"` +} + +// ComposedApplication combines application and two library settings. +type ComposedApplication struct { + Label string `yaml:"label"` + Component ComponentSettings `yaml:"component"` + Audit AuditSettings `yaml:"audit"` +} + +// AuditResult is the smaller interface needed by the audit consumer. +type AuditResult interface { + Value(configkit.Path) (any, bool) +} + +// NewAuditSettings takes a copy of the second library's settings. +func NewAuditSettings(result AuditResult) (AuditSettings, error) { + value, ok := result.Value(configkit.Keys("audit")) + settings, typed := value.(AuditSettings) + if !ok || !typed { + return AuditSettings{}, errors.New("audit settings unavailable") + } + settings.Rules = append([]AuditRule(nil), settings.Rules...) + return settings, nil +} + +func auditDefinition[T any](selectSettings func(*T) *AuditSettings) configkit.Definition[T] { + audit := configkit.Keys("audit") + return configkit.Definition[T]{ + SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(audit.Key("rules"), "id")}, + Resolve: func(root *T, resolution *configkit.Resolution) error { + configkit.Default(resolution, audit.Key("enabled"), &selectSettings(root).Enabled, true, "enable audit by default") + return nil + }, + Validate: func(root *T, validation *configkit.Validation) { + if selectSettings(root).Enabled && len(selectSettings(root).Rules) == 0 { + validation.Error(audit.Key("rules"), "enabled audit requires a rule") + } + }, + } +} + +// LoadComposedApplication applies application and library callbacks in order in +// one load. A placed component input remains an ordinary underlay. +func LoadComposedApplication(main, component configkit.Input) (*configkit.Result[ComposedApplication], error) { + componentRules := ComponentDefinition(func(root *ComposedApplication) *ComponentSettings { return &root.Component }) + auditRules := auditDefinition(func(root *ComposedApplication) *AuditSettings { return &root.Audit }) + identities := append(componentRules.SequenceIdentities, auditRules.SequenceIdentities...) + definition := configkit.Definition[ComposedApplication]{ + SequenceIdentities: identities, + Sensitive: componentRules.Sensitive, + Resolve: func(root *ComposedApplication, resolution *configkit.Resolution) error { + configkit.Normalize(resolution, configkit.Keys("label"), &root.Label, strings.TrimSpace(root.Label), "trim application label") + if err := componentRules.Resolve(root, resolution); err != nil { + return err + } + return auditRules.Resolve(root, resolution) + }, + Validate: func(root *ComposedApplication, validation *configkit.Validation) { + if root.Label == "" { + validation.Error(configkit.Keys("label"), "application label is required") + } + componentRules.Validate(root, validation) + auditRules.Validate(root, validation) + }, + } + component.Destination = configkit.Keys("component") + return configkit.LoadLayered(main, configkit.LayeredOptions[ComposedApplication]{Underlays: []configkit.Underlay{{Inputs: []configkit.Input{component}}}, Definition: definition}) +} diff --git a/examples/consumers/result_composition_test.go b/examples/consumers/result_composition_test.go new file mode 100644 index 0000000..22b14bb --- /dev/null +++ b/examples/consumers/result_composition_test.go @@ -0,0 +1,69 @@ +package consumers + +import ( + "io/fs" + "path" + "testing" + "testing/fstest" + + configkit "go.maximumdirect.net/configkit" +) + +func TestComposedConsumersShareOneLoad(t *testing.T) { + filesystem := configkit.NewFilesystem("components", fstest.MapFS{ + "config/component.yml": &fstest.MapFile{Data: []byte("name: ' component '\nresource: asset.txt\nentries:\n - {id: parent, resource: asset.txt}\n - {id: child, extends: {id: parent}}\n")}, + "config/asset.txt": &fstest.MapFile{Data: []byte("shared asset")}, + }) + component := configkit.Input{Source: filesystem.File("config/component.yml")} + load := func(main string) *configkit.Result[ComposedApplication] { + t.Helper() + result, err := LoadComposedApplication(configkit.Input{Source: configkit.Bytes("app.yml", []byte(main))}, component) + if err != nil { + t.Fatal(err) + } + return result + } + first := load("label: ' app '\naudit: {enabled: false, rules: [{id: first}]}\n") + second := load("label: second\naudit: {rules: [{id: second}]}\n") + componentRuntime, err := NewComponent(first) + if err != nil { + t.Fatal(err) + } + audit, err := NewAuditSettings(first) + if err != nil { + t.Fatal(err) + } + if first.Config.Label != "app" || componentRuntime.Settings.Name != "component" || string(componentRuntime.Resource) != "shared asset" || audit.Enabled || audit.Rules[0].ID != "first" { + t.Fatalf("first result = %#v %#v", componentRuntime, audit) + } + secondAudit, err := NewAuditSettings(second) + if err != nil || !secondAudit.Enabled || secondAudit.Rules[0].ID != "second" || audit.Enabled { + t.Fatalf("second audit = %#v, %v", secondAudit, err) + } + resource := configkit.Keys("component", "entries").Index(1).Key("resource") + info, ok := first.Metadata().Lookup(resource) + if !ok || len(info.Origin.Inheritance) == 0 || len(info.Origin.Locations) == 0 { + t.Fatalf("inherited origin = %#v, %v", info, ok) + } + context, ok := first.SourceContext(info.Origin.Locations[0].SourceID) + if !ok { + t.Fatal("resource context unavailable") + } + data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, first.Config.Component.Entries[1].Resource)) + if err != nil || string(data) != "shared asset" { + t.Fatalf("inherited resource = %q, %v", data, err) + } + _, err = LoadComposedApplication(configkit.Input{Source: configkit.Bytes("invalid.yml", []byte("label: app\naudit: {rules: [{id: same}, {id: same}]}\n"))}, component) + if err == nil { + t.Fatal("duplicate audit identities accepted") + } + badComponent := configkit.Input{Source: configkit.Bytes("bad-component.yml", []byte("name: good\nentries: [{id: duplicate}, {id: duplicate}]\n"))} + _, err = LoadComposedApplication(configkit.Input{Source: configkit.Bytes("app.yml", []byte("label: app\naudit: {rules: [{id: valid}]}\n"))}, badComponent) + if err == nil { + t.Fatal("duplicate component identities accepted") + } + _, err = LoadComposedApplication(configkit.Input{Source: configkit.Bytes("invalid.yml", []byte("label: ' '\naudit: {rules: [{id: valid}]}\n"))}, component) + if err == nil { + t.Fatal("application validation did not run") + } +}