stack_processor_utils.go

package exec

import (
	stderrors "errors"
	"fmt"
	"hash/fnv"
	"os"
	"path/filepath"
	"reflect"
	"slices"
	"sort"
	"strconv"
	"strings"
	"sync"

	"github.com/go-viper/mapstructure/v2"
	"github.com/pkg/errors"
	"github.com/santhosh-tekuri/jsonschema/v5"
	"gopkg.in/yaml.v3"

	errUtils "github.com/cloudposse/atmos/errors"
	cfg "github.com/cloudposse/atmos/pkg/config"
	log "github.com/cloudposse/atmos/pkg/logger"
	m "github.com/cloudposse/atmos/pkg/merge"
	"github.com/cloudposse/atmos/pkg/perf"
	"github.com/cloudposse/atmos/pkg/schema"
	stackimports "github.com/cloudposse/atmos/pkg/stack/imports"
	atmostmpl "github.com/cloudposse/atmos/pkg/template"
	u "github.com/cloudposse/atmos/pkg/utils"
	"github.com/cloudposse/atmos/pkg/version/manager"
)

// Mutex to serialize writes to importsConfig maps during parallel import processing.
var importsConfigLock = &sync.Mutex{}

// extractLocalsResult holds the results of parsing raw YAML and extracting locals.
type extractLocalsResult struct {
	locals       map[string]any // Resolved locals.
	settings     map[string]any // Settings section (for template context).
	vars         map[string]any // Vars section (for template context).
	env          map[string]any // Env section (for template context).
	versionTrack string         // Stack-asserted version track.
	hasLocals    bool           // Whether any locals section exists in the file (including empty locals).
}

// localsExtractionCache memoizes extractLocalsFromRawYAML results keyed by a
// composite of the file path and a content fingerprint. Within a single command
// execution against a real filesystem, file content is immutable (and is itself
// cached via getFileContentSyncMap), so the parse + locals resolution is fully
// deterministic and may be served from cache on repeat imports of the same file.
//
// On the customer workload, extractLocalsFromRawYAML was called 22,181 times for
// ~836 unique files (~26 calls per file via transitive imports), accumulating 13s
// of cumulative CPU time. ~7s of that was UnmarshalYAMLFromFile re-parsing the
// same YAML content for the same file path. This cache eliminates the repeat work.
//
// The cache key includes a 64-bit FNV-1a hash of the YAML content so that test
// callers reusing the same logical file path with different content (a common
// pattern in stack_processor_utils_test.go) do not see stale results, and so that
// a future caller doing dynamic content generation cannot trip on a stale parse.
// FNV-1a was chosen for speed and stdlib availability; collisions on map-key
// strings are not a security concern here because the cache only feeds back to
// the same function under the same atmosConfig.
//
// Cached entries are deep-copied on retrieval (the result struct contains four
// maps: locals/settings/vars/env, all of which downstream consumers store into
// shared template contexts; mutating them would corrupt the cache). Deep-copy
// cost is dominated by map allocation and is typically <50µs per call — well
// below the 533µs avg of the un-cached path.
var localsExtractionCache sync.Map // map[string]*extractLocalsResult (immutable post-insert).

// hexBase is the base argument passed to strconv.FormatUint when building the
// hex-encoded portion of localsCacheKey.
const hexBase = 16

// localsCacheKey builds a stable cache key from the absolute file path and a
// content fingerprint. The fingerprint is a 64-bit FNV-1a hash of yamlContent
// so that the same file path used with two different contents (mostly a test
// pattern) yields two distinct cache entries.
func localsCacheKey(filePath, yamlContent string) string {
	h := fnv.New64a()
	_, _ = h.Write([]byte(yamlContent))
	return filePath + "@" + strconv.FormatUint(h.Sum64(), hexBase)
}

// cloneExtractLocalsResult deep-copies an extractLocalsResult so the cache value
// remains immutable across concurrent retrievals. Returns the same nil hint when
// the source is nil.
func cloneExtractLocalsResult(src *extractLocalsResult) *extractLocalsResult {
	if src == nil {
		return nil
	}
	dst := &extractLocalsResult{
		hasLocals:    src.hasLocals,
		versionTrack: src.versionTrack,
	}
	if src.locals != nil {
		if cloned, err := m.DeepCopyMap(src.locals); err == nil {
			dst.locals = cloned
		}
	}
	if src.settings != nil {
		if cloned, err := m.DeepCopyMap(src.settings); err == nil {
			dst.settings = cloned
		}
	}
	if src.vars != nil {
		if cloned, err := m.DeepCopyMap(src.vars); err == nil {
			dst.vars = cloned
		}
	}
	if src.env != nil {
		if cloned, err := m.DeepCopyMap(src.env); err == nil {
			dst.env = cloned
		}
	}
	return dst
}

// ClearLocalsExtractionCache clears the locals extraction cache.
// This should be called between independent operations (like tests) to ensure
// fresh processing of files whose on-disk content may have changed.
func ClearLocalsExtractionCache() {
	defer perf.Track(nil, "exec.ClearLocalsExtractionCache")()

	localsExtractionCache.Range(func(key, _ any) bool {
		localsExtractionCache.Delete(key)
		return true
	})
}

// extractLocalsFromRawYAML parses raw YAML content and extracts/resolves file-scoped locals.
// This function is called BEFORE template processing to make locals available during template execution.
// The raw YAML may contain unresolved templates like {{ .locals.X }}, which YAML treats as strings.
// The locals resolver handles resolving self-references between locals.
// Returns the resolved locals and other sections (settings, vars, env) that should be available during template processing.
//
// Locals are extracted and merged in order of specificity:
// 1. Global locals (root level)
// 2. Section-specific locals (terraform, helmfile, packer sections)
//
// Section-specific locals inherit from and can override global locals.
// All resolved locals are flattened into a single map for template processing.
//
// Results are memoized in localsExtractionCache keyed by filePath. See the cache
// declaration for rationale and the deep-copy contract.
func extractLocalsFromRawYAML(atmosConfig *schema.AtmosConfiguration, yamlContent string, filePath string) (*extractLocalsResult, error) {
	defer perf.Track(atmosConfig, "exec.extractLocalsFromRawYAML")()

	// Fast path: result is cached for this (file path, content fingerprint)
	// pair. Deep-copy on retrieval to keep the cache value immutable across
	// concurrent callers.
	cacheKey := localsCacheKey(filePath, yamlContent)
	if raw, found := localsExtractionCache.Load(cacheKey); found {
		if cached, ok := raw.(*extractLocalsResult); ok {
			return cloneExtractLocalsResult(cached), nil
		}
	}

	// Parse raw YAML to extract the structure.
	// YAML treats template expressions like {{ .locals.X }} as plain strings,
	// so parsing succeeds even with unresolved templates.
	// Use Atmos's YAML unmarshaling which properly handles custom tags like !terraform.state
	// by converting them to strings (e.g., "!terraform.state component .output").
	// Create a default config if nil (UnmarshalYAMLFromFile requires non-nil config).
	configToUse := atmosConfig
	if configToUse == nil {
		configToUse = &schema.AtmosConfiguration{}
	}
	rawConfig, err := u.UnmarshalYAMLFromFile[map[string]any](configToUse, yamlContent, filePath)
	if err != nil {
		// Provide a helpful hint if the file might contain Go template directives
		// that aren't valid YAML. Files with .yaml.tmpl extension are processed
		// as templates first, which allows non-YAML-valid Go template syntax.
		hint := ""
		if !strings.HasSuffix(filePath, u.TemplateExtension) {
			hint = " (hint: if this file contains Go template directives, rename it to .yaml.tmpl)"
		}
		return nil, fmt.Errorf("%w: failed to parse YAML for locals extraction%s: %w", errUtils.ErrInvalidStackManifest, hint, err)
	}

	if rawConfig == nil {
		empty := &extractLocalsResult{}
		localsExtractionCache.Store(cacheKey, empty)
		return cloneExtractLocalsResult(empty), nil
	}

	// Derive the stack name from the file path so that YAML functions like
	// !terraform.state (2-arg form) can resolve their implicit stack reference.
	// Previously, an empty string was passed here, which caused !terraform.state
	// to fail with "stack is required" (see GitHub issue #2080).
	currentStack := deriveStackNameForLocals(atmosConfig, rawConfig, filePath)

	localsCtx, err := ProcessStackLocals(atmosConfig, rawConfig, filePath, currentStack)
	if err != nil {
		return nil, fmt.Errorf("%w: failed to process stack locals: %w", errUtils.ErrInvalidStackManifest, err)
	}

	result := buildLocalsResult(rawConfig, localsCtx)
	// Cache the canonical result and return a deep copy so the cache remains
	// the single immutable source of truth. Concurrent goroutines that race
	// on the first cache miss for a given file path will both run the parse
	// (cheap given the cache hit on subsequent calls), and the later Store
	// silently wins — both results are identical for the same input.
	localsExtractionCache.Store(cacheKey, result)
	return cloneExtractLocalsResult(result), nil
}

// deriveStackNameForLocals derives the stack name from the file path and raw config
// so that YAML functions in locals (like !terraform.state) can use stack context.
// This uses the same logic as describe_locals.go (deriveStackName) to compute the
// stack name from the file path, vars section, and atmos config.
// Returns empty string if the stack name cannot be determined.
func deriveStackNameForLocals(atmosConfig *schema.AtmosConfiguration, rawConfig map[string]any, filePath string) string {
	if atmosConfig == nil {
		return ""
	}

	// Extract vars section for stack name derivation.
	var varsSection map[string]any
	if vs, ok := rawConfig[cfg.VarsSectionName].(map[string]any); ok {
		varsSection = vs
	}

	// Compute relative stack file name from file path.
	stackFileName := computeStackFileName(atmosConfig, filePath)
	if stackFileName == "" {
		return ""
	}

	return deriveStackName(atmosConfig, stackFileName, varsSection, rawConfig)
}

// computeStackFileName computes the relative stack file name from an absolute file path
// by stripping the stacks base path prefix and the file extension.
// This produces a name like "deploy/dev" or "orgs/acme/plat/dev/us-east-1".
func computeStackFileName(atmosConfig *schema.AtmosConfiguration, filePath string) string {
	if atmosConfig == nil {
		return ""
	}

	// Get the absolute stacks base path.
	stacksBasePath := filepath.Join(atmosConfig.BasePath, atmosConfig.Stacks.BasePath)
	absStacksBasePath, err := filepath.Abs(stacksBasePath)
	if err != nil {
		return ""
	}

	absFilePath, err := filepath.Abs(filePath)
	if err != nil {
		return ""
	}

	// Strip the base path prefix.
	rel, err := filepath.Rel(absStacksBasePath, absFilePath)
	if err != nil {
		return ""
	}

	// Remove known stack/template suffixes (longest first to handle .yaml.tmpl correctly).
	for _, suffix := range []string{
		u.YamlTemplateExtension, // .yaml.tmpl
		u.YmlTemplateExtension,  // .yml.tmpl
		u.YamlFileExtension,     // .yaml
		u.YmlFileExtension,      // .yml
	} {
		if strings.HasSuffix(rel, suffix) {
			rel = strings.TrimSuffix(rel, suffix)

			break
		}
	}

	return rel
}

// buildLocalsResult builds an extractLocalsResult from raw config and resolved locals context.
func buildLocalsResult(rawConfig map[string]any, localsCtx *LocalsContext) *extractLocalsResult {
	result := &extractLocalsResult{
		locals: localsCtx.MergeForTemplateContext(),
	}

	// Detect locals section presence (including empty locals).
	// This allows empty locals: {} to still enable template context.
	if _, ok := rawConfig[cfg.LocalsSectionName]; ok {
		result.hasLocals = true
	}
	if localsCtx.HasTerraformLocals || localsCtx.HasHelmfileLocals || localsCtx.HasPackerLocals {
		result.hasLocals = true
	}

	// Ensure locals map is never nil when hasLocals is true.
	if result.hasLocals && result.locals == nil {
		result.locals = make(map[string]any)
	}

	// Extract settings, vars, env sections for template context.
	if settings, ok := rawConfig[cfg.SettingsSectionName].(map[string]any); ok {
		result.settings = settings
	}
	if vars, ok := rawConfig[cfg.VarsSectionName].(map[string]any); ok {
		result.vars = vars
	}
	if env, ok := rawConfig[cfg.EnvSectionName].(map[string]any); ok {
		result.env = env
	}
	if versionSection, ok := rawConfig["version"].(map[string]any); ok {
		if track, ok := versionSection["track"].(string); ok {
			result.versionTrack = track
		}
	}

	return result
}

// processTemplatesInSection processes Go templates in a section (settings, vars, or env) using the provided context.
// This allows sections to reference resolved locals and other processed sections.
// Returns the processed section or an error if template processing fails.
// IMPORTANT: Uses ignoreMissingTemplateValues=false so that templates referencing values not in the
// current context (like {{ .atmos_component }}) will fail, and the caller can fall back to raw values.
// This preserves those templates for later processing when the full context is available.
func processTemplatesInSection(atmosConfig *schema.AtmosConfiguration, section map[string]any, context map[string]any, filePath string) (map[string]any, error) {
	defer perf.Track(atmosConfig, "exec.processTemplatesInSection")()

	if len(section) == 0 {
		return section, nil
	}

	section = processStructuredTemplateRefs(section, context).(map[string]any)

	// Convert section to YAML for template processing.
	yamlStr, err := u.ConvertToYAML(section)
	if err != nil {
		return nil, stderrors.Join(errUtils.ErrInvalidStackManifest, fmt.Errorf("failed to convert section to YAML: %w", err))
	}

	// Quick check: if no template markers, return as-is.
	if !strings.Contains(yamlStr, "{{") {
		return section, nil
	}

	// Process templates in the YAML string.
	// Use ignoreMissingTemplateValues=false so templates with missing values fail
	// (e.g., {{ .atmos_component }} when component context isn't available yet).
	// The caller will fall back to raw values, preserving templates for later processing.
	processed, err := ProcessTmpl(atmosConfig, filePath, yamlStr, context, false)
	if err != nil {
		return nil, stderrors.Join(errUtils.ErrInvalidStackManifest, fmt.Errorf("failed to process templates in section: %w", err))
	}

	// Parse the processed YAML back to a map.
	var result map[string]any
	if err := yaml.Unmarshal([]byte(processed), &result); err != nil {
		return nil, stderrors.Join(errUtils.ErrInvalidStackManifest, fmt.Errorf("failed to parse processed section YAML: %w", err))
	}

	return result, nil
}

