feat: Add Automatic Validator Value Documentation (#6)

* feat: automatically append `stringvalidator.OneOf` values to string attribute descriptions.

* feat: `description_validator` now correctly parses `stringvalidator.OneOf` arguments with commas and appends possible values to string attribute descriptions.

* refactor: Replace regex-based parsing of `stringvalidator.OneOf` with `go/ast` for robust argument extraction.

Author: hanneshayashi

internal/convert/description_validator.go

@@ -0,0 +1,97 @@
+package convert
+
+import (
+	"fmt"
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"strconv"
+	"strings"
+)
+
+// AppendValidators parses stringvalidator.OneOf validators from the provided Validators object
+// and appends the possible values to the Description.
+//
+// It uses go/parser to safely extract values from the schema definition, handling
+// escaped quotes, commas, and other Go syntax correctly.
+func (d *Description) AppendValidators(v Validators) {
+	if d.description == nil {
+		empty := ""
+		d.description = &empty
+	}
+
+	for _, custom := range v.custom {
+		if custom.SchemaDefinition == "" {
+			continue
+		}
+
+		// Parse the expression
+		expr, err := parser.ParseExpr(custom.SchemaDefinition)
+		if err != nil {
+			// If we can't parse it, we can't extract values safely.
+			// Just skip description augmentation.
+			continue
+		}
+
+		// Inspect the AST to find OneOf calls
+		ast.Inspect(expr, func(n ast.Node) bool {
+			// We look for function calls
+			call, ok := n.(*ast.CallExpr)
+			if !ok {
+				return true
+			}
+
+			// Check if function is stringvalidator.OneOf
+			// This could be a SelectorExpr (pkg.Func)
+			sel, ok := call.Fun.(*ast.SelectorExpr)
+			if !ok {
+				return true
+			}
+
+			// Check package name
+			id, ok := sel.X.(*ast.Ident)
+			if !ok || id.Name != "stringvalidator" {
+				return true
+			}
+
+			// Check function name
+			if sel.Sel.Name != "OneOf" {
+				return true
+			}
+
+			// Extract arguments
+			var values []string
+			for _, arg := range call.Args {
+				// We expect string literals
+				lit, ok := arg.(*ast.BasicLit)
+				if !ok || lit.Kind != token.STRING {
+					continue
+				}
+
+				// Unquote the string value
+				val, err := strconv.Unquote(lit.Value)
+				if err != nil {
+					continue
+				}
+
+				values = append(values, fmt.Sprintf("`%s`", val))
+			}
+
+			if len(values) > 0 {
+				suffix := fmt.Sprintf("Possible values: %s", strings.Join(values, ", "))
+
+				// Avoid appending if already present
+				if strings.Contains(*d.description, suffix) {
+					return true
+				}
+
+				if *d.description != "" {
+					*d.description += "\n"
+				}
+				*d.description += suffix
+			}
+
+			return true
+		})
+	}
+}

internal/convert/description_validator_test.go

@@ -0,0 +1,101 @@
+package convert
+
+import (
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+	specschema "github.com/hashicorp/terraform-plugin-codegen-spec/schema"
+)
+
+func TestDescription_AppendValidators(t *testing.T) {
+	tests := []struct {
+		name         string
+		initialDesc  *string
+		validators   Validators
+		expectedDesc string
+	}{
+		{
+			name:        "Empty description, simple OneOf",
+			initialDesc: nil,
+			validators: NewValidators(ValidatorTypeString, specschema.CustomValidators{
+				{
+					SchemaDefinition: `stringvalidator.OneOf("a", "b")`,
+				},
+			}),
+			expectedDesc: "Possible values: `a`, `b`",
+		},
+		{
+			name:        "Existing description, simple OneOf",
+			initialDesc: stringPtr("Some description."),
+			validators: NewValidators(ValidatorTypeString, specschema.CustomValidators{
+				{
+					SchemaDefinition: `stringvalidator.OneOf("foo", "bar")`,
+				},
+			}),
+			expectedDesc: "Some description.\nPossible values: `foo`, `bar`",
+		},
+		{
+			name:        "Multiline OneOf",
+			initialDesc: stringPtr("Desc"),
+			validators: NewValidators(ValidatorTypeString, specschema.CustomValidators{
+				{
+					SchemaDefinition: `stringvalidator.OneOf(
+"val1",
+"val2",
+)`,
+				},
+			}),
+			expectedDesc: "Desc\nPossible values: `val1`, `val2`",
+		},
+		{
+			name:        "Commas inside quotes",
+			initialDesc: stringPtr("Desc"),
+			validators: NewValidators(ValidatorTypeString, specschema.CustomValidators{
+				{
+					SchemaDefinition: `stringvalidator.OneOf("a,b", "c")`,
+				},
+			}),
+			expectedDesc: "Desc\nPossible values: `a,b`, `c`",
+		},
+		{
+			name:        "No OneOf",
+			initialDesc: stringPtr("Desc"),
+			validators: NewValidators(ValidatorTypeString, specschema.CustomValidators{
+				{
+					SchemaDefinition: `stringvalidator.LengthAtLeast(1)`,
+				},
+			}),
+			expectedDesc: "Desc",
+		},
+		{
+			name:        "Multiple OneOf (should append both)",
+			initialDesc: stringPtr("Desc"),
+			validators: NewValidators(ValidatorTypeString, specschema.CustomValidators{
+				{
+					SchemaDefinition: `stringvalidator.OneOf("a", "b")`,
+				},
+				{
+					// This case is artificial, usually there's only one OneOf, but good to test behavior
+					SchemaDefinition: `stringvalidator.OneOf("c", "d")`,
+				},
+			}),
+			expectedDesc: "Desc\nPossible values: `a`, `b`\nPossible values: `c`, `d`",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			d := NewDescription(tt.initialDesc)
+			d.AppendValidators(tt.validators)
+
+			got := d.Description()
+			if diff := cmp.Diff(tt.expectedDesc, got); diff != "" {
+				t.Errorf("AppendValidators() mismatch (-want +got):\n%s", diff)
+			}
+		})
+	}
+}
+
+func stringPtr(s string) *string {
+	return &s
+}

internal/datasource/string_attribute.go

@@ -41,6 +41,8 @@ func NewGeneratorStringAttribute(name string, a *datasource.StringAttribute) (Ge
 
 	v := convert.NewValidators(convert.ValidatorTypeString, a.Validators.CustomValidators())
 
+	d.AppendValidators(v)
+
 	return GeneratorStringAttribute{
 		AssociatedExternalType:   schema.NewAssocExtType(a.AssociatedExternalType),
 		ComputedOptionalRequired: c,

internal/provider/string_attribute.go

@@ -41,6 +41,8 @@ func NewGeneratorStringAttribute(name string, a *provider.StringAttribute) (Gene
 
 	v := convert.NewValidators(convert.ValidatorTypeString, a.Validators.CustomValidators())
 
+	d.AppendValidators(v)
+
 	return GeneratorStringAttribute{
 		AssociatedExternalType: schema.NewAssocExtType(a.AssociatedExternalType),
 		OptionalRequired:       c,

internal/resource/string_attribute.go

@@ -47,6 +47,8 @@ func NewGeneratorStringAttribute(name string, a *resource.StringAttribute) (Gene
 
 	v := convert.NewValidators(convert.ValidatorTypeString, a.Validators.CustomValidators())
 
+	d.AppendValidators(v)
+
 	return GeneratorStringAttribute{
 		AssociatedExternalType:   generatorschema.NewAssocExtType(a.AssociatedExternalType),
 		ComputedOptionalRequired: c,