Add scoped inspection views

This commit is contained in:
2026-11-21 04:06:45 +00:00
parent f514936c9c
commit 68a6da2388
4 changed files with 198 additions and 1 deletions

View File

@@ -1,6 +1,6 @@
# Implementation plan: typed result values and focused inspection # Implementation plan: typed result values and focused inspection
Status: implementation in progress; Stages 1–2 complete. Status: implementation in progress; Stages 1–3 complete.
## Scope and working instructions ## Scope and working instructions
@@ -127,6 +127,8 @@ Value tests and the public boundary tests when this stage is runnable.
## Stage 3 — Add the inspection view and canonical scope selection ## Stage 3 — Add the inspection view and canonical scope selection
**Complete.**
Add a root-owned, non-generic `Inspection` with unexported state retaining the Add a root-owned, non-generic `Inspection` with unexported state retaining the
existing engine Inspection and normalized scope. Put scope-aware implementation existing engine Inspection and normalized scope. Put scope-aware implementation
in engine (a small private-to-consumers view/helper is sufficient); do not copy the in engine (a small private-to-consumers view/helper is sufficient); do not copy the

View File

@@ -0,0 +1,91 @@
package configkit_test
import (
"bytes"
"reflect"
"testing"
configkit "go.maximumdirect.net/configkit"
)
func TestInspectionViewScopeAndQueries(t *testing.T) {
result, err := configkit.Load[map[string]any](configkit.Bytes("view.yml", []byte("a: {child: one}\nab: two\nitems: [{name: first}]\n'a/b': {'': value}\n")))
if err != nil {
t.Fatal(err)
}
view, ok := result.InspectSubtree(configkit.Keys("a"))
if !ok {
t.Fatal("view unavailable")
}
var paths []string
for _, path := range view.HistoricalPaths() {
paths = append(paths, path.String())
}
if !reflect.DeepEqual(paths, []string{"/a", "/a/child"}) {
t.Fatalf("scope paths = %#v", paths)
}
if _, ok := view.Metadata().Lookup(configkit.Keys("ab")); !ok {
t.Fatal("metadata filtered")
}
if _, ok := view.Explain(configkit.Keys("ab")); !ok {
t.Fatal("native query filtered")
}
var output bytes.Buffer
if err := view.WriteExplanation(&output, configkit.Keys("ab")); err != nil {
t.Fatal(err)
}
if len(view.Sources()) != len(result.Sources()) || len(view.Sources()) == 0 {
t.Fatal("sources filtered")
}
if _, ok := view.Source(view.Sources()[0].ID); !ok {
t.Fatal("source unavailable")
}
if _, ok := result.InspectSubtree(configkit.Keys("absent")); !ok {
t.Fatal("absent scope rejected")
}
if _, ok := result.InspectSubtree(configkit.Path{}.Index(-1)); ok {
t.Fatal("invalid scope accepted")
}
keyScope, _ := result.InspectSubtree(configkit.Keys("items", "0"))
indexScope, _ := result.InspectSubtree(configkit.Keys("items").Index(0))
if !reflect.DeepEqual(keyScope.HistoricalPaths(), indexScope.HistoricalPaths()) {
t.Fatal("numeric scope differs")
}
escaped, _ := result.InspectSubtree(configkit.Keys("a/b", ""))
if got := escaped.HistoricalPaths(); len(got) != 1 || got[0].String() != "/a~1b/" {
t.Fatalf("escaped scope = %#v", got)
}
root, _ := result.InspectSubtree(configkit.Path{})
if !reflect.DeepEqual(root.HistoricalPaths(), result.Metadata().HistoricalPaths()) {
t.Fatal("root scope filtered")
}
}
func TestInspectionViewUnavailable(t *testing.T) {
var result *configkit.Result[map[string]any]
if _, ok := result.InspectSubtree(configkit.Path{}); ok {
t.Fatal("nil result accepted")
}
if _, ok := (&configkit.Result[map[string]any]{}).InspectSubtree(configkit.Path{}); ok {
t.Fatal("manual result accepted")
}
var view configkit.Inspection
if len(view.HistoricalPaths()) != 0 || view.Sources() != nil {
t.Fatal("zero view returned records")
}
if _, ok := view.Metadata().Lookup(configkit.Path{}); ok {
t.Fatal("zero metadata")
}
if _, ok := view.Source("source-1"); ok {
t.Fatal("zero source")
}
if _, ok := view.SourceContext("source-1"); ok {
t.Fatal("zero source context")
}
if _, ok := view.Explain(configkit.Path{}); ok {
t.Fatal("zero explanation")
}
if err := view.WriteExplanation(&bytes.Buffer{}, configkit.Path{}); err == nil {
t.Fatal("zero explanation rendering")
}
}