func processStructuredTemplateRefs(value any, context map[string]any) any {
	switch typed := value.(type) {
	case map[string]any:
		result := make(map[string]any, len(typed))
		for k, v := range typed {
			result[k] = processStructuredTemplateRefs(v, context)
		}
		return result
	case []any:
		result := make([]any, len(typed))
		for i, v := range typed {
			result[i] = processStructuredTemplateRefs(v, context)
		}
		return result
	case string:
		ref, ok, err := atmostmpl.ExtractPlainFieldRef(typed)
		if err != nil || !ok {
			return typed
		}
		if resolved, found := atmostmpl.LookupFieldPath(context, ref.Path); found {
			return resolved
		}
		return typed
	default:
		return value
	}
}

// extractAndAddLocalsToContext extracts locals from YAML and adds them to the template context.
// Returns the updated context and any error encountered during locals extraction.
// Note: The "locals" key in context is reserved for file-scoped locals and will override
// any user-provided "locals" key in the import context.
// Settings, vars, and env sections are also added to the context so templates can reference them.
// For template files (.tmpl), YAML parse errors are logged and the function continues
// without locals, since template files may contain Go template syntax that isn't valid YAML
// until after template processing.
func extractAndAddLocalsToContext(
	atmosConfig *schema.AtmosConfiguration,
	yamlContent string,
	filePath string,
	relativeFilePath string,
	context map[string]any,
) (map[string]any, error) {
	defer perf.Track(atmosConfig, "exec.extractAndAddLocalsToContext")()

	// Clone the input context so concurrent goroutines processing sibling imports
	// (in processYAMLConfigFileWithContextInternal, which fans out to one goroutine
	// per import while sharing mergedContext) cannot race on the file-scoped
	// delete + assign below. Without the clone, the parent context was mutated
	// directly, producing a data race surfaced by `go test -race` on
	// TestHierarchicalImports_*. Cloning is a shallow copy: the values are shared
	// references but the map header is per-goroutine, which is the only mutation
	// surface inside this function.
	clonedContext := make(map[string]any, len(context))
	for k, v := range context {
		if k == cfg.LocalsSectionName {
			// Enforce file-scoped locals: drop inherited locals during the
			// clone. This replaces the previous in-place delete on the shared
			// parent context.
			continue
		}
		clonedContext[k] = v
	}
	context = clonedContext

	extractResult, localsErr := extractLocalsFromRawYAML(atmosConfig, yamlContent, filePath)
	if localsErr != nil {
		// For template files (.tmpl), YAML parse errors are expected since the raw content
		// may contain Go template syntax that isn't valid YAML until after processing.
		// Log the error and continue without locals - template processing will happen next.
		if strings.HasSuffix(filePath, u.TemplateExtension) {
			log.Trace("Skipping locals extraction for template file with invalid YAML", "file", relativeFilePath, "error", localsErr)
			return context, nil
		}
		// Circular dependencies in locals are a stack misconfiguration error.
		// Return a helpful error with hints on how to fix it.
		if stderrors.Is(localsErr, errUtils.ErrLocalsCircularDep) {
			return context, errUtils.Build(errUtils.ErrLocalsCircularDep).
				WithCause(localsErr).
				WithContext("file", relativeFilePath).
				WithHintf("Fix the circular dependency in '%s'", relativeFilePath).
				WithHint("Ensure locals don't reference each other in a cycle").
				WithHintf("Use 'atmos describe locals --stack %s' to inspect locals", relativeFilePath).
				WithExitCode(1).
				Err()
		}
		return context, localsErr
	}

	// Only modify context if a locals section exists in the file.
	// This preserves the original behavior where files without locals don't trigger
	// template processing (see the len(context) > 0 check in ProcessBaseStackConfig).
	// We check hasLocals instead of len(locals) to support empty locals: {} sections,
	// which should still enable template context.
	if !extractResult.hasLocals {
		return manager.AddTemplateContext(atmosConfig, yamlContent, context, extractResult.versionTrack)
	}

	// context is never nil here: the clone above always allocates a fresh map
	// (make returns a non-nil empty map when len(input)==0). The historical
	// `if context == nil { context = make(...) }` initializer is now dead.

	// Add resolved locals to the template context first.
	// This allows settings/vars/env templates to reference locals.
	context[cfg.LocalsSectionName] = extractResult.locals
	var versionContextErr error
	context, versionContextErr = manager.AddTemplateContext(atmosConfig, yamlContent, context, extractResult.versionTrack)
	if versionContextErr != nil {
		return context, versionContextErr
	}
	log.Trace("Extracted and resolved locals", "file", relativeFilePath, "count", len(extractResult.locals))

	// Process templates in settings, vars, env sections using the resolved locals.
	// This enables bidirectional references between locals and settings:
	//   locals:
	//     stage: dev
	//   settings:
	//     context:
	//       stage_from_local: '{{ .locals.stage }}'  # Now resolves to "dev"
	//   vars:
	//     setting_value: '{{ .settings.context.stage_from_local }}'  # Now resolves to "dev"
	//
	// Note: We need to process these sections AFTER locals are resolved so they can reference .locals,
	// but BEFORE adding them to the context so vars can reference the resolved settings values.
	// Seed section context with any external import context so that settings/vars/env
	// templates referencing import-provided values can resolve during section processing.
	// Locals are always overridden to ensure file-scoped locality.
	localsOnlyContext := map[string]any{}
	for k, v := range context {
		localsOnlyContext[k] = v
	}
	localsOnlyContext[cfg.LocalsSectionName] = extractResult.locals

	// Process templates in settings if it contains template expressions.
	if extractResult.settings != nil {
		processedSettings, err := processTemplatesInSection(atmosConfig, extractResult.settings, localsOnlyContext, relativeFilePath)
		if err != nil {
			log.Debug("Failed to process templates in settings section", "file", relativeFilePath, "error", err)
			// Fall back to raw settings on error.
			context[cfg.SettingsSectionName] = extractResult.settings
		} else {
			context[cfg.SettingsSectionName] = processedSettings
		}
	}
	if extractResult.vars != nil {
		// For vars, we need locals, external context, and processed settings available.
		varsContext := map[string]any{}
		for k, v := range localsOnlyContext {
			varsContext[k] = v
		}
		if processedSettings, ok := context[cfg.SettingsSectionName].(map[string]any); ok {
			varsContext[cfg.SettingsSectionName] = processedSettings
		}
		processedVars, err := processTemplatesInSection(atmosConfig, extractResult.vars, varsContext, relativeFilePath)
		if err != nil {
			log.Debug("Failed to process templates in vars section", "file", relativeFilePath, "error", err)
			// Fall back to raw vars on error.
			context[cfg.VarsSectionName] = extractResult.vars
		} else {
			context[cfg.VarsSectionName] = processedVars
		}
	}
	if extractResult.env != nil {
		// For env, we need locals, external context, processed settings, and processed vars.
		envContext := map[string]any{}
		for k, v := range localsOnlyContext {
			envContext[k] = v
		}
		if processedSettings, ok := context[cfg.SettingsSectionName].(map[string]any); ok {
			envContext[cfg.SettingsSectionName] = processedSettings
		}
		if processedVars, ok := context[cfg.VarsSectionName].(map[string]any); ok {
			envContext[cfg.VarsSectionName] = processedVars
		}
		processedEnv, err := processTemplatesInSection(atmosConfig, extractResult.env, envContext, relativeFilePath)
		if err != nil {
			log.Debug("Failed to process templates in env section", "file", relativeFilePath, "error", err)
			// Fall back to raw env on error.
			context[cfg.EnvSectionName] = extractResult.env
		} else {
			context[cfg.EnvSectionName] = processedEnv
		}
	}

	return context, nil
}

// stackProcessResult holds the result of processing a single stack in parallel.
type stackProcessResult struct {
	index         int
	stackFileName string
	yamlConfig    string
	finalConfig   map[string]any
	stackConfig   map[string]any
	importsConfig map[string]map[string]any
	uniqueImports []string
	mergeContext  *m.MergeContext
	err           error
}

// ProcessYAMLConfigFiles takes a list of paths to stack manifests, processes and deep-merges all imports, and returns a list of stack configs.
func ProcessYAMLConfigFiles(
	atmosConfig *schema.AtmosConfiguration,
	stacksBasePath string,
	terraformComponentsBasePath string,
	helmfileComponentsBasePath string,
	packerComponentsBasePath string,
	ansibleComponentsBasePath string,
	filePaths []string,
	processStackDeps bool,
	processComponentDeps bool,
	ignoreMissingFiles bool,
) (
	[]string,
	map[string]any,
	map[string]map[string]any,
	error,
) {
	defer perf.Track(atmosConfig, "exec.ProcessYAMLConfigFiles")()

	count := len(filePaths)
	listResult := make([]string, count)
	mapResult := make(map[string]any, count)
	rawStackConfigs := make(map[string]map[string]any, count)

	// Create channel for results - no locks needed with channels.
	results := make(chan stackProcessResult, count)
	var wg sync.WaitGroup
	wg.Add(count)

	for i, filePath := range filePaths {
		go func(i int, p string) {
			defer wg.Done()

			stackBasePath := stacksBasePath
			if len(stackBasePath) < 1 {
				stackBasePath = filepath.Dir(p)
			}

			stackFileName := strings.TrimSuffix(
				strings.TrimSuffix(
					u.TrimBasePathFromPath(stackBasePath+"/", p),
					u.DefaultStackConfigFileExtension,
				),
				".yml",
			)

			// Each goroutine gets its own merge context to avoid data races.
			// For single-file operations (like describe component), use the
			// SetLastMergeContext/GetLastMergeContext mechanism instead.
			mergeContext := m.NewMergeContext()
			if atmosConfig != nil && atmosConfig.TrackProvenance {
				mergeContext.EnableProvenance()
			}

			processingResult, mergeContext, err := ProcessYAMLConfigFileWithContext(
				atmosConfig,
				stackBasePath,
				p,
				map[string]map[string]any{},
				nil,
				ignoreMissingFiles,
				false,
				atmosConfig != nil && atmosConfig.Templates.Settings.IgnoreMissingTemplateValues,
				false,
				map[string]any{},
				map[string]any{},
				map[string]any{},
				map[string]any{},
				"",
				mergeContext,
			)
			if err != nil {
				results <- stackProcessResult{index: i, err: err}
				return
			}

			if mergeContext != nil {
				if len(mergeContext.ImportChain) > 0 {
					log.Trace("After processing file, merge context has import chain", "file", stackFileName, "import_chain_length", len(mergeContext.ImportChain), "import_chain", mergeContext.ImportChain)
				} else {
					log.Trace("After processing file, merge context has empty import chain", "file", stackFileName)
				}
			}

			var imports []string
			for k := range processingResult.ImportsConfig {
				imports = append(imports, k)
			}

			uniqueImports := u.UniqueStrings(imports)
			sort.Strings(uniqueImports)

			componentStackMap := map[string]map[string][]string{}

			finalConfig, err := ProcessStackConfig(
				atmosConfig,
				stackBasePath,
				terraformComponentsBasePath,
				helmfileComponentsBasePath,
				packerComponentsBasePath,
				ansibleComponentsBasePath,
				p,
				processingResult.DeepMergedConfig,
				processStackDeps,
				processComponentDeps,
				"",
				componentStackMap,
				processingResult.ImportsConfig,
				true,
			)
			if err != nil {
				results <- stackProcessResult{index: i, err: err}
				return
			}

			finalConfig["imports"] = uniqueImports

			yamlConfig, err := u.ConvertToYAML(finalConfig)
			if err != nil {
				results <- stackProcessResult{index: i, err: err}
				return
			}

			// Send result via channel (lock-free).
			results <- stackProcessResult{
				index:         i,
				stackFileName: stackFileName,
				yamlConfig:    yamlConfig,
				finalConfig:   finalConfig,
				stackConfig:   processingResult.StackConfig,
				importsConfig: processingResult.ImportsConfig,
				uniqueImports: uniqueImports,
				mergeContext:  mergeContext,
				err:           nil,
			}
		}(i, filePath)
	}

	// Close results channel when all goroutines complete.
	go func() {
		wg.Wait()
		close(results)
	}()

	// Collect all results from channel (no lock contention).
	for result := range results {
		if result.err != nil {
			return nil, nil, nil, result.err
		}

		// Store merge context for this stack file if provenance tracking is enabled.
		if atmosConfig != nil && atmosConfig.TrackProvenance && result.mergeContext != nil && result.mergeContext.IsProvenanceEnabled() {
			SetMergeContextForStack(result.stackFileName, result.mergeContext)
			// Also set as last merge context for backward compatibility (note: may be overwritten by other results)
			SetLastMergeContext(result.mergeContext)
		}

		listResult[result.index] = result.yamlConfig
		mapResult[result.stackFileName] = result.finalConfig
		rawStackConfigs[result.stackFileName] = map[string]any{
			"stack":        result.stackConfig,
			"imports":      result.importsConfig,
			"import_files": result.uniqueImports,
		}
	}

	return listResult, mapResult, rawStackConfigs, nil
}

// ProcessYAMLConfigFile takes a path to a YAML stack manifest,
// recursively processes and deep-merges all the imports,
// and returns the final stack config.
func ProcessYAMLConfigFile(
	atmosConfig *schema.AtmosConfiguration,
	basePath string,
	filePath string,
	importsConfig map[string]map[string]any,
	context map[string]any,
	ignoreMissingFiles bool,
	skipTemplatesProcessingInImports bool,
	ignoreMissingTemplateValues bool,
	skipIfMissing bool,
	parentTerraformOverridesInline map[string]any,
	parentTerraformOverridesImports map[string]any,
	parentHelmfileOverridesInline map[string]any,
	parentHelmfileOverridesImports map[string]any,
	atmosManifestJsonSchemaFilePath string,
) (*schema.StackManifestProcessingResult, error) {
	defer perf.Track(atmosConfig, "exec.ProcessYAMLConfigFile")()

	// Create merge context for single-file operations
	var mergeContext *m.MergeContext
	if atmosConfig != nil && atmosConfig.TrackProvenance {
		mergeContext = m.NewMergeContext()
		mergeContext.EnableProvenance()
	}

	// Call the context-aware version
	result, mergeContext, err := ProcessYAMLConfigFileWithContext(
		atmosConfig,
		basePath,
		filePath,
		importsConfig,
		context,
		ignoreMissingFiles,
		skipTemplatesProcessingInImports,
		ignoreMissingTemplateValues,
		skipIfMissing,
		parentTerraformOverridesInline,
		parentTerraformOverridesImports,
		parentHelmfileOverridesInline,
		parentHelmfileOverridesImports,
		atmosManifestJsonSchemaFilePath,
		mergeContext,
	)

	// Store merge context if provenance tracking is enabled (for single-file operations like describe component)
	if atmosConfig != nil && atmosConfig.TrackProvenance && mergeContext != nil && mergeContext.IsProvenanceEnabled() {
		SetLastMergeContext(mergeContext)
	}

	return result, err
}

