Add field-level metadata generation for mmv1 resources (#12792)

Author: roaks3

docs/content/reference/metadata.md

@@ -30,3 +30,11 @@ The version of the API used for this resource e.g., "v2".
 ### `api_resource_type_kind`
 
 The API "resource type kind" used for this resource e.g., "Function".
+
+### `fields`
+
+The list of fields used by this resource. Each field can contain the following attributes:
+
+- `field`: The name of the field in Terraform, including the path e.g., "build_config.source.storage_source.bucket"
+- `api_field`: The name of the field in the API, including the path e.g., "build_config.source.storage_source.bucket". Defaults to the value of `field`.
+- `provider_only`: If true, the field is only present in the provider. This primarily applies for virtual fields and url-only parameters. When set to true, `api_field` should be left empty, as it will be ignored. Default: `false`.

mmv1/api/resource.go

@@ -500,6 +500,12 @@ func (r Resource) UserParameters() []*Type {
 	})
 }
 
+func (r Resource) UserVirtualFields() []*Type {
+	return google.Reject(r.VirtualFields, func(p *Type) bool {
+		return p.Exclude
+	})
+}
+
 func (r Resource) ServiceVersion() string {
 	if r.CaiBaseUrl != "" {
 		return extractVersionFromBaseUrl(r.CaiBaseUrl)
@@ -615,6 +621,28 @@ func (r Resource) RootProperties() []*Type {
 	return props
 }
 
+// Returns a sorted list of all "leaf" properties, meaning properties that have
+// no children.
+func (r Resource) LeafProperties() []*Type {
+	types := r.AllNestedProperties(google.Concat(r.RootProperties(), r.UserVirtualFields()))
+
+	// Remove types that have children, because we only want "leaf" fields
+	types = slices.DeleteFunc(types, func(t *Type) bool {
+		nestedProperties := t.NestedProperties()
+		return len(nestedProperties) > 0
+	})
+
+	// Sort types by lineage
+	slices.SortFunc(types, func(a, b *Type) int {
+		if a.MetadataLineage() < b.MetadataLineage() {
+			return -1
+		}
+		return 1
+	})
+
+	return types
+}
+
 // Return the product-level async object, or the resource-specific one
 // if one exists.
 func (r Resource) GetAsync() *Async {

mmv1/api/resource_test.go

@@ -198,3 +198,120 @@ func TestResourceServiceVersion(t *testing.T) {
 		})
 	}
 }
+
+func TestLeafProperties(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		description string
+		obj         Resource
+		expected    Type
+	}{
+		{
+			description: "non-nested type",
+			obj: Resource{
+				BaseUrl: "test",
+				Properties: []*Type{
+					{
+						Name: "basic",
+						Type: "String",
+					},
+				},
+			},
+			expected: Type{
+				Name: "basic",
+			},
+		},
+		{
+			description: "nested type",
+			obj: Resource{
+				BaseUrl: "test",
+				Properties: []*Type{
+					{
+						Name: "root",
+						Type: "NestedObject",
+						Properties: []*Type{
+							{
+								Name: "foo",
+								Type: "NestedObject",
+								Properties: []*Type{
+									{
+										Name: "bars",
+										Type: "Array",
+										ItemType: &Type{
+											Type: "NestedObject",
+											Properties: []*Type{
+												{
+													Name: "fooBar",
+													Type: "String",
+												},
+											},
+										},
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+			expected: Type{
+				Name: "fooBar",
+			},
+		},
+		{
+			description: "nested virtual",
+			obj: Resource{
+				BaseUrl: "test",
+				VirtualFields: []*Type{
+					{
+						Name: "root",
+						Type: "NestedObject",
+						Properties: []*Type{
+							{
+								Name: "foo",
+								Type: "String",
+							},
+						},
+					},
+				},
+			},
+			expected: Type{
+				Name: "foo",
+			},
+		},
+		{
+			description: "nested param",
+			obj: Resource{
+				BaseUrl: "test",
+				Parameters: []*Type{
+					{
+						Name: "root",
+						Type: "NestedObject",
+						Properties: []*Type{
+							{
+								Name: "foo",
+								Type: "String",
+							},
+						},
+					},
+				},
+			},
+			expected: Type{
+				Name: "foo",
+			},
+		},
+	}
+
+	for _, tc := range cases {
+		tc := tc
+
+		t.Run(tc.description, func(t *testing.T) {
+			t.Parallel()
+
+			tc.obj.SetDefault(nil)
+			if got, want := tc.obj.LeafProperties(), tc.expected; got[0].Name != want.Name {
+				t.Errorf("expected %q to be %q", got[0].Name, want.Name)
+			}
+		})
+	}
+}

mmv1/api/type.go

@@ -399,6 +399,39 @@ func (t Type) Lineage() string {
 	return fmt.Sprintf("%s.%s", t.ParentMetadata.Lineage(), google.Underscore(t.Name))
 }
 
+// Returns a dot notation path to where the field is nested within the parent
+// object. eg: parent.meta.label.foo
+// This format is intended for resource metadata, to be used for connecting a Terraform
+// type with a corresponding API type.
+func (t Type) MetadataLineage() string {
+	if t.ParentMetadata == nil {
+		return google.Underscore(t.Name)
+	}
+
+	// Skip arrays because otherwise the array name will be included twice
+	if t.ParentMetadata.IsA("Array") {
+		return t.ParentMetadata.MetadataLineage()
+	}
+
+	return fmt.Sprintf("%s.%s", t.ParentMetadata.MetadataLineage(), google.Underscore(t.Name))
+}
+
+// Returns a dot notation path to where the field is nested within the parent
+// object. eg: parent.meta.label.foo
+// This format is intended for to represent an API type.
+func (t Type) MetadataApiLineage() string {
+	apiName := t.ApiName
+	if t.ParentMetadata == nil {
+		return google.Underscore(apiName)
+	}
+
+	if t.ParentMetadata.IsA("Array") {
+		return t.ParentMetadata.MetadataApiLineage()
+	}
+
+	return fmt.Sprintf("%s.%s", t.ParentMetadata.MetadataApiLineage(), google.Underscore(apiName))
+}
+
 // Returns the lineage in snake case
 func (t Type) LineageAsSnakeCase() string {
 	if t.ParentMetadata == nil {
@@ -1065,6 +1098,22 @@ func (t *Type) IsForceNew() bool {
 						!(parent.FlattenObject && t.IsA("KeyValueLabels"))))))
 }
 
+// Returns true if the type does not correspond to an API type
+func (t *Type) ProviderOnly() bool {
+	// These are special case fields created by the generator which have no API counterpart
+	if t.IsA("KeyValueEffectiveLabels") || t.IsA("KeyValueTerraformLabels") {
+		return true
+	}
+
+	if t.UrlParamOnly || t.ClientSide {
+		return true
+	}
+
+	// The type is provider-only if any of its ancestors are provider-only (it is inherited)
+	parent := t.Parent()
+	return parent != nil && parent.ProviderOnly()
+}
+
 // Returns an updated path for a given Terraform field path (e.g.
 // 'a_field', 'parent_field.0.child_name'). Returns nil if the property
 // is not included in the resource's properties and removes keys that have