diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 8e974f0..8668159 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–6 complete. +Status: implementation in progress; Stages 1–7 complete. ## Scope and working instructions @@ -267,6 +267,8 @@ concurrent-mutation contract. ## Stage 7 — Demonstrate one-library handoff +**Complete.** + Add a maintained example and focused test under `examples/consumers/`, for example `result_component.go` and `result_component_test.go`, using representative small library-owned settings rather than adding an actual PromptKit dependency. diff --git a/examples/consumers/result_component.go b/examples/consumers/result_component.go new file mode 100644 index 0000000..581ac01 --- /dev/null +++ b/examples/consumers/result_component.go @@ -0,0 +1,121 @@ +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"` +} + +// 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) +} diff --git a/examples/consumers/result_component_test.go b/examples/consumers/result_component_test.go new file mode 100644 index 0000000..8d06f2e --- /dev/null +++ b/examples/consumers/result_component_test.go @@ -0,0 +1,53 @@ +package consumers + +import ( + "bytes" + "strings" + "testing" + "testing/fstest" + + configkit "go.maximumdirect.net/configkit" +) + +func TestComponentHandoff(t *testing.T) { + filesystem := configkit.NewFilesystem("application", fstest.MapFS{ + "config/main.yml": &fstest.MapFile{Data: []byte("component: {name: ' example ', resource: asset.txt, token: disposable-canary}\n")}, + "config/asset.txt": &fstest.MapFile{Data: []byte("resource data")}, + }) + result, err := LoadComponentApplication(filesystem.File("config/main.yml")) + if err != nil { + t.Fatal(err) + } + runtime, err := NewComponent(result) + if err != nil { + t.Fatal(err) + } + if runtime.Settings.Name != "example" || len(runtime.Settings.Entries) != 1 || runtime.Settings.Entries[0].ID != "default" || string(runtime.Resource) != "resource data" { + t.Fatalf("component runtime = %#v", runtime) + } + entries, found := result.Metadata().Lookup(configkit.Keys("component", "entries")) + if !result.Metadata().IsExplicit(configkit.Keys("component", "resource")) || !found || entries.Origin.Layer != configkit.LayerUnderlay { + t.Fatal("presence did not retain source distinction") + } + view, ok := InspectComponent(result) + if !ok { + t.Fatal("component view unavailable") + } + var output bytes.Buffer + if err := view.WriteEffective(&output); err != nil { + t.Fatal(err) + } + if strings.Contains(output.String(), "disposable-canary") || !strings.Contains(output.String(), "example") { + t.Fatalf("unsafe report: %s", output.String()) + } + if _, ok := view.Explain(configkit.Keys("component", "resource")); !ok { + t.Fatal("resource explanation unavailable") + } + if diff, err := view.Diff(view); err != nil || len(diff) != 0 { + t.Fatalf("view diff = %#v, %v", diff, err) + } + _, err = LoadComponentApplication(configkit.Bytes("invalid.yml", []byte("component: {name: ' '}\n"))) + if err == nil { + t.Fatal("component validation did not fail") + } +}