// ProcessYAMLConfigFileWithContext takes a path to a YAML stack manifest,
// recursively processes and deep-merges all the imports with context tracking,
// and returns the final stack config.
func ProcessYAMLConfigFileWithContext(
	atmosConfig *schema.AtmosConfiguration,
	basePath string,
	filePath string,
	importsConfig map[string]map[string]any,
	context map[string]any,
	ignoreMissingFiles bool,
	skipTemplatesProcessingInImports bool,
	ignoreMissingTemplateValues bool,
	skipIfMissing bool,
	parentTerraformOverridesInline map[string]any,
	parentTerraformOverridesImports map[string]any,
	parentHelmfileOverridesInline map[string]any,
	parentHelmfileOverridesImports map[string]any,
	atmosManifestJsonSchemaFilePath string,
	mergeContext *m.MergeContext,
) (*schema.StackManifestProcessingResult, *m.MergeContext, error) {
	defer perf.Track(atmosConfig, "exec.ProcessYAMLConfigFileWithContext")()

	return processYAMLConfigFileWithContextInternal(
		atmosConfig,
		basePath,
		filePath,
		basePath,
		schema.StackImportNestedImportsLocal,
		importsConfig,
		context,
		// Top-level call: no accumulated import-path context yet. It is built up
		// from earlier imports as the manifest's import list is processed.
		nil,
		ignoreMissingFiles,
		skipTemplatesProcessingInImports,
		ignoreMissingTemplateValues,
		skipIfMissing,
		parentTerraformOverridesInline,
		parentTerraformOverridesImports,
		parentHelmfileOverridesInline,
		parentHelmfileOverridesImports,
		atmosManifestJsonSchemaFilePath,
		mergeContext,
	)
}

// importFileResult holds the result of processing a single import file in parallel.
type importFileResult struct {
	index                        int
	importFile                   string
	yamlConfig                   map[string]any
	yamlConfigRaw                map[string]any
	terraformOverridesInline     map[string]any
	terraformOverridesImports    map[string]any
	helmfileOverridesInline      map[string]any
	helmfileOverridesImports     map[string]any
	importRelativePathWithoutExt string
	mergeContext                 *m.MergeContext
	err                          error
}

// jsonPointerToPositionKey converts a JSON Pointer (RFC 6901, e.g.
// "/components/terraform/0/vars") as returned by
// jsonschema.BasicError.InstanceLocation into the dot/bracket path format
// u.PositionMap keys use (built via u.AppendJSONPathKey/AppendJSONPathIndex),
// so a position lookup by path succeeds.
func jsonPointerToPositionKey(pointer string) string {
	if pointer == "" {
		return ""
	}
	segments := strings.Split(strings.TrimPrefix(pointer, "/"), "/")
	path := ""
	for _, seg := range segments {
		seg = strings.ReplaceAll(seg, "~1", "/")
		seg = strings.ReplaceAll(seg, "~0", "~")
		if idx, err := strconv.Atoi(seg); err == nil {
			path = u.AppendJSONPathIndex(path, idx)
			continue
		}
		path = u.AppendJSONPathKey(path, seg)
	}
	return path
}

// isSchemaBranchWrapperMessage reports whether a jsonschema.BasicError.Error
// is a structural "one of these sub-schemas should have matched" wrapper
// (from oneOf/anyOf/$ref indirection) rather than an actionable leaf
// violation: oneOf/anyOf constructs report every failed candidate branch, so
// a single mistake (e.g. a wrong type) can otherwise produce many redundant
// lines at the same location; dropping wrapper messages keeps only the
// specific ones (e.g. "expected object, but got string").
func isSchemaBranchWrapperMessage(msg string) bool {
	return strings.HasPrefix(msg, "doesn't validate with") ||
		msg == "oneOf failed" ||
		msg == "anyOf failed"
}

// formatManifestSchemaValidationErrors renders a jsonschema.ValidationError as
// a Markdown list of GCC-style diagnostic lines ("file:line:col: error:
// path: message" per item), matching the convention `atmos validate
// editorconfig --format=gcc` already uses, instead of a raw BasicOutput JSON
// dump. BasicOutput's first entry is always a generic "doesn't validate with
// <schema>" wrapper around the whole document (empty KeywordLocation);
// wrapper entries throughout (including nested oneOf/anyOf branch failures)
// are dropped in favor of the specific leaf violations.
//
// Markdown list syntax (not plain lines) is deliberate: the CLI's error box
// renders this as CommonMark, which treats a lone "\n" between plain
// paragraph text as a soft break (collapsed to a space) rather than a line
// break -- only list items reliably keep one diagnostic per rendered line.
// The leading "\n" pushes every item, including the first, onto its own
// line rather than running into the box's own "Error:" label inline.
func formatManifestSchemaValidationErrors(relativeFilePath string, e *jsonschema.ValidationError, positions u.PositionMap) string {
	items := collectManifestSchemaErrorItems(e, positions)
	if len(items) == 0 {
		return fmt.Sprintf("\n- %s: error: %s", relativeFilePath, e.Error())
	}
	rendered := renderManifestSchemaErrorItems(relativeFilePath, items)
	return "\n" + strings.Join(rendered, "\n")
}

// manifestSchemaTypeAlternatives coalesces the distinct expected types that
// failed a shared oneOf/anyOf branch for the same instance location and
// actual value, so they render as one "expected X or Y, but got Z" finding
// instead of one line per failed branch.
type manifestSchemaTypeAlternatives struct {
	path        string
	position    u.Position
	got         string
	expected    []string
	expectedSet map[string]struct{}
}

// manifestSchemaErrorItem is one candidate finding collected from a
// jsonschema.ValidationError's BasicOutput -- either a concrete leaf message,
// or a coalesced type-alternatives entry.
type manifestSchemaErrorItem struct {
	path     string
	position u.Position
	message  string
	types    *manifestSchemaTypeAlternatives
}

// collectManifestSchemaErrorItems walks a jsonschema.ValidationError's
// BasicOutput and builds one item per actionable leaf finding, coalescing
// oneOf/anyOf type-mismatch branches for the same instance location and
// actual value into a single manifestSchemaTypeAlternatives entry.
func collectManifestSchemaErrorItems(e *jsonschema.ValidationError, positions u.PositionMap) []manifestSchemaErrorItem {
	items := make([]manifestSchemaErrorItem, 0)
	alternatives := make(map[string]*manifestSchemaTypeAlternatives)
	for _, basicErr := range e.BasicOutput().Errors {
		if basicErr.KeywordLocation == "" || isSchemaBranchWrapperMessage(basicErr.Error) {
			continue
		}
		path := jsonPointerToPositionKey(basicErr.InstanceLocation)
		if path == "" {
			path = "(root)"
		}
		pos := u.GetYAMLPosition(positions, jsonPointerToPositionKey(basicErr.InstanceLocation))
		if expected, got, ok := schemaTypeAlternative(basicErr.Error); ok {
			key := path + "\x00" + got
			alternative := alternatives[key]
			if alternative == nil {
				alternative = &manifestSchemaTypeAlternatives{
					path: path, position: pos, got: got,
					expectedSet: make(map[string]struct{}),
				}
				alternatives[key] = alternative
				items = append(items, manifestSchemaErrorItem{types: alternative})
			}
			if _, seen := alternative.expectedSet[expected]; !seen {
				alternative.expectedSet[expected] = struct{}{}
				alternative.expected = append(alternative.expected, expected)
			}
			continue
		}
		items = append(items, manifestSchemaErrorItem{path: path, position: pos, message: manifestSchemaErrorMessage(basicErr.Error)})
	}
	return items
}

// manifestSchemaItemHasDescendant reports whether some other item's path is a
// nested child of path (a JSON object/array descendant), which makes path's
// own type-mismatch finding a redundant cascade rather than the actionable
// error.
func manifestSchemaItemHasDescendant(items []manifestSchemaErrorItem, current int, path string) bool {
	for index, candidate := range items {
		if index == current {
			continue
		}
		candidatePath := candidate.path
		if candidate.types != nil {
			candidatePath = candidate.types.path
		}
		if strings.HasPrefix(candidatePath, path+".") || strings.HasPrefix(candidatePath, path+"[") {
			return true
		}
	}
	return false
}

// manifestSchemaItemHasSpecificFinding reports whether some other item names
// exactly path with a specific (non-type-alternative) finding, which makes
// path's own type-mismatch finding a redundant cascade.
func manifestSchemaItemHasSpecificFinding(items []manifestSchemaErrorItem, current int, path string) bool {
	for index, candidate := range items {
		if index != current && candidate.types == nil && candidate.path == path {
			return true
		}
	}
	return false
}

// renderManifestSchemaErrorItems renders each collected item as a GCC-style
// diagnostic line, dropping type-mismatch items that are cascades of a more
// specific sibling finding.
func renderManifestSchemaErrorItems(relativeFilePath string, items []manifestSchemaErrorItem) []string {
	rendered := make([]string, 0, len(items))
	// Distinct failing branches of an outer oneOf/anyOf (e.g. the manifest's
	// top-level "workflows vs. everything else" split) can each independently
	// surface the very same leaf violation; dedupe by the exact rendered line
	// so a single mistake still reads as a single finding.
	seen := make(map[string]struct{}, len(items))
	for index, item := range items {
		var line string
		if item.types != nil {
			// A type mismatch from a sibling oneOf branch is only a cascade when
			// another branch explains the same value (for example, a string that
			// misses the !include pattern) or identifies a more-specific child
			// finding. Keep the type diagnostic when every branch failed only on
			// type, since then it is the actionable error.
			if manifestSchemaItemHasSpecificFinding(items, index, item.types.path) || manifestSchemaItemHasDescendant(items, index, item.types.path) {
				continue
			}
			message := fmt.Sprintf("expected %s, but got %s", strings.Join(item.types.expected, " or "), item.types.got)
			line = fmt.Sprintf("- %s:%d:%d: error: %s: %s", relativeFilePath, item.types.position.Line, item.types.position.Column, item.types.path, message)
		} else {
			line = fmt.Sprintf("- %s:%d:%d: error: %s: %s", relativeFilePath, item.position.Line, item.position.Column, item.path, item.message)
		}
		if _, ok := seen[line]; ok {
			continue
		}
		seen[line] = struct{}{}
		rendered = append(rendered, line)
	}
	return rendered
}

// manifestSchemaErrorMessage replaces implementation-detail regex failures
// with guidance that matches the stack manifest's YAML syntax.
func manifestSchemaErrorMessage(message string) string {
	if message == "does not match pattern '^!include'" {
		return "file references must use the !include YAML tag"
	}
	return message
}

// schemaTypeAlternative identifies equivalent oneOf type branches. A value
// such as an array can fail both `type: object` and `type: string`; rendering
// each branch separately adds noise without adding an actionable finding.
func schemaTypeAlternative(message string) (expected string, got string, ok bool) {
	const (
		prefix = "expected "
		marker = ", but got "
	)
	if !strings.HasPrefix(message, prefix) {
		return "", "", false
	}
	parts := strings.SplitN(strings.TrimPrefix(message, prefix), marker, 2)
	if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
		return "", "", false
	}
	return parts[0], parts[1], true
}

