config/module: disallow root modules named "root"

Fixes #11038

This is a **short term fix**.

Terraform core doesn't currently handle root modules named "root" well
because the prefix `[]string{"root"}` has special meaning and Terraform
core [currently] can't disambiguate between the root module and a module
named "root" in the root module.

This PR introduces a short term fix by simply disallowing root modules
named "root". This shouldn't break any BC because since 0.8.0 this
didn't work at all in many broken ways (including crashes).

Longer term, this should be fixed by removing the special prefix at all
and having empty paths be root. I started down this path but the core
changes necessary are far too scary for a patch release. We can aim for
0.9.

config/module/test-fixtures/validate-module-root-grandchild/child/child/main.tf

@@ -0,0 +1 @@
+# Empty

config/module/test-fixtures/validate-module-root-grandchild/child/main.tf

@@ -0,0 +1 @@
+module "root" { source = "./child" }

config/module/test-fixtures/validate-module-root-grandchild/main.tf

@@ -0,0 +1,3 @@
+module "child" {
+    source = "./child"
+}

config/module/test-fixtures/validate-module-root/child/main.tf

@@ -0,0 +1 @@
+# Empty

config/module/test-fixtures/validate-module-root/main.tf

@@ -0,0 +1,3 @@
+module "root" {
+    source = "./child"
+}

config/module/tree.go

@@ -261,6 +261,14 @@ func (t *Tree) Validate() error {
 	// If something goes wrong, here is our error template
 	newErr := &TreeError{Name: []string{t.Name()}}
 
+	// Terraform core does not handle root module children named "root".
+	// We plan to fix this in the future but this bug was brought up in
+	// the middle of a release and we don't want to introduce wide-sweeping
+	// changes at that time.
+	if len(t.path) == 1 && t.name == "root" {
+		return fmt.Errorf("root module cannot contain module named 'root'")
+	}
+
 	// Validate our configuration first.
 	if err := t.config.Validate(); err != nil {
 		newErr.Err = err

config/module/tree_test.go

@@ -288,6 +288,18 @@ func TestTreeValidate_table(t *testing.T) {
 			"validate-alias-bad",
 			"alias must be defined",
 		},
+
+		{
+			"root module named root",
+			"validate-module-root",
+			"cannot contain module",
+		},
+
+		{
+			"grandchild module named root",
+			"validate-module-root-grandchild",
+			"",
+		},
 	}
 
 	for i, tc := range cases {