Add description override codegenerator option (#4456)

Use this option to override the Subnet IPConfigurations field to explain
that it is removed if it crosses 2000 entries.

Author: matthchr

v2/api/network/v1api20201101/virtual_networks_subnet_types_gen.go

@@ -895,6 +895,9 @@ status:
 #     Set to 'false' to disable our heuristics if a property is incorrectly 
 #     identified as an ARM reference.
 #
+# $description: <string>
+#     Overrides the property description with the provided value.
+#
 # $importConfigMapMode: <optional|required>
 #     Specifies that the property can be imported from a config map.
 #     Optional: The property may be specified as string or imported from a config map.
@@ -3104,6 +3107,9 @@ objectModelConfiguration:
       VirtualNetworks_Subnet: # TODO: There must always be a parent and child in the same API version. See https://github.com/Azure/azure-service-operator/issues/3002
         $exportAs: VirtualNetworksSubnet
         $supportedFrom: v2.0.0-alpha.1
+      VirtualNetworksSubnet_STATUS:
+        IpConfigurations:
+          $description: "An array of references to the network interface IP configurations using subnet. This field is not included if there are more than 2000 entries."
       VirtualNetworks_VirtualNetworkPeering:
         $exportAs: VirtualNetworksVirtualNetworkPeering
         $supportedFrom: v2.0.0-alpha.1
@@ -3409,6 +3415,9 @@ objectModelConfiguration:
       VirtualNetworks_Subnet: # TODO: There must always be a parent and child in the same API version. See https://github.com/Azure/azure-service-operator/issues/3002
         $exportAs: VirtualNetworksSubnet
         $supportedFrom: v2.11.0
+      VirtualNetworksSubnet_STATUS:
+        IpConfigurations:
+          $description: "An array of references to the network interface IP configurations using subnet. This field is not included if there are more than 2000 entries."
       VirtualNetworks_VirtualNetworkPeering:
         $exportAs: VirtualNetworksVirtualNetworkPeering
         $supportedFrom: v2.11.0

v2/api/network/v1api20240301/virtual_networks_subnet_types_gen.go

@@ -103,7 +103,6 @@ require (
 	github.com/prometheus/common v0.55.0 // indirect
 	github.com/prometheus/procfs v0.15.1 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
-	github.com/rotisserie/eris v0.5.4 // indirect
 	github.com/samber/lo v1.47.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/stoewer/go-strcase v1.3.0 // indirect

v2/azure-arm.yaml

@@ -199,6 +199,7 @@ func createAllPipelineStages(
 		pipeline.StripUnreferencedTypeDefinitions(),
 
 		pipeline.RenameProperties(configuration.ObjectModelConfiguration),
+		pipeline.OverrideDescriptions(configuration), // After flatten and rename to make easier to use
 		pipeline.AddStatusConditions(idFactory).UsedFor(pipeline.ARMTarget),
 
 		pipeline.AddOperatorSpec(configuration, idFactory).UsedFor(pipeline.ARMTarget),

v2/cmd/asoctl/go.mod

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ * Licensed under the MIT license.
+ */
+
+package pipeline
+
+import (
+	"context"
+
+	"github.com/pkg/errors"
+
+	"github.com/Azure/azure-service-operator/v2/tools/generator/internal/astmodel"
+	"github.com/Azure/azure-service-operator/v2/tools/generator/internal/config"
+)
+
+// OverrideDescriptionsStageId is the unique identifier for this pipeline stage
+const OverrideDescriptionsStageId = "overrideDescriptions"
+
+// OverrideDescriptions overrides the specified property descriptions
+func OverrideDescriptions(configuration *config.Configuration) *Stage {
+	stage := NewStage(
+		OverrideDescriptionsStageId,
+		"Applies the configured description overrides",
+		func(ctx context.Context, state *State) (*State, error) {
+			visitor := createDescriptionOverrideVisitor(configuration)
+			result := make(astmodel.TypeDefinitionSet)
+			for _, def := range state.Definitions() {
+				newDef, err := visitor.VisitDefinition(def, def.Name())
+				if err != nil {
+					return nil, err
+				}
+
+				result.Add(newDef)
+			}
+
+			if err := configuration.ObjectModelConfiguration.Description.VerifyConsumed(); err != nil {
+				return nil, errors.Wrap(err, "verifying description augmentation")
+			}
+
+			return state.WithDefinitions(result), nil
+		})
+
+	stage.RequiresPrerequisiteStages(FlattenPropertiesStageId, RenamePropertiesStageID)
+	return stage
+}
+
+func createDescriptionOverrideVisitor(
+	configuration *config.Configuration,
+) astmodel.TypeVisitor[astmodel.InternalTypeName] {
+	visitor := astmodel.TypeVisitorBuilder[astmodel.InternalTypeName]{
+		VisitObjectType: func(
+			this *astmodel.TypeVisitor[astmodel.InternalTypeName],
+			it *astmodel.ObjectType,
+			ctx astmodel.InternalTypeName,
+		) (astmodel.Type, error) {
+			result := it
+			name := ctx
+			for _, prop := range it.Properties().AsSlice() {
+				// If the property has an overridden description, use it
+				description, ok := configuration.ObjectModelConfiguration.Description.Lookup(name, prop.PropertyName())
+				if !ok {
+					continue
+				}
+				prop = prop.WithDescription(description)
+				result = result.WithProperty(prop)
+			}
+
+			return result, nil
+		},
+	}
+
+	return visitor.Build()
+}

v2/tools/generator/internal/codegen/code_generator.go

@@ -47,6 +47,7 @@ applyKubernetesResourceInterface                  azure      Add the KubernetesR
 flattenProperties                                            Apply flattening to properties marked for flattening
 stripUnreferenced                                            Strip unreferenced types
 renameProperties                                             Rename properties
+overrideDescriptions                                         Applies the configured description overrides
 addStatusConditions                               azure      Add the property 'Conditions' to all status types and implements genruntime.Conditioner on all resources
 addOperatorSpec                                   azure      Adds the property 'OperatorSpec' to all Spec types that require it
 addKubernetesExporter                             azure      Adds the KubernetesExporter interface to resources that need it

v2/tools/generator/internal/codegen/pipeline/override_descriptions.go

@@ -37,6 +37,7 @@ addSerializationTypeTag                                 Adds a property tag to p
 flattenProperties                                       Apply flattening to properties marked for flattening
 stripUnreferenced                                       Strip unreferenced types
 renameProperties                                        Rename properties
+overrideDescriptions                                    Applies the configured description overrides
 addCrossplaneOwnerProperties                 crossplane Add the 3-tuple of (xName, xNameRef, xNameSelector) for each owning resource
 addCrossplaneForProviderProperty             crossplane Add a 'ForProvider' property on every spec
 addCrossplaneAtProviderProperty              crossplane Add an 'AtProvider' property on every status

v2/tools/generator/internal/codegen/testdata/TestGolden_NewARMCodeGeneratorFromConfigCreatesRightPipeline.golden

@@ -39,6 +39,7 @@ applyKubernetesResourceInterface           azure      Add the KubernetesResource
 flattenProperties                                     Apply flattening to properties marked for flattening
 stripUnused                                           Strip unused types for test
 renameProperties                                      Rename properties
+overrideDescriptions                                  Applies the configured description overrides
 addStatusConditions                        azure      Add the property 'Conditions' to all status types and implements genruntime.Conditioner on all resources
 addOperatorSpec                            azure      Adds the property 'OperatorSpec' to all Spec types that require it
 addKubernetesExporter                      azure      Adds the KubernetesExporter interface to resources that need it

v2/tools/generator/internal/codegen/testdata/TestGolden_NewCrossplaneCodeGeneratorFromConfigCreatesRightPipeline.golden

@@ -50,6 +50,7 @@ type ObjectModelConfiguration struct {
 
 	// Property access fields here (alphabetical, please)
 	ARMReference                   propertyAccess[bool]
+	Description                    propertyAccess[string]
 	ImportConfigMapMode            propertyAccess[ImportConfigMapMode]
 	IsSecret                       propertyAccess[bool]
 	PropertyNameInNextVersion      propertyAccess[string]
@@ -110,6 +111,8 @@ func NewObjectModelConfiguration() *ObjectModelConfiguration {
 	// Initialize property access fields here (alphabetical, please)
 	result.ARMReference = makePropertyAccess[bool](
 		result, func(c *PropertyConfiguration) *configurable[bool] { return &c.ARMReference })
+	result.Description = makePropertyAccess[string](
+		result, func(c *PropertyConfiguration) *configurable[string] { return &c.Description })
 	result.ImportConfigMapMode = makePropertyAccess[ImportConfigMapMode](
 		result, func(c *PropertyConfiguration) *configurable[ImportConfigMapMode] { return &c.ImportConfigMapMode })
 	result.IsSecret = makePropertyAccess[bool](

v2/tools/generator/internal/codegen/testdata/TestGolden_NewTestCodeGeneratorCreatesRightPipeline.golden

@@ -24,6 +24,7 @@ type PropertyConfiguration struct {
 	name string
 	// Configurable properties here (alphabetical, please)
 	ARMReference                   configurable[bool]                // Specify whether this property is an ARM reference
+	Description                    configurable[string]              // Specify a description override for this property
 	ImportConfigMapMode            configurable[ImportConfigMapMode] // The config map mode
 	IsSecret                       configurable[bool]                // Specify whether this property is a secret
 	NameInNextVersion              configurable[string]              // Name this property has in the next version
@@ -42,6 +43,7 @@ const (
 // Tags used in yaml files to specify configurable properties. Alphabetical please.
 const (
 	armReferenceTag                   = "$armReference"                   // Bool specifying whether a property is an ARM reference
+	descriptionTag                    = "$description"                    // String overriding the properties default description
 	exportAsConfigMapPropertyNameTag  = "$exportAsConfigMapPropertyName"  // String specifying the name of the property set to export this property as a config map.
 	importConfigMapModeTag            = "$importConfigMapMode"            // string specifying the ImportConfigMapMode mode
 	isSecretTag                       = "$isSecret"                       // Bool specifying whether a property contains a secret
@@ -56,6 +58,7 @@ func NewPropertyConfiguration(name string) *PropertyConfiguration {
 		name: name,
 		// Initialize configurable properties here (alphabetical, please)
 		ARMReference:                   makeConfigurable[bool](armReferenceTag, scope),
+		Description:                    makeConfigurable[string](descriptionTag, scope),
 		ImportConfigMapMode:            makeConfigurable[ImportConfigMapMode](importConfigMapModeTag, scope),
 		IsSecret:                       makeConfigurable[bool](isSecretTag, scope),
 		NameInNextVersion:              makeConfigurable[string](nameInNextVersionTag, scope),
@@ -165,6 +168,18 @@ func (pc *PropertyConfiguration) UnmarshalYAML(value *yaml.Node) error {
 			continue
 		}
 
+		// description: string
+		if strings.EqualFold(lastId, descriptionTag) && c.Kind == yaml.ScalarNode {
+			var description string
+			err := c.Decode(&description)
+			if err != nil {
+				return eris.Wrapf(err, "decoding %s", descriptionTag)
+			}
+
+			pc.Description.Set(description)
+			continue
+		}
+
 		// No handler for this value, return an error
 		return eris.Errorf(
 			"property configuration, unexpected yaml value %s: %s (line %d col %d)", lastId, c.Value, c.Line, c.Column)