// processYAMLConfigFileWithContextInternal is the internal recursive implementation.
//
//nolint:gocognit,revive,cyclop,funlen,nestif
func processYAMLConfigFileWithContextInternal(
	atmosConfig *schema.AtmosConfiguration,
	basePath string,
	filePath string,
	localBasePath string,
	inheritedNestedImports string,
	importsConfig map[string]map[string]any,
	context map[string]any,
	importPathContext map[string]any,
	ignoreMissingFiles bool,
	skipTemplatesProcessingInImports bool,
	ignoreMissingTemplateValues bool,
	skipIfMissing bool,
	parentTerraformOverridesInline map[string]any,
	parentTerraformOverridesImports map[string]any,
	parentHelmfileOverridesInline map[string]any,
	parentHelmfileOverridesImports map[string]any,
	atmosManifestJsonSchemaFilePath string,
	mergeContext *m.MergeContext,
) (*schema.StackManifestProcessingResult, *m.MergeContext, error) {
	var stackConfigs []map[string]any
	inheritedNestedImports = normalizeNestedImports(inheritedNestedImports)
	if localBasePath == "" {
		localBasePath = basePath
	}
	relativeFilePath := u.TrimBasePathFromPath(basePath+"/", filePath)

	log.Trace("Processing YAML config file", "file", relativeFilePath)

	// Initialize or update merge context with current file.
	if mergeContext == nil {
		mergeContext = m.NewMergeContext()
		// Enable provenance if configured.
		if atmosConfig != nil && atmosConfig.TrackProvenance {
			mergeContext.EnableProvenance()
		}
	}
	mergeContext = mergeContext.WithFile(relativeFilePath)
	log.Trace("Merge context updated with file", "file", relativeFilePath, "import_chain_length", len(mergeContext.ImportChain), "track_provenance", atmosConfig != nil && atmosConfig.TrackProvenance)

	globalTerraformSection := map[string]any{}
	globalHelmfileSection := map[string]any{}
	globalOverrides := map[string]any{}
	terraformOverrides := map[string]any{}
	helmfileOverrides := map[string]any{}
	finalTerraformOverrides := map[string]any{}
	finalHelmfileOverrides := map[string]any{}

	// Use uncached file reads when provenance tracking is enabled to ensure YAML position tracking works correctly.
	var stackYamlConfig string
	var err error
	if atmosConfig != nil && atmosConfig.TrackProvenance {
		stackYamlConfig, err = GetFileContentWithoutCache(filePath)
	} else {
		stackYamlConfig, err = GetFileContent(filePath)
	}
	// If the file does not exist (`err != nil`), and `ignoreMissingFiles = true`, don't return the error.
	//
	// `ignoreMissingFiles = true` is used when executing `atmos describe affected` command.
	// If we add a new stack manifest with some component configurations to the current branch, then the new file will not be present in
	// the remote branch (with which the current branch is compared), and Atmos would throw an error.
	//
	// `skipIfMissing` is used in Atmos imports (https://atmos.tools/core-concepts/stacks/imports).
	// Set it to `true` to ignore the imported manifest if it does not exist, and don't throw an error.
	// This is useful when generating Atmos manifests using other tools, but the imported files are not present yet at the generation time.
	if err != nil {
		if ignoreMissingFiles || skipIfMissing {
			return emptyStackManifestProcessingResult(), nil, nil
		} else {
			return nil, nil, err
		}
	}
	if stackYamlConfig == "" {
		return emptyStackManifestProcessingResult(), nil, nil
	}

	// Track whether context was originally provided from outside (e.g., via import context).
	// This is important because we should only process templates during import when:
	// 1. The file has a .tmpl extension, OR
	// 2. Context was explicitly passed from outside (not just extracted from the file itself).
	// Without this check, files with locals/settings/vars/env sections would have their templates
	// processed prematurely, before component-specific context (like atmos_component) is available.
	originalContextProvided := len(context) > 0

	// Extract and resolve file-scoped locals before template processing.
	// Locals can reference other locals using {{ .locals.X }} syntax.
	// The resolved locals are added to the template context so they're available during template processing.
	// This enables patterns like:
	//   locals:
	//     stage: prod
	//     name_prefix: "{{ .locals.stage }}-app"
	//   components:
	//     terraform:
	//       myapp:
	//         vars:
	//           name: "{{ .locals.name_prefix }}"
	if !skipTemplatesProcessingInImports {
		var localsErr error
		context, localsErr = extractAndAddLocalsToContext(atmosConfig, stackYamlConfig, filePath, relativeFilePath, context)
		if localsErr != nil {
			if mergeContext != nil {
				return nil, nil, mergeContext.FormatError(localsErr, fmt.Sprintf("stack manifest '%s'", relativeFilePath))
			}
			return nil, nil, fmt.Errorf("stack manifest '%s': %w", relativeFilePath, localsErr)
		}
	}

	stackManifestTemplatesProcessed := stackYamlConfig
	stackManifestTemplatesErrorMessage := ""

	// Process `Go` templates in the imported stack manifest if it has a template extension.
	// Files with .yaml.tmpl or .yml.tmpl extensions are always processed as templates.
	// Other .tmpl files are processed only when context is provided (backward compatibility).
	// https://atmos.tools/core-concepts/stacks/imports#go-templates-in-imports
	if !skipTemplatesProcessingInImports && (u.IsTemplateFile(filePath) || len(context) > 0) { //nolint:nestif // Template processing error handling requires conditional formatting based on context
		stackManifestTemplateInput := stackYamlConfig
		if len(context) > 0 {
			// Preserve explicit YAML function tags while evaluating structured template references.
			// A plain yaml.Unmarshal drops a scalar's custom tag and leaves only its arguments,
			// which would prevent the later YAML-function resolver from recognizing it.
			if rawStackConfig, err := u.UnmarshalYAMLFromFile[map[string]any](atmosConfig, stackYamlConfig, filePath); err == nil {
				if processedStructured, ok := processStructuredTemplateRefs(rawStackConfig, context).(map[string]any); ok {
					if renderedStructured, err := u.ConvertToYAML(processedStructured); err == nil {
						stackManifestTemplateInput = renderedStructured
					}
				}
			}
		}

		var tmplErr error
		stackManifestTemplatesProcessed, tmplErr = ProcessTmpl(atmosConfig, relativeFilePath, stackManifestTemplateInput, context, ignoreMissingTemplateValues)
		if tmplErr != nil {
			// If template processing failed and the only context is from file extraction
			// (locals/settings/vars/env, not from an explicit import context), this is likely
			// due to templates referencing component context (like {{ .atmos_component }}) that
			// isn't available during import. Fall back to the raw content — these templates will
			// be processed later in ProcessStacks when the full component context is available.
			if !originalContextProvided {
				log.Debug("Template processing deferred for file with file-extracted context only",
					"file", relativeFilePath, "error", tmplErr)
				stackManifestTemplatesProcessed = stackManifestTemplateInput
			} else {
				if atmosConfig.Logs.Level == u.LogLevelTrace || atmosConfig.Logs.Level == u.LogLevelDebug {
					stackManifestTemplatesErrorMessage = fmt.Sprintf("\n\n%s", stackYamlConfig)
				}
				wrappedErr := fmt.Errorf("%w: %w", errUtils.ErrInvalidStackManifest, tmplErr)
				if mergeContext != nil {
					return nil, nil, mergeContext.FormatError(wrappedErr, fmt.Sprintf("stack manifest '%s'%s", relativeFilePath, stackManifestTemplatesErrorMessage))
				}
				return nil, nil, fmt.Errorf("%w: stack manifest '%s'\n%w%s", errUtils.ErrInvalidStackManifest, relativeFilePath, tmplErr, stackManifestTemplatesErrorMessage)
			}
		}
	}

	stackConfigMap, positions, err := u.UnmarshalYAMLFromFileWithPositions[schema.AtmosSectionMapType](atmosConfig, stackManifestTemplatesProcessed, filePath)
	if err != nil {
		if atmosConfig.Logs.Level == u.LogLevelTrace || atmosConfig.Logs.Level == u.LogLevelDebug {
			stackManifestTemplatesErrorMessage = fmt.Sprintf("\n\n%s", stackYamlConfig)
		}
		// Check if we have merge context to provide enhanced error formatting
		if mergeContext != nil {
			// Wrap the error with the sentinel first to preserve it
			wrappedErr := fmt.Errorf("%w: %v", errUtils.ErrInvalidStackManifest, err)
			// Then format it with context information
			e := mergeContext.FormatError(wrappedErr, fmt.Sprintf("stack manifest '%s'%s", relativeFilePath, stackManifestTemplatesErrorMessage))
			return nil, nil, e
		} else {
			e := fmt.Errorf("%w: stack manifest '%s'\n%v%s", errUtils.ErrInvalidStackManifest, relativeFilePath, err, stackManifestTemplatesErrorMessage)
			return nil, nil, e
		}
	}

	// Store resolved file-level sections in stackConfigMap so they're available during describe_stacks.
	// The context contains resolved values from extractAndAddLocalsToContext, but the YAML content
	// (and thus stackConfigMap) may still have unresolved template expressions.
	// By updating stackConfigMap with resolved values, we ensure templates like {{ .locals.X }}
	// and {{ .vars.X }} can be resolved correctly.
	if resolvedLocals, ok := context[cfg.LocalsSectionName].(map[string]any); ok && len(resolvedLocals) > 0 {
		stackConfigMap[cfg.LocalsSectionName] = resolvedLocals
	}
	if resolvedVars, ok := context[cfg.VarsSectionName].(map[string]any); ok && len(resolvedVars) > 0 {
		stackConfigMap[cfg.VarsSectionName] = resolvedVars
	}
	if resolvedSettings, ok := context[cfg.SettingsSectionName].(map[string]any); ok && len(resolvedSettings) > 0 {
		stackConfigMap[cfg.SettingsSectionName] = resolvedSettings
	}
	if resolvedEnv, ok := context[cfg.EnvSectionName].(map[string]any); ok && len(resolvedEnv) > 0 {
		stackConfigMap[cfg.EnvSectionName] = resolvedEnv
	}

	// Enable provenance tracking in merge context if tracking is enabled
	if atmosConfig.TrackProvenance && mergeContext != nil && len(positions) > 0 {
		mergeContext.EnableProvenance()
		mergeContext.Positions = positions // Store positions for merge operations
	}

	// If the path to the Atmos manifest JSON Schema is provided, validate the stack manifest against it
	if atmosManifestJsonSchemaFilePath != "" {
		// Convert the data to JSON and back to Go map to prevent the error:
		// jsonschema: invalid jsonType: map[interface {}]interface {}
		dataJson, err := u.ConvertToJSONFast(stackConfigMap)
		if err != nil {
			return nil, nil, err
		}

		dataFromJson, err := u.ConvertFromJSON(dataJson)
		if err != nil {
			return nil, nil, err
		}

		atmosManifestJsonSchemaValidationErrorFormat := "Atmos manifest JSON Schema validation error in the file '%s':\n%v"

		// Check cache first to avoid re-compiling the same schema for every stack file.
		compiledSchema, found := getCachedCompiledSchema(atmosManifestJsonSchemaFilePath)

		if !found {
			// Schema not in cache - compile it and cache the result.
			compiler := jsonschema.NewCompiler()

			atmosManifestJsonSchemaFileReader, err := os.Open(atmosManifestJsonSchemaFilePath)
			if err != nil {
				return nil, nil, errors.Errorf(atmosManifestJsonSchemaValidationErrorFormat, relativeFilePath, err)
			}
			defer func() {
				_ = atmosManifestJsonSchemaFileReader.Close()
			}()

			if err := compiler.AddResource(atmosManifestJsonSchemaFilePath, atmosManifestJsonSchemaFileReader); err != nil {
				return nil, nil, errors.Errorf(atmosManifestJsonSchemaValidationErrorFormat, relativeFilePath, err)
			}

			compiler.Draft = jsonschema.Draft2020

			compiledSchema, err = compiler.Compile(atmosManifestJsonSchemaFilePath)
			if err != nil {
				return nil, nil, errors.Errorf(atmosManifestJsonSchemaValidationErrorFormat, relativeFilePath, err)
			}

			// Store compiled schema in cache for reuse.
			cacheCompiledSchema(atmosManifestJsonSchemaFilePath, compiledSchema)
		}

		// Validate using the compiled schema (whether cached or newly compiled).
		if err = compiledSchema.Validate(dataFromJson); err != nil {
			switch e := err.(type) {
			case *jsonschema.ValidationError:
				// Position lookup is best-effort: re-parse the manifest content
				// into a yaml.Node here (independent of the `positions` above,
				// which is only populated when atmosConfig.TrackProvenance is
				// on) so line/column are always available for a validation
				// failure, regardless of that unrelated global setting.
				var manifestNode yaml.Node
				var errorPositions u.PositionMap
				if yaml.Unmarshal([]byte(stackManifestTemplatesProcessed), &manifestNode) == nil {
					errorPositions = u.ExtractYAMLPositions(&manifestNode, true)
				}
				// GCC-style lines already carry the file path per violation, so
				// no outer "validation error in the file '%s'" wrapper sentence
				// is needed here (unlike the setup-error cases below, which are
				// each a single, file-level problem).
				return nil, nil, errors.New(formatManifestSchemaValidationErrors(relativeFilePath, e, errorPositions))
			default:
				return nil, nil, errors.Errorf(atmosManifestJsonSchemaValidationErrorFormat, relativeFilePath, err)
			}
		}
	}

	// Check if the `overrides` sections exist and if we need to process overrides for the components in this stack manifest and its imports

	// Global overrides in this stack manifest
	if i, ok := stackConfigMap[cfg.OverridesSectionName]; ok {
		if globalOverrides, ok = i.(map[string]any); !ok {
			return nil, nil, fmt.Errorf("%w in the stack manifest '%s'", errUtils.ErrInvalidOverridesSection, relativeFilePath)
		}
	}

	// Terraform overrides in this stack manifest
	if o, ok := stackConfigMap[cfg.TerraformSectionName]; ok {
		if globalTerraformSection, ok = o.(map[string]any); !ok {
			return nil, nil, fmt.Errorf("%w in the stack manifest '%s'", errUtils.ErrInvalidTerraformSection, relativeFilePath)
		}

		if i, ok := globalTerraformSection[cfg.OverridesSectionName]; ok {
			if terraformOverrides, ok = i.(map[string]any); !ok {
				return nil, nil, fmt.Errorf("%w in the stack manifest '%s'", errUtils.ErrInvalidTerraformOverridesSection, relativeFilePath)
			}
		}
	}

	// Helmfile overrides in this stack manifest
	if o, ok := stackConfigMap[cfg.HelmfileSectionName]; ok {
		if globalHelmfileSection, ok = o.(map[string]any); !ok {
			return nil, nil, fmt.Errorf("%w in the stack manifest '%s'", errUtils.ErrInvalidHelmfileSection, relativeFilePath)
		}

		if i, ok := globalHelmfileSection[cfg.OverridesSectionName]; ok {
			if helmfileOverrides, ok = i.(map[string]any); !ok {
				return nil, nil, fmt.Errorf("%w in the stack manifest '%s'", errUtils.ErrInvalidHelmfileOverridesSection, relativeFilePath)
			}
		}
	}

	parentTerraformOverridesInline, err = m.MergeWithContext(
		atmosConfig,
		[]map[string]any{globalOverrides, terraformOverrides, parentTerraformOverridesInline},
		mergeContext,
	)
	if err != nil {
		return nil, nil, err
	}

	parentHelmfileOverridesInline, err = m.MergeWithContext(
		atmosConfig,
		[]map[string]any{globalOverrides, helmfileOverrides, parentHelmfileOverridesInline},
		mergeContext,
	)
	if err != nil {
		return nil, nil, err
	}

	// Find and process all imports
	importStructs, err := ProcessImportSection(stackConfigMap, relativeFilePath)
	if err != nil {
		return nil, nil, err
	}

	// Record provenance for each import if provenance tracking is enabled.
	// Use the import path as the key so we can look it up later when building the final array.
	if atmosConfig.TrackProvenance && mergeContext != nil && mergeContext.IsProvenanceEnabled() && len(importStructs) > 0 {
		for i, importStruct := range importStructs {
			// Look up position for this import array element.
			arrayPath := fmt.Sprintf("import[%d]", i)
			if pos, exists := positions[arrayPath]; exists {
				// Get depth from merge context using the dedicated method.
				depth := mergeContext.GetImportDepth()

				entry := m.ProvenanceEntry{
					File:   relativeFilePath,
					Line:   pos.Line,
					Column: pos.Column,
					Type:   mergeContext.GetProvenanceType(),
					Depth:  depth,
				}

				// Store provenance using a special key format that includes the import path.
				// This allows us to look it up later when building the final flattened array.
				// Format: "__import__:<import-path>" (e.g., "__import__:mixins/region/us-east-2")
				importKey := fmt.Sprintf("__import__:%s", importStruct.Path)

				// Only record if not already recorded (first occurrence wins).
				if !mergeContext.HasProvenance(importKey) {
					mergeContext.RecordProvenance(importKey, entry)
				}
			}
		}
	}

	// accumulatedImportContext carries the `settings`/`vars`/`env` sections defined by
	// EARLIER imports in this manifest so that LATER imports can reference them in their
	// import path (e.g. a Git `?ref={{ .settings.context.deployment_repo_version }}`).
	// It is seeded from the context propagated by the parent import and grows as each
	// import in this manifest is processed (see the accumulation after the merge block).
	// This context is used ONLY for templating import path strings — it does not affect
	// file-content template processing/deferral, nor the authoritative deep-merge order.
	accumulatedImportContext := importPathContext
	if accumulatedImportContext == nil {
		accumulatedImportContext = map[string]any{}
	}

	//nolint:staticcheck // atmosConfig nil check is present.
	log.Trace("Processing import structs", "count", len(importStructs), "file", relativeFilePath, "track_provenance", atmosConfig != nil && atmosConfig.TrackProvenance)
	for _, importStruct := range importStructs {
		imp := importStruct.Path
		nestedImports := importStruct.NestedImports
		if nestedImports == "" {
			nestedImports = inheritedNestedImports
		}
		nestedImports = normalizeNestedImports(nestedImports)

		if imp == "" {
			return nil, nil, fmt.Errorf("%w in the manifest '%s'", errUtils.ErrInvalidImport, relativeFilePath)
		}

		// Render Go templates in the import path so an import can reference values
		// (`settings`/`vars`/`env`) defined by earlier imports in this manifest, plus
		// this import's own `context`. Only the path string is rendered here; the
		// imported file's content templating (and its deferral logic) is left untouched.
		renderedImp, impErr := renderImportPath(atmosConfig, relativeFilePath, imp, accumulatedImportContext, importStruct)
		if impErr != nil {
			return nil, nil, impErr
		}
		imp = renderedImp

		// Snapshot the accumulated context for the child import. The outer loop is
		// sequential, so this captures only the sections from earlier siblings.
		childImportContext := accumulatedImportContext

		var importMatches []stackimports.RemoteImportMatch

		// Capture remote status and original import key before resolution.
		// For remote imports, the original URI must be preserved as the import key
		// so that downstream lookups and imports output use the user-specified URI
		// rather than the local cache path.
		isRemote := stackimports.IsRemote(imp)

		// Check if the import is a remote URL.
		if isRemote {
			// Resolve the per-import cache TTL, falling back to the global default.
			importTTL := importStruct.TTL
			if importTTL == "" && atmosConfig != nil {
				importTTL = atmosConfig.Imports.TTL
			}
			// Download the remote import.
			log.Debug("Downloading remote stack import", "uri", imp, "file", relativeFilePath, "nested_imports", nestedImports, "ttl", importTTL)
			remoteMatches, err := stackimports.ResolveRemoteImportNested(atmosConfig, imp, nestedImports, importTTL)
			if err != nil {
				if importStruct.SkipIfMissing {
					log.Debug("Skipping missing remote import", "uri", imp)
					continue
				}
				return nil, nil, fmt.Errorf("%w '%s' in file '%s': %w",
					errUtils.ErrDownloadRemoteImport, imp, relativeFilePath, err)
			}
			importMatches = remoteMatches
		} else {
			// Local import - handle extension resolution and glob matching.
			impWithExt := imp
			ext := filepath.Ext(imp)
			if ext == "" {
				extensions := []string{
					u.YamlFileExtension,
					u.YmlFileExtension,
					u.YamlTemplateExtension,
					u.YmlTemplateExtension,
				}

				found := false
				for _, extension := range extensions {
					testPath := filepath.Join(basePath, imp+extension)
					if _, err := os.Stat(testPath); err == nil {
						impWithExt = imp + extension
						found = true
						break
					}
				}

				if !found {
					// Default to .yaml if no file is found.
					impWithExt = imp + u.DefaultStackConfigFileExtension
				}
			} else if ext == u.YamlFileExtension || ext == u.YmlFileExtension {
				// Check if there's a template version of this file.
				templatePath := impWithExt + u.TemplateExtension
				if _, err := os.Stat(filepath.Join(basePath, templatePath)); err == nil {
					impWithExt = templatePath
				}
			}

			impWithExtPath := filepath.Join(basePath, impWithExt)

			if impWithExtPath == filePath {
				return nil, nil, fmt.Errorf("%w: manifest '%s' imports itself via '%s'",
					errUtils.ErrStackImportSelf, relativeFilePath, imp)
			}

			// Find all import matches in the glob.
			var err error
			localMatches, err := u.GetGlobMatches(impWithExtPath)
			if err != nil || len(localMatches) == 0 {
				// Retry (b/c we are using `doublestar` library and it sometimes has issues reading many files in a Docker container).
				// TODO: review `doublestar` library.

				localMatches, err = u.GetGlobMatches(impWithExtPath)
				if err != nil || len(localMatches) == 0 {
					// The import was not found -> check if the import is a Go template; if not, return the error.
					isGolangTemplate, err2 := IsGolangTemplate(atmosConfig, imp)
					if err2 != nil {
						return nil, nil, err2
					}

					// If the import is not a Go template and SkipIfMissing is false, return the error.
					// The wrapped `err` from GetGlobMatches already carries ErrFailedToFindImport, so
					// callers using errors.Is (see describe_affected_utils.go) keep matching. When
					// err is nil but localMatches is empty (defensive guard for unexpected empty/nil
					// results from u.GetGlobMatches), we wrap ErrFailedToFindImport explicitly.
					if !isGolangTemplate && !importStruct.SkipIfMissing {
						if err != nil {
							return nil, nil, fmt.Errorf("%w: import '%s' in file '%s': %w",
								errUtils.ErrStackImportNotFound, imp, relativeFilePath, err)
						}
						if len(localMatches) == 0 {
							return nil, nil, fmt.Errorf(
								"%w: import '%s' in file '%s': %w",
								errUtils.ErrStackImportNotFound,
								imp,
								relativeFilePath,
								errUtils.ErrFailedToFindImport,
							)
						}
					}
				}
			}
			importMatches = make([]stackimports.RemoteImportMatch, len(localMatches))
			for i, match := range localMatches {
				importMatches[i] = stackimports.RemoteImportMatch{Path: match}
			}
		}

		// Process `context` in hierarchical imports.
		// Deep-merge the parent `context` with the current `context` and propagate the result to the entire chain of imports.
		// The parent `context` takes precedence over the current (imported) `context` and will override items with the same keys.
		// TODO: instead of calling the conversion functions, we need to switch to generics and update everything to support it
		listOfMaps := []map[string]any{importStruct.Context, context}
		mergedContext, err := m.MergeWithContext(atmosConfig, listOfMaps, mergeContext)
		if err != nil {
			return nil, nil, err
		}

		// Initialize provenance storage before parallel processing to avoid data races.
		// All goroutines will share the same ProvenanceStorage (which is thread-safe).
		// This prevents multiple goroutines from racing to initialize the Provenance pointer.
		if atmosConfig != nil && atmosConfig.TrackProvenance && mergeContext != nil {
			mergeContext.EnableProvenance()
		}

		// Process the imports in the current manifest in parallel.
		// While the file I/O, parsing, and recursive import processing can be done in parallel,
		// the merge operations must be sequential to preserve Atmos inheritance order.
		results := make([]importFileResult, len(importMatches))
		var wg sync.WaitGroup

		for i, importMatch := range importMatches {
			wg.Add(1)
			go func(index int, match stackimports.RemoteImportMatch) {
				defer wg.Done()
				file := match.Path
				childBasePath := basePath
				if nestedImports == schema.StackImportNestedImportsLocal {
					childBasePath = localBasePath
				}
				if nestedImports == schema.StackImportNestedImportsRemote && match.BasePath != "" {
					childBasePath = match.BasePath
				}

				// Process the import file (expensive I/O + parsing + recursive imports).
				importResult, importMergeContext, processErr := processYAMLConfigFileWithContextInternal(
					atmosConfig,
					childBasePath,
					file,
					localBasePath,
					nestedImports,
					importsConfig,
					mergedContext,
					childImportContext,
					ignoreMissingFiles,
					importStruct.SkipTemplatesProcessing,
					importStruct.IgnoreMissingTemplateValues || (atmosConfig != nil && atmosConfig.Templates.Settings.IgnoreMissingTemplateValues),
					importStruct.SkipIfMissing,
					parentTerraformOverridesInline,
					parentTerraformOverridesImports,
					parentHelmfileOverridesInline,
					parentHelmfileOverridesImports,
					// Forward the schema path (empty unless the caller, e.g. `atmos validate
					// stacks`, explicitly requested schema validation) so imported files are
					// schema-checked too, not just the top-level entry file. Without this, a
					// schema violation living entirely inside an imported mixin was invisible:
					// `ValidateStacks`' own best-effort first pass discards its errors, and its
					// second pass skips imported files, trusting recursive import processing
					// (here) to catch them — which it couldn't while this was hardcoded to "".
					atmosManifestJsonSchemaFilePath,
					mergeContext,
				)
				if processErr != nil {
					results[index] = importFileResult{index: index, err: processErr}
					return
				}

				// Calculate import relative path.
				importRelativePathWithExt := strings.Replace(filepath.ToSlash(file), filepath.ToSlash(basePath)+"/", "", 1)
				ext2 := filepath.Ext(importRelativePathWithExt)
				if ext2 == "" {
					ext2 = u.DefaultStackConfigFileExtension
				}
				importRelativePathWithoutExt := strings.TrimSuffix(importRelativePathWithExt, ext2)

				// For remote imports, use the original URI as the import key
				// instead of the cache-derived path.
				if match.Key != "" {
					importRelativePathWithoutExt = match.Key
				}

				// Store result with all necessary data for sequential merging.
				results[index] = importFileResult{
					index:                        index,
					importFile:                   file,
					yamlConfig:                   importResult.DeepMergedConfig,
					yamlConfigRaw:                importResult.StackConfig,
					terraformOverridesInline:     importResult.TerraformOverridesInline,
					terraformOverridesImports:    importResult.TerraformOverridesImports,
					helmfileOverridesInline:      importResult.HelmfileOverridesInline,
					helmfileOverridesImports:     importResult.HelmfileOverridesImports,
					importRelativePathWithoutExt: importRelativePathWithoutExt,
					mergeContext:                 importMergeContext,
					err:                          nil,
				}
			}(i, importMatch)
		}

		// Wait for all parallel processing to complete.
		wg.Wait()

		// Sequentially merge results in the original import order to preserve Atmos inheritance.
		log.Trace("Processing import results", "count", len(results), "track_provenance", atmosConfig != nil && atmosConfig.TrackProvenance)
		for _, result := range results {
			if result.err != nil {
				return nil, nil, result.err
			}

			// Store merge context for imported files if provenance tracking is enabled.
			processImportProvenanceTracking(atmosConfig, &result, mergeContext)

			// From the imported manifest, get the `overrides` sections and merge them with the parent `overrides` section.
			// The inline `overrides` section takes precedence over the imported `overrides` section inside the imported manifest.
			parentTerraformOverridesImports, err = m.MergeWithContext(
				atmosConfig,
				[]map[string]any{parentTerraformOverridesImports, result.terraformOverridesImports, result.terraformOverridesInline},
				mergeContext,
			)
			if err != nil {
				return nil, nil, err
			}

			// From the imported manifest, get the `overrides` sections and merge them with the parent `overrides` section.
			// The inline `overrides` section takes precedence over the imported `overrides` section inside the imported manifest.
			parentHelmfileOverridesImports, err = m.MergeWithContext(
				atmosConfig,
				[]map[string]any{parentHelmfileOverridesImports, result.helmfileOverridesImports, result.helmfileOverridesInline},
				mergeContext,
			)
			if err != nil {
				return nil, nil, err
			}

			// Append to stackConfigs in order.
			stackConfigs = append(stackConfigs, result.yamlConfig)

			// Record metadata for this import.
			// We record every time we encounter an import to track all files that import it,
			// but we use the path as a unique key so only the first entry is kept per import path.
			if atmosConfig.TrackProvenance && mergeContext != nil && mergeContext.IsProvenanceEnabled() {
				// Get depth from merge context using the dedicated method.
				depth := mergeContext.GetImportDepth()

				// Store metadata using special key format: "__import_meta__:<import-path>".
				// Note: We don't have line number info here since this is during recursive processing,
				// not YAML parsing. We'll use line 1 as a placeholder.
				metaKey := fmt.Sprintf("__import_meta__:%s", result.importRelativePathWithoutExt)

				// Only record if not already recorded (first occurrence wins for the metadata)
				if !mergeContext.HasProvenance(metaKey) {
					mergeContext.RecordProvenance(metaKey, m.ProvenanceEntry{
						File:   mergeContext.CurrentFile, // The file that's importing this file
						Line:   1,                        // Placeholder - we don't have exact line info here
						Column: 1,
						Type:   mergeContext.GetProvenanceType(),
						Depth:  depth,
					})
				}
			}

			// Protect concurrent writes to importsConfig map.
			// When processing imports in parallel at nested levels, multiple goroutines
			// may reach this point simultaneously for different imports.
			importsConfigLock.Lock()
			importsConfig[result.importRelativePathWithoutExt] = result.yamlConfigRaw
			importsConfigLock.Unlock()

			// Fold this import's resolved `settings`/`vars`/`env` into the running
			// import-path context so that LATER imports in this manifest can reference
			// them in their import paths. Template-only: does not change merge order.
			sections := extractImportPathSections(result.yamlConfig)
			if len(sections) > 0 {
				accumulatedImportContext, err = m.MergeWithContext(
					atmosConfig,
					[]map[string]any{accumulatedImportContext, sections},
					mergeContext,
				)
				if err != nil {
					return nil, nil, err
				}
			}
		}
	}

	// Terraform `overrides`
	finalTerraformOverrides, err = m.MergeWithContext(
		atmosConfig,
		[]map[string]any{parentTerraformOverridesImports, parentTerraformOverridesInline},
		mergeContext,
	)
	if err != nil {
		return nil, nil, err
	}

	// Helmfile `overrides`
	finalHelmfileOverrides, err = m.MergeWithContext(
		atmosConfig,
		[]map[string]any{parentHelmfileOverridesImports, parentHelmfileOverridesInline},
		mergeContext,
	)
	if err != nil {
		return nil, nil, err
	}

	// Add the `overrides` section to all components in this stack manifest
	if len(finalTerraformOverrides) > 0 || len(finalHelmfileOverrides) > 0 {
		if componentsSection, ok := stackConfigMap[cfg.ComponentsSectionName].(map[string]any); ok {
			// Terraform
			if len(finalTerraformOverrides) > 0 {
				if terraformSection, ok := componentsSection[cfg.TerraformSectionName].(map[string]any); ok {
					for _, compSection := range terraformSection {
						if componentSection, ok := compSection.(map[string]any); ok {
							componentSection[cfg.OverridesSectionName] = finalTerraformOverrides
						}
					}
				}
			}

			// Helmfile
			if len(finalHelmfileOverrides) > 0 {
				if helmfileSection, ok := componentsSection[cfg.HelmfileSectionName].(map[string]any); ok {
					for _, compSection := range helmfileSection {
						if componentSection, ok := compSection.(map[string]any); ok {
							componentSection[cfg.OverridesSectionName] = finalHelmfileOverrides
						}
					}
				}
			}
		}
	}

	if len(stackConfigMap) > 0 {
		stackConfigs = append(stackConfigs, stackConfigMap)
	}

	// Deep-merge the stack manifest and all the imports
	stackConfigsDeepMerged, err := m.MergeWithContext(atmosConfig, stackConfigs, mergeContext)
	if err != nil {
		// The error already contains context information from MergeWithContext
		return nil, nil, err
	}

	// NOTE: We don't store merge context here because ProcessYAMLConfigFileWithContext
	// can be called from parallel goroutines in ProcessYAMLConfigFiles, which would create
	// a race condition. Instead, the caller should store the merge context if needed.

	return &schema.StackManifestProcessingResult{
		DeepMergedConfig:          stackConfigsDeepMerged,
		ImportsConfig:             importsConfig,
		StackConfig:               stackConfigMap,
		TerraformOverridesInline:  parentTerraformOverridesInline,
		TerraformOverridesImports: parentTerraformOverridesImports,
		HelmfileOverridesInline:   parentHelmfileOverridesInline,
		HelmfileOverridesImports:  parentHelmfileOverridesImports,
	}, mergeContext, nil
}

