cty: Various new mark-inspecting helpers

I've seen variants of each of these hand-written many times in callers, so
it's well past time to bring them upstream to better support the common
marks-related usage patterns that have emerged downstream.

Author: apparentlymart

CHANGELOG.md

@@ -10,6 +10,9 @@
 
   This new function allows inspecting and transforming marks with far less overhead, by creating new values only for parts of a structure that actually need to change and by reusing (rather than recreating) the "payloads" of the values being modified when we know that only the marks have changed.
 
+- `cty.ValueMarksOfType` and `cty.ValueMarksOfTypeDeep` make it easier to use type-based rather than value-based mark schemes, where different values of a common type are used to track a specific kind of relationship with multiple external values.
+- `cty.Value.HasMarkDeep` provides a "deep" version of the existing `cty.Value.HasMark`, searching throughout a possibly-nested structure for any values that have the given mark.
+
 # 1.16.4 (August 20, 2025)
 
 * `cty.UnknownAsNull` now accepts marked values and preserves the given marks in its result. Previously it had no direct support for marks and so would either panic or return incorrect results when given marked values.

cty/marks.go

@@ -2,6 +2,8 @@ package cty
 
 import (
 	"fmt"
+	"io"
+	"iter"
 	"strings"
 )
 
@@ -119,6 +121,60 @@ func (val Value) HasMark(mark interface{}) bool {
 	return false
 }
 
+// HasMarkDeep is like [HasMark] but also searches any values nested inside
+// the given value.
+func (val Value) HasMarkDeep(mark interface{}) bool {
+	found := false
+	Walk(val, func(p Path, v Value) (bool, error) {
+		if v.HasMark(mark) {
+			found = true
+			return false, io.EOF // arbitrary error just to stop the Walk early
+		}
+		return true, nil
+	})
+	return found
+}
+
+// ValueMarksOfType returns an iterable sequence of any marks directly
+// associated with the given value that can be type-asserted to the given
+// type.
+func ValueMarksOfType[T any](v Value) iter.Seq[T] {
+	return func(yield func(T) bool) {
+		yieldValueMarksOfType(v, yield)
+	}
+}
+
+// ValueMarksOfTypeDeep is like [ValueMarksOfType] but also visits any values
+// nested inside the given value.
+//
+// The same value may be produced multiple times if multiple nested values are
+// marked with it.
+func ValueMarksOfTypeDeep[T any](v Value) iter.Seq[T] {
+	return func(yield func(T) bool) {
+		Walk(v, func(p Path, v Value) (bool, error) {
+			if !yieldValueMarksOfType(v, yield) {
+				return false, io.EOF // arbitrary error just to stop the Walk early
+			}
+			return true, nil
+		})
+	}
+}
+
+func yieldValueMarksOfType[T any](v Value, yield func(T) bool) bool {
+	mr, ok := v.v.(marker)
+	if !ok {
+		return true
+	}
+	for mark := range mr.marks {
+		if v, ok := mark.(T); ok {
+			if !yield(v) {
+				return false
+			}
+		}
+	}
+	return true
+}
+
 // ContainsMarked returns true if the receiving value or any value within it
 // is marked.
 //

cty/marks_test.go

@@ -2,7 +2,10 @@ package cty
 
 import (
 	"fmt"
+	"slices"
 	"testing"
+
+	"github.com/google/go-cmp/cmp"
 )
 
 func TestContainsMarked(t *testing.T) {
@@ -507,3 +510,57 @@ func TestReapplyMarks(t *testing.T) {
 		t.Fatalf("Value changed re-applying marks\n1st: %#v\n2nd: %#v\n", first, second)
 	}
 }
+
+func TestHasMarkDeep(t *testing.T) {
+	obj := ObjectVal(map[string]Value{
+		"nested": ObjectVal(map[string]Value{
+			"marked": True.Mark("boop"),
+		}),
+	})
+	if !obj.HasMarkDeep("boop") {
+		t.Error("did not find nested mark")
+	}
+}
+
+func TestValueMarksOfType(t *testing.T) {
+	t.Run("shallow", func(t *testing.T) {
+		obj := ObjectVal(map[string]Value{
+			"nested": ObjectVal(map[string]Value{
+				"marked 1": True.Mark("nested"),
+				"marked 2": True.Mark(2),
+			}),
+		}).Mark("shallow").Mark(2)
+		got := slices.Collect(ValueMarksOfType[string](obj))
+		want := []string{"shallow"}
+		if diff := cmp.Diff(want, got); diff != "" {
+			t.Error("wrong result\n" + diff)
+		}
+	})
+	t.Run("only nested", func(t *testing.T) {
+		obj := ObjectVal(map[string]Value{
+			"nested": ObjectVal(map[string]Value{
+				"marked 1": True.Mark("nested"),
+				"marked 2": True.Mark(2),
+			}),
+		})
+		got := slices.Collect(ValueMarksOfType[string](obj))
+		want := []string(nil)
+		if diff := cmp.Diff(want, got); diff != "" {
+			t.Error("wrong result\n" + diff)
+		}
+	})
+}
+
+func TestValueMarksOfTypeDeep(t *testing.T) {
+	obj := ObjectVal(map[string]Value{
+		"nested": ObjectVal(map[string]Value{
+			"marked 1": True.Mark("boop"),
+			"marked 2": True.Mark(2),
+		}),
+	})
+	got := slices.Collect(ValueMarksOfTypeDeep[string](obj))
+	want := []string{"boop"}
+	if diff := cmp.Diff(want, got); diff != "" {
+		t.Error("wrong result\n" + diff)
+	}
+}