Add deprecation surpression tracking

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/deprecation/deprecation.go

@@ -0,0 +1,96 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: BUSL-1.1
+
+package deprecation
+
+import (
+	"sync"
+
+	"github.com/hashicorp/hcl/v2"
+	"github.com/hashicorp/terraform/internal/addrs"
+	"github.com/hashicorp/terraform/internal/lang/marks"
+	"github.com/hashicorp/terraform/internal/tfdiags"
+	"github.com/zclconf/go-cty/cty"
+)
+
+// Deprecations keeps track of meta-information related to deprecation, e.g. which module calls
+// suppress deprecation warnings.
+type Deprecations struct {
+	// Must hold this lock when accessing all fields after this one.
+	mu sync.Mutex
+
+	suppressedModules addrs.Set[addrs.Module]
+}
+
+func NewDeprecations() *Deprecations {
+	return &Deprecations{
+		suppressedModules: addrs.MakeSet[addrs.Module](),
+	}
+}
+
+func (d *Deprecations) SuppressModuleCallDeprecation(addr addrs.Module) {
+	d.mu.Lock()
+	defer d.mu.Unlock()
+
+	d.suppressedModules.Add(addr)
+}
+
+func (d *Deprecations) Validate(value cty.Value, module addrs.Module, rng *hcl.Range) (cty.Value, tfdiags.Diagnostics) {
+	var diags tfdiags.Diagnostics
+	deprecationMarks := marks.GetDeprecationMarks(value)
+	if len(deprecationMarks) == 0 {
+		return value, diags
+	}
+
+	notDeprecatedValue := marks.RemoveDeprecationMarks(value)
+
+	// Check if we need to suppress deprecation warnings for this module call.
+	if d.IsModuleCallDeprecationSuppressed(module) {
+		return notDeprecatedValue, diags
+	}
+
+	for _, depMark := range deprecationMarks {
+		diags = diags.Append(&hcl.Diagnostic{
+			Severity: hcl.DiagWarning,
+			Summary:  "Deprecated value used",
+			Detail:   depMark.Message,
+			Subject:  rng,
+		})
+	}
+
+	return notDeprecatedValue, diags
+}
+
+func (d *Deprecations) ValidateAsConfig(value cty.Value, module addrs.Module) tfdiags.Diagnostics {
+	var diags tfdiags.Diagnostics
+	_, pvms := value.UnmarkDeepWithPaths()
+
+	if len(pvms) == 0 || d.IsModuleCallDeprecationSuppressed(module) {
+		return diags
+	}
+
+	for _, pvm := range pvms {
+		for m := range pvm.Marks {
+			if depMark, ok := m.(marks.DeprecationMark); ok {
+				diags = diags.Append(
+					tfdiags.AttributeValue(
+						tfdiags.Warning,
+						"Deprecated value used",
+						depMark.Message,
+						pvm.Path,
+					),
+				)
+			}
+		}
+	}
+	return diags
+}
+
+func (d *Deprecations) IsModuleCallDeprecationSuppressed(addr addrs.Module) bool {
+	for _, mod := range d.suppressedModules {
+		if mod.TargetContains(addr) {
+			return true
+		}
+	}
+	return false
+}

internal/lang/marks/marks.go

@@ -17,16 +17,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 +49,33 @@ func Contains(val cty.Value, mark valueMark) bool {
 	return ret
 }
 
+// FilterDeprecationMarks returns all deprecation marks present in the given
+// cty.ValueMarks.
+func FilterDeprecationMarks(marks cty.ValueMarks) []DeprecationMark {
+	depMarks := []DeprecationMark{}
+	for mark := range marks {
+		if d, ok := mark.(DeprecationMark); ok {
+			depMarks = append(depMarks, d)
+		}
+	}
+	return depMarks
+}
+
+// GetDeprecationMarks returns all deprecation marks present on the given
+// cty.Value.
+func GetDeprecationMarks(val cty.Value) []DeprecationMark {
+	_, marks := val.UnmarkDeep()
+	return FilterDeprecationMarks(marks)
+}
+
+// RemoveDeprecationMarks returns a copy of the given cty.Value with all
+// deprecation marks removed.
+func RemoveDeprecationMarks(val cty.Value) cty.Value {
+	newVal, pvms := val.UnmarkDeepWithPaths()
+	otherPvms := RemoveAll(pvms, Deprecation)
+	return newVal.MarkWithPaths(otherPvms)
+}
+
 // Sensitive indicates that this value is marked as sensitive in the context of
 // Terraform.
 const Sensitive = valueMark("Sensitive")
@@ -51,3 +92,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")
+
+// DeprecationMark is a mark indicating that a value is deprecated. It is a struct
+// rather than a primitive type so that it can carry a deprecation message.
+type DeprecationMark struct {
+	Message string
+}
+
+func (d DeprecationMark) GoString() string {
+	return "marks.deprecation<" + d.Message + ">"
+}
+
+// Empty deprecation mark for usage in marks.Has / Contains / etc
+var Deprecation = NewDeprecation("")
+
+func NewDeprecation(message string) DeprecationMark {
+	return DeprecationMark{
+		Message: message,
+	}
+}

internal/lang/marks/marks_test.go

@@ -0,0 +1,41 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: BUSL-1.1
+
+package marks
+
+import (
+	"testing"
+
+	"github.com/zclconf/go-cty/cty"
+)
+
+func TestDeprecationMark(t *testing.T) {
+	deprecation := cty.StringVal("OldValue").Mark(NewDeprecation("This is outdated"))
+
+	composite := cty.ObjectVal(map[string]cty.Value{
+		"foo": deprecation,
+		"bar": deprecation,
+		"baz": cty.StringVal("Not deprecated"),
+	})
+
+	if !deprecation.IsMarked() {
+		t.Errorf("Expected deprecation to be marked")
+	}
+	if composite.IsMarked() {
+		t.Errorf("Expected composite to be marked")
+	}
+
+	if !Has(deprecation, Deprecation) {
+		t.Errorf("Expected deprecation to be marked with Deprecation")
+	}
+	if Has(composite, Deprecation) {
+		t.Errorf("Expected composite to be marked with Deprecation")
+	}
+
+	if !Contains(deprecation, Deprecation) {
+		t.Errorf("Expected deprecation 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)
 		}