// emptyStackManifestProcessingResult returns a result with initialized empty
// maps, used when a missing or empty manifest is deliberately skipped.
func emptyStackManifestProcessingResult() *schema.StackManifestProcessingResult {
	return &schema.StackManifestProcessingResult{
		DeepMergedConfig:          map[string]any{},
		ImportsConfig:             map[string]map[string]any{},
		StackConfig:               map[string]any{},
		TerraformOverridesInline:  map[string]any{},
		TerraformOverridesImports: map[string]any{},
		HelmfileOverridesInline:   map[string]any{},
		HelmfileOverridesImports:  map[string]any{},
	}
}

// renderImportPath renders Go templates embedded in a stack import path.
//
// This lets an import reference values defined by EARLIER imports in the same manifest,
// for example pinning a remote import's Git ref from a globally-defined variable:
//
//	import:
//	  - ./_defaults    # sets settings.context.deployment_repo_version
//	  - "github.com/org/repo//stacks/catalog/foo?ref={{ .settings.context.deployment_repo_version }}"
//
// The template data is the accumulated `settings`/`vars`/`env` from earlier imports,
// overlaid with this import's own explicit `context` (which takes precedence). Only the
// path string is rendered; the imported file's content templating is untouched.
//
// Rendering is skipped when the path has no `{{`, when `skip_templates_processing` is set,
// or when templating is disabled in `atmos.yaml`. A missing value produces a hard error
// (with a hint) unless `ignore_missing_template_values` is set on the import or globally.
func renderImportPath(
	atmosConfig *schema.AtmosConfiguration,
	relativeFilePath string,
	imp string,
	accumulatedImportContext map[string]any,
	importStruct schema.StackImport,
) (string, error) {
	defer perf.Track(atmosConfig, "exec.renderImportPath")()

	if importStruct.SkipTemplatesProcessing || !strings.Contains(imp, "{{") {
		return imp, nil
	}
	// Honor the global templating switch so disabling templates also disables import-path
	// templating (and preserves raw `{{ ... }}` paths for callers that rely on that).
	if atmosConfig != nil && !atmosConfig.Templates.Settings.Enabled {
		return imp, nil
	}

	ignoreMissing := importStruct.IgnoreMissingTemplateValues ||
		(atmosConfig != nil && atmosConfig.Templates.Settings.IgnoreMissingTemplateValues)

	// Overlay the import's explicit `context` on top of the accumulated context.
	tmplData := accumulatedImportContext
	if len(importStruct.Context) > 0 {
		merged, err := m.Merge(atmosConfig, []map[string]any{accumulatedImportContext, importStruct.Context})
		if err != nil {
			return "", err
		}
		tmplData = merged
	}

	rendered, err := ProcessTmpl(atmosConfig, fmt.Sprintf("import-path(%s)", relativeFilePath), imp, tmplData, ignoreMissing)
	if err != nil {
		wrapped := fmt.Errorf("%w: import path '%s' in file '%s': %w",
			errUtils.ErrImportPathTemplate, imp, relativeFilePath, err)
		return "", errUtils.Build(wrapped).
			WithHint("Define the referenced variable in an earlier import (e.g. a `_defaults` file) or in this import's `context:`.").
			WithHint("Set `ignore_missing_template_values: true` on the import (or `templates.settings.ignore_missing_template_values` in atmos.yaml) to leave unresolved values as-is.").
			Err()
	}

	return rendered, nil
}

