Introduce introduce helper to add placeholders to all flags (#509)

Adds `setAllFlagPlaceholders` helper, to be used in #510.

This helper allows you to annotate all local flags with a placeholder in a single function call.
It panics if:
- You try to annotate a flag that does not exist
- You do not annotate all flags

These panics happen during command _construction_. So this validation is caught at dev / test time. Not intended to be a real runtime check.

Commit 2 of 3 for GROW-2511

GitOrigin-RevId: 216bdbdc51fa7c4ddf144905f9962243f2b910e5

Author: davidharting

cmd/flagusages.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/charmbracelet/lipgloss"
 	"github.com/render-oss/cli/pkg/style"
+	"github.com/spf13/cobra"
 	"github.com/spf13/pflag"
 )
 
@@ -29,9 +30,47 @@ func setAnnotationBestEffort(flags *pflag.FlagSet, flagName, key string, values
 }
 
 // setFlagPlaceholder applies help-output placeholder metadata to a flag.
-// Returns true when the placeholder was applied successfully, false otherwise.
-func setFlagPlaceholder(flags *pflag.FlagSet, flagName, placeholder string) bool {
-	return setAnnotationBestEffort(flags, flagName, flagPlaceholderAnnotation, []string{placeholder})
+// Panics when called with an invalid flag name so command wiring mistakes (e.g., wrong flag name) fail loudly in dev and test
+func setFlagPlaceholder(flags *pflag.FlagSet, flagName, placeholder string) {
+	if flags == nil {
+		panic("setFlagPlaceholder called with nil flag set")
+	}
+	if flags.Lookup(flagName) == nil {
+		panic(fmt.Sprintf("setFlagPlaceholder called with unknown flag %q", flagName))
+	}
+	_ = flags.SetAnnotation(flagName, flagPlaceholderAnnotation, []string{placeholder})
+}
+
+// setAllFlagPlaceholders applies help-output placeholder metadata to every local value flag.
+// Panics when any visible value flag is missing a placeholder or any placeholder names an invalid flag.
+// These panics happen during command construction, so they are intended as a dev and test aid.
+func setAllFlagPlaceholders(cmd *cobra.Command, placeholders map[string]string) {
+	if cmd == nil {
+		panic("setAllFlagPlaceholders called with nil command")
+	}
+	if len(placeholders) == 0 {
+		panic("setAllFlagPlaceholders called with no placeholders")
+	}
+	for flagName, placeholder := range placeholders {
+		setFlagPlaceholder(cmd.Flags(), flagName, placeholder)
+	}
+	cmd.LocalFlags().VisitAll(func(flag *pflag.Flag) {
+		if flag.Hidden || isBoolFlag(flag) {
+			return
+		}
+		if _, ok := placeholders[flag.Name]; !ok {
+			panic(fmt.Sprintf("setAllFlagPlaceholders missing placeholder for flag %q", flag.Name))
+		}
+	})
+}
+
+func isBoolFlag(flag *pflag.Flag) bool {
+	switch flag.Value.Type() {
+	case "bool", "boolfunc":
+		return true
+	default:
+		return false
+	}
 }
 
 func placeholderFromAnnotation(flag *pflag.Flag) (string, bool) {

cmd/root_test.go

@@ -402,7 +402,7 @@ func TestRootHelpOmitsEmptyGroupHeaders(t *testing.T) {
 func TestGetDescriptiveTypeNameUsesAnnotationWhenPresent(t *testing.T) {
 	flags := pflag.NewFlagSet("test", pflag.ContinueOnError)
 	flags.String("region", "", "Filter by region.")
-	require.True(t, setFlagPlaceholder(flags, "region", "REGION"))
+	setFlagPlaceholder(flags, "region", "REGION")
 
 	require.Equal(t, "REGION", getDescriptiveTypeName(flags.Lookup("region"), "string"))
 	require.Equal(t, "string", getDescriptiveTypeName(flags.Lookup("missing"), "string"))
@@ -426,6 +426,96 @@ func TestServicesEnvironmentIDsFlagHasPlaceholderAnnotation(t *testing.T) {
 	require.Equal(t, placeholderEnvIDs, placeholder)
 }
 
+func requireFlagPlaceholder(t *testing.T, flags *pflag.FlagSet, flagName, expected string) {
+	t.Helper()
+
+	require.NotNil(t, flags)
+	flag := flags.Lookup(flagName)
+	require.NotNil(t, flag)
+	placeholder, ok := placeholderFromAnnotation(flag)
+	require.True(t, ok)
+	require.Equal(t, expected, placeholder)
+}
+
+func TestSetAllFlagPlaceholders(t *testing.T) {
+	t.Run("applies placeholders for all value flags", func(t *testing.T) {
+		cmd := &cobra.Command{Use: "test"}
+		cmd.Flags().String("region", "", "region")
+		cmd.Flags().String("plan", "", "plan")
+
+		setAllFlagPlaceholders(cmd, map[string]string{
+			"region": "REGION",
+			"plan":   "PLAN",
+		})
+
+		requireFlagPlaceholder(t, cmd.Flags(), "region", "REGION")
+		requireFlagPlaceholder(t, cmd.Flags(), "plan", "PLAN")
+	})
+
+	t.Run("requires placeholders for local value flags only", func(t *testing.T) {
+		root := &cobra.Command{Use: "root"}
+		root.PersistentFlags().String("output", "", "output")
+		cmd := &cobra.Command{Use: "test"}
+		cmd.Flags().String("region", "", "region")
+		cmd.Flags().Bool("confirm", false, "confirm")
+		cmd.Flags().String("hidden", "", "hidden")
+		require.NoError(t, cmd.Flags().MarkHidden("hidden"))
+		root.AddCommand(cmd)
+
+		setAllFlagPlaceholders(cmd, map[string]string{
+			"region": "REGION",
+		})
+
+		requireFlagPlaceholder(t, cmd.Flags(), "region", "REGION")
+	})
+
+	t.Run("panics when a value flag is missing a placeholder", func(t *testing.T) {
+		cmd := &cobra.Command{Use: "test"}
+		cmd.Flags().String("region", "", "region")
+		cmd.Flags().String("plan", "", "plan")
+
+		require.Panics(t, func() {
+			setAllFlagPlaceholders(cmd, map[string]string{
+				"region": "REGION",
+			})
+		})
+	})
+
+	t.Run("panics when any flag does not exist", func(t *testing.T) {
+		cmd := &cobra.Command{Use: "test"}
+
+		require.Panics(t, func() {
+			setAllFlagPlaceholders(cmd, map[string]string{
+				"missing": "MISSING",
+			})
+		})
+	})
+
+	t.Run("panics for empty placeholder set", func(t *testing.T) {
+		cmd := &cobra.Command{Use: "test"}
+
+		require.Panics(t, func() {
+			setAllFlagPlaceholders(cmd, map[string]string{})
+		})
+	})
+
+	t.Run("panics for nil placeholder set", func(t *testing.T) {
+		cmd := &cobra.Command{Use: "test"}
+
+		require.Panics(t, func() {
+			setAllFlagPlaceholders(cmd, nil)
+		})
+	})
+
+	t.Run("panics for nil command", func(t *testing.T) {
+		require.Panics(t, func() {
+			setAllFlagPlaceholders(nil, map[string]string{
+				"region": "REGION",
+			})
+		})
+	})
+}
+
 func TestSetAnnotationBestEffort(t *testing.T) {
 	t.Run("returns true for existing flag", func(t *testing.T) {
 		flags := pflag.NewFlagSet("test", pflag.ContinueOnError)
@@ -440,13 +530,38 @@ func TestSetAnnotationBestEffort(t *testing.T) {
 		flags := pflag.NewFlagSet("test", pflag.ContinueOnError)
 
 		require.NotPanics(t, func() {
-			ok := setFlagPlaceholder(flags, "missing", "FORMAT")
+			ok := setAnnotationBestEffort(flags, "missing", flagPlaceholderAnnotation, []string{"FORMAT"})
 			require.False(t, ok)
 		})
 	})
 
 	t.Run("returns false for nil flagset", func(t *testing.T) {
-		require.False(t, setFlagPlaceholder(nil, "output", "FORMAT"))
+		require.False(t, setAnnotationBestEffort(nil, "output", flagPlaceholderAnnotation, []string{"FORMAT"}))
+	})
+}
+
+func TestSetFlagPlaceholder(t *testing.T) {
+	t.Run("applies placeholder to existing flag", func(t *testing.T) {
+		flags := pflag.NewFlagSet("test", pflag.ContinueOnError)
+		flags.String("output", "", "output format")
+
+		setFlagPlaceholder(flags, "output", "FORMAT")
+
+		requireFlagPlaceholder(t, flags, "output", "FORMAT")
+	})
+
+	t.Run("panics for missing flag", func(t *testing.T) {
+		flags := pflag.NewFlagSet("test", pflag.ContinueOnError)
+
+		require.Panics(t, func() {
+			setFlagPlaceholder(flags, "missing", "FORMAT")
+		})
+	})
+
+	t.Run("panics for nil flagset", func(t *testing.T) {
+		require.Panics(t, func() {
+			setFlagPlaceholder(nil, "output", "FORMAT")
+		})
 	})
 }