path: Introduce package with initial tftypes.AttributePath abstraction (#390)

* path: Introduce package with initial tftypes.AttributePath abstraction

Reference: #81
Reference: #161
Reference: #172
Reference: #365

This introduces a native abstraction over terraform-plugin-go's `tftypes.AttributePath`, allowing the framework to own the implementation details and extend the functionality further. Provider developers will be closer to removing a direct dependency on terraform-plugin-go. This is a major breaking change, however it is necessary before 1.0 to prevent compatibility issues in the future.

This functionality is only intended to replace `tftypes.AttributePath` usage and not mess with the `tfsdk.Config`, `tfsdk.Plan`, and `tfsdk.State` type `tftypes.Value` data storage fields or their underlying data manipulation logic. This does leave the framework in an awkward half-state until those are further refactored (likely towards native `attr.Value`), but is done to try and reduce the review complexity of this initial migration. Additional followup changes will introduce the concept of path expressions, which will allow provider developers to match against multiple paths or reference parent paths in schema-based plan modifier and validation functionality.

To prevent import cycles between `attr` and `diag` packages due changing the `attr.TypeWithValidate` type `Validate` method signature from `Validate(context.Context, tftypes.Value, *tftypes.AttributePath) diag.Diagnostics` to `Validate(context.Context, tftypes.Value, path.Path) diag.Diagnostics`, the `TypeWithValidation` interface is moved a new `xattr` package underneath `attr` with Go and website documentation to direct provider developers to the other package. This will also solve a prior issue with trying to implement `TypeWithModifyPlan` support.

Naming and location of anything in this initial implementation can be adjusted as necessary.

Provider developers can migrate to the new path handling by replacing:

```go
tftypes.NewAttributePath().WithAttributeName("example")
```

With the equivalent:

```go
path.Root("example")
```

Then using the `(Path).At*` methods to extend the path definition instead of `(*tftypes.AttributePath).With*` methods:

| Current                  | New             |
| ------------------------ | --------------- |
| `WithAttributeName()`    | `AtName()`      |
| `WithElementKeyInt()`    | `AtListIndex()` |
| `WithElementKeyString()` | `AtMapKey()`    |
| `WithElementKeyValue()`  | `AtSetValue()`  |

Author: bflad

.changelog/390.txt

@@ -0,0 +1,35 @@
+```release-note:note
+Attribute path handling is now included in the `path` package of this Go module, rather than being dependent on low level terraform-plugin-go types. To migrate, `tftypes.NewAttributePath().WithAttributeName(` can be replaced with `path.Root(`, then subsequent step replacements are `WithAttributeName` to `AtName`, `WithElementKeyInt` to `AtListIndex`, `WithElementKeyString` to `AtMapKey`, and `WithElementKeyValue` to `AtSetValue`. For example, `tftypes.NewAttributePath().WithAttributeName("parent_attr").WithElementKeyInt(0).WithAttributeName("nested_attr")` should become `path.Root("parent_attr").AtListIndex(0).AtName("nested_attr")`.
+```
+
+```release-note:feature
+path: Introduced framework abstraction for attribute path handling
+```
+
+```release-note:breaking-change
+attr: The `TypeWithValidate` interface has been moved under the `attr/xattr` package and the `*tftypes.AttributePath` parameter is replaced with `path.Path`
+```
+
+```release-note:breaking-change
+diag: The `NewAttributeErrorDiagnostic` and `NewAttributeWarningDiagnostic` function `*tftypes.AttributePath` parameters are replaced with `path.Path`
+```
+
+```release-note:breaking-change
+diag: The `DiagnosticWithPath` interface `Path` method `*tftypes.AttributePath` return is replaced with `path.Path`
+```
+
+```release-note:breaking-change
+diag: The `Diagnostics` type `AddAttributeError` and `AddAttributeWarning` method `*tftypes.AttributePath` parameters are replaced with `path.Path`
+```
+
+```release-note:breaking-change
+tfsdk: The `Config`, `Plan`, and `State` types `GetAttribute` and `SetAttribute` methods `*tftypes.AttributePath` parameters are replaced with `path.Path`
+```
+
+```release-note:breaking-change
+tfsdk: The `ModifyAttributePlanRequest`, `ModifyResourcePlanResponse`, and `ValidateAttributeRequest` type `AttributePath *tftypes.AttributePath` fields are replaced with `AttributePath path.Path`
+```
+
+```release-note:breaking-change
+tfsdk: The `RequiresReplaceIf` and `ResourceImportStatePassthroughID` function `*tftypes.AttributePath` parameters are replaced with `path.Path`
+```

attr/doc.go

@@ -0,0 +1,4 @@
+// Package attr contains type and value interfaces for core framework and
+// provider-defined data types. The underlying xattr package contains
+// additional interfaces for advanced type functionality.
+package attr

attr/type.go

@@ -3,13 +3,15 @@ package attr
 import (
 	"context"
 
-	"github.com/hashicorp/terraform-plugin-framework/diag"
 	"github.com/hashicorp/terraform-plugin-go/tftypes"
 )
 
 // Type defines an interface for describing a kind of attribute. Types are
 // collections of constraints and behaviors such that they can be reused on
 // multiple attributes easily.
+//
+// Refer also to the xattr package, which contains additional extensions for
+// Type, such as validation.
 type Type interface {
 	// TerraformType returns the tftypes.Type that should be used to
 	// represent this type. This constrains what user input will be
@@ -74,18 +76,6 @@ type TypeWithElementTypes interface {
 	ElementTypes() []Type
 }
 
-// TypeWithValidate extends the Type interface to include a Validate method,
-// used to bundle consistent validation logic with the Type.
-type TypeWithValidate interface {
-	Type
-
-	// Validate returns any warnings or errors about the value that is
-	// being used to populate the Type. It is generally used to check the
-	// data format and ensure that it complies with the requirements of the
-	// Type.
-	Validate(context.Context, tftypes.Value, *tftypes.AttributePath) diag.Diagnostics
-}
-
 // TypeWithPlaintextDescription extends the Type interface to include a
 // Description method, used to bundle extra information to include in attribute
 // descriptions with the Type. It expects the description to be written as

attr/xattr/doc.go

@@ -0,0 +1,3 @@
+// Package xattr contains additional interfaces for attr types. This package
+// is separate from the core attr package to prevent import cycles.
+package xattr

attr/xattr/type.go

@@ -0,0 +1,22 @@
+package xattr
+
+import (
+	"context"
+
+	"github.com/hashicorp/terraform-plugin-framework/attr"
+	"github.com/hashicorp/terraform-plugin-framework/diag"
+	"github.com/hashicorp/terraform-plugin-framework/path"
+	"github.com/hashicorp/terraform-plugin-go/tftypes"
+)
+
+// TypeWithValidate extends the attr.Type interface to include a Validate
+// method, used to bundle consistent validation logic with the Type.
+type TypeWithValidate interface {
+	attr.Type
+
+	// Validate returns any warnings or errors about the value that is
+	// being used to populate the Type. It is generally used to check the
+	// data format and ensure that it complies with the requirements of the
+	// Type.
+	Validate(context.Context, tftypes.Value, path.Path) diag.Diagnostics
+}

diag/attribute_error_diagnostic.go

@@ -1,11 +1,11 @@
 package diag
 
 import (
-	"github.com/hashicorp/terraform-plugin-go/tftypes"
+	"github.com/hashicorp/terraform-plugin-framework/path"
 )
 
 // NewAttributeErrorDiagnostic returns a new error severity diagnostic with the given summary, detail, and path.
-func NewAttributeErrorDiagnostic(path *tftypes.AttributePath, summary string, detail string) DiagnosticWithPath {
+func NewAttributeErrorDiagnostic(path path.Path, summary string, detail string) DiagnosticWithPath {
 	return withPath{
 		Diagnostic: NewErrorDiagnostic(summary, detail),
 		path:       path,

diag/attribute_warning_diagnostic.go

@@ -1,11 +1,11 @@
 package diag
 
 import (
-	"github.com/hashicorp/terraform-plugin-go/tftypes"
+	"github.com/hashicorp/terraform-plugin-framework/path"
 )
 
 // NewAttributeWarningDiagnostic returns a new warning severity diagnostic with the given summary, detail, and path.
-func NewAttributeWarningDiagnostic(path *tftypes.AttributePath, summary string, detail string) DiagnosticWithPath {
+func NewAttributeWarningDiagnostic(path path.Path, summary string, detail string) DiagnosticWithPath {
 	return withPath{
 		Diagnostic: NewWarningDiagnostic(summary, detail),
 		path:       path,

diag/diagnostic.go

@@ -1,8 +1,6 @@
 package diag
 
-import (
-	"github.com/hashicorp/terraform-plugin-go/tftypes"
-)
+import "github.com/hashicorp/terraform-plugin-framework/path"
 
 // Diagnostic is an interface for providing enhanced feedback.
 //
@@ -48,5 +46,5 @@ type DiagnosticWithPath interface {
 	//
 	// If present, this enables the display of source configuration context for
 	// supporting implementations such as Terraform CLI commands.
-	Path() *tftypes.AttributePath
+	Path() path.Path
 }

diag/diagnostics.go

@@ -1,7 +1,7 @@
 package diag
 
 import (
-	"github.com/hashicorp/terraform-plugin-go/tftypes"
+	"github.com/hashicorp/terraform-plugin-framework/path"
 )
 
 // Diagnostics represents a collection of diagnostics.
@@ -11,12 +11,12 @@ import (
 type Diagnostics []Diagnostic
 
 // AddAttributeError adds a generic attribute error diagnostic to the collection.
-func (diags *Diagnostics) AddAttributeError(path *tftypes.AttributePath, summary string, detail string) {
+func (diags *Diagnostics) AddAttributeError(path path.Path, summary string, detail string) {
 	diags.Append(NewAttributeErrorDiagnostic(path, summary, detail))
 }
 
 // AddAttributeWarning adds a generic attribute warning diagnostic to the collection.
-func (diags *Diagnostics) AddAttributeWarning(path *tftypes.AttributePath, summary string, detail string) {
+func (diags *Diagnostics) AddAttributeWarning(path path.Path, summary string, detail string) {
 	diags.Append(NewAttributeWarningDiagnostic(path, summary, detail))
 }