// extractImportPathSections returns a shallow map containing only the `settings`, `vars`,
// and `env` sections present in an imported manifest's merged config. These are the sections
// that can be referenced when templating subsequent imports' paths in the same manifest.
func extractImportPathSections(cfgMap map[string]any) map[string]any {
	out := map[string]any{}
	for _, section := range []string{cfg.SettingsSectionName, cfg.VarsSectionName, cfg.EnvSectionName} {
		if v, ok := cfgMap[section]; ok && v != nil {
			out[section] = v
		}
	}
	return out
}

// processSettingsIntegrationsGithub deep-merges the `settings.integrations.github` section from stack manifests with the `integrations.github` section from `atmos.yaml`.
func processSettingsIntegrationsGithub(atmosConfig *schema.AtmosConfiguration, settings map[string]any) (map[string]any, error) {
	defer perf.Track(atmosConfig, "exec.processSettingsIntegrationsGithub")()

	settingsIntegrationsSection := make(map[string]any)
	settingsIntegrationsGithubSection := make(map[string]any)

	// Find `settings.integrations.github` section from stack manifests
	//nolint:nestif // Nested type assertions for settings.integrations.github extraction.
	if settingsIntegrations, ok := settings[cfg.IntegrationsSectionName]; ok {
		if settingsIntegrationsMap, ok := settingsIntegrations.(map[string]any); ok {
			settingsIntegrationsSection = settingsIntegrationsMap
			if settingsIntegrationsGithub, ok := settingsIntegrationsMap[cfg.GithubSectionName]; ok {
				if settingsIntegrationsGithubMap, ok := settingsIntegrationsGithub.(map[string]any); ok {
					settingsIntegrationsGithubSection = settingsIntegrationsGithubMap
				}
			}
		}
	}

	// deep-merge the `settings.integrations.github` section from stack manifests with  the `integrations.github` section from `atmos.yaml`
	settingsIntegrationsGithubMerged, err := m.Merge(
		atmosConfig,
		[]map[string]any{
			atmosConfig.Integrations.GitHub,
			settingsIntegrationsGithubSection,
		},
	)
	if err != nil {
		return nil, err
	}

	// Update the `settings.integrations.github` section
	if len(settingsIntegrationsGithubMerged) > 0 {
		if settings == nil {
			settings = make(map[string]any)
		}
		settingsIntegrationsSection[cfg.GithubSectionName] = settingsIntegrationsGithubMerged
		settings[cfg.IntegrationsSectionName] = settingsIntegrationsSection
	}

	return settings, nil
}

// FindComponentStacks finds all infrastructure stack manifests where the component or the base component is defined.
func FindComponentStacks(
	componentType string,
	component string,
	baseComponent string,
	componentStackMap map[string]map[string][]string,
) ([]string, error) {
	defer perf.Track(nil, "exec.FindComponentStacks")()

	var stacks []string

	//nolint:nestif // Nested lookups for component and base component stack configurations.
	if componentStackConfig, componentStackConfigExists := componentStackMap[componentType]; componentStackConfigExists {
		if componentStacks, componentStacksExist := componentStackConfig[component]; componentStacksExist {
			stacks = append(stacks, componentStacks...)
		}

		if baseComponent != "" {
			if baseComponentStacks, baseComponentStacksExist := componentStackConfig[baseComponent]; baseComponentStacksExist {
				stacks = append(stacks, baseComponentStacks...)
			}
		}
	}

	unique := u.UniqueStrings(stacks)
	sort.Strings(unique)
	return unique, nil
}

// FindComponentDependenciesLegacy finds all imports where the component or the base component(s) are defined.
// Component depends on the imported config file if any of the following conditions is true:
//  1. The imported config file has any of the global `backend`, `backend_type`, `env`, `remote_state_backend`, `remote_state_backend_type`,
//     `settings` or `vars` sections which are not empty.
//  2. The imported config file has the component type section, which has any of the `backend`, `backend_type`, `env`, `remote_state_backend`,
//     `remote_state_backend_type`, `settings` or `vars` sections which are not empty.
//  3. The imported config file has the cfg.ComponentsSectionName section, which has the component type section, which has the component section.
//  4. The imported config file has the cfg.ComponentsSectionName section, which has the component type section, which has the base component(s) section,
//     and the base component section is defined inline (not imported).
//
//nolint:gocognit,revive,cyclop,funlen // Complex legacy dependency resolution logic.
func FindComponentDependenciesLegacy(
	stack string,
	componentType string,
	component string,
	baseComponents []string,
	stackImports map[string]map[string]any,
) ([]string, error) {
	defer perf.Track(nil, "exec.FindComponentDependenciesLegacy")()

	var deps []string

	sectionsToCheck := []string{
		cfg.BackendSectionName,
		cfg.BackendTypeSectionName,
		cfg.EnvSectionName,
		cfg.RemoteStateBackendSectionName,
		cfg.RemoteStateBackendTypeSectionName,
		cfg.SettingsSectionName,
		cfg.VarsSectionName,
	}

	for stackImportName, stackImportMap := range stackImports {
		if sectionContainsAnyNotEmptySections(stackImportMap, sectionsToCheck) {
			deps = append(deps, stackImportName)
			continue
		}

		if sectionContainsAnyNotEmptySections(stackImportMap, []string{componentType}) {
			if sectionContainsAnyNotEmptySections(stackImportMap[componentType].(map[string]any), sectionsToCheck) {
				deps = append(deps, stackImportName)
				continue
			}
		}

		stackImportMapComponentsSection, ok := stackImportMap[cfg.ComponentsSectionName].(map[string]any)
		if !ok {
			continue
		}

		stackImportMapComponentTypeSection, ok := stackImportMapComponentsSection[componentType].(map[string]any)
		if !ok {
			continue
		}

		if stackImportMapComponentSection, ok := stackImportMapComponentTypeSection[component].(map[string]any); ok {
			if len(stackImportMapComponentSection) > 0 {
				deps = append(deps, stackImportName)
				continue
			}
		}

		// Process base component(s)
		// Only include the imported config file into "deps" if all the following conditions are `true`:
		// 1. The imported config file has the base component(s) section(s)
		// 2. The imported config file does not import other config files (which means that instead it defined the base component sections inline)
		// 3. If the imported config file does import other config files, check that the base component sections in them are different by using
		// `reflect.DeepEqual`. If they are the same, don't include the imported config file since it does not specify anything for the base component
		for _, baseComponent := range baseComponents {
			baseComponentSection, ok := stackImportMapComponentTypeSection[baseComponent].(map[string]any)

			if !ok || len(baseComponentSection) == 0 {
				continue
			}

			importOfStackImportStructs, err := ProcessImportSection(stackImportMap, stack)
			if err != nil {
				return nil, err
			}

			if len(importOfStackImportStructs) == 0 {
				deps = append(deps, stackImportName)
				continue
			}

			for _, importOfStackImportStruct := range importOfStackImportStructs {
				importOfStackImportMap, ok := stackImports[importOfStackImportStruct.Path]
				if !ok {
					continue
				}

				importOfStackImportComponentsSection, ok := importOfStackImportMap[cfg.ComponentsSectionName].(map[string]any)
				if !ok {
					continue
				}

				importOfStackImportComponentTypeSection, ok := importOfStackImportComponentsSection[componentType].(map[string]any)
				if !ok {
					continue
				}

				importOfStackImportBaseComponentSection, ok := importOfStackImportComponentTypeSection[baseComponent].(map[string]any)
				if !ok {
					continue
				}

				if !reflect.DeepEqual(baseComponentSection, importOfStackImportBaseComponentSection) {
					deps = append(deps, stackImportName)
					break
				}
			}
		}
	}

	deps = append(deps, stack)
	unique := u.UniqueStrings(deps)
	sort.Strings(unique)
	return unique, nil
}

