feat: add new metadata to stack (#383)

cmd/terramate/cli/cli.go

@@ -819,6 +819,9 @@ func (c *cli) printMetadata() {
 		c.log("\tterramate.stack.name=%q", stackMeta.Name())
 		c.log("\tterramate.stack.description=%q", stackMeta.Desc())
 		c.log("\tterramate.stack.path.absolute=%q", stackMeta.Path())
+		c.log("\tterramate.stack.path.basename=%q", stackMeta.PathBase())
+		c.log("\tterramate.stack.path.relative=%q", stackMeta.RelPath())
+		c.log("\tterramate.stack.path.to_root=%q", stackMeta.RelPathToRoot())
 	}
 }
 

cmd/terramate/e2etests/exp_metadata_test.go

@@ -45,6 +45,9 @@ stack "/stack":
 	terramate.stack.name="stack"
 	terramate.stack.description=""
 	terramate.stack.path.absolute="/stack"
+	terramate.stack.path.basename="stack"
+	terramate.stack.path.relative="stack"
+	terramate.stack.path.to_root=".."
 `,
 			},
 		},
@@ -63,21 +66,33 @@ stack "/somedir/stack3":
 	terramate.stack.name="stack3"
 	terramate.stack.description=""
 	terramate.stack.path.absolute="/somedir/stack3"
+	terramate.stack.path.basename="stack3"
+	terramate.stack.path.relative="somedir/stack3"
+	terramate.stack.path.to_root="../.."
 
 stack "/somedir/stack4":
 	terramate.stack.name="stack4"
 	terramate.stack.description=""
 	terramate.stack.path.absolute="/somedir/stack4"
+	terramate.stack.path.basename="stack4"
+	terramate.stack.path.relative="somedir/stack4"
+	terramate.stack.path.to_root="../.."
 
 stack "/stack1":
 	terramate.stack.name="stack1"
 	terramate.stack.description=""
 	terramate.stack.path.absolute="/stack1"
+	terramate.stack.path.basename="stack1"
+	terramate.stack.path.relative="stack1"
+	terramate.stack.path.to_root=".."
 
 stack "/stack2":
 	terramate.stack.name="stack2"
 	terramate.stack.description=""
 	terramate.stack.path.absolute="/stack2"
+	terramate.stack.path.basename="stack2"
+	terramate.stack.path.relative="stack2"
+	terramate.stack.path.to_root=".."
 `,
 			},
 		},
@@ -97,6 +112,9 @@ stack "/stack1":
 	terramate.stack.name="stack1"
 	terramate.stack.description=""
 	terramate.stack.path.absolute="/stack1"
+	terramate.stack.path.basename="stack1"
+	terramate.stack.path.relative="stack1"
+	terramate.stack.path.to_root=".."
 `,
 			},
 		},
@@ -116,11 +134,17 @@ stack "/somedir/stack3":
 	terramate.stack.name="stack3"
 	terramate.stack.description=""
 	terramate.stack.path.absolute="/somedir/stack3"
+	terramate.stack.path.basename="stack3"
+	terramate.stack.path.relative="somedir/stack3"
+	terramate.stack.path.to_root="../.."
 
 stack "/somedir/stack4":
 	terramate.stack.name="stack4"
 	terramate.stack.description=""
 	terramate.stack.path.absolute="/somedir/stack4"
+	terramate.stack.path.basename="stack4"
+	terramate.stack.path.relative="somedir/stack4"
+	terramate.stack.path.to_root="../.."
 `,
 			},
 		},

docs/sharing-data.md

@@ -243,7 +243,7 @@ accessed through the variable namespace **terramate**.
 This can be referenced from any Terramate code to reference
 information like the path of the stack or its name.
 
-## terramate.stack.path.absolute (string) 
+## terramate.stack.path.absolute (string)
 
 The absolute path of the stack relative to the project
 root directory, not the host root directory. So it is absolute
@@ -261,9 +261,59 @@ Given this project layout:
 * **stack-a** = /stacks/stack-a
 * **stack-b** = /stacks/stack-b
 
-## terramate.stack.name (string) 
+## terramate.stack.path.relative (string)
 
