Merge branch 'main' into fix-5810-feature-default-isolation

Author: dhotcolorado

docs/src/data/changelog/v1.0.4/stack-dependencies.mdx

@@ -0,0 +1,56 @@
+---
+version: "v1.0.4"
+category: "experiments-updated"
+---
+
+#### `stack-dependencies` — Nested stack paths and discovery integration
+
+The `stack-dependencies` experiment gains two improvements: nested stack path references at arbitrary depth, and integration with the `find` and `list` discovery commands.
+
+**Nested stack path references**
+
+`stack.<name>.<nested_stack>.path` now resolves at arbitrary nesting depth. Previously, only units within a stack were reachable via `stack.<name>.<unit_name>.path`; nested stacks are now first-class references too.
+
+```hcl
+# terragrunt.stack.hcl
+
+stack "infra" {
+  source = "../catalog/stacks/infra"
+  path   = "infra"
+}
+
+unit "app" {
+  source = "../catalog/units/app"
+  path   = "app"
+
+  autoinclude {
+    dependency "deep" {
+      # infra contains a nested "deep" stack; reference it directly.
+      config_path = stack.infra.deep.path
+    }
+
+    inputs = {
+      val = dependency.deep.outputs.val
+    }
+  }
+}
+```
+
+**Discovery commands surface stack dependencies**
+
+The `terragrunt find` and `terragrunt list` discovery commands now reflect stack dependencies generated by the `autoinclude` block. The DAG output correctly orders units by their autoinclude dependencies and shows dependency relationships in JSON, tree, and long formats.
+
+```bash
+# JSON output includes dependency relationships from autoinclude
+$ terragrunt find --json --dag --dependencies --experiment stack-dependencies
+
+# Long list format shows a Dependencies column
+$ terragrunt list --long --dependencies --dag --experiment stack-dependencies
+
+# Tree format visualizes the dependency hierarchy
+$ terragrunt list --tree --dag --experiment stack-dependencies
+```
+
+Multi-level dependency trees (for example, `A → B,C` where `B → D,E`) are ordered correctly in DAG mode: leaf units appear first, parents appear after all their dependencies.
+
+To learn more, see the [experiment documentation](/reference/experiments/active#stack-dependencies).

docs/src/data/experiments/stack-dependencies.mdx

@@ -143,3 +143,22 @@ Provide your feedback on the [Stack Dependencies RFC](https://github.com/gruntwo
 - [ ] Performance validation at scale
 
 </Since>
+
+<Since version="1.0.4">
+
+- [x] Create `internal/hclparse` package with two-phase stack file parser and autoinclude data structures
+- [x] Implement `terragrunt.autoinclude.hcl` file generator with relative path resolution
+- [x] Implement AST-walking partial evaluator for mixed `local.*` + `dependency.*` expressions
+- [x] Integrate autoinclude parsing and generation into `pkg/config/stack.go` stack generation pipeline
+- [x] Auto-merge `terragrunt.autoinclude.hcl` into unit config during `ParseConfig()` with deep merge
+- [x] Add `tryGetStackOutput()` for dependency blocks targeting stack directories
+- [x] Add `ExtractAutoIncludeDependencyPaths()` so DAG sees dependencies from autoinclude files
+- [x] Add integration tests and test fixtures for end-to-end validation
+- [x] E2E validation with `stack run apply` and `stack run destroy`
+- [x] Resolve `stack.<name>.<nested_stack>.path` at arbitrary nesting depth
+- [x] Surface autoinclude dependencies in `terragrunt find` and `terragrunt list` (JSON, tree, and long formats)
+- [ ] Community feedback on `autoinclude` syntax and merge behavior
+- [ ] Integration with CAS for generated files
+- [ ] Performance validation at scale
+
+</Since>

internal/discovery/helpers.go

@@ -290,7 +290,11 @@ func stackDependencyPaths(fs vfs.FS, depPaths []string, c component.Component) (
 	expanded := make([]string, 0, len(depPaths))
 
 	for _, depPath := range depPaths {
-		unitPaths := inthclparse.UnitPathsFromStackDir(fs, depPath)
+		unitPaths, err := inthclparse.UnitPathsFromStackDir(fs, depPath)
+		if err != nil {
+			return nil, err
+		}
+
 		if len(unitPaths) > 0 {
 			expanded = append(expanded, unitPaths...)
 

internal/hclparse/autoinclude.go

@@ -1,6 +1,7 @@
 package hclparse
 
 import (
+	"fmt"
 	iofs "io/fs"
 	"path/filepath"
 
@@ -179,53 +180,89 @@ func BuildAutoIncludeEvalContext(unitRefs, stackRefs []ComponentRef) *hcl.EvalCo
 // AutoIncludeDependencyPaths reads the terragrunt.autoinclude.hcl file in
 // unitDir and returns resolved dependency config_path values.
 // Returns (nil, nil) if the file does not exist or has no dependencies.
+// Panics when fs is nil (programmer error). Returns EmptyArgError when unitDir
+// is empty so callers can distinguish bad input from a missing file.
 func AutoIncludeDependencyPaths(fs vfs.FS, unitDir string) ([]string, error) {
+	if fs == nil {
+		panic(fmt.Sprintf("hclparse.AutoIncludeDependencyPaths: fs is nil (unitDir=%q)", unitDir))
+	}
+
+	if unitDir == "" {
+		return nil, EmptyArgError{Func: "AutoIncludeDependencyPaths", Arg: "unitDir"}
+	}
+
 	unitDir = util.ResolvePath(unitDir)
 	autoIncludePath := filepath.Join(unitDir, AutoIncludeFile)
 
-	data, err := vfs.ReadFile(fs, autoIncludePath)
+	body, err := readAutoIncludeBody(fs, autoIncludePath)
+	if err != nil || body == nil {
+		return nil, err
+	}
+
+	paths := make([]string, 0, len(body.Blocks))
+
+	for _, block := range body.Blocks {
+		if depPath, ok := extractDependencyConfigPath(block, unitDir); ok {
+			paths = append(paths, depPath)
+		}
+	}
+
+	return paths, nil
+}
+
+// readAutoIncludeBody reads and parses the autoinclude file at path.
+// Returns (nil, nil) when the file does not exist.
+func readAutoIncludeBody(fs vfs.FS, path string) (*hclsyntax.Body, error) {
+	data, err := vfs.ReadFile(fs, path)
 	if errors.Is(err, iofs.ErrNotExist) {
 		return nil, nil
 	}
 
 	if err != nil {
-		return nil, FileReadError{FilePath: autoIncludePath, Err: err}
+		return nil, FileReadError{FilePath: path, Err: err}
 	}
 
-	file, diags := hclsyntax.ParseConfig(data, autoIncludePath, hcl.Pos{Line: 1, Column: 1})
+	file, diags := hclsyntax.ParseConfig(data, path, hcl.Pos{Line: 1, Column: 1})
 	if diags.HasErrors() {
-		return nil, FileParseError{FilePath: autoIncludePath, Detail: diags.Error()}
+		return nil, FileParseError{FilePath: path, Detail: diags.Error()}
 	}
 
 	body, ok := file.Body.(*hclsyntax.Body)
 	if !ok {
-		return nil, UnexpectedBodyTypeError{FilePath: autoIncludePath}
+		return nil, UnexpectedBodyTypeError{FilePath: path}
 	}
 
-	var paths []string
-
-	for _, block := range body.Blocks {
-		if block.Type != blockDependency || len(block.Labels) == 0 {
-			continue
-		}
+	return body, nil
+}
 
-		configPathAttr, exists := block.Body.Attributes[attrConfigPath]
-		if !exists {
-			continue
-		}
+// extractDependencyConfigPath returns the resolved absolute config_path for a
+// dependency block, or ("", false) if the block is not a valid dependency or
+// config_path cannot be evaluated to a string.
+//
+// The nil eval context passed to Expr.Value is intentional: GenerateAutoIncludeFile
+// always writes config_path as a literal quoted string via writeDependencyBlock
+// (see generate.go), so no variable resolution is required. If that contract is
+// ever relaxed to emit interpolations, callers must pass a real eval context
+// here or the dependency will be silently dropped from the DAG.
+func extractDependencyConfigPath(block *hclsyntax.Block, unitDir string) (string, bool) {
+	if block.Type != blockDependency || len(block.Labels) == 0 {
+		return "", false
+	}
 
-		val, valDiags := configPathAttr.Expr.Value(nil)
-		if valDiags.HasErrors() || !val.IsKnown() || val.IsNull() || val.Type() != cty.String {
-			continue
-		}
+	configPathAttr, exists := block.Body.Attributes[attrConfigPath]
+	if !exists {
+		return "", false
+	}
 
-		depPath := val.AsString()
-		if !filepath.IsAbs(depPath) {
-			depPath = filepath.Clean(filepath.Join(unitDir, depPath))
-		}
+	val, diags := configPathAttr.Expr.Value(nil)
+	if diags.HasErrors() || !val.IsKnown() || val.IsNull() || val.Type() != cty.String {
+		return "", false
+	}
 
-		paths = append(paths, util.ResolvePath(depPath))
+	depPath := val.AsString()
+	if !filepath.IsAbs(depPath) {
+		depPath = filepath.Clean(filepath.Join(unitDir, depPath))
 	}
 
-	return paths, nil
+	return util.ResolvePath(depPath), true
 }

internal/hclparse/errors.go

@@ -133,3 +133,13 @@ type LocalsMaxIterError struct {
 func (e LocalsMaxIterError) Error() string {
 	return fmt.Sprintf("locals evaluation exceeded %d iterations with %d unresolved locals", e.MaxIterations, e.Remaining)
 }
+
+// EmptyArgError indicates that a required string argument was empty.
+type EmptyArgError struct {
+	Func string
+	Arg  string
+}
+
+func (e EmptyArgError) Error() string {
+	return fmt.Sprintf("hclparse.%s: %s is empty", e.Func, e.Arg)
+}