Module Output Deprecation using marks

internal/command/jsonstate/state.go

@@ -620,6 +620,7 @@ func SensitiveAsBool(val cty.Value) cty.Value {
 func unmarkValueForMarshaling(v cty.Value) (unmarkedV cty.Value, sensitivePaths []cty.Path, err error) {
 	val, pvms := v.UnmarkDeepWithPaths()
 	sensitivePaths, otherMarks := marks.PathsWithMark(pvms, marks.Sensitive)
+	_, otherMarks = marks.PathsWithMark(otherMarks, marks.Deprecation)
 	if len(otherMarks) != 0 {
 		return cty.NilVal, nil, fmt.Errorf(
 			"%s: cannot serialize value marked as %#v for inclusion in a state snapshot (this is a bug in Terraform)",

internal/configs/named_values.go

@@ -345,12 +345,14 @@ type Output struct {
 	DependsOn   []hcl.Traversal
 	Sensitive   bool
 	Ephemeral   bool
+	Deprecated  string
 
 	Preconditions []*CheckRule
 
 	DescriptionSet bool
 	SensitiveSet   bool
 	EphemeralSet   bool
+	DeprecatedSet  bool
 
 	DeclRange hcl.Range
 }
@@ -402,6 +404,12 @@ func decodeOutputBlock(block *hcl.Block, override bool) (*Output, hcl.Diagnostic
 		o.EphemeralSet = true
 	}
 
+	if attr, exists := content.Attributes["deprecated"]; exists {
+		valDiags := gohcl.DecodeExpression(attr.Expr, nil, &o.Deprecated)
+		diags = append(diags, valDiags...)
+		o.DeprecatedSet = true
+	}
+
 	if attr, exists := content.Attributes["depends_on"]; exists {
 		deps, depsDiags := DecodeDependsOn(attr)
 		diags = append(diags, depsDiags...)
@@ -525,6 +533,9 @@ var outputBlockSchema = &hcl.BodySchema{
 		{
 			Name: "ephemeral",
 		},
+		{
+			Name: "deprecated",
+		},
 	},
 	Blocks: []hcl.BlockHeaderSchema{
 		{Type: "precondition"},

internal/configs/named_values_test.go

@@ -48,3 +48,30 @@ func TestVariableInvalidDefault(t *testing.T) {
 		}
 	}
 }
+
+func TestOutputDeprecation(t *testing.T) {
+	src := `
+		output "foo" {
+			value = "bar"
+			deprecated = "This output is deprecated"
+		}
+	`
+
+	hclF, diags := hclsyntax.ParseConfig([]byte(src), "test.tf", hcl.InitialPos)
+	if diags.HasErrors() {
+		t.Fatal(diags.Error())
+	}
+
+	b, diags := parseConfigFile(hclF.Body, nil, false, false)
+	if diags.HasErrors() {
+		t.Fatalf("unexpected error: %q", diags)
+	}
+
+	if !b.Outputs[0].DeprecatedSet {
+		t.Fatalf("expected output to be deprecated")
+	}
+
+	if b.Outputs[0].Deprecated != "This output is deprecated" {
+		t.Fatalf("expected output to have deprecation message")
+	}
+}

internal/lang/checks.go

@@ -93,6 +93,17 @@ You can correct this by removing references to ephemeral values, or by using the
 		return "", diags
 	}
 
+	if depMarks := marks.FilterDeprecationMarks(valMarks); len(depMarks) > 0 {
+		for _, depMark := range depMarks {
+			diags = diags.Append(&hcl.Diagnostic{
+				Severity: hcl.DiagWarning,
+				Summary:  "Deprecated value used",
+				Detail:   depMark.Message,
+				Subject:  expr.Range().Ptr(),
+			})
+		}
+	}
+
 	// NOTE: We've discarded any other marks the string might have been carrying,
 	// aside from the sensitive mark.
 

internal/lang/marks/marks.go

@@ -4,6 +4,7 @@
 package marks
 
 import (
+	"github.com/hashicorp/hcl/v2"
 	"github.com/zclconf/go-cty/cty"
 )
 
@@ -17,16 +18,30 @@ func (m valueMark) GoString() string {
 }
 
 // Has returns true if and only if the cty.Value has the given mark.
-func Has(val cty.Value, mark valueMark) bool {
-	return val.HasMark(mark)
+func Has(val cty.Value, mark interface{}) bool {
+	switch m := mark.(type) {
+	case valueMark:
+		return val.HasMark(m)
+
+	// For value marks Has returns true if a mark of the type is present
+	case DeprecationMark:
+		for depMark := range val.Marks() {
+			if _, ok := depMark.(DeprecationMark); ok {
+				return true
+			}
+		}
+		return false
+	default:
+		panic("Unknown mark type")
+	}
 }
 
 // Contains returns true if the cty.Value or any any value within it contains
 // the given mark.
-func Contains(val cty.Value, mark valueMark) bool {
+func Contains(val cty.Value, mark interface{}) bool {
 	ret := false
 	cty.Walk(val, func(_ cty.Path, v cty.Value) (bool, error) {
-		if v.HasMark(mark) {
+		if Has(v, mark) {
 			ret = true
 			return false, nil
 		}
@@ -35,6 +50,33 @@ func Contains(val cty.Value, mark valueMark) bool {
 	return ret
 }
 
+func FilterDeprecationMarks(marks cty.ValueMarks) []DeprecationMark {
+	depMarks := []DeprecationMark{}
+	for mark := range marks {
+		if d, ok := mark.(DeprecationMark); ok {
+			depMarks = append(depMarks, d)
+		}
+	}
+	return depMarks
+}
+
+func GetDeprecationMarks(val cty.Value) []DeprecationMark {
+	_, marks := val.UnmarkDeep()
+	return FilterDeprecationMarks(marks)
+
+}
+
+func RemoveDeprecationMarks(val cty.Value) cty.Value {
+	newVal, marks := val.Unmark()
+	for mark := range marks {
+		if _, ok := mark.(DeprecationMark); ok {
+			continue
+		}
+		newVal = newVal.Mark(mark)
+	}
+	return newVal
+}
+
 // Sensitive indicates that this value is marked as sensitive in the context of
 // Terraform.
 const Sensitive = valueMark("Sensitive")
@@ -51,3 +93,22 @@ const Ephemeral = valueMark("Ephemeral")
 // another value's type. This is part of the implementation of the console-only
 // `type` function.
 const TypeType = valueMark("TypeType")
+
+type DeprecationMark struct {
+	Message string
+	Origin  *hcl.Range
+}
+
+func (d DeprecationMark) GoString() string {
+	return "marks.deprecation<" + d.Message + ">"
+}
+
+// Empty deprecation mark for usage in marks.Has / Contains / etc
+var Deprecation = NewDeprecation("", nil)
+
+func NewDeprecation(message string, origin *hcl.Range) DeprecationMark {
+	return DeprecationMark{
+		Message: message,
+		Origin:  origin,
+	}
+}

internal/lang/marks/marks_test.go

@@ -0,0 +1,52 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: BUSL-1.1
+
+package marks
+
+import (
+	"testing"
+
+	"github.com/hashicorp/hcl/v2"
+	"github.com/zclconf/go-cty/cty"
+)
+
+func TestDeprecationMark(t *testing.T) {
+	deprecationWithoutRange := cty.StringVal("OldValue").Mark(NewDeprecation("This is outdated", nil))
+	deprecationWithRange := cty.StringVal("OldValue").Mark(NewDeprecation("This is outdated", &hcl.Range{Filename: "example.tf", Start: hcl.Pos{Line: 1, Column: 1}, End: hcl.Pos{Line: 1, Column: 10}}))
+
+	composite := cty.ObjectVal(map[string]cty.Value{
+		"foo": deprecationWithRange,
+		"bar": deprecationWithoutRange,
+		"baz": cty.StringVal("Not deprecated"),
+	})
+
+	if !deprecationWithRange.IsMarked() {
+		t.Errorf("Expected deprecationWithRange to be marked")
+	}
+	if !deprecationWithoutRange.IsMarked() {
+		t.Errorf("Expected deprecationWithoutRange to be marked")
+	}
+	if composite.IsMarked() {
+		t.Errorf("Expected composite to be marked")
+	}
+
+	if !Has(deprecationWithRange, Deprecation) {
+		t.Errorf("Expected deprecationWithRange to be marked with Deprecation")
+	}
+	if !Has(deprecationWithoutRange, Deprecation) {
+		t.Errorf("Expected deprecationWithoutRange to be marked with Deprecation")
+	}
+	if Has(composite, Deprecation) {
+		t.Errorf("Expected composite to be marked with Deprecation")
+	}
+
+	if !Contains(deprecationWithRange, Deprecation) {
+		t.Errorf("Expected deprecationWithRange to be contain Deprecation Mark")
+	}
+	if !Contains(deprecationWithoutRange, Deprecation) {
+		t.Errorf("Expected deprecationWithoutRange to be contain Deprecation Mark")
+	}
+	if !Contains(composite, Deprecation) {
+		t.Errorf("Expected composite to be contain Deprecation Mark")
+	}
+}

internal/lang/marks/paths.go

@@ -4,6 +4,7 @@
 package marks
 
 import (
+	"fmt"
 	"sort"
 	"strings"
 
@@ -28,16 +29,36 @@ func PathsWithMark(pvms []cty.PathValueMarks, wantMark any) (withWanted []cty.Pa
 	}
 
 	for _, pvm := range pvms {
-		if _, ok := pvm.Marks[wantMark]; ok {
+		pathHasMark := false
+		pathHasOtherMarks := false
+		for mark := range pvm.Marks {
+			switch wantMark.(type) {
+			case valueMark, string:
+				if mark == wantMark {
+					pathHasMark = true
+				} else {
+					pathHasOtherMarks = true
+				}
+
+			// For data marks we check if a mark of the type exists
+			case DeprecationMark:
+				if _, ok := mark.(DeprecationMark); ok {
+					pathHasMark = true
+				} else {
+					pathHasOtherMarks = true
+				}
+
+			default:
+				panic(fmt.Sprintf("unexpected mark type %T", wantMark))
+			}
+		}
+
+		if pathHasMark {
 			withWanted = append(withWanted, pvm.Path)
 		}
 
-		for mark := range pvm.Marks {
-			if mark != wantMark {
-				withOthers = append(withOthers, pvm)
-				// only add a path with unwanted marks a single time
-				break
-			}
+		if pathHasOtherMarks {
+			withOthers = append(withOthers, pvm)
 		}
 	}
 
@@ -57,7 +78,21 @@ func RemoveAll(pvms []cty.PathValueMarks, remove any) []cty.PathValueMarks {
 	var res []cty.PathValueMarks
 
 	for _, pvm := range pvms {
-		delete(pvm.Marks, remove)
+		switch remove.(type) {
+		case valueMark, string:
+			delete(pvm.Marks, remove)
+
+		case DeprecationMark:
+			// We want to delete all marks of this type
+			for mark := range pvm.Marks {
+				if _, ok := mark.(DeprecationMark); ok {
+					delete(pvm.Marks, mark)
+				}
+			}
+
+		default:
+			panic(fmt.Sprintf("unexpected mark type %T", remove))
+		}
 		if len(pvm.Marks) > 0 {
 			res = append(res, pvm)
 		}