-The name of the stack.
+The stack path relative from the project root directory.
+
+Given this project layout:
+
+```
+.
+└── stacks
+    ├── stack-a
+    └── stack-b
+```
+
+* **stack-a** = stacks/stack-a
+* **stack-b** = stacks/stack-b
+
+## terramate.stack.path.basename (string)
+
+The base name of the stack path.
+
+Given this project layout:
+
+```
+.
+└── stacks
+    ├── stack-a
+    └── stack-b
+```
+
+* **stack-a** = stack-a
+* **stack-b** = stack-b
+
+## terramate.stack.path.to\_root (string)
+
+The relative path from the stack to the project root.
+
+Given this project layout:
+
+```
+.
+└── stacks
+    ├── stack-a
+    └── stack-b
+```
+
+* **stack-a** = ../..
+* **stack-b** = ../..
+
+## terramate.stack.name (string)
+
+The name of the stack as defined on the stack configuration.
+If the stack doesn't have a name defined on its configuration
+the name will default to `terramate.stack.path.basename`.
 
 Given this stack layout (from the root of the project):
 
@@ -280,7 +330,7 @@ Given this stack layout (from the root of the project):
 Please consider [stack configuration](stack.md) to see how
 you can change the default stack name.
 
-## terramate.stack.description (string) 
+## terramate.stack.description (string)
 
 The description of the stack, if it has any.
 The default value is an empty string.
@@ -293,14 +343,14 @@ you can change the default stack description.
 Here is a list of older metadata that still can be used but are in the
 process of deprecation.
 
-### terramate.path (string) 
+### terramate.path (string)
 
 Superseded by terramate.stack.path.absolute.
 
-### terramate.name (string) 
+### terramate.name (string)
 
 Superseded by terramate.stack.name.
 
-### terramate.description (string) 
+### terramate.description (string)
 
 Superseded by terramate.stack.description.

generate/genfile/genfile_test.go

@@ -140,8 +140,16 @@ func TestLoadGenerateFiles(t *testing.T) {
 					path: "/stack/test.tm",
 					add: generateFile(
 						labels("test"),
-						str("content", "${terramate.stack.path.absolute}-${terramate.stack.name}-${terramate.stack.description}"),
-					),
+						expr("content", `<<EOT
+
+stack_path_abs=${terramate.stack.path.absolute}
+stack_path_rel=${terramate.stack.path.relative}
+stack_path_to_root=${terramate.stack.path.to_root}
+stack_path_basename=${terramate.stack.path.basename}
+stack_name=${terramate.stack.name}
+stack_description=${terramate.stack.description}
+EOT`,
+						)),
 				},
 			},
 			want: []result{
@@ -150,7 +158,14 @@ func TestLoadGenerateFiles(t *testing.T) {
 					condition: true,
 					file: genFile{
 						origin: "/stack/test.tm",
-						body:   "/stack-stack-",
+						body: `
+stack_path_abs=/stack
+stack_path_rel=stack
+stack_path_to_root=..
+stack_path_basename=stack
+stack_name=stack
+stack_description=
+`,
 					},
 				},
 			},

generate/genhcl/genhcl_test.go

@@ -859,9 +859,12 @@ func TestLoadGeneratedHCL(t *testing.T) {
 					add: generateHCL(
 						labels("root"),
 						content(
-							expr("stack_path_absolute", "terramate.stack.path.absolute"),
-							expr("stack_name", "terramate.stack.name"),
 							expr("stack_description", "terramate.stack.description"),
+							expr("stack_name", "terramate.stack.name"),
+							expr("stack_path_abs", "terramate.stack.path.absolute"),
+							expr("stack_path_basename", "terramate.stack.path.basename"),
+							expr("stack_path_rel", "terramate.stack.path.relative"),
+							expr("stack_path_to_root", "terramate.stack.path.to_root"),
 						),
 					),
 				},
@@ -875,7 +878,10 @@ func TestLoadGeneratedHCL(t *testing.T) {
 						body: hcldoc(
 							str("stack_description", ""),
 							str("stack_name", "stack"),
-							str("stack_path_absolute", "/stacks/stack"),
+							str("stack_path_abs", "/stacks/stack"),
+							str("stack_path_basename", "stack"),
+							str("stack_path_rel", "stacks/stack"),
+							str("stack_path_to_root", "../.."),
 						),
 					},
 				},

stack/eval.go

