Use native path readers for discovery

This commit is contained in:
2026-11-21 19:35:13 +00:00
parent 8e51ecf77e
commit 0c9e719312
5 changed files with 87 additions and 4 deletions

View File

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

View File

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

View File

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

View File

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

View File

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