Add provider-defined version function (#592)

This PR adds a new provider-defined function `provider::apko::version()`
that returns version information for both the terraform-provider-apko
and the underlying apko package.

## Changes

- **New Function**: Added `provider::apko::version()` function that
returns an object with:
  - `provider_version`: The version of the terraform-provider-apko
  - `apko_version`: The version of the underlying apko package

- **Implementation**: 
  - Created `version_function.go` with the function implementation
- Updated provider to register the function in the `Functions()` method
  - Function uses runtime debug info to detect apko package version

- **Testing**:
  - Added acceptance test with `TF_ACC=1` support
  - Test verifies both provider and apko versions are returned correctly

- **Documentation**:
  - Created example usage in `examples/functions/apko_version/`

## Usage Example

```terraform
locals {
  version_info = provider::apko::version()
}

output "provider_version" {
  value = local.version_info.provider_version
}

output "apko_version" {
  value = local.version_info.apko_version
}
```

This provides a cleaner UX compared to data sources for simple version
queries.

---------

Signed-off-by: Jason Hall <[email protected]>

Author: imjasonh

docs/functions/version.md

@@ -0,0 +1,25 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "version function - terraform-provider-apko"
+subcategory: ""
+description: |-
+  Get version information
+---
+
+# function: version
+
+Returns version information for the terraform-provider-apko and the underlying apko package.
+
+
+
+## Signature
+
+<!-- signature generated by tfplugindocs -->
+```text
+version() object
+```
+
+## Arguments
+
+<!-- arguments generated by tfplugindocs -->
+

examples/functions/apko_version/main.tf

@@ -0,0 +1,26 @@
+terraform {
+  required_providers {
+    apko = {
+      source = "chainguard-dev/apko"
+    }
+  }
+}
+
+locals {
+  version_info = provider::apko::version()
+}
+
+output "provider_version" {
+  description = "The version of the terraform-provider-apko"
+  value       = local.version_info.provider_version
+}
+
+output "apko_version" {
+  description = "The version of the underlying apko package"
+  value       = local.version_info.apko_version
+}
+
+output "all_version_info" {
+  description = "Complete version information object"
+  value       = local.version_info
+}

internal/provider/provider.go

@@ -11,6 +11,7 @@ import (
 	"github.com/hashicorp/terraform-plugin-framework-validators/int64validator"
 	"github.com/hashicorp/terraform-plugin-framework-validators/stringvalidator"
 	"github.com/hashicorp/terraform-plugin-framework/datasource"
+	"github.com/hashicorp/terraform-plugin-framework/function"
 	"github.com/hashicorp/terraform-plugin-framework/provider"
 	"github.com/hashicorp/terraform-plugin-framework/provider/schema"
 	"github.com/hashicorp/terraform-plugin-framework/resource"
@@ -196,6 +197,14 @@ func (p *Provider) DataSources(ctx context.Context) []func() datasource.DataSour
 	}
 }
 
+func (p *Provider) Functions(ctx context.Context) []func() function.Function {
+	return []func() function.Function{
+		func() function.Function {
+			return NewVersionFunction(p.version)
+		},
+	}
+}
+
 func New(version string) func() provider.Provider {
 	return func() provider.Provider {
 		return &Provider{

internal/provider/version_function.go

@@ -0,0 +1,79 @@
+package provider
+
+import (
+	"context"
+	"runtime/debug"
+
+	"github.com/hashicorp/terraform-plugin-framework/attr"
+	"github.com/hashicorp/terraform-plugin-framework/function"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+)
+
+// Ensure provider defined types fully satisfy framework interfaces.
+var _ function.Function = &VersionFunction{}
+
+func NewVersionFunction(providerVersion string) function.Function {
+	return &VersionFunction{
+		providerVersion: providerVersion,
+	}
+}
+
+// VersionFunction defines the function implementation.
+type VersionFunction struct {
+	providerVersion string
+}
+
+func (f *VersionFunction) Metadata(ctx context.Context, req function.MetadataRequest, resp *function.MetadataResponse) {
+	resp.Name = "version"
+}
+
+func (f *VersionFunction) Definition(ctx context.Context, req function.DefinitionRequest, resp *function.DefinitionResponse) {
+	resp.Definition = function.Definition{
+		Summary:             "Get version information",
+		MarkdownDescription: "Returns version information for the terraform-provider-apko and the underlying apko package.",
+		Return: function.ObjectReturn{
+			AttributeTypes: map[string]attr.Type{
+				"provider_version": types.StringType,
+				"apko_version":     types.StringType,
+			},
+		},
+	}
+}
+
+func (f *VersionFunction) Run(ctx context.Context, req function.RunRequest, resp *function.RunResponse) {
+	// Use the provider version stored in the function
+	providerVersion := f.providerVersion
+	if providerVersion == "" {
+		providerVersion = "unknown"
+	}
+
+	// Get the apko version from build info
+	apkoVersion := "unknown"
+	if info, ok := debug.ReadBuildInfo(); ok {
+		for _, dep := range info.Deps {
+			if dep.Path == "chainguard.dev/apko" {
+				apkoVersion = dep.Version
+				break
+			}
+		}
+	}
+
+	// Create the return object
+	objectValue, diags := types.ObjectValue(
+		map[string]attr.Type{
+			"provider_version": types.StringType,
+			"apko_version":     types.StringType,
+		},
+		map[string]attr.Value{
+			"provider_version": types.StringValue(providerVersion),
+			"apko_version":     types.StringValue(apkoVersion),
+		},
+	)
+
+	if diags.HasError() {
+		resp.Error = function.FuncErrorFromDiags(ctx, diags)
+		return
+	}
+
+	resp.Error = function.ConcatFuncErrors(resp.Error, resp.Result.Set(ctx, objectValue))
+}

internal/provider/version_function_test.go

@@ -0,0 +1,35 @@
+package provider
+
+import (
+	"regexp"
+	"testing"
+
+	"github.com/hashicorp/terraform-plugin-testing/helper/resource"
+)
+
+func TestAccVersionFunction(t *testing.T) {
+	resource.UnitTest(t, resource.TestCase{
+		PreCheck:                 func() { testAccPreCheck(t) },
+		ProtoV6ProviderFactories: testAccProtoV6ProviderFactories,
+		Steps: []resource.TestStep{{
+			Config: `
+locals {
+  version_info = provider::apko::version()
+}
+
+output "provider_version" {
+  value = local.version_info.provider_version
+}
+
+output "apko_version" {
+  value = local.version_info.apko_version
+}`,
+			Check: resource.ComposeTestCheckFunc(
+				// Check that the provider version is "test" (as set in testAccProtoV6ProviderFactories)
+				resource.TestCheckOutput("provider_version", "test"),
+				// Check that apko version is not empty and looks like a version
+				resource.TestMatchOutput("apko_version", regexp.MustCompile(`^v\d+\.\d+\.\d+.*|unknown$`)),
+			),
+		}},
+	})
+}