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 } // WriteEffective renders the saved value at the reporting scope with its // original sensitivity. Unavailable values and nil writers return an error; // writer errors can leave partial output. func (i Inspection) WriteEffective(output io.Writer) error { return i.view.WriteEffective(output) } // Diff compares frozen views at the same canonical scope, including differences // at an ancestor when the existing comparison treats that ancestor atomically. // Views may come from different root Go types. Unavailable or mismatched views // return an error without records. func (i Inspection) Diff(other Inspection) ([]Difference, error) { values, err := i.view.Diff(other.view) if err != nil { return nil, err } return fromEngineDifferences(values), nil } // 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)) }