Add scoped inspection views
This commit is contained in:
@@ -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
|
||||
|
||||
91
facade_inspection_view_test.go
Normal file
91
facade_inspection_view_test.go
Normal 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
71
inspection_view.go
Normal 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))
|
||||
}
|
||||
33
internal/engine/inspection_view.go
Normal file
33
internal/engine/inspection_view.go
Normal 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
|
||||
}
|
||||
Reference in New Issue
Block a user