feat: add deprecated schema (#81)

Author: azrod

.changelog/80.txt

@@ -0,0 +1,3 @@
+```release-note:feature
+`Deprecated` - Added a new DeprecatedResource Struct in base schema.
+```

deprecated.go

@@ -3,7 +3,8 @@ package superschema
 import "fmt"
 
 const (
-	warningDeprecated = "\n\n ~> **Attribute deprecated** "
+	warningAttributeDeprecated = "\n\n ~> **Attribute deprecated** "
+	warningResourceDeprecated  = "\n\n !> **Resource deprecated** "
 )
 
 // Deprecated is a struct to describe a deprecated attribute.
@@ -64,7 +65,7 @@ func (d *Deprecated) computeDeprecatedDocumentation() string {
 		return d.MarkdownDeprecationMessage
 	}
 
-	message := warningDeprecated
+	message := warningAttributeDeprecated
 
 	switch {
 	case d.Renamed:
@@ -108,3 +109,110 @@ func (d *Deprecated) GetDeprecationMessage() string {
 func (d *Deprecated) GetMarkdownDeprecationMessage() string {
 	return d.computeDeprecatedDocumentation()
 }
+
+// DeprecatedResource is a struct to describe a deprecated resource or data source.
+type DeprecatedResource struct {
+	// DeprecationMessage is the message to display in the CLI when the user
+	// attempts to use the deprecated resource.
+	// This field is required.
+	DeprecationMessage string
+
+	// MarkdownDeprecationMessage is the message to display in the Documentation portal
+	// when the user attempts to use the deprecated attribute.
+	// This field is required if ComputeMarkdownDeprecationMessage is false.
+	MarkdownDeprecationMessage string
+
+	// ComputeMarkdownDeprecationMessage is a flag to indicate whether the MarkdownDeprecationMessage
+	// should be computed from the parameters of the Deprecated struct.
+	ComputeMarkdownDeprecationMessage bool
+
+	// Renamed is a flag to indicate whether the resource or datasource has been renamed.
+	// Removed is a flag to indicate whether the resource or datasource has been removed.
+	// One of these fields must be true.
+	Renamed, Removed bool
+
+	// TargetResourceName is the name of the resource that replaces the deprecated resource or data source.
+	// These fields are required if the resource or data source has been renamed and computeMarkdownDeprecationMessage is true.
+	TargetResourceName string
+
+	// TargetRelease is the release version in which the resource or datasource was deprecated. (e.g. v1.0.0).
+	// This field is Required.
+	TargetRelease string
+	// LinkToIssue is the link to the GitHub issue that describes the deprecation.
+	// This field is optional.
+	LinkToIssue string
+	// LinkToMigrationGuide is the link to the actual resource documentation.
+	// This field is optional.
+	LinkToMigrationGuide string
+	// LinkToNewResourceDoc is the link to the terraform documentation for the resource that replaces the deprecated attribute.
+	// This field is optional.
+	LinkToNewResourceDoc string
+	// LinkToMilestone is the link to the GitHub milestone that describes the release in which the attribute was deprecated.
+	// This field is optional.
+	LinkToMilestone string
+}
+
+func (d *DeprecatedResource) computeDeprecatedDocumentation(isResource bool) string {
+
+	if (!d.ComputeMarkdownDeprecationMessage && d.MarkdownDeprecationMessage == "") || (d.Renamed && d.TargetResourceName == "" && d.ComputeMarkdownDeprecationMessage) || d.TargetRelease == "" {
+		return ""
+	}
+
+	if d.Removed && d.Renamed {
+		return ""
+	}
+
+	ressOrData := func() string {
+		if isResource {
+			return "resource"
+		}
+		return "data source"
+	}()
+
+	message := warningResourceDeprecated + d.MarkdownDeprecationMessage
+
+	if d.ComputeMarkdownDeprecationMessage {
+		switch {
+		case d.Renamed:
+			if d.TargetResourceName == "" {
+				return ""
+			}
+			if d.LinkToNewResourceDoc != "" {
+				message += fmt.Sprintf("The %s has renamed to [`%s`](%s)", ressOrData, d.TargetResourceName, d.LinkToNewResourceDoc)
+			} else {
+				message += fmt.Sprintf("The %s has renamed to `%s`", ressOrData, d.TargetResourceName)
+			}
+		case d.Removed:
+			message += fmt.Sprintf("The %s has been removed", ressOrData)
+		default:
+			return ""
+		}
+	}
+
+	if d.LinkToMilestone != "" {
+		message += fmt.Sprintf(", it will be removed in the version [`%s`](%s) of the provider", d.TargetRelease, d.LinkToMilestone)
+	} else {
+		message += fmt.Sprintf(", it will be removed in the version `%s` of the provider", d.TargetRelease)
+	}
+
+	if d.LinkToIssue != "" {
+		message += fmt.Sprintf(". See the [GitHub issue](%s) for more information.", d.LinkToIssue)
+	}
+
+	return addEndDot(message)
+}
+
+// GetDeprecationMessage returns the deprecation message for the attribute.
+func (d *DeprecatedResource) GetDeprecationMessage() string {
+
+	if d.LinkToMigrationGuide != "" {
+		return fmt.Sprintf("%s. See the migration guide(%s) for more information.", d.DeprecationMessage, d.LinkToMigrationGuide)
+	}
+
+	return d.DeprecationMessage
+}
+
+// GetMarkdownDeprecationMessage returns the markdown deprecation message for the attribute.
+func (d *DeprecatedResource) GetMarkdownDeprecationMessage(isResource bool) string {
+	return d.computeDeprecatedDocumentation(isResource)
+}

schema.go

@@ -35,7 +35,6 @@ const (
 )
 
 type Schema struct {
-	Deprecated Deprecated
 	Common     SchemaDetails
 	Resource   SchemaDetails
 	DataSource SchemaDetails
@@ -44,25 +43,34 @@ type Schema struct {
 
 type SchemaDetails struct {
 	MarkdownDescription string
-	DeprecationMessage  string
+	Deprecated          DeprecatedResource
+
+	// Deprecated: Use Deprecated instead.
+	DeprecationMessage string
 }
 
 func (s Schema) GetResource(ctx context.Context) schemaR.Schema {
+
 	if s.Resource.MarkdownDescription != "" {
 		s.Common.MarkdownDescription = addToDescription(s.Common.MarkdownDescription, s.Resource.MarkdownDescription)
 	}
 
+	// * Deprecated is a struct that contains the deprecation message and the target resource name.
 	if s.Resource.DeprecationMessage != "" {
-		s.Common.DeprecationMessage = addToDescription(s.Common.MarkdownDescription, s.Resource.DeprecationMessage)
+		s.Common.DeprecationMessage = s.Resource.DeprecationMessage
+	}
+
+	if s.Resource.Deprecated != (DeprecatedResource{}) {
+		s.Common.Deprecated = s.Resource.Deprecated
 	}
 
-	if s.Deprecated.DeprecationMessage != "" {
-		s.Common.DeprecationMessage = addToDescription(s.Common.MarkdownDescription, s.Deprecated.DeprecationMessage)
+	if s.Common.Deprecated != (DeprecatedResource{}) {
+		s.Common.MarkdownDescription = addToDescription(s.Common.MarkdownDescription, s.Common.Deprecated.GetMarkdownDeprecationMessage(true))
 	}
 
 	return schemaR.Schema{
 		MarkdownDescription: s.Common.MarkdownDescription,
-		DeprecationMessage:  s.Common.DeprecationMessage,
+		DeprecationMessage:  s.Common.Deprecated.GetDeprecationMessage(),
 		Attributes:          s.Attributes.process(ctx, resourceT).(map[string]schemaR.Attribute),
 	}
 }
@@ -72,17 +80,22 @@ func (s Schema) GetDataSource(ctx context.Context) schemaD.Schema {
 		s.Common.MarkdownDescription = addToDescription(s.Common.MarkdownDescription, s.DataSource.MarkdownDescription)
 	}
 
+	// * Deprecated is a struct that contains the deprecation message and the target resource name.
 	if s.DataSource.DeprecationMessage != "" {
-		s.Common.DeprecationMessage = addToDescription(s.Common.MarkdownDescription, s.DataSource.DeprecationMessage)
+		s.Common.DeprecationMessage = s.DataSource.DeprecationMessage
+	}
+
+	if s.DataSource.Deprecated != (DeprecatedResource{}) {
+		s.Common.Deprecated = s.DataSource.Deprecated
 	}
 
-	if s.Deprecated.DeprecationMessage != "" {
-		s.Common.DeprecationMessage = addToDescription(s.Common.MarkdownDescription, s.Deprecated.DeprecationMessage)
+	if s.Common.Deprecated != (DeprecatedResource{}) {
+		s.Common.MarkdownDescription = addToDescription(s.Common.MarkdownDescription, s.Common.Deprecated.GetMarkdownDeprecationMessage(true))
 	}
 
 	return schemaD.Schema{
 		MarkdownDescription: s.Common.MarkdownDescription,
-		DeprecationMessage:  s.Common.DeprecationMessage,
+		DeprecationMessage:  s.Common.Deprecated.GetDeprecationMessage(),
 		Attributes:          s.Attributes.process(ctx, dataSourceT).(map[string]schemaD.Attribute),
 	}
 }