feat: Adding render preview for expansion (#6737)

* feat: Adding `render` preview for `expansion`

* chore: Refactoring `WriteTo`

* chore: Adding `duplicate-dependency-labels` strict control

* docs: Cleaning up docs gating

Author: yhakbar

docs/src/data/changelog/v1.1.4/duplicate-dependency-labels.mdx

@@ -0,0 +1,35 @@
+---
+version: "v1.1.4"
+category: "new-features"
+---
+
+#### `duplicate-dependency-labels` strict control
+
+Declaring two `dependency` blocks with the same label in one `terragrunt.hcl` configuration file parsed without error, and then quietly resolved every reference to that label to whichever block came last. The blocks before it were silently overridden:
+
+```hcl
+dependency "vpc" {
+  config_path = "../vpc-us-east-1"
+}
+
+dependency "vpc" {
+  config_path = "../vpc-us-west-2"
+}
+
+inputs = {
+  # Reads ../vpc-us-west-2.
+  vpc_id = dependency.vpc.outputs.vpc_id
+}
+```
+
+Terragrunt now warns when it finds this. With the new [`duplicate-dependency-labels`](/reference/strict-controls/active#duplicate-dependency-labels) strict control enabled, the warning becomes an error naming the address the blocks share:
+
+```bash
+terragrunt run plan --strict-control duplicate-dependency-labels
+```
+
+```text
+/path/to/terragrunt.hcl: dependency vpc is declared more than once; every dependency needs an address of its own
+```
+
+Give each block a label of its own. A configuration that was relying on the shadowing to pick the last block should keep only that block.

docs/src/data/changelog/v1.1.4/render-expansion-preview.mdx

@@ -0,0 +1,31 @@
+---
+version: "v1.1.4"
+category: "experiments-updated"
+---
+
+#### `render` previews what an expanded `dependency` block expanded to
+
+With the [`block-iteration`](/reference/experiments/active#block-iteration) experiment enabled, a `dependency` block that carries an `expansion` block now renders as it was written, followed by the elements it expanded into, commented out and with their bodies resolved:
+
+```bash
+$ terragrunt render --experiment block-iteration
+dependency "aurora" {
+  expansion {
+    for_each = toset(["web", "api"])
+  }
+
+  config_path = "../aurora-${each.key}"
+}
+
+# Expands to:
+#
+# dependency "aurora" {
+#   config_path = "../aurora-api"
+# }
+#
+# dependency "aurora" {
+#   config_path = "../aurora-web"
+# }
+```
+
+The elements are comments because they aren't valid Terragrunt HCL configurations (you are not allowed to use the same dependency label twice in Terragrunt configurations), the previews are there to help you understand how expansion will resolve.

docs/src/data/commands/render.mdx

@@ -18,6 +18,10 @@ flags:
   - render-all
 ---
 
+import { Aside } from '@astrojs/starlight/components';
+import Before from '@components/Before.astro';
+import Since from '@components/Since.astro';
+
 Render the Terragrunt configuration in the current working directory, with as much work done as possible beforehand (that is, with all includes merged, dependencies resolved/interpolated, function calls executed, etc).
 
 The only supported format at the moment is JSON, but support for HCL will be added in a future version.
@@ -83,3 +87,67 @@ terragrunt render --all --json -w
 ```
 
 This will render all configurations discovered from the current working directory and write the rendered configurations to `terragrunt.rendered.json` files adjacent to the configurations they are derived from.
+
+## Expanded dependencies
+
+<Before version="1.1.4">
+Previewing how a `dependency` block expands will be supported in v1.1.4.
+</Before>
+
+<Since version="1.1.4">
+
+<Aside type="tip" title="Experimental">
+Expanding a `dependency` block over a `count` or `for_each` is gated behind the [`block-iteration`](/reference/experiments/active#block-iteration) experiment. Enable it with `--experiment=block-iteration` or `TG_EXPERIMENT=block-iteration`.
+</Aside>
+
+A `dependency` block that carries an `expansion` block renders as it was written, references and all, followed by the elements it expanded into. Each element is commented out, with its body resolved against the iteration it came from:
+
+```bash
+$ terragrunt render --experiment block-iteration
+dependency "aurora" {
+  expansion {
+    for_each = toset(["web", "api"])
+  }
+
+  config_path = "../aurora-${each.key}"
+}
+
+# Expands to:
+#
+# dependency "aurora" {
+#   config_path = "../aurora-api"
+# }
+#
+# dependency "aurora" {
+#   config_path = "../aurora-web"
+# }
+```
+
+`count` reads the same way:
+
+```bash
+$ terragrunt render --experiment block-iteration
+dependency "shard" {
+  expansion {
+    count = 2
+  }
+
+  config_path = "../shard-${count.index}"
+}
+
+# Expands to:
+#
+# dependency "shard" {
+#   config_path = "../shard-0"
+# }
+#
+# dependency "shard" {
+#   config_path = "../shard-1"
+# }
+```
+
+The expanded blocks are in comments because they are not a valid Terragrunt configuration: they all carry one label, and only the last block with a given label can be referenced. Terragrunt warns about that, and rejects it outright under the `duplicate-dependency-labels` [strict control](/reference/strict-controls/active#duplicate-dependency-labels). They are present as comments to help you predict how Terragrunt will expand the block with an `expansion` block.
+
+A `dependency` block with no `expansion` block renders as it always has.
+
+</Since>

docs/src/data/strict-controls/duplicate-dependency-labels.mdx

@@ -0,0 +1,36 @@
+---
+name: duplicate-dependency-labels
+status: active
+since: "1.1.4"
+---
+
+Throw an error when two `dependency` blocks in one configuration claim the same address.
+
+### `duplicate-dependency-labels` - Reason
+
+Two `dependency` blocks written with the same label both parse, and Terragrunt then resolves every reference to that label to whichever block came last. The blocks before it are unreachable, with nothing to say so:
+
+```hcl
+dependency "vpc" {
+  config_path = "../vpc-us-east-1"
+}
+
+dependency "vpc" {
+  config_path = "../vpc-us-west-2"
+}
+
+inputs = {
+  # Reads ../vpc-us-west-2. The first block may as well not be there.
+  vpc_id = dependency.vpc.outputs.vpc_id
+}
+```
+
+Terragrunt warns about this by default. Enabling the control turns it into an error naming the address the blocks share:
+
+```text
+/path/to/terragrunt.hcl: dependency vpc is declared more than once; every dependency needs an address of its own
+```
+
+Give each block a label of its own. A configuration that was relying on the shadowing to pick the last block should keep only that block.
+
+Blocks are compared by the address they resolve to rather than by label alone, so the elements of a block expanded with the [`block-iteration`](/reference/experiments/active#block-iteration) experiment, which all carry the label the block was written with, remain valid.

internal/strict/controls/controls.go

@@ -94,6 +94,10 @@ const (
 	LegacyGCSPublicPrefix = "legacy-gcs-public-prefix"
 
 	OptionalHooks = "optional-hooks"
+
+	// DuplicateDependencyLabels is the control that prevents two `dependency` blocks in one
+	// configuration from claiming the same address.
+	DuplicateDependencyLabels = "duplicate-dependency-labels"
 )
 
 // LegacyGCSDeprecationWarning is the warning text emitted when a plain
@@ -234,6 +238,15 @@ func New() strict.Controls {
 			Warning: "Using an `include` block without a label is deprecated. Please use the `include` block with a label instead. For more information, see https://docs.terragrunt.com/migrate/bare-include/",
 		},
 
+		&Control{
+			Name:        DuplicateDependencyLabels,
+			Description: "Prevents two `dependency` blocks in one configuration from claiming the same address.",
+			Error: errors.New( //nolint:staticcheck // user-facing message intentionally written as full sentences
+				"Two `dependency` blocks address the same dependency. Give each block a label of its own.",
+			),
+			Warning: "Two `dependency` blocks address the same dependency, so only the last of them can be referenced and the rest are unreachable. Give each block a label of its own. In a future version of Terragrunt, this will result in an error.",
+		},
+
 		&Control{
 			Name:        DoubleStar,
 			Description: "Use the `**` glob pattern to select all files in a directory and its subdirectories.",

internal/strict/controls/controls_test.go

@@ -248,3 +248,16 @@ func TestControlEvaluate(t *testing.T) {
 		require.ErrorIs(t, err, bootErr)
 	})
 }
+
+// TestDuplicateDependencyLabelsControlIsRegistered pins that the control the dependency
+// decoder looks up by name is one the registry hands back.
+func TestDuplicateDependencyLabelsControlIsRegistered(t *testing.T) {
+	t.Parallel()
+
+	ctrl := controls.New().Find(controls.DuplicateDependencyLabels)
+
+	if assert.NotNil(t, ctrl, "duplicate-dependency-labels must be registered") {
+		assert.Equal(t, strict.ActiveStatus, ctrl.GetStatus())
+		assert.Error(t, ctrl.(*controls.Control).Error)
+	}
+}