diff --git a/command.go b/command.go index 1c7aa69..1cab711 100644 --- a/command.go +++ b/command.go @@ -6,8 +6,8 @@ import ( "github.com/rs/zerolog" "github.com/spf13/cobra" + "github.com/spf13/pflag" "github.com/urfave/sflags" - "github.com/urfave/sflags/gen/gpflag" ) // NewCommand creates a new Cobra command with type-safe configuration handling. @@ -15,10 +15,14 @@ import ( // It wraps the provided Cobra command with automatic configuration loading, // populating flags from the config struct, and executing the command with // configuration management. +// +// A flag is named after its field's mapstructure key path, so --log-level sets +// log.level; see registerConfigFlags. Set a flag tag name on a field to choose +// its flag name instead. func NewCommand[T any](cmd *cobra.Command, runFunc func(context.Context, *T) error, defaultConfig *T, opts ...CommandOpt) *cobra.Command { cmd.RunE = CobraRunE(runFunc) - if err := gpflag.ParseTo(defaultConfig, cmd.Flags(), sflags.InheritDeprecated(), sflags.InheritHidden()); err != nil { + if err := registerConfigFlags(cmd.Flags(), defaultConfig, sflags.InheritDeprecated(), sflags.InheritHidden()); err != nil { panic(fmt.Sprintf("cli: failed to register flags from config type: %v", err)) } @@ -45,3 +49,24 @@ func WithGlobalZerologLevel(level zerolog.Level) CommandOpt { zerolog.SetGlobalLevel(level) } } + +// UndocumentedFlags returns the visible flags in cmd's tree that have no usage +// text, as "command path --flag" strings. A flag a user can see in --help +// without a description is a defect, so a consumer can guard its CLI with +// +// require.Empty(t, cli.UndocumentedFlags(rootCmd)) +// +// Hidden and deprecated flags are not reported, since --help does not list them. +func UndocumentedFlags(cmd *cobra.Command) []string { + var missing []string + cmd.Flags().VisitAll(func(f *pflag.Flag) { + if f.Usage == "" && !f.Hidden && f.Deprecated == "" { + missing = append(missing, cmd.CommandPath()+" --"+f.Name) + } + }) + for _, child := range cmd.Commands() { + missing = append(missing, UndocumentedFlags(child)...) + } + + return missing +} diff --git a/config.go b/config.go index e20feb1..06d751c 100644 --- a/config.go +++ b/config.go @@ -164,7 +164,7 @@ func InitConfig(orgName, appName string, cmd *cobra.Command, cfg any, opts ...In v.SetEnvPrefix(appName) v.SetEnvKeyReplacer(strings.NewReplacer("-", "_", ".", "_")) - err = v.BindPFlags(cmd.Flags()) + err = bindFlags(v, cmd.Flags()) if err != nil { return nil, err } @@ -505,3 +505,39 @@ func CobraRunE[T any](execFunc func(context.Context, *T) error, opt ...CobraOpt[ return execFunc(ctx, &cfg) } } + +// bindFlags binds fs's flags into v. A flag generated from a config struct +// field binds to the config key the field is decoded from, not to its own name, +// so its value reaches the config; any other flag binds under its name. A +// deprecated alias that was set counts as its canonical flag being set. +func bindFlags(v *viper.Viper, fs *pflag.FlagSet) error { + var err error + fs.VisitAll(func(f *pflag.Flag) { + if err != nil { + return + } + if target := annotation(f, aliasOfAnnotation); target != "" { + if canonical := fs.Lookup(target); canonical != nil && f.Changed { + canonical.Changed = true + } + + return + } + + key := annotation(f, configKeyAnnotation) + if key == "" { + key = f.Name + } + err = v.BindPFlag(key, f) + }) + + return err +} + +func annotation(f *pflag.Flag, name string) string { + if values := f.Annotations[name]; len(values) > 0 { + return values[0] + } + + return "" +} diff --git a/flags.go b/flags.go new file mode 100644 index 0000000..39e3643 --- /dev/null +++ b/flags.go @@ -0,0 +1,181 @@ +package cli + +import ( + "fmt" + "reflect" + "slices" + "strings" + + "github.com/spf13/pflag" + "github.com/urfave/sflags" + "github.com/urfave/sflags/gen/gpflag" +) + +const ( + // configKeyAnnotation is the pflag annotation holding the config key a + // flag sets: the dotted path of the config struct field's mapstructure + // names, which is where the config is decoded from. + configKeyAnnotation = "dioad-cli-config-key" + // aliasOfAnnotation marks a deprecated alias flag, and names the flag + // it is an alias of. + aliasOfAnnotation = "dioad-cli-alias-of" +) + +// registerConfigFlags adds a flag to dst for every field of cfg, a pointer to +// the config struct. +// +// sflags names a flag from the Go field path, but the config is decoded from +// the fields' mapstructure keys, and the two differ for a renamed field, a +// named struct squashed into its parent, or a nested block. A flag named after +// the wrong key sets a value nothing decodes. So each flag is named from the +// field's mapstructure key path ("log-level" for log.level), and records that +// path in an annotation so InitConfig binds it to the right key. +// +// A field whose own flag tag, or an ancestor's, names the flag keeps that name: +// the author chose it. A flag whose name changed is also registered under its +// previous sflags name, hidden and deprecated, so existing command lines keep +// working. +func registerConfigFlags(dst *pflag.FlagSet, cfg any, opts ...sflags.OptFunc) error { + generated := pflag.NewFlagSet("generated", pflag.ContinueOnError) + if err := gpflag.ParseTo(cfg, generated, opts...); err != nil { + return err + } + + keys := map[string]configFlag{} + walkConfigFlags(reflect.TypeOf(cfg), "", nil, false, generated, opts, keys) + + var err error + generated.VisitAll(func(f *pflag.Flag) { + if err != nil { + return + } + err = addFlag(dst, f, keys[f.Name]) + }) + + return err +} + +// configFlag is what walkConfigFlags learns about one generated flag. +type configFlag struct { + key string + name string +} + +// walkConfigFlags records, for each flag in generated that belongs to a field +// of t, the config key it sets and the name it should have. +func walkConfigFlags(t reflect.Type, flagPrefix string, keyPath []string, explicit bool, generated *pflag.FlagSet, opts []sflags.OptFunc, out map[string]configFlag) { + for t.Kind() == reflect.Pointer { + t = t.Elem() + } + if t.Kind() != reflect.Struct { + return + } + + for i := range t.NumField() { + field := t.Field(i) + if field.PkgPath != "" && !field.Anonymous { + continue + } + + if name, _, _ := strings.Cut(field.Tag.Get("flag"), ","); name == "-" { + continue + } + var flagName string + if !field.Anonymous { + var ok bool + if flagName, ok = sflagsName(field, flagPrefix, opts); !ok { + continue + } + } + msName, squash := mapstructureName(field) + fieldExplicit := explicit || hasExplicitFlagName(field) + + fieldKey := keyPath + if !squash && (!field.Anonymous || msName != "") { + if msName == "" { + msName = strings.ToLower(field.Name) + } + fieldKey = append(append([]string{}, keyPath...), msName) + } + + if flagName != "" && generated.Lookup(flagName) != nil { + name := flagName + if !fieldExplicit { + name = strings.Join(fieldKey, "-") + } + out[flagName] = configFlag{key: strings.Join(fieldKey, "."), name: name} + + continue + } + + nextPrefix := flagName + "-" + if field.Anonymous { + nextPrefix = flagPrefix + } + walkConfigFlags(field.Type, nextPrefix, fieldKey, fieldExplicit, generated, opts, out) + } +} + +// sflagsName returns the name sflags gives field's flag under prefix, by asking +// sflags itself so the two cannot disagree. It reports false when the field has +// no flag (`flag:"-"`). +func sflagsName(field reflect.StructField, prefix string, opts []sflags.OptFunc) (string, bool) { + probe := reflect.StructOf([]reflect.StructField{{ + Name: field.Name, + Type: reflect.TypeFor[string](), + Tag: field.Tag, + }}) + flags, err := sflags.ParseStruct(reflect.New(probe).Interface(), append(append([]sflags.OptFunc{}, opts...), sflags.Prefix(prefix))...) + if err != nil || len(flags) != 1 { + return "", false + } + + return flags[0].Name, true +} + +// mapstructureName returns field's mapstructure key and whether it is squashed. +func mapstructureName(field reflect.StructField) (string, bool) { + parts := strings.Split(field.Tag.Get("mapstructure"), ",") + if slices.Contains(parts[1:], "squash") { + return parts[0], true + } + + return parts[0], false +} + +// hasExplicitFlagName reports whether field's flag tag gives the flag a name, +// as opposed to only options such as hidden. +func hasExplicitFlagName(field reflect.StructField) bool { + name, _, _ := strings.Cut(field.Tag.Get("flag"), ",") + + return name != "" && name != "-" +} + +// addFlag registers f on dst under the name info chose, with an alias under +// f's previous name if it changed. +func addFlag(dst *pflag.FlagSet, f *pflag.Flag, info configFlag) error { + name := f.Name + if info.name != "" && dst.Lookup(info.name) == nil { + name = info.name + } + + added := dst.VarPF(f.Value, name, f.Shorthand, f.Usage) + added.NoOptDefVal = f.NoOptDefVal + added.Hidden = f.Hidden + added.Deprecated = f.Deprecated + if info.key != "" { + added.Annotations = map[string][]string{configKeyAnnotation: {info.key}} + } + + if name == f.Name || dst.Lookup(f.Name) != nil { + return nil + } + + alias := dst.VarPF(f.Value, f.Name, "", f.Usage) + alias.NoOptDefVal = f.NoOptDefVal + alias.Hidden = true + alias.Deprecated = fmt.Sprintf("use --%s", name) + alias.Annotations = map[string][]string{aliasOfAnnotation: {name}} + + return nil +} diff --git a/flags_test.go b/flags_test.go new file mode 100644 index 0000000..4ce144e --- /dev/null +++ b/flags_test.go @@ -0,0 +1,196 @@ +package cli_test + +import ( + "context" + "fmt" + "testing" + + "github.com/spf13/cobra" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/dioad/cli" +) + +type rateLimitBlock struct { + RateLimitRPS float64 `desc:"requests per second" mapstructure:"rate-limit-rps"` +} + +type managementBlock struct { + ListenAddress string `desc:"management listen address" mapstructure:"listen-address"` +} + +// flagKeysConfig has the three shapes issue #18 reports: a named struct +// squashed into its parent, a field whose key differs from its Go name, and a +// nested block. +type flagKeysConfig struct { + RateLimit rateLimitBlock `desc:"" mapstructure:",squash"` + AllowedOrigins []string `desc:"origins allowed by CORS" mapstructure:"cors-allowed-origins"` + Management managementBlock `mapstructure:"management"` + Plain string `desc:"a plain field" mapstructure:"plain"` + Chosen string `desc:"named by its flag tag" flag:"picked" mapstructure:"chosen-key"` +} + +func newFlagKeysCmd() *cobra.Command { + return cli.NewCommand(&cobra.Command{Use: "testapp"}, func(context.Context, *flagKeysConfig) error { return nil }, &flagKeysConfig{}) +} + +func TestNewCommand_FlagsAreNamedAfterConfigKeys(t *testing.T) { + t.Parallel() + cmd := newFlagKeysCmd() + + for _, name := range []string{"rate-limit-rps", "cors-allowed-origins", "management-listen-address", "plain", "picked"} { + assert.NotNil(t, cmd.Flags().Lookup(name), "--%s should exist", name) + } + assert.Nil(t, cmd.Flags().Lookup("chosen-key"), "a flag tag name wins over the mapstructure key") +} + +func TestNewCommand_OldFlagNamesStayAsDeprecatedAliases(t *testing.T) { + t.Parallel() + cmd := newFlagKeysCmd() + + for oldName, newName := range map[string]string{ + "rate-limit-rate-limit-rps": "rate-limit-rps", + "allowed-origins": "cors-allowed-origins", + "management-listen-address": "management-listen-address", + } { + if oldName == newName { + continue + } + alias := cmd.Flags().Lookup(oldName) + require.NotNil(t, alias, "--%s should still be accepted", oldName) + assert.True(t, alias.Hidden, "--%s is hidden", oldName) + assert.Contains(t, alias.Deprecated, "--"+newName) + } +} + +// TestInitConfig_EveryGeneratedFlagReachesTheConfig is the check issue #18 +// asks for: set each generated flag and confirm the decoded struct changed, so +// a flag named for a key nothing decodes cannot go unnoticed. +func TestInitConfig_EveryGeneratedFlagReachesTheConfig(t *testing.T) { + t.Parallel() + + tests := []struct { + flag string + value string + check func(t *testing.T, cfg *flagKeysConfig) + }{ + {"rate-limit-rps", "5", func(t *testing.T, c *flagKeysConfig) { assert.InDelta(t, 5.0, c.RateLimit.RateLimitRPS, 0) }}, + {"cors-allowed-origins", "https://a.example", func(t *testing.T, c *flagKeysConfig) { + assert.Equal(t, []string{"https://a.example"}, c.AllowedOrigins) + }}, + {"management-listen-address", ":4444", func(t *testing.T, c *flagKeysConfig) { assert.Equal(t, ":4444", c.Management.ListenAddress) }}, + {"plain", "p", func(t *testing.T, c *flagKeysConfig) { assert.Equal(t, "p", c.Plain) }}, + {"picked", "c", func(t *testing.T, c *flagKeysConfig) { assert.Equal(t, "c", c.Chosen) }}, + // The previous names keep working. + {"rate-limit-rate-limit-rps", "7", func(t *testing.T, c *flagKeysConfig) { assert.InDelta(t, 7.0, c.RateLimit.RateLimitRPS, 0) }}, + {"allowed-origins", "https://b.example", func(t *testing.T, c *flagKeysConfig) { + assert.Equal(t, []string{"https://b.example"}, c.AllowedOrigins) + }}, + } + for _, tt := range tests { + t.Run(tt.flag, func(t *testing.T) { + t.Parallel() + cmd := newFlagKeysCmd() + require.NoError(t, cmd.Flags().Parse([]string{"--" + tt.flag + "=" + tt.value})) + + var cfg flagKeysConfig + _, err := cli.InitConfig("testorg", "testapp", cmd, &cfg, cli.WithoutLogging()) + + require.NoError(t, err) + tt.check(t, &cfg) + }) + } +} + +func TestInitConfig_FlagOverridesConfigFileAtTheDecodedKey(t *testing.T) { + t.Parallel() + cmd := newFlagKeysCmd() + cmd.Flags().StringP("config", "c", "", "config file") + require.NoError(t, cmd.Flags().Parse([]string{ + "--config=" + writeYAML(t, "management:\n listen-address: ':1'\nrate-limit-rps: 1\n"), + "--rate-limit-rps=9", + })) + + var cfg flagKeysConfig + _, err := cli.InitConfig("testorg", "testapp", cmd, &cfg, cli.WithoutLogging()) + + require.NoError(t, err) + assert.InDelta(t, 9.0, cfg.RateLimit.RateLimitRPS, 0, "the flag beats the file") + assert.Equal(t, ":1", cfg.Management.ListenAddress, "an unset flag leaves the file's value") +} + +func TestInitConfig_EnvironmentOverridesUseTheConfigKey(t *testing.T) { + t.Setenv("TESTAPP_MANAGEMENT_LISTEN_ADDRESS", ":5555") + cmd := newFlagKeysCmd() + + var cfg flagKeysConfig + _, err := cli.InitConfig("testorg", "testapp", cmd, &cfg, cli.WithoutLogging()) + + require.NoError(t, err) + assert.Equal(t, ":5555", cfg.Management.ListenAddress) +} + +func TestNewCommand_CommonLoggingFlagsMatchTheConfigKeys(t *testing.T) { + t.Parallel() + cmd := cli.NewCommand(&cobra.Command{Use: "testapp"}, func(context.Context, *cli.CommonConfig) error { return nil }, &cli.CommonConfig{}) + + for _, name := range []string{"log-level", "log-file", "log-max-size", "log-max-age", "log-max-backups", "log-use-local-time", "log-compress"} { + flag := cmd.Flags().Lookup(name) + require.NotNil(t, flag, "--%s should exist", name) + assert.NotEmpty(t, flag.Usage, "--%s needs help text", name) + assert.False(t, flag.Hidden, "--%s is visible", name) + } + + mode := cmd.Flags().Lookup("log-mode") + require.NotNil(t, mode) + assert.True(t, mode.Hidden, "mode is reserved for future use, so --help does not list it") +} + +func TestNewCommand_PreviousLoggingFlagsStayAsDeprecatedAliases(t *testing.T) { + t.Parallel() + cmd := cli.NewCommand(&cobra.Command{Use: "testapp"}, func(context.Context, *cli.CommonConfig) error { return nil }, &cli.CommonConfig{}) + + for oldName, newName := range map[string]string{"logging-level": "log-level", "logging-local-time": "log-use-local-time"} { + alias := cmd.Flags().Lookup(oldName) + require.NotNil(t, alias, "--%s should still be accepted", oldName) + assert.True(t, alias.Hidden) + assert.Contains(t, alias.Deprecated, "--"+newName) + } + + var cfg cli.CommonConfig + require.NoError(t, cmd.Flags().Parse([]string{"--logging-level=debug"})) + _, err := cli.InitConfig("testorg", "testapp", cmd, &cfg, cli.WithoutLogging()) + require.NoError(t, err) + assert.Equal(t, "debug", cfg.Logging.Level, "the old name still sets the value") +} + +func TestUndocumentedFlags(t *testing.T) { + t.Parallel() + root := &cobra.Command{Use: "app"} + child := &cobra.Command{Use: "child"} + root.AddCommand(child) + root.Flags().String("documented", "", "has usage") + root.Flags().String("bare", "", "") + child.Flags().String("child-bare", "", "") + child.Flags().String("hidden-bare", "", "") + require.NoError(t, child.Flags().MarkHidden("hidden-bare")) + + assert.ElementsMatch(t, []string{"app --bare", "app child --child-bare"}, cli.UndocumentedFlags(root)) +} + +func TestNewCommand_CommonConfigHasNoUndocumentedFlags(t *testing.T) { + t.Parallel() + cmd := cli.NewCommand(&cobra.Command{Use: "testapp"}, func(context.Context, *cli.CommonConfig) error { return nil }, &cli.CommonConfig{}) + + assert.Empty(t, cli.UndocumentedFlags(cmd)) +} + +func ExampleUndocumentedFlags() { + root := &cobra.Command{Use: "app"} + root.Flags().String("port", "", "port to listen on") + root.Flags().String("mystery", "", "") + + fmt.Println(cli.UndocumentedFlags(root)) + // Output: [app --mystery] +} diff --git a/logging/config.go b/logging/config.go index 7621cea..5a01aa3 100644 --- a/logging/config.go +++ b/logging/config.go @@ -21,32 +21,32 @@ package logging type Config struct { // Level specifies the logging level: trace, debug, info, warn, error, fatal, panic. // Empty string defaults to application-configured level or zerolog.WarnLevel. - Level string `mapstructure:"level"` + Level string `desc:"log level: trace, debug, info, warn, error, fatal or panic" mapstructure:"level"` // File specifies the path to the log file. Supports home directory expansion (~). // Empty string disables file logging (logs to stdout only). - File string `mapstructure:"file"` + File string `desc:"log file path, with ~ expanded; empty logs to stdout only" mapstructure:"file"` // MaxSize is the maximum size of the log file in MB before rotation occurs. // Default is 100 MB. - MaxSize int `mapstructure:"max-size"` + MaxSize int `desc:"maximum log file size in MB before it is rotated" mapstructure:"max-size"` // MaxAge is the maximum number of days to keep old log files. // Default is 0 (no limit). - MaxAge int `mapstructure:"max-age"` + MaxAge int `desc:"days to keep rotated log files; 0 keeps them all" mapstructure:"max-age"` // MaxBackups is the maximum number of old log files to retain. // Default is 0 (keep all). - MaxBackups int `mapstructure:"max-backups"` + MaxBackups int `desc:"rotated log files to keep; 0 keeps them all" mapstructure:"max-backups"` // LocalTime determines if rotated filenames use local time instead of UTC. // Default is false. - LocalTime bool `mapstructure:"use-local-time"` + LocalTime bool `desc:"name rotated log files with local time instead of UTC" mapstructure:"use-local-time"` // Compress determines if old log files are gzip-compressed after rotation. // Default is false. - Compress bool `mapstructure:"compress"` + Compress bool `desc:"gzip rotated log files" mapstructure:"compress"` // Mode is reserved for future use. - Mode string `mapstructure:"mode"` + Mode string `flag:",hidden" mapstructure:"mode"` }