cfgcascade

type Cascade[T any] struct {
	// Layers are the ranked config sources. They do not need to be pre-sorted;
	// Resolve sorts them by Rank before processing.
	Layers []Layer[T]

	// MergeFn combines two values. It receives (base, overlay) where overlay
	// comes from the higher-ranked (more specific) layer. The returned value
	// becomes the new base for subsequent merges.
	MergeFn func(base, overlay T) T
}

type DefaultProvider[T any] struct {
	ProviderName string
	Default      T
}

type EnvProvider struct {
	// ProviderName is the human-readable name for this provider.
	ProviderName string

	// Prefix is the env var prefix to match (e.g. "TAP_"). Only variables
	// starting with this prefix are included.
	Prefix string

	// Keys lists the env var names (without prefix) to look up. If empty,
	// the provider returns ErrNotExist. Each key is looked up as Prefix+key.
	// For example, Keys=["DEFAULT_KEG", "LOG_LEVEL"] with Prefix="TAP_"
	// looks up TAP_DEFAULT_KEG and TAP_LOG_LEVEL.
	Keys []string
}

type FuncProvider[T any] struct {
	ProviderName string
	Fn           func(getenv func(string) string) (T, error)
}

type Layer[T any] struct {
	Rank     int
	Provider Provider[T]
}

type MissingProvider[T any] struct {
	ProviderName string
}

type Provider[T any] interface {
	// Load returns a value from this source. Return an error wrapping
	// os.ErrNotExist to signal that the source is absent (graceful skip).
	Load(getenv func(string) string) (T, error)

	// Name returns a human-readable name for this provider (e.g. "user-config",
	// "env-vars").
	Name() string
}

type ProviderError struct {
	Name string
	Err  error
}

type ResolvedValue[T any] struct {
	// Value is the final merged configuration.
	Value T

	// Sources lists the names of providers that contributed, ordered from
	// most-specific (highest rank) to least-specific.
	Sources []string

	// Errors lists providers that returned non-ErrNotExist errors.
	Errors []ProviderError
}