diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 91eac81..e085a79 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,6 +1,6 @@ # Implementation plan: typed result values and focused inspection -Status: ready for implementation; no stages implemented by this document. +Status: implementation in progress; Stage 1 complete. ## Scope and working instructions @@ -47,6 +47,8 @@ units according to agent policy; do not publish a release or modify dependencies ## Stage 1 — Implement private current-value navigation +**Complete.** + Read `internal/engine/schema.go`, `schema_fields.go`, `value_operation.go`, `decode.go`, and semantic paths before adding a small engine helper, for example in `internal/engine/result_value.go`. Accept the current Go root, an engine Path, diff --git a/internal/engine/result_value.go b/internal/engine/result_value.go new file mode 100644 index 0000000..43e0250 --- /dev/null +++ b/internal/engine/result_value.go @@ -0,0 +1,99 @@ +package engine + +import "reflect" + +// ResultValue navigates the current Go value without projecting or copying it. +func ResultValue(root any, path Path, secrets SecretBinding) (any, bool) { + if !path.valid() { + return nil, false + } + current := reflect.ValueOf(root) + if len(path.segments) == 0 { + return root, true + } + builder := schemaBuilder{cache: make(map[reflect.Type]*typeDescriptor), building: make(map[reflect.Type]bool), secrets: secrets, lookup: true} + for _, segment := range path.segments { + seen := make(map[valueVisit]bool) + for current.IsValid() && (current.Kind() == reflect.Pointer || current.Kind() == reflect.Interface) { + if current.IsNil() { + return nil, false + } + if current.Kind() == reflect.Pointer { + visit := valueVisit{typeOf: current.Type(), kind: current.Kind(), ptr: current.Pointer()} + if seen[visit] { + return nil, false + } + seen[visit] = true + } + current = current.Elem() + } + if !current.IsValid() { + return nil, false + } + descriptor, issue := builder.describe(current.Type(), Path{}) + if issue != nil { + return nil, false + } + switch descriptor.kind { + case descriptorStruct: + if segment.kind == pathSegmentIndex { + return nil, false + } + if position, ok := descriptor.fieldByName[segment.key]; ok { + current = resultField(current, descriptor.fields[position].index) + } else if descriptor.inlineMap != nil { + current = resultMapEntry(resultField(current, descriptor.inlineMap.index), segment.key) + } else { + return nil, false + } + case descriptorMap: + if segment.kind == pathSegmentIndex { + return nil, false + } + current = resultMapEntry(current, segment.key) + case descriptorSlice, descriptorArray: + index, ok := schemaIndex(segment) + if !ok || index >= current.Len() { + return nil, false + } + current = current.Index(index) + default: + return nil, false + } + if !current.IsValid() { + return nil, false + } + } + if !current.CanInterface() { + return nil, false + } + return current.Interface(), true +} + +func resultField(root reflect.Value, index []int) reflect.Value { + current := root + for position, field := range index { + if current.Kind() != reflect.Struct { + return reflect.Value{} + } + current = current.Field(field) + if position < len(index)-1 { + for current.Kind() == reflect.Pointer { + if current.IsNil() { + return reflect.Value{} + } + current = current.Elem() + } + } + } + return current +} + +func resultMapEntry(value reflect.Value, name string) reflect.Value { + if !value.IsValid() || value.Kind() != reflect.Map { + return reflect.Value{} + } + key := reflect.New(value.Type().Key()).Elem() + key.SetString(name) + return value.MapIndex(key) +} diff --git a/internal/engine/result_value_test.go b/internal/engine/result_value_test.go new file mode 100644 index 0000000..a87d2fd --- /dev/null +++ b/internal/engine/result_value_test.go @@ -0,0 +1,67 @@ +package engine + +import ( + "reflect" + "testing" +) + +func TestResultValueNavigation(t *testing.T) { + type key string + type embedded struct{ Name string } + type root struct { + Embedded *embedded `yaml:",inline"` + Extra map[key]any `yaml:",inline"` + List []int `yaml:"list"` + Any any `yaml:"any"` + } + value := root{Embedded: &embedded{Name: "named"}, Extra: map[key]any{"a/b": nil}, List: []int{3}, Any: map[string]any{"n": []any{"ok"}}} + parsed, _ := ParsePath("/any/n/0") + for _, tc := range []struct { + path Path + want any + ok bool + }{ + {Keys("name"), "named", true}, + {Keys("a/b"), nil, true}, + {Keys("missing"), nil, false}, + {Keys("list").Index(0), 3, true}, + {Keys("list").Key("0"), nil, false}, + {parsed, "ok", true}, + {Keys("list").Index(2), nil, false}, + {Path{}.Index(-1), nil, false}, + } { + got, ok := ResultValue(value, tc.path, SecretBinding{}) + if ok != tc.ok || !reflect.DeepEqual(got, tc.want) { + t.Errorf("%s: got %#v, %v; want %#v, %v", tc.path.String(), got, ok, tc.want, tc.ok) + } + } + value.Embedded = nil + if _, ok := ResultValue(value, Keys("name"), SecretBinding{}); ok { + t.Fatal("nil inline pointer was traversed") + } +} + +func TestResultValueTerminalAndPointerCycle(t *testing.T) { + type pointer *pointer + var cycle pointer + cycle = &cycle + var nilSlice []string + for _, value := range []any{nil, nilSlice, make(chan int), cycle} { + got, ok := ResultValue(value, Path{}, SecretBinding{}) + if !ok || reflect.TypeOf(got) != reflect.TypeOf(value) { + t.Fatalf("terminal %#v: got %#v, %v", value, got, ok) + } + } + if _, ok := ResultValue(cycle, Keys("x"), SecretBinding{}); ok { + t.Fatal("pointer cycle was traversed") + } + channel := make(chan int) + value := struct{ Channel chan int }{Channel: channel} + got, ok := ResultValue(value, Keys("channel"), SecretBinding{}) + if !ok || got != channel { + t.Fatalf("unsupported terminal: got %#v, %v", got, ok) + } + if _, ok := ResultValue(value, Keys("channel", "x"), SecretBinding{}); ok { + t.Fatal("unsupported terminal accepted navigation") + } +} diff --git a/internal/engine/schema.go b/internal/engine/schema.go index 84427a6..a6f2009 100644 --- a/internal/engine/schema.go +++ b/internal/engine/schema.go @@ -115,6 +115,7 @@ type schemaBuilder struct { building map[reflect.Type]bool journal []reflect.Type secrets SecretBinding + lookup bool } func (b *schemaBuilder) describe(current reflect.Type, path Path) (*typeDescriptor, *schemaIssue) { @@ -128,6 +129,11 @@ func (b *schemaBuilder) describe(current reflect.Type, path Path) (*typeDescript defer delete(b.building, current) fail := func(code Code, message string) (*typeDescriptor, *schemaIssue) { + // Lookup may reach unsupported values as terminals; they remain leaves. + if b.lookup && (code == CodeSchemaUnsupportedType || code == CodeSchemaTextCodec) { + descriptor.kind = descriptorInvalid + return descriptor, nil + } delete(b.cache, current) return nil, &schemaIssue{code: code, path: path.clone(), message: message} }