function: Initial provider defined functions implementation

.changes/unreleased/ENHANCEMENTS-20231211-125057.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'diag: Added `NewArgumentErrorDiagnostic()` and `NewArgumentWarningDiagnostic()`
+  functions, which create diagnostics with the function argument position set'
+time: 2023-12-11T12:50:57.570179-05:00
+custom:
+  Issue: "889"

.changes/unreleased/ENHANCEMENTS-20231211-125151.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'provider: Added `ProviderWithFunctions` interface for implementing provider
+  defined functions'
+time: 2023-12-11T12:51:51.441373-05:00
+custom:
+  Issue: "889"

.changes/unreleased/ENHANCEMENTS-20231211-125843.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'diag: Added `(Diagnostics).AddArgumentError()` and `(Diagnostics).AddArgumentWarning()`
+  methods for appending function argument diagnostics'
+time: 2023-12-11T12:58:43.277177-05:00
+custom:
+  Issue: "889"

.changes/unreleased/FEATURES-20231211-125122.yaml

@@ -0,0 +1,5 @@
+kind: FEATURES
+body: 'function: New package for implementing provider defined functions'
+time: 2023-12-11T12:51:22.409392-05:00
+custom:
+  Issue: "889"

.changes/unreleased/NOTES-20231214-082931.yaml

@@ -0,0 +1,6 @@
+kind: NOTES
+body: Provider-defined function support is in technical preview and offered without
+  compatibility promises until Terraform 1.8 is generally available.
+time: 2023-12-14T08:29:31.188561-05:00
+custom:
+  Issue: "889"

diag/argument_error_diagnostic.go

@@ -0,0 +1,13 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package diag
+
+// NewArgumentErrorDiagnostic returns a new error severity diagnostic with the
+// given summary, detail, and function argument.
+func NewArgumentErrorDiagnostic(functionArgument int, summary string, detail string) DiagnosticWithFunctionArgument {
+	return withFunctionArgument{
+		Diagnostic:       NewErrorDiagnostic(summary, detail),
+		functionArgument: functionArgument,
+	}
+}

diag/argument_warning_diagnostic.go

@@ -0,0 +1,13 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package diag
+
+// NewArgumentWarningDiagnostic returns a new warning severity diagnostic with
+// the given summary, detail, and function argument.
+func NewArgumentWarningDiagnostic(functionArgument int, summary string, detail string) DiagnosticWithFunctionArgument {
+	return withFunctionArgument{
+		Diagnostic:       NewWarningDiagnostic(summary, detail),
+		functionArgument: functionArgument,
+	}
+}

diag/diagnostic.go

@@ -38,6 +38,21 @@ 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,6 +13,18 @@ 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,6 +12,130 @@ 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/with_function_argument.go

@@ -0,0 +1,54 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
+package diag
+
+var _ DiagnosticWithFunctionArgument = withFunctionArgument{}
+
+// withFunctionArgument wraps a diagnostic with function argument information.
+type withFunctionArgument struct {
+	Diagnostic
+
+	functionArgument int
+}
+
+// Equal returns true if the other diagnostic is wholly equivalent.
+func (d withFunctionArgument) Equal(other Diagnostic) bool {
+	o, ok := other.(withFunctionArgument)
+
+	if !ok {
+		return false
+	}
+
+	if d.functionArgument != o.functionArgument {
+		return false
+	}
+
+	if d.Diagnostic == nil {
+		return d.Diagnostic == o.Diagnostic
+	}
+
+	return d.Diagnostic.Equal(o.Diagnostic)
+}
+
+// FunctionArgument returns the diagnostic function argument.
+func (d withFunctionArgument) FunctionArgument() int {
+	return d.functionArgument
+}
+
+// WithFunctionArgument wraps a diagnostic with function argument information
+// or overwrites the function argument.
+func WithFunctionArgument(functionArgument int, d Diagnostic) DiagnosticWithFunctionArgument {
+	wp, ok := d.(withFunctionArgument)
+
+	if !ok {
+		return withFunctionArgument{
+			Diagnostic:       d,
+			functionArgument: functionArgument,
+		}
+	}
+
+	wp.functionArgument = functionArgument
+
+	return wp
+}