71
inspection_view.go Normal file
View File

@@ -0,0 +1,71 @@
package configkit
import (
"io"
"go.maximumdirect.net/configkit/internal/engine"
)
// Inspection is a reporting view of a completed load. Its scope filters
// enumeration; explicit queries and source records retain their native paths.
type Inspection struct{ view engine.InspectionView }
// InspectSubtree selects a canonical JSON Pointer reporting location, including
// an absent location. Equivalent key and index spellings select the same scope.
// Nil, manually constructed results and invalid paths cannot produce a view.
func (r *Result[T]) InspectSubtree(path Path) (Inspection, bool) {
if r == nil {
return Inspection{}, false
}
view, ok := engine.NewInspectionView(r.inspection, toEnginePath(path))
return Inspection{view: view}, ok
}
// Metadata returns the unfiltered metadata of the completed load.
func (i Inspection) Metadata() Metadata { return Metadata{value: i.view.Inspection().Metadata()} }
// HistoricalPaths returns observed paths at or beneath the reporting scope.
func (i Inspection) HistoricalPaths() []Path {
values := i.view.HistoricalPaths()
paths := make([]Path, len(values))
for index := range values {
paths[index] = fromEnginePath(values[index])
}
return paths
}
// Sources returns the full detached source catalog.
func (i Inspection) Sources() []SourceInfo {
values := i.view.Inspection().Sources()
if values == nil {
return nil
}
result := make([]SourceInfo, len(values))
for index := range values {
result[index] = fromEngineSourceInfo(values[index])
}
return result
}
// Source returns a detached record from the full source catalog.
func (i Inspection) Source(id string) (SourceInfo, bool) {
value, ok := i.view.Inspection().Source(id)
return fromEngineSourceInfo(value), ok
}
// SourceContext returns the borrowed resource context for an acquired source.
func (i Inspection) SourceContext(id string) (ResourceContext, bool) {
value, ok := i.view.Inspection().SourceContext(id)
return ResourceContext{FS: value.FS, BaseDir: value.BaseDir}, ok
}
// Explain queries a native path, whether or not it lies within the scope.
func (i Inspection) Explain(path Path) (Explanation, bool) {
value, ok := i.view.Inspection().Explain(toEnginePath(path))
return fromEngineExplanation(value), ok
}
// WriteExplanation renders an explicit native path using the frozen load.
func (i Inspection) WriteExplanation(output io.Writer, path Path) error {
return i.view.Inspection().WriteExplanation(output, toEnginePath(path))
}

View File

@@ -0,0 +1,33 @@
package engine
// InspectionView borrows an inspection and selects a canonical reporting scope.
type InspectionView struct {
inspection *Inspection
scope Path
}
func NewInspectionView(inspection *Inspection, scope Path) (InspectionView, bool) {
if inspection == nil || !scope.valid() {
return InspectionView{}, false
}
normalized, err := ParsePath(scope.String())
if err != nil {
return InspectionView{}, false
}
return InspectionView{inspection: inspection, scope: normalized}, true
}
func (v InspectionView) Inspection() *Inspection { return v.inspection }
func (v InspectionView) HistoricalPaths() []Path {
if v.inspection == nil {
return nil
}
var paths []Path
for _, path := range v.inspection.Metadata().HistoricalPaths() {
if pathContains(v.scope, path) {
paths = append(paths, path)
}
}
return paths
}