// ProcessImportSection processes the `import` section in stack manifests.
// The `import` section can contain:
// 1. Project-relative paths (e.g. "mixins/region/us-east-2")
// 2. Paths relative to the current stack file (e.g. "./_defaults")
// 3. StackImport structs containing either of the above path types (e.g. "path: mixins/region/us-east-2").
func ProcessImportSection(stackMap map[string]any, filePath string) ([]schema.StackImport, error) {
	defer perf.Track(nil, "exec.ProcessImportSection")()

	stackImports, ok := stackMap[cfg.ImportSectionName]

	// If the stack file does not have the `import` section, return
	if !ok || stackImports == nil {
		return nil, nil
	}

	// Check if the `import` section is a list of objects
	importsList, ok := stackImports.([]any)
	if !ok {
		return nil, fmt.Errorf("%w in the file '%s'", errUtils.ErrInvalidImportSection, filePath)
	}
	if len(importsList) == 0 {
		return nil, nil
	}

	var result []schema.StackImport

	for _, imp := range importsList {
		if imp == nil {
			return nil, fmt.Errorf("%w in the file '%s'", errUtils.ErrInvalidImport, filePath)
		}

		// 1. Try to decode the import as the `StackImport` struct
		var importObj schema.StackImport
		err := mapstructure.Decode(imp, &importObj)
		if err == nil {
			if importObj.NestedImports != "" {
				importObj.NestedImports = normalizeNestedImports(importObj.NestedImports)
				if err := validateNestedImports(importObj.NestedImports); err != nil {
					return nil, fmt.Errorf("%w in the file '%s'", err, filePath)
				}
			}
			importObj.Path = u.ResolveRelativePath(importObj.Path, filePath)
			result = append(result, importObj)
			continue
		}

		// 2. Try to cast the import to a string
		s, ok := imp.(string)
		if !ok {
			return nil, fmt.Errorf("%w '%v' in the file '%s'", errUtils.ErrInvalidImport, imp, filePath)
		}
		if s == "" {
			return nil, fmt.Errorf("%w (empty) in the file '%s'", errUtils.ErrInvalidImport, filePath)
		}

		s = u.ResolveRelativePath(s, filePath)
		result = append(result, schema.StackImport{Path: s})
	}

	return result, nil
}

func normalizeNestedImports(value string) string {
	if value == "" {
		return schema.StackImportNestedImportsLocal
	}
	return strings.ToLower(strings.TrimSpace(value))
}

func validateNestedImports(value string) error {
	switch normalizeNestedImports(value) {
	case schema.StackImportNestedImportsLocal, schema.StackImportNestedImportsRemote:
		return nil
	default:
		return fmt.Errorf("%w: nested_imports must be either 'local' or 'remote'", errUtils.ErrInvalidImport)
	}
}

// sectionContainsAnyNotEmptySections checks if a section contains any of the provided low-level sections, and it's not empty.
func sectionContainsAnyNotEmptySections(section map[string]any, sectionsToCheck []string) bool {
	for _, s := range sectionsToCheck {
		if len(s) > 0 {
			if v, ok := section[s]; ok {
				if v2, ok2 := v.(map[string]any); ok2 && len(v2) > 0 {
					return true
				}
				if v2, ok2 := v.(string); ok2 && len(v2) > 0 {
					return true
				}
			}
		}
	}
	return false
}

// ProcessBaseComponentConfig processes base component(s) config.
//
// initialMergeConfig is the effective AtmosConfiguration for the target component, pre-computed
// from the component's own settings layers (including settings.list_merge_strategy). When nil,
// the global atmosConfig is used. Passing an effective config here ensures that
// settings.list_merge_strategy set at the component level governs how base-component
// lists are merged across the metadata.inherits chain (issue #2396, see also PR #2480).
func ProcessBaseComponentConfig(
	atmosConfig *schema.AtmosConfiguration,
	initialMergeConfig *schema.AtmosConfiguration,
	baseComponentConfig *schema.BaseComponentConfig,
	allComponentsMap map[string]any,
	component string,
	stack string,
	baseComponent string,
	componentBasePath string,
	checkBaseComponentExists bool,
	baseComponents *[]string,
) error {
	defer perf.Track(atmosConfig, "exec.ProcessBaseComponentConfig")()

	if initialMergeConfig == nil {
		initialMergeConfig = atmosConfig
	}

	// Include the effective list_merge_strategy in the cache key so that components
	// with different per-component strategies do not share a cache entry whose merged
	// list values were produced with a different strategy.
	cacheKey := fmt.Sprintf("%s:%s:%s:%s", stack, component, baseComponent, initialMergeConfig.Settings.ListMergeStrategy)

	// Skip cache when provenance tracking is enabled, as we need to record provenance entries during processing.
	if !atmosConfig.TrackProvenance {
		// Check cache first.
		if cachedConfig, cachedBaseComponents, found := getCachedBaseComponentConfig(cacheKey); found {
			*baseComponentConfig = *cachedConfig
			*baseComponents = *cachedBaseComponents
			return nil
		}
	}

	// Process normally if not cached.
	visited := make(map[string]bool)
	err := processBaseComponentConfigInternal(
		atmosConfig,
		initialMergeConfig,
		baseComponentConfig,
		allComponentsMap,
		component,
		stack,
		baseComponent,
		componentBasePath,
		checkBaseComponentExists,
		baseComponents,
		visited,
	)
	if err != nil {
		return err
	}

	// Store result in cache after processing.
	cacheBaseComponentConfig(cacheKey, baseComponentConfig)
	return nil
}

