From 0c9e719312d05d0c8f9ade114011c0476aa5fd00 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 19:35:13 +0000 Subject: [PATCH] Use native path readers for discovery --- docs/roadmap/implementation.md | 7 ++- integrations/ckconfig/configkit_adapter.go | 2 +- integrations/ckconfig/contracts.go | 11 +++- integrations/ckconfig/discovery_test.go | 65 ++++++++++++++++++++++ integrations/ckconfig/explain.go | 6 +- 5 files changed, 87 insertions(+), 4 deletions(-) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 2f4299a..ef7c3e5 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -76,7 +76,12 @@ work for subsequent stages, not reasons to stop. ## Stage 2: Separate native path enumeration from metadata lookup -Status: pending. +Status: complete. + +Evidence: Added the optional native path reader and metadata fallback, populated +whole-result views, and exercised selected candidates, empty readers, the legacy +fallback, and discovery filters alongside existing missing-metadata coverage. +`GOWORK=off GOTOOLCHAIN=local go test ./...` passed in ckconfig with Go 1.27.4. Primary files: [contracts.go](../../integrations/ckconfig/contracts.go), [explain.go](../../integrations/ckconfig/explain.go), and diff --git a/integrations/ckconfig/configkit_adapter.go b/integrations/ckconfig/configkit_adapter.go index fd5b470..2ad00eb 100644 --- a/integrations/ckconfig/configkit_adapter.go +++ b/integrations/ckconfig/configkit_adapter.go @@ -60,7 +60,7 @@ func FromConfigKit[I, S, T any]( return acquired, err } metadata := result.Metadata() - acquired.Value.Effective, acquired.Value.Explanation, acquired.Value.Metadata = result, result, &metadata + acquired.Value.Effective, acquired.Value.Explanation, acquired.Value.Metadata, acquired.Value.Paths = result, result, &metadata, &metadata return acquired, nil } scope.Compare = func(ctx context.Context, request ComparisonRequest[I], state S) (commandkit.Acquired[[]configkit.Difference], error) { diff --git a/integrations/ckconfig/contracts.go b/integrations/ckconfig/contracts.go index 1902330..70d6d57 100644 --- a/integrations/ckconfig/contracts.go +++ b/integrations/ckconfig/contracts.go @@ -80,11 +80,19 @@ type ExplanationReader interface { Explain(configkit.Path) (configkit.Explanation, bool) } +// PathReader supplies native candidates for configuration path discovery. +type PathReader interface { + HistoricalPaths() []configkit.Path +} + // View exposes native configuration evidence used to build reports. type View struct { Effective EffectiveWriter Sources SourceReader Explanation ExplanationReader + // Paths supplies discovery candidates. When nil, discovery uses Metadata. + // A nonnil reader may return an empty list without triggering that fallback. + Paths PathReader // Metadata supplies native configuration path metadata when available. Metadata *configkit.Metadata // Findings supplies native diagnostics and their ordinary presentations. @@ -102,7 +110,8 @@ type Findings struct { // ScopeFeatures describes optional modes within configuration operations. type ScopeFeatures struct { - // PathDiscovery indicates support for metadata-backed path discovery. + // PathDiscovery indicates support for path discovery using Paths or, when + // absent, Metadata. Metadata is required to describe and filter candidates. PathDiscovery bool // PathShow indicates support for displaying a selected effective path. PathShow bool diff --git a/integrations/ckconfig/discovery_test.go b/integrations/ckconfig/discovery_test.go index a0eb7f4..6cbbdd2 100644 --- a/integrations/ckconfig/discovery_test.go +++ b/integrations/ckconfig/discovery_test.go @@ -154,3 +154,68 @@ func TestExplainBareHelpRecordsDeliveryFailure(t *testing.T) { t.Fatalf("help delivery = %#v, input/state/acquire=%d/%d/%d", result, inputs, states, calls) } } + +type discoveryPaths []configkit.Path + +func (paths discoveryPaths) HistoricalPaths() []configkit.Path { return paths } + +func TestExplainDiscoveryUsesSuppliedPaths(t *testing.T) { + scope := FromConfigKit("app", "", func(_ context.Context, selection Selection, _, _ struct{}) (*configkit.Result[map[string]any], error) { + return configkit.Load(configkit.Mapping("fixture", map[string]any{ + "focus": map[string]any{"keep": 1, "gone": map[string]any{"child": 2}}, + "sibling": 3, + }), configkit.Options[map[string]any]{Overrides: selection.Overrides}) + }) + scope.Features.Overrides = true + acquire := scope.Acquire + var reader PathReader + scope.Acquire = func(ctx context.Context, request Request, input, state struct{}) (commandkit.Acquired[View], error) { + acquired, err := acquire(ctx, request, input, state) + acquired.Value.Paths = reader + return acquired, err + } + app := newConfigTestApp(t, Command(Suite[struct{}, struct{}]{Scopes: []Scope[struct{}, struct{}]{scope}})) + run := func(args ...string) pathDiscoveryReport { + t.Helper() + var out bytes.Buffer + arguments := append([]string{"config", "explain", "--list", "--format=json", "--set=/focus/gone=null"}, args...) + outcome := app.Execute(context.Background(), arguments, commandkit.Streams{Out: &out, Err: io.Discard}) + var report pathDiscoveryReport + if outcome.Kind != commandkit.OutcomeSuccess { + t.Fatalf("discovery %v: %#v", args, outcome) + } + if err := json.Unmarshal(out.Bytes(), &report); err != nil { + t.Fatal(err) + } + return report + } + reader = discoveryPaths{configkit.Keys("focus", "keep"), configkit.Keys("focus", "gone"), configkit.Keys("focus", "gone", "child")} + check := func(report pathDiscoveryReport, want ...string) { + t.Helper() + var got []string + for _, entry := range report.Paths { + got = append(got, entry.Path) + } + if !reflect.DeepEqual(got, want) { + t.Fatalf("paths = %v, want %v", got, want) + } + } + check(run(), "/focus/keep", "/focus/gone") + check(run("--historical"), "/focus/keep", "/focus/gone", "/focus/gone/child") + check(run("--under=/focus/gone", "--historical"), "/focus/gone", "/focus/gone/child") + check(run("--historical", "--explicit=true"), "/focus/keep", "/focus/gone") + check(run("--historical", "--explicit=false")) + reader = discoveryPaths(nil) + check(run("--historical")) + reader = discoveryPaths{} + check(run("--historical")) + reader = nil + fallback := run() + foundSibling := false + for _, entry := range fallback.Paths { + foundSibling = foundSibling || entry.Path == "/sibling" + } + if !foundSibling { + t.Fatalf("metadata fallback omitted sibling: %#v", fallback.Paths) + } +} diff --git a/integrations/ckconfig/explain.go b/integrations/ckconfig/explain.go index 889d41f..f94ef84 100644 --- a/integrations/ckconfig/explain.go +++ b/integrations/ckconfig/explain.go @@ -134,7 +134,11 @@ func runConfigExplanation[I, S any](invocation commandkit.Invocation, plan *conf if plan.under != nil { prefix = pointerTokens(plan.under.String()) } - for _, path := range acquired.Value.Metadata.HistoricalPaths() { + paths := acquired.Value.Paths + if paths == nil { + paths = acquired.Value.Metadata + } + for _, path := range paths.HistoricalPaths() { pointer := path.String() if plan.under != nil && !pathWithin(pointer, prefix) { continue