@@ -85,6 +85,9 @@ func (e *EvalCtx) HasNamespace(name string) bool {
 func metaToCtyMap(m Metadata) (map[string]cty.Value, error) {
 	path, err := eval.FromMapToObject(map[string]cty.Value{
 		"absolute": cty.StringVal(m.Path()),
+		"relative": cty.StringVal(m.RelPath()),
+		"basename": cty.StringVal(m.PathBase()),
+		"to_root":  cty.StringVal(m.RelPathToRoot()),
 	})
 	if err != nil {
 		return nil, errors.E(err, "creating stack.path obj")

stack/globals_test.go

@@ -255,28 +255,40 @@ func TestLoadGlobals(t *testing.T) {
 				{
 					path: "/stacks/stack-1",
 					add: globals(
-						expr("stack_path", "terramate.stack.path.absolute"),
+						expr("stack_path_abs", "terramate.stack.path.absolute"),
+						expr("stack_path_rel", "terramate.stack.path.relative"),
+						expr("stack_path_to_root", "terramate.stack.path.to_root"),
+						expr("stack_path_basename", "terramate.stack.path.basename"),
 						expr("stack_name", "terramate.stack.name"),
 						expr("stack_description", "terramate.stack.description"),
 					),
 				},
 				{
 					path: "/stacks/stack-2",
 					add: globals(
-						expr("stack_path", "terramate.stack.path.absolute"),
+						expr("stack_path_abs", "terramate.stack.path.absolute"),
+						expr("stack_path_rel", "terramate.stack.path.relative"),
+						expr("stack_path_to_root", "terramate.stack.path.to_root"),
+						expr("stack_path_basename", "terramate.stack.path.basename"),
 						expr("stack_name", "terramate.stack.name"),
 						expr("stack_description", "terramate.stack.description"),
 					),
 				},
 			},
 			want: map[string]*hclwrite.Block{
 				"/stacks/stack-1": globals(
-					str("stack_path", "/stacks/stack-1"),
+					str("stack_path_abs", "/stacks/stack-1"),
+					str("stack_path_rel", "stacks/stack-1"),
+					str("stack_path_to_root", "../.."),
+					str("stack_path_basename", "stack-1"),
 					str("stack_name", "stack-1"),
 					str("stack_description", ""),
 				),
 				"/stacks/stack-2": globals(
-					str("stack_path", "/stacks/stack-2"),
+					str("stack_path_abs", "/stacks/stack-2"),
+					str("stack_path_rel", "stacks/stack-2"),
+					str("stack_path_to_root", "../.."),
+					str("stack_path_basename", "stack-2"),
 					str("stack_name", "stack-2"),
 					str("stack_description", "someDescriptionStack2"),
 				),

stack/stack.go

@@ -35,6 +35,9 @@ type (
 		// path is the absolute path of the stack relative to project's root.
 		path string
 
+		// relPathToRoot is the relative path from the stack to root.
+		relPathToRoot string
+
 		// name of the stack.
 		name string
 
@@ -57,9 +60,18 @@ type (
 
 	// Metadata has all metadata loaded per stack
 	Metadata interface {
+		// Name of the stack.
 		Name() string
+		// Path is the absolute path of the stack (relative to project root).
 		Path() string
+		// RelPath is the relative path of the from root.
+		RelPath() string
+		// PathBase is the basename of the stack path.
+		PathBase() string
+		// Desc is the description of the stack (relative to project root).
 		Desc() string
+		// RelPathToRoot is the relative path from the stack to root.
+		RelPathToRoot() string
 	}
 )
 
@@ -70,14 +82,24 @@ func New(root string, cfg hcl.Config) S {
 		name = filepath.Base(cfg.AbsDir())
 	}
 
+	rel, err := filepath.Rel(cfg.AbsDir(), root)
+	if err != nil {
+		// This is an invariant on Terramate, stacks must always be
+		// inside the root dir.
+		panic(errors.E(
+			"No relative path from stack %q to root %q",
+			cfg.AbsDir(), root, err))
+	}
+
 	return S{
-		name:     name,
-		desc:     cfg.Stack.Description,
-		after:    cfg.Stack.After,
-		before:   cfg.Stack.Before,
-		wants:    cfg.Stack.Wants,
-		hostpath: cfg.AbsDir(),
-		path:     project.PrjAbsPath(root, cfg.AbsDir()),
+		name:          name,
+		desc:          cfg.Stack.Description,
+		after:         cfg.Stack.After,
+		before:        cfg.Stack.Before,
+		wants:         cfg.Stack.Wants,
+		hostpath:      cfg.AbsDir(),
+		path:          project.PrjAbsPath(root, cfg.AbsDir()),
+		relPathToRoot: rel,
 	}
 }
 
@@ -113,6 +135,15 @@ func (s S) String() string { return s.Path() }
 // Path returns the project's absolute path of stack.
 func (s S) Path() string { return s.path }
 
+// PathBase returns the base name of the stack path.
+func (s S) PathBase() string { return filepath.Base(s.path) }
+
+// RelPath returns the project's relative path of stack.
+func (s S) RelPath() string { return s.path[1:] }
+
+// RelPathToRoot returns the relative path from the stack to root.
+func (s S) RelPathToRoot() string { return s.relPathToRoot }
+
 // HostPath returns the file system absolute path of stack.
 func (s S) HostPath() string { return s.hostpath }