// processBaseComponentConfigInternal is the internal recursive implementation.
//
// initialMergeConfig carries the effective AtmosConfiguration for the target component.
// At each level the function updates it with the current base component's settings so
// that settings.list_merge_strategy declared on any component in the inheritance chain
// is applied when merging that component's lists (issue #2396).
//
//nolint:gocognit,revive,cyclop,funlen
func processBaseComponentConfigInternal(
	atmosConfig *schema.AtmosConfiguration,
	initialMergeConfig *schema.AtmosConfiguration,
	baseComponentConfig *schema.BaseComponentConfig,
	allComponentsMap map[string]any,
	component string,
	stack string,
	baseComponent string,
	componentBasePath string,
	checkBaseComponentExists bool,
	baseComponents *[]string,
	visited map[string]bool,
) error {
	if component == baseComponent {
		return nil
	}

	// Cycle detection: check if we've already visited this (component, baseComponent) pair
	// on the current DFS path. The defer delete ensures entries are cleaned up on backtrack,
	// so diamond inheritance (shared ancestor reached via sibling branches) is not falsely
	// flagged as circular.
	visitKey := component + ":" + baseComponent
	if visited[visitKey] {
		return fmt.Errorf("%w: '%s' -> '%s' in the stack '%s'",
			errUtils.ErrCircularComponentInheritance, component, baseComponent, stack)
	}
	visited[visitKey] = true
	defer delete(visited, visitKey)

	var baseComponentVars map[string]any
	var baseComponentSettings map[string]any
	var baseComponentEnv map[string]any
	var baseComponentAuth map[string]any
	var baseComponentSecrets map[string]any
	var baseComponentDependencies map[string]any
	var baseComponentLocals map[string]any
	var baseComponentProviders map[string]any
	var baseComponentHooks map[string]any
	var baseComponentTest map[string]any
	var baseComponentMocks map[string]any
	var baseComponentGenerate map[string]any
	var baseComponentCommand string
	var baseComponentProvider string
	var baseComponentPaths any
	var baseComponentManifests any
	var baseComponentValidate any
	var baseComponentPlugins any
	var baseComponentRender map[string]any
	var baseComponentHelm map[string]any
	var baseComponentBackendType string
	var baseComponentBackendSection map[string]any
	var baseComponentRemoteStateBackendType string
	var baseComponentRemoteStateBackendSection map[string]any
	var baseComponentSourceSection map[string]any
	var baseComponentProvisionSection map[string]any
	var baseComponentRetry map[string]any
	var baseComponentMap map[string]any
	var ok bool

	*baseComponents = append(*baseComponents, baseComponent)

	if baseComponentSection, baseComponentSectionExist := allComponentsMap[baseComponent]; baseComponentSectionExist {
		baseComponentMap, ok = baseComponentSection.(map[string]any)
		if !ok {
			// Depending on the code and libraries, the section can have different map types: map[string]any or map[string]any
			// We try to convert to both
			baseComponentMapOfStrings, ok := baseComponentSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w for the base component '%s' of the component '%s' in the stack '%s'",
					errUtils.ErrInvalidBaseComponentConfig, baseComponent, component, stack)
			}
			baseComponentMap = baseComponentMapOfStrings
		}

		// First, process the base component(s) of this base component.
		// Skip component chain resolution for abstract components — their metadata.component
		// is a pointer to the Terraform directory but should not trigger inheritance traversal.
		// Following it on processed data (where mergeComponentConfigurations has promoted
		// metadata.component to a top-level "component" key) can create circular references.
		isAbstract := isAbstractComponent(baseComponentMap)
		if !isAbstract {
			if baseComponentOfBaseComponent, baseComponentOfBaseComponentExist := baseComponentMap["component"]; baseComponentOfBaseComponentExist {
				baseComponentOfBaseComponentString, ok := baseComponentOfBaseComponent.(string)
				if !ok {
					return fmt.Errorf("%w 'component:' of the component '%s' in the stack '%s'",
						errUtils.ErrInvalidComponentAttribute, baseComponent, stack)
				}

				err := processBaseComponentConfigInternal(
					atmosConfig,
					initialMergeConfig,
					baseComponentConfig,
					allComponentsMap,
					baseComponent,
					stack,
					baseComponentOfBaseComponentString,
					componentBasePath,
					checkBaseComponentExists,
					baseComponents,
					visited,
				)
				if err != nil {
					return err
				}
			}
		}

		// Base component metadata.
		// This is per component, not deep-merged and not inherited from base components and globals.
		componentMetadata := map[string]any{}
		if i, ok := baseComponentMap["metadata"]; ok {
			componentMetadata, ok = i.(map[string]any)
			if !ok {
				return fmt.Errorf("%w '%s.metadata' in the stack '%s'", errUtils.ErrInvalidComponentMetadata, component, stack)
			}

			if inheritList, inheritListExist := componentMetadata[cfg.InheritsSectionName].([]any); inheritListExist {
				for _, v := range inheritList {
					baseComponentFromInheritList, ok := v.(string)
					if !ok {
						return fmt.Errorf("%w '%s.metadata.inherits' in the stack '%s'", errUtils.ErrInvalidComponentMetadataInherits, component, stack)
					}

					if _, ok := allComponentsMap[baseComponentFromInheritList]; !ok {
						if checkBaseComponentExists {
							errorMessage := fmt.Sprintf(
								"The component '%[1]s' in the stack manifest '%[2]s' inherits from '%[3]s' "+
									"(using 'metadata.inherits'), but '%[3]s' is not defined in any of the config files for the stack '%[2]s'",
								component,
								stack,
								baseComponentFromInheritList,
							)
							return errors.New(errorMessage)
						}
					}

					// Process the baseComponentFromInheritList components recursively to find `componentInheritanceChain`.
					err := processBaseComponentConfigInternal(
						atmosConfig,
						initialMergeConfig,
						baseComponentConfig,
						allComponentsMap,
						component,
						stack,
						baseComponentFromInheritList,
						componentBasePath,
						checkBaseComponentExists,
						baseComponents,
						visited,
					)
					if err != nil {
						return err
					}
				}
			}
		}

		if baseComponentVarsSection, baseComponentVarsSectionExist := baseComponentMap[cfg.VarsSectionName]; baseComponentVarsSectionExist {
			baseComponentVars, ok = baseComponentVarsSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w: '%s.vars' in the stack '%s'", errUtils.ErrInvalidVarsSection, baseComponent, stack)
			}
		}

		if baseComponentSettingsSection, baseComponentSettingsSectionExist := baseComponentMap[cfg.SettingsSectionName]; baseComponentSettingsSectionExist {
			baseComponentSettings, ok = baseComponentSettingsSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w: '%s.settings' in the stack '%s'", errUtils.ErrInvalidSettingsSection, baseComponent, stack)
			}
		}

		if baseComponentEnvSection, baseComponentEnvSectionExist := baseComponentMap[cfg.EnvSectionName]; baseComponentEnvSectionExist {
			baseComponentEnv, ok = baseComponentEnvSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w: '%s.env' in the stack '%s'", errUtils.ErrInvalidEnvSection, baseComponent, stack)
			}
		}

		if baseComponentAuthSection, baseComponentAuthSectionExist := baseComponentMap[cfg.AuthSectionName]; baseComponentAuthSectionExist {
			baseComponentAuth, ok = baseComponentAuthSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w: '%s.auth' in the stack '%s'", errUtils.ErrInvalidAuthSection, baseComponent, stack)
			}
		}

		if baseComponentSecretsSection, baseComponentSecretsSectionExist := baseComponentMap[cfg.SecretsSectionName]; baseComponentSecretsSectionExist {
			baseComponentSecrets, ok = baseComponentSecretsSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w: '%s.secrets' in the stack '%s'", errUtils.ErrInvalidComponentSecrets, baseComponent, stack)
			}
		}

		if baseComponentDependenciesSection, baseComponentDependenciesSectionExist := baseComponentMap[cfg.DependenciesSectionName]; baseComponentDependenciesSectionExist {
			baseComponentDependencies, ok = baseComponentDependenciesSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w: '%s.dependencies' in the stack '%s'", errUtils.ErrInvalidComponentDependencies, baseComponent, stack)
			}
		}

		if baseComponentLocalsSection, baseComponentLocalsSectionExist := baseComponentMap[cfg.LocalsSectionName]; baseComponentLocalsSectionExist {
			baseComponentLocals, ok = baseComponentLocalsSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w: '%s.locals' in the stack '%s'", errUtils.ErrInvalidComponentLocals, baseComponent, stack)
			}
		}

		if baseComponentProvidersSection, baseComponentProvidersSectionExist := baseComponentMap[cfg.ProvidersSectionName]; baseComponentProvidersSectionExist {
			baseComponentProviders, ok = baseComponentProvidersSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w '%s.providers' in the stack '%s'", errUtils.ErrInvalidComponentProviders, baseComponent, stack)
			}
		}

		// Base component required_providers (DEV-3124).
		var baseComponentRequiredProviders map[string]any
		if baseComponentRequiredProvidersSection, baseComponentRequiredProvidersSectionExist := baseComponentMap[cfg.RequiredProvidersSectionName]; baseComponentRequiredProvidersSectionExist {
			baseComponentRequiredProviders, ok = baseComponentRequiredProvidersSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w '%s.required_providers' in the stack '%s'", errUtils.ErrInvalidComponentRequiredProviders, baseComponent, stack)
			}
		}

		// Base component required_version (DEV-3124).
		var baseComponentRequiredVersion string
		if baseComponentRequiredVersionSection, baseComponentRequiredVersionSectionExist := baseComponentMap[cfg.RequiredVersionSectionName]; baseComponentRequiredVersionSectionExist {
			baseComponentRequiredVersion, ok = baseComponentRequiredVersionSection.(string)
			if !ok {
				return fmt.Errorf("%w '%s.required_version' in the stack '%s'", errUtils.ErrInvalidComponentRequiredVersion, baseComponent, stack)
			}
		}

		if baseComponentHooksSection, baseComponentHooksSectionExist := baseComponentMap[cfg.HooksSectionName]; baseComponentHooksSectionExist {
			baseComponentHooks, ok = baseComponentHooksSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w '%s.hooks' in the stack '%s'", errUtils.ErrInvalidComponentHooks, baseComponent, stack)
			}
		}

		if baseComponentTestSection, baseComponentTestSectionExist := baseComponentMap[cfg.TestSectionName]; baseComponentTestSectionExist {
			baseComponentTest, ok = baseComponentTestSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w '%s.test' in the stack '%s'", errUtils.ErrInvalidConfig, baseComponent, stack)
			}
		}

		if baseComponentMocksSection, baseComponentMocksSectionExist := baseComponentMap[cfg.MocksSectionName]; baseComponentMocksSectionExist {
			baseComponentMocks, ok = baseComponentMocksSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w '%s.mocks' in the stack '%s'", errUtils.ErrInvalidConfig, baseComponent, stack)
			}
		}

		if baseComponentGenerateSection, baseComponentGenerateSectionExist := baseComponentMap[cfg.GenerateSectionName]; baseComponentGenerateSectionExist {
			baseComponentGenerate, ok = baseComponentGenerateSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w '%s.generate' in the stack '%s'", errUtils.ErrInvalidComponentGenerate, baseComponent, stack)
			}
		}

		if baseComponentProviderSection, baseComponentProviderSectionExist := baseComponentMap[cfg.ProviderSectionName]; baseComponentProviderSectionExist {
			baseComponentProvider, ok = baseComponentProviderSection.(string)
			if !ok {
				return fmt.Errorf("%w '%s.provider' in the stack '%s'", errUtils.ErrInvalidConfig, baseComponent, stack)
			}
		}

		if baseComponentPathsSection, baseComponentPathsSectionExist := baseComponentMap[cfg.PathsSectionName]; baseComponentPathsSectionExist {
			baseComponentPaths = baseComponentPathsSection
		}

		if baseComponentManifestsSection, baseComponentManifestsSectionExist := baseComponentMap[cfg.ManifestsSectionName]; baseComponentManifestsSectionExist {
			baseComponentManifests = baseComponentManifestsSection
		}

		if baseComponentValidateSection, baseComponentValidateSectionExist := baseComponentMap[cfg.ValidateSectionName]; baseComponentValidateSectionExist {
			baseComponentValidate = baseComponentValidateSection
		}

		if baseComponentPluginsSection, baseComponentPluginsSectionExist := baseComponentMap[cfg.PluginsSectionName]; baseComponentPluginsSectionExist {
			baseComponentPlugins = baseComponentPluginsSection
		}

		if baseComponentRenderSection, baseComponentRenderSectionExist := baseComponentMap[cfg.RenderSectionName]; baseComponentRenderSectionExist {
			baseComponentRender, ok = baseComponentRenderSection.(map[string]any)
			if !ok {
				return fmt.Errorf("%w '%s.render' in the stack '%s'", errUtils.ErrInvalidConfig, baseComponent, stack)
			}
		}

		// Base component native Helm fields (chart, values, etc.).
		baseComponentHelm = extractHelmComponentSection(baseComponentMap)

		// Base component backend
		if i, ok2 := baseComponentMap[cfg.BackendTypeSectionName]; ok2 {
			baseComponentBackendType, ok = i.(string)
			if !ok {
				return fmt.Errorf("%w '%s.backend_type' in the stack '%s'", errUtils.ErrInvalidComponentBackendType, baseComponent, stack)
			}
		}

		if i, ok2 := baseComponentMap[cfg.BackendSectionName]; ok2 {
			baseComponentBackendSection, ok = i.(map[string]any)
			if !ok {
				return fmt.Errorf("%w '%s.backend' in the stack '%s'", errUtils.ErrInvalidComponentBackend, baseComponent, stack)
			}
		}

		// Base component remote state backend
		if i, ok2 := baseComponentMap[cfg.RemoteStateBackendTypeSectionName]; ok2 {
			baseComponentRemoteStateBackendType, ok = i.(string)
			if !ok {
				return fmt.Errorf("%w '%s.remote_state_backend_type' in the stack '%s'", errUtils.ErrInvalidComponentRemoteStateBackendType, baseComponent, stack)
			}
		}

		if i, ok2 := baseComponentMap[cfg.RemoteStateBackendSectionName]; ok2 {
			baseComponentRemoteStateBackendSection, ok = i.(map[string]any)
			if !ok {
				return fmt.Errorf("%w '%s.remote_state_backend' in the stack '%s'", errUtils.ErrInvalidComponentRemoteStateBackend, baseComponent, stack)
			}
		}

		// Base component source (when source inheritance is enabled).
		if atmosConfig.Stacks.Inherit.IsSourceInheritanceEnabled() {
			if i, ok2 := baseComponentMap[cfg.SourceSectionName]; ok2 {
				baseComponentSourceSection, ok = normalizeComponentSourceSection(i)
				if !ok {
					return fmt.Errorf("%w '%s.source' in the stack '%s'", errUtils.ErrInvalidComponentSource, baseComponent, stack)
				}
			}
		}

		// Base component provision (when source inheritance is enabled).
		// Provision follows the same inheritance rules as source.
		if atmosConfig.Stacks.Inherit.IsSourceInheritanceEnabled() {
			if i, ok2 := baseComponentMap[cfg.ProvisionSectionName]; ok2 {
				baseComponentProvisionSection, ok = i.(map[string]any)
				if !ok {
					return fmt.Errorf("%w '%s.provision' in the stack '%s'", errUtils.ErrInvalidComponentProvision, baseComponent, stack)
				}
			}
		}

		// Base component `command`
		if baseComponentCommandSection, baseComponentCommandSectionExist := baseComponentMap[cfg.CommandSectionName]; baseComponentCommandSectionExist {
			baseComponentCommand, ok = baseComponentCommandSection.(string)
			if !ok {
				return fmt.Errorf("%w '%s.command' in the stack '%s'", errUtils.ErrInvalidComponentCommand, baseComponent, stack)
			}
		}

		// Base component `retry` — abstract components can define defaults that concrete
		// components inherit and override.
		if i, ok2 := baseComponentMap[cfg.RetrySectionName]; ok2 {
			baseComponentRetry, ok = i.(map[string]any)
			if !ok {
				return fmt.Errorf("%w '%s.retry' in the stack '%s'", errUtils.ErrInvalidConfig, baseComponent, stack)
			}
		}

		if len(baseComponentConfig.FinalBaseComponentName) == 0 {
			baseComponentConfig.FinalBaseComponentName = baseComponent
		}

		// Determine the effective merge config for this inheritance level.
		// settings.list_merge_strategy declared on the base component (or passed in via
		// initialMergeConfig from the target component) controls how list-valued sections
		// are merged when accumulating the inheritance chain (issue #2396, PR #2480).
		// The raw baseComponentSettings are consulted here — before they are themselves
		// merged — so the strategy always comes from the original YAML, not a previously
		// merged value that may have been overwritten.
		levelMergeConfig := effectiveAtmosConfig(initialMergeConfig, baseComponentSettings)

		// Base component `vars`
		merged, err := m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentVars, baseComponentVars})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentVars = merged

		// Base component `settings`
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentSettings, baseComponentSettings})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentSettings = merged

		// Base component `env`
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentEnv, baseComponentEnv})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentEnv = merged

		// Base component `auth`
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentAuth, baseComponentAuth})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentAuth = merged

		// Base component `secrets` — abstract/base components can declare secrets that concrete
		// components inherit (instance-scoped, like the rest of the component-level layers).
		merged, err = m.Merge(atmosConfig, []map[string]any{baseComponentConfig.BaseComponentSecrets, baseComponentSecrets})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentSecrets = merged

		// Base component `dependencies`
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentDependencies, baseComponentDependencies})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentDependencies = merged

		// Base component `locals` (for template processing, not passed to terraform/helmfile).
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentLocals, baseComponentLocals})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentLocals = merged

		// Base component `metadata` (when metadata inheritance is enabled).
		// Merge all metadata fields except 'inherits' and 'type'.
		// - 'inherits' is the meta-property defining inheritance, not inherited itself.
		// - 'type' is per-component and should not be inherited.
		if atmosConfig.Stacks.Inherit.IsMetadataInheritanceEnabled() {
			baseMetadataForMerge := make(map[string]any)
			for k, v := range componentMetadata {
				// Skip 'inherits' - it's the meta-property defining inheritance, not inherited itself.
				if k == cfg.InheritsSectionName {
					continue
				}
				// Skip 'type' - component type is per-component, not inherited.
				if k == "type" {
					continue
				}
				baseMetadataForMerge[k] = v
			}
			merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentMetadata, baseMetadataForMerge})
			if err != nil {
				return err
			}
			baseComponentConfig.BaseComponentMetadata = merged
		}

		// Base component `providers`
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentProviders, baseComponentProviders})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentProviders = merged

		// Base component `required_providers` (DEV-3124).
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentRequiredProviders, baseComponentRequiredProviders})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentRequiredProviders = merged

		// Base component `required_version` (DEV-3124).
		// String values are not merged - the most specific value wins.
		if baseComponentRequiredVersion != "" {
			baseComponentConfig.BaseComponentRequiredVersion = baseComponentRequiredVersion
		}

		// Base component `hooks`
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentHooks, baseComponentHooks})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentHooks = merged

		// Base component `test`
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentTest, baseComponentTest})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentTest = merged

		// Base component `mocks` are literal output fixtures and inherit like
		// other map sections; the concrete component wins on key conflicts.
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentMocks, baseComponentMocks})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentMocks = merged

		// Base component `generate`
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentGenerate, baseComponentGenerate})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentGenerate = merged

		// Base component `provider`
		if baseComponentProvider != "" {
			baseComponentConfig.BaseComponentProvider = baseComponentProvider
		}

		// Base component `paths`
		mergedAny, err := mergeComponentAnySection(levelMergeConfig, cfg.PathsSectionName, baseComponentConfig.BaseComponentPaths, baseComponentPaths)
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentPaths = mergedAny

		// Base component `manifests`
		mergedAny, err = mergeComponentAnySection(levelMergeConfig, cfg.ManifestsSectionName, baseComponentConfig.BaseComponentManifests, baseComponentManifests)
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentManifests = mergedAny

		// Base component `validate`
		mergedAny, err = mergeComponentAnySection(levelMergeConfig, cfg.ValidateSectionName, baseComponentConfig.BaseComponentValidate, baseComponentValidate)
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentValidate = mergedAny

		// Base component `plugins` (Helm CLI plugins list).
		mergedAny, err = mergeComponentAnySection(levelMergeConfig, cfg.PluginsSectionName, baseComponentConfig.BaseComponentPlugins, baseComponentPlugins)
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentPlugins = mergedAny

		// Base component `render`
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentRender, baseComponentRender})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentRender = merged

		// Base component native Helm fields.
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentHelm, baseComponentHelm})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentHelm = merged

		// Base component `command`
		baseComponentConfig.BaseComponentCommand = baseComponentCommand

		// Base component `backend_type`
		baseComponentConfig.BaseComponentBackendType = baseComponentBackendType

		// Base component `backend`
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentBackendSection, baseComponentBackendSection})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentBackendSection = merged

		// Base component `remote_state_backend_type`
		baseComponentConfig.BaseComponentRemoteStateBackendType = baseComponentRemoteStateBackendType

		// Base component `remote_state_backend`
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentRemoteStateBackendSection, baseComponentRemoteStateBackendSection})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentRemoteStateBackendSection = merged

		// Base component `source` (when source inheritance is enabled).
		if atmosConfig.Stacks.Inherit.IsSourceInheritanceEnabled() {
			merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentSourceSection, baseComponentSourceSection})
			if err != nil {
				return err
			}
			baseComponentConfig.BaseComponentSourceSection = merged
		}

		// Base component `provision` (when source inheritance is enabled).
		// Provision follows the same inheritance rules as source.
		if atmosConfig.Stacks.Inherit.IsSourceInheritanceEnabled() {
			merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentProvisionSection, baseComponentProvisionSection})
			if err != nil {
				return err
			}
			baseComponentConfig.BaseComponentProvisionSection = merged
		}

		// Base component `retry` — deep-merge so multi-level inheritance composes correctly.
		merged, err = m.Merge(levelMergeConfig, []map[string]any{baseComponentConfig.BaseComponentRetry, baseComponentRetry})
		if err != nil {
			return err
		}
		baseComponentConfig.BaseComponentRetry = merged

		baseComponentConfig.ComponentInheritanceChain = u.UniqueStrings(append([]string{baseComponent}, baseComponentConfig.ComponentInheritanceChain...))
	} else {
		if checkBaseComponentExists {
			// Check if the base component exists as Terraform/Helmfile component
			// If it does exist, don't throw errors if it is not defined in YAML config
			componentPath := filepath.Join(componentBasePath, baseComponent)
			componentPathExists, err := u.IsDirectory(componentPath)
			if err != nil || !componentPathExists {
				return errors.New("The component '" + component + "' inherits from the base component '" +
					baseComponent + "' (using 'component:' attribute), " + "but `" + baseComponent + "' is not defined in any of the YAML config files for the stack '" + stack + "'")
			}
		}
	}

	return nil
}

// FindComponentsDerivedFromBaseComponents finds all components that derive from the given base components.
func FindComponentsDerivedFromBaseComponents(
	stack string,
	allComponents map[string]any,
	baseComponents []string,
) ([]string, error) {
	defer perf.Track(nil, "exec.FindComponentsDerivedFromBaseComponents")()

	res := []string{}

	for component, compSection := range allComponents {
		componentSection, ok := compSection.(map[string]any)
		if !ok {
			return nil, fmt.Errorf("%w '%s' in the file '%s'", errUtils.ErrInvalidComponentsSection, component, stack)
		}

		if base, baseComponentExist := componentSection[cfg.ComponentSectionName]; baseComponentExist {
			baseComponent, ok := base.(string)
			if !ok {
				return nil, fmt.Errorf("%w 'component' of the component '%s' in the file '%s'", errUtils.ErrInvalidComponentAttribute, component, stack)
			}

			if baseComponent != "" && slices.Contains(baseComponents, baseComponent) {
				res = append(res, component)
			}
		}
	}

	return res, nil
}