Add native configuration subtree scopes

This commit is contained in:
2026-11-21 19:38:35 +00:00
parent 0c9e719312
commit 41bd3a69d4
3 changed files with 312 additions and 48 deletions

View File

@@ -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:

View File

@@ -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,

View File

@@ -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)
}
}