From 41bd3a69d4b488994df4892dc2ba0f5ebbc6f5eb Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 19:38:35 +0000 Subject: [PATCH] Add native configuration subtree scopes --- docs/roadmap/implementation.md | 9 +- integrations/ckconfig/configkit_adapter.go | 169 +++++++++++----- integrations/ckconfig/subtree_adapter_test.go | 182 ++++++++++++++++++ 3 files changed, 312 insertions(+), 48 deletions(-) create mode 100644 integrations/ckconfig/subtree_adapter_test.go diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index ef7c3e5..3f1c2bb 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -120,7 +120,14 @@ Existing whole-result discovery remains supported. ## Stage 3: Add the typed-result subtree scope adapter -Status: pending. +Status: complete. + +Evidence: Added the typed loader and native subtree adapter, sharing acquisition +and comparison coordination with the whole-result adapter. Offline scope and CLI +tests cover focused output and paths, explicit outside-focus explanations, +whole-load warnings and failures, error identity, absence and null, unavailable +inspection, and native comparison including an atomic ancestor. The independent +ckconfig suite passed with Go 1.27.4 and `GOWORK=off GOTOOLCHAIN=local`. Add the following public sibling of `FromConfigKit` in the ckconfig package: diff --git a/integrations/ckconfig/configkit_adapter.go b/integrations/ckconfig/configkit_adapter.go index 2ad00eb..e0326a2 100644 --- a/integrations/ckconfig/configkit_adapter.go +++ b/integrations/ckconfig/configkit_adapter.go @@ -33,29 +33,7 @@ func FromConfigKit[I, S, T any]( } scope.Acquire = func(ctx context.Context, request Request, input I, state S) (commandkit.Acquired[View], error) { - result, err := load(ctx, request.Selection, input, state) - acquired := commandkit.Acquired[View]{} - if err != nil { - var loadError *configkit.LoadError - if errors.As(err, &loadError) && loadError != nil { - records := loadError.Diagnostics() - messages, explanation := configKitDiagnostics(name, loadError.Sources(), records) - acquired.Value.Sources = loadError - acquired.Value.Findings = &Findings{Records: records, Messages: messages} - acquired.Explanation = explanation - return acquired, err - } - } - if result == nil { - if err != nil { - return acquired, err - } - return commandkit.Acquired[View]{}, fmt.Errorf("ConfigKit scope %q returned a nil result", name) - } - records := result.Diagnostics() - messages, explanation := configKitDiagnostics(name, result.Sources(), records) - acquired.Value = View{Sources: result, Findings: &Findings{Records: records, Messages: messages}} - acquired.Explanation = explanation + result, acquired, err := acquireConfigKit(ctx, name, load, request.Selection, input, state) if err != nil { return acquired, err } @@ -64,33 +42,10 @@ func FromConfigKit[I, S, T any]( return acquired, nil } scope.Compare = func(ctx context.Context, request ComparisonRequest[I], state S) (commandkit.Acquired[[]configkit.Difference], error) { - if err := ctx.Err(); err != nil { - return commandkit.Acquired[[]configkit.Difference]{}, fmt.Errorf("ConfigKit scope %q comparison before left load: %w", name, err) - } - - acquired := commandkit.Acquired[[]configkit.Difference]{} - left, leftDiagnostics, leftExplanation, err := loadComparisonSide(ctx, name, "left", load, request.Left, state) - acquired.Diagnostics = append(acquired.Diagnostics, leftDiagnostics...) - acquired.Explanation = appendConfigKitExplanation(acquired.Explanation, leftExplanation) + left, right, acquired, err := loadComparisonPair(ctx, name, load, request, state) if err != nil { return acquired, err } - - if err := ctx.Err(); err != nil { - return acquired, fmt.Errorf("ConfigKit scope %q comparison after left load: %w", name, err) - } - - right, rightDiagnostics, rightExplanation, err := loadComparisonSide(ctx, name, "right", load, request.Right, state) - acquired.Diagnostics = append(acquired.Diagnostics, rightDiagnostics...) - acquired.Explanation = appendConfigKitExplanation(acquired.Explanation, rightExplanation) - if err != nil { - return acquired, err - } - - if err := ctx.Err(); err != nil { - return acquired, fmt.Errorf("ConfigKit scope %q comparison before native diff: %w", name, err) - } - acquired.Value, err = configkit.Diff(left, right) if err != nil { return acquired, fmt.Errorf("ConfigKit scope %q native diff: %w", name, err) @@ -100,6 +55,126 @@ func FromConfigKit[I, S, T any]( return scope } +// FromConfigKitSubtree adapts an application-owned typed loader to the same +// operations as FromConfigKit, using native inspection at path. Loading and +// validation cover the whole result; sources and findings retain that context. +// Discovery and rendering use the focused inspection, while explicit paths and +// comparison retain ConfigKit's native semantics. Construction and help do not +// load configuration, and a nil loader is recorded as a construction issue. +func FromConfigKitSubtree[I, S, T any]( + name, summary string, + path configkit.Path, + load func(context.Context, Selection, I, S) (*configkit.Result[T], error), +) Scope[I, S] { + scope := Scope[I, S]{ + Name: name, Summary: summary, + Operations: []Operation{Validate, Show, Sources, Explain, Diff}, + Features: ScopeFeatures{PathDiscovery: true, PathShow: true}, + } + if load == nil { + return WithScopeError(scope, fmt.Errorf("ConfigKit scope %q loader must not be nil", name)) + } + scope.Acquire = func(ctx context.Context, request Request, input I, state S) (commandkit.Acquired[View], error) { + result, acquired, err := acquireConfigKit(ctx, name, load, request.Selection, input, state) + if err != nil { + return acquired, err + } + inspection, ok := result.InspectSubtree(path) + if !ok { + return acquired, fmt.Errorf("ConfigKit scope %q inspection at %q is unavailable", name, path.String()) + } + metadata := inspection.Metadata() + acquired.Value.Effective = inspection + acquired.Value.Explanation = inspection + acquired.Value.Paths = inspection + acquired.Value.Metadata = &metadata + acquired.Value.Sources = inspection + return acquired, nil + } + scope.Compare = func(ctx context.Context, request ComparisonRequest[I], state S) (commandkit.Acquired[[]configkit.Difference], error) { + left, right, acquired, err := loadComparisonPair(ctx, name, load, request, state) + if err != nil { + return acquired, err + } + leftView, ok := left.InspectSubtree(path) + if !ok { + return acquired, fmt.Errorf("ConfigKit scope %q left inspection at %q is unavailable", name, path.String()) + } + rightView, ok := right.InspectSubtree(path) + if !ok { + return acquired, fmt.Errorf("ConfigKit scope %q right inspection at %q is unavailable", name, path.String()) + } + if err := ctx.Err(); err != nil { + return acquired, fmt.Errorf("ConfigKit scope %q comparison before native diff: %w", name, err) + } + acquired.Value, err = leftView.Diff(rightView) + if err != nil { + return acquired, fmt.Errorf("ConfigKit scope %q native diff: %w", name, err) + } + return acquired, nil + } + return scope +} + +func acquireConfigKit[I, S, T any](ctx context.Context, name string, + load func(context.Context, Selection, I, S) (*configkit.Result[T], error), + selection Selection, input I, state S, +) (*configkit.Result[T], commandkit.Acquired[View], error) { + result, err := load(ctx, selection, input, state) + acquired := commandkit.Acquired[View]{} + if err != nil { + var loadError *configkit.LoadError + if errors.As(err, &loadError) && loadError != nil { + records := loadError.Diagnostics() + messages, explanation := configKitDiagnostics(name, loadError.Sources(), records) + acquired.Value.Sources = loadError + acquired.Value.Findings = &Findings{Records: records, Messages: messages} + acquired.Explanation = explanation + return result, acquired, err + } + } + if result == nil { + if err != nil { + return nil, acquired, err + } + return nil, acquired, fmt.Errorf("ConfigKit scope %q returned a nil result", name) + } + records := result.Diagnostics() + messages, explanation := configKitDiagnostics(name, result.Sources(), records) + acquired.Value = View{Sources: result, Findings: &Findings{Records: records, Messages: messages}} + acquired.Explanation = explanation + return result, acquired, err +} + +func loadComparisonPair[I, S, T any](ctx context.Context, name string, + load func(context.Context, Selection, I, S) (*configkit.Result[T], error), + request ComparisonRequest[I], state S, +) (*configkit.Result[T], *configkit.Result[T], commandkit.Acquired[[]configkit.Difference], error) { + acquired := commandkit.Acquired[[]configkit.Difference]{} + if err := ctx.Err(); err != nil { + return nil, nil, acquired, fmt.Errorf("ConfigKit scope %q comparison before left load: %w", name, err) + } + left, diagnostics, explanation, err := loadComparisonSide(ctx, name, "left", load, request.Left, state) + acquired.Diagnostics = append(acquired.Diagnostics, diagnostics...) + acquired.Explanation = appendConfigKitExplanation(acquired.Explanation, explanation) + if err != nil { + return nil, nil, acquired, err + } + if err := ctx.Err(); err != nil { + return nil, nil, acquired, fmt.Errorf("ConfigKit scope %q comparison after left load: %w", name, err) + } + right, diagnostics, explanation, err := loadComparisonSide(ctx, name, "right", load, request.Right, state) + acquired.Diagnostics = append(acquired.Diagnostics, diagnostics...) + acquired.Explanation = appendConfigKitExplanation(acquired.Explanation, explanation) + if err != nil { + return nil, nil, acquired, err + } + if err := ctx.Err(); err != nil { + return nil, nil, acquired, fmt.Errorf("ConfigKit scope %q comparison before native diff: %w", name, err) + } + return left, right, acquired, nil +} + func loadComparisonSide[I, S, T any]( ctx context.Context, scope, side string, diff --git a/integrations/ckconfig/subtree_adapter_test.go b/integrations/ckconfig/subtree_adapter_test.go new file mode 100644 index 0000000..0003b02 --- /dev/null +++ b/integrations/ckconfig/subtree_adapter_test.go @@ -0,0 +1,182 @@ +package ckconfig + +import ( + "bytes" + "context" + "errors" + "io" + "reflect" + "strings" + "testing" + + commandkit "go.maximumdirect.net/commandkit" + configkit "go.maximumdirect.net/configkit" +) + +func TestSubtreeScopeUsesNativeInspection(t *testing.T) { + definition := configkit.Definition[map[string]any]{Validate: func(_ *map[string]any, validation *configkit.Validation) { + validation.Warning(configkit.Keys("sibling"), "sibling warning") + }} + makeResult := func(value any) *configkit.Result[map[string]any] { + t.Helper() + result, err := configkit.Load(configkit.Mapping("application", map[string]any{"storage": value, "sibling": "outside"}), configkit.Options[map[string]any]{Definition: definition}) + if err != nil { + t.Fatal(err) + } + return result + } + left, right := makeResult(map[string]any{"name": "before"}), makeResult(map[string]any{"name": "after"}) + calls := 0 + scope := FromConfigKitSubtree("storage", "", configkit.Keys("storage"), func(_ context.Context, selection Selection, _, _ struct{}) (*configkit.Result[map[string]any], error) { + calls++ + if selection.Config.Value == "after" { + return right, nil + } + return left, nil + }) + app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{scope}})) + if calls != 0 { + t.Fatal("construction acquired configuration") + } + run := func(args ...string) (commandkit.Outcome, string, string) { + t.Helper() + var out, diagnostics bytes.Buffer + outcome := app.Execute(context.Background(), append(append([]string{"config"}, args...), "--scope=storage"), commandkit.Streams{Out: &out, Err: &diagnostics}) + return outcome, out.String(), diagnostics.String() + } + for _, tc := range []struct { + args []string + contains, excludes string + }{ + {[]string{"show"}, "before", "outside"}, + {[]string{"explain", "--list"}, "/storage/name", "/sibling"}, + {[]string{"explain", "--path=/sibling"}, "/sibling", ""}, + {[]string{"sources"}, "application", ""}, + {[]string{"diff", "--config=before", "--against-config=after"}, "after", ""}, + } { + outcome, output, diagnostics := run(tc.args...) + if outcome.Kind != commandkit.OutcomeSuccess || !strings.Contains(output, tc.contains) || (tc.excludes != "" && strings.Contains(output, tc.excludes)) { + t.Errorf("%v: outcome=%#v output=%q diagnostics=%q", tc.args, outcome, output, diagnostics) + } + } + lv, _ := left.InspectSubtree(configkit.Keys("storage")) + rv, _ := right.InspectSubtree(configkit.Keys("storage")) + want, err := lv.Diff(rv) + if err != nil { + t.Fatal(err) + } + got, err := scope.Compare(context.Background(), ComparisonRequest[struct{}]{Left: ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "before", Set: true}}}, Right: ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "after", Set: true}}}}, struct{}{}) + if err != nil || !reflect.DeepEqual(got.Value, want) || len(got.Diagnostics) != 2 { + t.Fatalf("comparison = %#v, %v; want %#v", got, err, want) + } +} + +func TestSubtreeScopeAbsenceAndErrors(t *testing.T) { + load := func(value map[string]any) *configkit.Result[map[string]any] { + t.Helper() + result, err := configkit.Load[map[string]any](configkit.Mapping("application", value)) + if err != nil { + t.Fatal(err) + } + return result + } + for _, tc := range []struct { + name string + result *configkit.Result[map[string]any] + wantWriteError bool + }{ + {"absent", load(map[string]any{"sibling": 1}), true}, {"null", load(map[string]any{"storage": nil}), false}, + } { + t.Run(tc.name, func(t *testing.T) { + scope := FromConfigKitSubtree("storage", "", configkit.Keys("storage"), func(context.Context, Selection, struct{}, struct{}) (*configkit.Result[map[string]any], error) { + return tc.result, nil + }) + acquired, err := scope.Acquire(context.Background(), Request{}, struct{}{}, struct{}{}) + if err != nil { + t.Fatal(err) + } + var output bytes.Buffer + err = acquired.Value.Effective.WriteEffective(&output) + if (err != nil) != tc.wantWriteError || (!tc.wantWriteError && !strings.Contains(output.String(), "null")) { + t.Fatalf("write = %q, %v", output.String(), err) + } + }) + } + cause := errors.New("application load failed") + result := load(map[string]any{"sibling": 1}) + scope := FromConfigKitSubtree("storage", "", configkit.Keys("storage"), func(context.Context, Selection, struct{}, struct{}) (*configkit.Result[map[string]any], error) { + return result, cause + }) + acquired, err := scope.Acquire(context.Background(), Request{}, struct{}{}, struct{}{}) + if !errors.Is(err, cause) || acquired.Value.Sources == nil || acquired.Value.Findings == nil { + t.Fatalf("load failure = %#v, %v", acquired, err) + } + app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{scope}})) + outcome := app.Execute(context.Background(), []string{"config", "show", "--scope=storage"}, commandkit.Streams{Out: io.Discard, Err: io.Discard}) + if outcome.Kind != commandkit.OutcomeOperational || !errors.Is(outcome.Cause, cause) { + t.Fatalf("outcome = %#v", outcome) + } + unavailable := FromConfigKitSubtree("storage", "", configkit.Keys("storage"), func(context.Context, Selection, struct{}, struct{}) (*configkit.Result[map[string]any], error) { + return &configkit.Result[map[string]any]{}, nil + }) + acquired, err = unavailable.Acquire(context.Background(), Request{}, struct{}{}, struct{}{}) + if err == nil || acquired.Value.Findings == nil || acquired.Value.Sources == nil { + t.Fatalf("unavailable = %#v, %v", acquired, err) + } + nilScope := FromConfigKitSubtree[struct{}, struct{}, map[string]any]("storage", "", configkit.Keys("storage"), nil) + if len(nilScope.issues) == 0 { + t.Fatal("nil loader not retained") + } +} + +func TestSubtreeScopeRetainsWholeLoadFailure(t *testing.T) { + path := configkit.Keys("sibling") + _, loadErr := configkit.Load(configkit.Bytes("bad application", []byte("{}\n")), configkit.Options[struct{}]{Definition: configkit.Definition[struct{}]{Version: &configkit.VersionRule{ + Path: path, Check: func(_ configkit.Version, validation *configkit.Validation) error { + validation.Warning(path, "outside warning") + return errors.New("invalid outside") + }, + }}}) + if loadErr == nil { + t.Fatal("fixture did not fail") + } + scope := FromConfigKitSubtree("storage", "", configkit.Keys("storage"), func(context.Context, Selection, struct{}, struct{}) (*configkit.Result[struct{}], error) { + return nil, loadErr + }) + acquired, err := scope.Acquire(context.Background(), Request{}, struct{}{}, struct{}{}) + var native *configkit.LoadError + if !errors.As(err, &native) || !errors.Is(err, loadErr) || acquired.Value.Sources == nil || acquired.Value.Findings == nil || !reflect.DeepEqual(acquired.Value.Findings.Records, native.Diagnostics()) || len(acquired.Explanation.Details) == 0 { + t.Fatalf("failure evidence = %#v, %v", acquired, err) + } + app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{scope}})) + outcome := app.Execute(context.Background(), []string{"config", "validate", "--scope=storage"}, commandkit.Streams{Out: io.Discard, Err: io.Discard}) + if !errors.Is(outcome.Cause, loadErr) { + t.Fatalf("validation outcome = %#v", outcome) + } +} + +func TestSubtreeComparisonRetainsNativeAncestor(t *testing.T) { + makeResult := func(item string) *configkit.Result[map[string]any] { + t.Helper() + result, err := configkit.Load[map[string]any](configkit.Mapping(item, map[string]any{"items": []any{item}})) + if err != nil { + t.Fatal(err) + } + return result + } + left, right := makeResult("before"), makeResult("after") + path := configkit.Keys("items", "0") + scope := FromConfigKitSubtree("item", "", path, func(_ context.Context, selection Selection, _, _ struct{}) (*configkit.Result[map[string]any], error) { + if selection.Config.Value == "right" { + return right, nil + } + return left, nil + }) + got, err := scope.Compare(context.Background(), ComparisonRequest[struct{}]{Right: ComparisonSide[struct{}]{Selection: Selection{Config: commandkit.Supplied[string]{Value: "right", Set: true}}}}, struct{}{}) + lv, _ := left.InspectSubtree(path) + rv, _ := right.InspectSubtree(path) + want, nativeErr := lv.Diff(rv) + if err != nil || nativeErr != nil || !reflect.DeepEqual(got.Value, want) || len(want) != 1 || want[0].Path.String() != "/items" { + t.Fatalf("comparison = %#v, %v; native = %#v, %v", got.Value, err, want, nativeErr) + } +}