merge

type MergeContext struct {
	// CurrentFile is the file currently being processed.
	CurrentFile string

	// ImportChain tracks the chain of imports leading to the current file.
	// The first element is the root file, the last is the current file.
	ImportChain []string

	// ParentContext is the parent merge context for nested operations.
	ParentContext *MergeContext

	// Provenance stores optional provenance tracking for configuration values.
	// This is nil by default (provenance disabled) for zero performance overhead.
	// Call EnableProvenance() to activate provenance tracking.
	Provenance *ProvenanceStorage

	// Positions stores YAML position information for values in the current file.
	// This maps JSONPath-style paths to line/column positions in the YAML file.
	// Used by MergeWithProvenance to record accurate provenance data.
	Positions u.PositionMap
}

type ProvenanceEntry struct {
	// File is the source file path where this value was defined.
	File string

	// Line is the line number (1-indexed) where this value appears.
	Line int

	// Column is the column number (1-indexed) where this value starts.
	Column int

	// Type indicates how this value was introduced (import, inline, override, computed, default).
	Type ProvenanceType

	// ValueHash is a hash of the value for change detection.
	// This allows detecting when a value was overridden with the same value.
	ValueHash string

	// Depth is the inheritance depth (0=parent stack, 1=direct import, 2+=nested imports).
	Depth int
}

type ProvenanceEntryParams struct {
	File   string
	Line   int
	Column int
	Type   ProvenanceType
	Value  any
	Depth  int
}

type ProvenanceStorage struct {
	// contains filtered or unexported fields
}

type ProvenanceTracker interface {
	// RecordProvenance records provenance information for a value at the given path.
	// The path should use JSONPath-style syntax (e.g., "vars.tags.environment").
	// Multiple entries for the same path represent the inheritance chain (base → override).
	RecordProvenance(path string, entry ProvenanceEntry)

	// GetProvenance returns the complete provenance chain for a given path.
	// The chain is ordered from base → override, with the last entry being the final value.
	// Returns nil if no provenance exists for the path.
	GetProvenance(path string) []ProvenanceEntry

	// HasProvenance checks if provenance information exists for the given path.
	// Returns false if provenance tracking is disabled or path has no provenance.
	HasProvenance(path string) bool

	// GetProvenancePaths returns all paths that have provenance information.
	// Returns nil if provenance tracking is disabled.
	// The order of paths is not guaranteed.
	GetProvenancePaths() []string

	// IsProvenanceEnabled returns true if provenance tracking is currently active.
	// When disabled, RecordProvenance calls should be no-ops for performance.
	IsProvenanceEnabled() bool

	// EnableProvenance activates provenance tracking for this tracker.
	// This should be called before any provenance recording occurs.
	// Once enabled, all merge/load operations should track provenance.
	EnableProvenance()
}

type ProvenanceType string