diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index fac97f7..a23cde3 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,6 +1,6 @@ # 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 @@ -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 +**Complete.** + Add a root-owned, non-generic `Inspection` with unexported state retaining the 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 diff --git a/facade_inspection_view_test.go b/facade_inspection_view_test.go new file mode 100644 index 0000000..4cfd897 --- /dev/null +++ b/facade_inspection_view_test.go @@ -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") + } +} diff --git a/inspection_view.go b/inspection_view.go new file mode 100644 index 0000000..430cac7 --- /dev/null +++ b/inspection_view.go @@ -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)) +} diff --git a/internal/engine/inspection_view.go b/internal/engine/inspection_view.go new file mode 100644 index 0000000..1b53324 --- /dev/null +++ b/internal/engine/inspection_view.go @@ -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 +}