Provide passive per-source resource contexts

resource_context.go

@@ -0,0 +1,32 @@
+package configkit
+
+import "io/fs"
+
+// ResourceContext provides a passive rooted filesystem view and a
+// slash-relative BaseDir for one acquired source. FS is borrowed: caller-owned
+// filesystems remain under caller control, and host files are opened afresh.
+// Querying this record performs no I/O. Resource contents may change after
+// loading; callers must close files they open through FS.
+type ResourceContext struct {
+	FS      fs.FS
+	BaseDir string
+}
+
+// SourceContext returns the context of an acquired source ID. Unknown IDs and
+// sources without context return false. It is nil-safe and performs no I/O.
+// Follow individual origin locations when an origin has multiple sources.
+func (r *Result[T]) SourceContext(id string) (ResourceContext, bool) {
+	if r == nil || r.inspection == nil {
+		return ResourceContext{}, false
+	}
+	context, ok := r.inspection.SourceContext(id)
+	return ResourceContext{FS: context.FS, BaseDir: context.BaseDir}, ok
+}
+
+// SourceContext returns a passive source context during the active resolution
+// callback. Like other Resolution queries, it cannot be used after callback
+// return and performs no filesystem operations itself.
+func (r *Resolution) SourceContext(id string) (ResourceContext, bool) {
+	context, ok := r.engineContext().SourceContext(id)
+	return ResourceContext{FS: context.FS, BaseDir: context.BaseDir}, ok
+}