function: Replace usage of diagnostics with function errors during ex…

…ecution of provider-defined functions (#925)

* Replacing function.RunResponse diagnostics with error

* Adding custom FunctionError

* Adding custom FunctionErrors

* Removing unneeded equateErrors gocmp option

* Switching to using convenience functions for adding errors to FunctionErrors

* Add copyright headers

* Refactor to use Error() method on function errors when converting to tfprotov5/6.FunctionError

* Adding documentation and testing for fwerrors types

* Formatting errors during conversion to tfprotov<5|6>.FunctionError

* Removing argument error and argument warning diagnostics

* Renaming field name for FunctionErrors from Error to Errors

* Modifying documentation to reflect that executing the Run() method of a provider-defined function returns FunctionErrors

* Remove references to AddArgumentError and AddArgumentWarning from diagnostics documentation

* Removing fwerror package and moving FunctionError to function package

* Refactoring to replace FunctionErrors slice with single FunctionError

* Bumping terraform-plugin-go to v0.22.0

* Removing unneeded DiagnosticWithFunctionArgument interface and implementation

* Altering function signature of ConcatFuncErrors

* Removing HasError method

* Updating docs

* Updates following code review

* Adding changelog entries

* Fix naming

* Update website/docs/plugin/framework/functions/errors.mdx

Co-authored-by: Austin Valle <austinvalle@gmail.com>

* Formatting

* Updates following code review

---------

Co-authored-by: Austin Valle <austinvalle@gmail.com>

.changes/unreleased/BREAKING CHANGES-20240227-112229.yaml

@@ -0,0 +1,5 @@
+kind: BREAKING CHANGES
+body: 'function: Altered the `RunResponse` type, replacing `Diagnostics` with `FuncError`'
+time: 2024-02-27T11:22:29.392126Z
+custom:
+  Issue: "925"

.changes/unreleased/BREAKING CHANGES-20240227-113128.yaml

@@ -0,0 +1,8 @@
+kind: BREAKING CHANGES
+body: 'diag: Removed `DiagnosticWithFunctionArgument` interface. Removed 
+  `NewArgumentErrorDiagnostic()`, `NewArgumentWarningDiagnostic()` and 
+  `WithFunctionArgument()` functions. Removed `AddArgumentError()` and
+  `AddArgumentWarning()` methods from `Diagnostics`.'
+time: 2024-02-27T11:31:28.09588Z
+custom:
+  Issue: "925"

.changes/unreleased/ENHANCEMENTS-20240227-112448.yaml

@@ -0,0 +1,5 @@
+kind: ENHANCEMENTS
+body: 'function: Added `FuncError` type, required for `RunResponse`'
+time: 2024-02-27T11:24:48.711538Z
+custom:
+  Issue: "925"

.changes/unreleased/ENHANCEMENTS-20240227-112633.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'function: Added `NewFuncError()` and `NewArgumentFuncError()` functions, which
+  create a `FuncError`'
+time: 2024-02-27T11:26:33.856219Z
+custom:
+  Issue: "925"

.changes/unreleased/ENHANCEMENTS-20240227-112752.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'function: Added `ConcatFuncErrors()` and `FuncErrorFromDiags()` helper functions
+  for use when working with `FuncError`'
+time: 2024-02-27T11:27:52.288519Z
+custom:
+  Issue: "925"

diag/diagnostic.go

@@ -38,21 +38,6 @@ type Diagnostic interface {
 	Equal(Diagnostic) bool
 }
 
-// DiagnosticWithFunctionArgument is a diagnostic associated with a
-// function argument.
-//
-// This information is used to display contextual source configuration to
-// practitioners.
-type DiagnosticWithFunctionArgument interface {
-	Diagnostic
-
-	// FunctionArgument points to a specific function argument position.
-	//
-	// If present, this enables the display of source configuration context for
-	// supporting implementations such as Terraform CLI commands.
-	FunctionArgument() int
-}
-
 // DiagnosticWithPath is a diagnostic associated with an attribute path.
 //
 // This attribute information is used to display contextual source configuration

diag/diagnostics.go

@@ -13,18 +13,6 @@ import (
 // or consistent.
 type Diagnostics []Diagnostic
 
-// AddArgumentError adds a generic function argument error diagnostic to the
-// collection.
-func (diags *Diagnostics) AddArgumentError(position int, summary string, detail string) {
-	diags.Append(NewArgumentErrorDiagnostic(position, summary, detail))
-}
-
-// AddArgumentWarning adds a function argument warning diagnostic to the
-// collection.
-func (diags *Diagnostics) AddArgumentWarning(position int, summary string, detail string) {
-	diags.Append(NewArgumentWarningDiagnostic(position, summary, detail))
-}
-
 // AddAttributeError adds a generic attribute error diagnostic to the collection.
 func (diags *Diagnostics) AddAttributeError(path path.Path, summary string, detail string) {
 	diags.Append(NewAttributeErrorDiagnostic(path, summary, detail))

diag/diagnostics_test.go

@@ -12,130 +12,6 @@ import (
 	"github.com/hashicorp/terraform-plugin-framework/path"
 )
 
-func TestDiagnosticsAddArgumentError(t *testing.T) {
-	t.Parallel()
-
-	testCases := map[string]struct {
-		diags    diag.Diagnostics
-		position int
-		summary  string
-		detail   string
-		expected diag.Diagnostics
-	}{
-		"nil-add": {
-			diags:    nil,
-			position: 0,
-			summary:  "one summary",
-			detail:   "one detail",
-			expected: diag.Diagnostics{
-				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
-			},
-		},
-		"add": {
-			diags: diag.Diagnostics{
-				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
-				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
-			},
-			position: 0,
-			summary:  "three summary",
-			detail:   "three detail",
-			expected: diag.Diagnostics{
-				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
-				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
-				diag.NewArgumentErrorDiagnostic(0, "three summary", "three detail"),
-			},
-		},
-		"duplicate": {
-			diags: diag.Diagnostics{
-				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
-				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
-			},
-			position: 0,
-			summary:  "one summary",
-			detail:   "one detail",
-			expected: diag.Diagnostics{
-				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
-				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
-			},
-		},
-	}
-
-	for name, tc := range testCases {
-		name, tc := name, tc
-		t.Run(name, func(t *testing.T) {
-			t.Parallel()
-
-			tc.diags.AddArgumentError(tc.position, tc.summary, tc.detail)
-
-			if diff := cmp.Diff(tc.diags, tc.expected); diff != "" {
-				t.Errorf("Unexpected response (+wanted, -got): %s", diff)
-			}
-		})
-	}
-}
-
-func TestDiagnosticsAddArgumentWarning(t *testing.T) {
-	t.Parallel()
-
-	testCases := map[string]struct {
-		diags    diag.Diagnostics
-		position int
-		summary  string
-		detail   string
-		expected diag.Diagnostics
-	}{
-		"nil-add": {
-			diags:    nil,
-			position: 0,
-			summary:  "one summary",
-			detail:   "one detail",
-			expected: diag.Diagnostics{
-				diag.NewArgumentWarningDiagnostic(0, "one summary", "one detail"),
-			},
-		},
-		"add": {
-			diags: diag.Diagnostics{
-				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
-				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
-			},
-			position: 0,
-			summary:  "three summary",
-			detail:   "three detail",
-			expected: diag.Diagnostics{
-				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
-				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
-				diag.NewArgumentWarningDiagnostic(0, "three summary", "three detail"),
-			},
-		},
-		"duplicate": {
-			diags: diag.Diagnostics{
-				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
-				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
-			},
-			position: 0,
-			summary:  "two summary",
-			detail:   "two detail",
-			expected: diag.Diagnostics{
-				diag.NewArgumentErrorDiagnostic(0, "one summary", "one detail"),
-				diag.NewArgumentWarningDiagnostic(0, "two summary", "two detail"),
-			},
-		},
-	}
-
-	for name, tc := range testCases {
-		name, tc := name, tc
-		t.Run(name, func(t *testing.T) {
-			t.Parallel()
-
-			tc.diags.AddArgumentWarning(tc.position, tc.summary, tc.detail)
-
-			if diff := cmp.Diff(tc.diags, tc.expected); diff != "" {
-				t.Errorf("Unexpected response (+wanted, -got): %s", diff)
-			}
-		})
-	}
-}
-
 func TestDiagnosticsAddAttributeError(t *testing.T) {
 	t.Parallel()
 

diag/doc.go

@@ -5,4 +5,7 @@
 // feedback mechanism for providers. It is designed for display in Terraform
 // user interfaces, rather than logging based feedback, which is generally
 // saved to a file for later inspection and troubleshooting.
+//
+// Practitioner feedback for provider defined functions is provided by the
+// [function.FuncError] type, rather than the [diag.Diagnostic] type.
 package diag