Expose layered configuration loading and inspection

internal/engine/layered.go

@@ -0,0 +1,50 @@
+package engine
+
+import "os"
+
+// Input selects one source and its independent import policy.
+type Input struct {
+	Source     Source
+	Imports    bool
+	Filesystem *FilesystemContext
+}
+
+// Underlay contains strictly composed contributions at one precedence tier.
+type Underlay struct{ Inputs []Input }
+
+// LayeredOptions selects lower-priority tiers and final application rules.
+type LayeredOptions[T any] struct {
+	Definition        Definition[T]
+	Underlays         []Underlay
+	Overlay           string
+	OverlayFilesystem *FilesystemContext
+	Overrides         []Override
+}
+
+// LoadLayered loads a main input and lower-priority grouped inputs through one
+// final decode, resolution, and validation lifecycle.
+func LoadLayered[T any](main Input, secrets SecretBinding, supplied ...LayeredOptions[T]) (*Loaded[T], error) {
+	if len(supplied) > 1 {
+		return nil, (&diagnosticAccumulator{diagnostics: []Diagnostic{optionDiagnostic(CodeOptionsInvalid, "LoadLayered accepts at most one options value")}}).loadError()
+	}
+	var options LayeredOptions[T]
+	if len(supplied) != 0 {
+		options = supplied[0]
+	}
+	request := loadRequest[T]{
+		main:       loadInput{source: main.Source, imports: main.Imports, filesystem: main.Filesystem},
+		definition: options.Definition, overlay: options.Overlay,
+		overlayFilesystem: options.OverlayFilesystem,
+		overrides:         append([]Override(nil), options.Overrides...),
+		underlays:         make([]loadGroup, len(options.Underlays)),
+	}
+	for index, underlay := range options.Underlays {
+		request.underlays[index].inputs = make([]loadInput, len(underlay.Inputs))
+		for inputIndex, input := range underlay.Inputs {
+			request.underlays[index].inputs[inputIndex] = loadInput{
+				source: input.Source, imports: input.Imports, filesystem: input.Filesystem,
+			}
+		}
+	}
+	return loadGroupedWithSecretLookup(request, secrets, os.LookupEnv)
+}