Redesign ConfigResolver to accept ConfigKey with decomposed parts

Author: bjaus

config/config.go

@@ -69,8 +69,8 @@
 //
 //	// Consul KV adapter
 //	func FromConsul(client *consul.Client, prefix string) cli.ConfigResolver {
-//	    return func(flagName string) (string, bool) {
-//	        pair, _, err := client.KV().Get(prefix+"/"+flagName, nil)
+//	    return func(key cli.ConfigKey) (string, bool) {
+//	        pair, _, err := client.KV().Get(prefix+"/"+key.Name, nil)
 //	        if err != nil || pair == nil { return "", false }
 //	        return string(pair.Value), true
 //	    }
@@ -97,8 +97,8 @@ import (
 
 // FromMap returns a [cli.ConfigResolver] backed by a string map.
 func FromMap(m map[string]string) cli.ConfigResolver {
-	return func(flagName string) (string, bool) {
-		v, ok := m[flagName]
+	return func(key cli.ConfigKey) (string, bool) {
+		v, ok := m[key.Name]
 		return v, ok
 	}
 }
@@ -116,9 +116,9 @@ func FromJSON(r io.Reader) (cli.ConfigResolver, error) {
 // Chain returns a [cli.ConfigResolver] that tries each resolver in order,
 // returning the value from the first resolver that reports found.
 func Chain(resolvers ...cli.ConfigResolver) cli.ConfigResolver {
-	return func(flagName string) (string, bool) {
+	return func(key cli.ConfigKey) (string, bool) {
 		for _, r := range resolvers {
-			if v, ok := r(flagName); ok {
+			if v, ok := r(key); ok {
 				return v, true
 			}
 		}

config/config_test.go

@@ -4,26 +4,31 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/bjaus/cli"
 	"github.com/bjaus/cli/config"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
+func key(name string) cli.ConfigKey {
+	return cli.ConfigKey{Name: name, Parts: []string{name}}
+}
+
 func TestFromMap(t *testing.T) {
 	t.Parallel()
 
 	m := map[string]string{"port": "8080", "host": "localhost"}
 	resolver := config.FromMap(m)
 
-	val, ok := resolver("port")
+	val, ok := resolver(key("port"))
 	assert.True(t, ok)
 	assert.Equal(t, "8080", val)
 
-	val, ok = resolver("host")
+	val, ok = resolver(key("host"))
 	assert.True(t, ok)
 	assert.Equal(t, "localhost", val)
 
-	_, ok = resolver("missing")
+	_, ok = resolver(key("missing"))
 	assert.False(t, ok)
 }
 
@@ -37,11 +42,11 @@ func TestFromJSON(t *testing.T) {
 		resolver, err := config.FromJSON(r)
 		require.NoError(t, err)
 
-		val, ok := resolver("port")
+		val, ok := resolver(key("port"))
 		assert.True(t, ok)
 		assert.Equal(t, "9090", val)
 
-		_, ok = resolver("missing")
+		_, ok = resolver(key("missing"))
 		assert.False(t, ok)
 	})
 
@@ -63,16 +68,16 @@ func TestChain(t *testing.T) {
 	chained := config.Chain(first, second)
 
 	// First match wins.
-	val, ok := chained("port")
+	val, ok := chained(key("port"))
 	assert.True(t, ok)
 	assert.Equal(t, "1111", val)
 
 	// Falls through to second.
-	val, ok = chained("host")
+	val, ok = chained(key("host"))
 	assert.True(t, ok)
 	assert.Equal(t, "second", val)
 
 	// No match.
-	_, ok = chained("missing")
+	_, ok = chained(key("missing"))
 	assert.False(t, ok)
 }

doc.go

@@ -192,9 +192,11 @@
 // Flag values can be loaded from external configuration sources via a
 // [ConfigResolver]. A resolver is a single function:
 //
-//	type ConfigResolver func(flagName string) (value string, found bool)
+//	type ConfigResolver func(key ConfigKey) (value string, found bool)
 //
-// Given a flag name, it returns the string value and whether it was found.
+// Given a [ConfigKey], it returns the string value and whether it was found.
+// The key provides both the full flag name ([ConfigKey.Name]) and decomposed
+// parts ([ConfigKey.Parts]) for resolvers backed by nested formats.
 // The framework handles all type conversion, validation, required checks,
 // and enum enforcement — the resolver only needs to return strings.
 //

example_test.go

@@ -545,9 +545,9 @@ func (c *ConfigServeCmd) Run(_ context.Context, _ []string) error {
 }
 
 func ExampleExecute_configResolver() {
-	resolver := cli.ConfigResolver(func(flagName string) (string, bool) {
+	resolver := cli.ConfigResolver(func(key cli.ConfigKey) (string, bool) {
 		m := map[string]string{"port": "9090", "host": "0.0.0.0"}
-		v, ok := m[flagName]
+		v, ok := m[key.Name]
 		return v, ok
 	})
 
@@ -571,8 +571,8 @@ func (c *ConfigProviderCmd) Run(_ context.Context, _ []string) error {
 }
 
 func (c *ConfigProviderCmd) ConfigResolver() cli.ConfigResolver {
-	return func(flagName string) (string, bool) {
-		if flagName == "port" {
+	return func(key cli.ConfigKey) (string, bool) {
+		if key.Name == "port" {
 			return "3000", true
 		}
 		return "", false

execute_test.go

@@ -1285,9 +1285,9 @@ func (c *configCmd) Run(_ context.Context, _ []string) error { return nil }
 func TestExecute_ConfigResolver_Applied(t *testing.T) {
 	t.Parallel()
 
-	resolver := cli.ConfigResolver(func(name string) (string, bool) {
+	resolver := cli.ConfigResolver(func(key cli.ConfigKey) (string, bool) {
 		m := map[string]string{"port": "9090", "host": "0.0.0.0"}
-		v, ok := m[name]
+		v, ok := m[key.Name]
 		return v, ok
 	})
 
@@ -1307,8 +1307,8 @@ func (c *envConfigCmd) Run(_ context.Context, _ []string) error { return nil }
 func TestExecute_EnvOverridesConfig(t *testing.T) {
 	t.Setenv("CFG_PORT", "5555")
 
-	resolver := cli.ConfigResolver(func(name string) (string, bool) {
-		if name == "port" {
+	resolver := cli.ConfigResolver(func(key cli.ConfigKey) (string, bool) {
+		if key.Name == "port" {
 			return "9090", true
 		}
 		return "", false
@@ -1323,8 +1323,8 @@ func TestExecute_EnvOverridesConfig(t *testing.T) {
 func TestExecute_ExplicitFlagOverridesConfig(t *testing.T) {
 	t.Parallel()
 
-	resolver := cli.ConfigResolver(func(name string) (string, bool) {
-		if name == "port" {
+	resolver := cli.ConfigResolver(func(key cli.ConfigKey) (string, bool) {
+		if key.Name == "port" {
 			return "9090", true
 		}
 		return "", false
@@ -1345,8 +1345,8 @@ func (c *reqConfigCmd) Run(_ context.Context, _ []string) error { return nil }
 func TestExecute_ConfigSatisfiesRequired(t *testing.T) {
 	t.Parallel()
 
-	resolver := cli.ConfigResolver(func(name string) (string, bool) {
-		if name == "name" {
+	resolver := cli.ConfigResolver(func(key cli.ConfigKey) (string, bool) {
+		if key.Name == "name" {
 			return "alice", true
 		}
 		return "", false
@@ -1369,8 +1369,8 @@ func TestExecute_ConfigValidatedAgainstEnum(t *testing.T) {
 	// Valid enum value from config.
 	cmd := &enumConfigCmd{}
 	err := cli.Execute(context.Background(), cmd, nil, cli.WithConfigResolver(
-		cli.ConfigResolver(func(name string) (string, bool) {
-			if name == "format" {
+		cli.ConfigResolver(func(key cli.ConfigKey) (string, bool) {
+			if key.Name == "format" {
 				return "json", true
 			}
 			return "", false
@@ -1382,8 +1382,8 @@ func TestExecute_ConfigValidatedAgainstEnum(t *testing.T) {
 	// Invalid enum value from config.
 	cmd2 := &enumConfigCmd{}
 	err = cli.Execute(context.Background(), cmd2, nil, cli.WithConfigResolver(
-		cli.ConfigResolver(func(name string) (string, bool) {
-			if name == "format" {
+		cli.ConfigResolver(func(key cli.ConfigKey) (string, bool) {
+			if key.Name == "format" {
 				return "xml", true
 			}
 			return "", false
@@ -1400,8 +1400,8 @@ type configProviderCmd struct {
 func (c *configProviderCmd) Run(_ context.Context, _ []string) error { return nil }
 
 func (c *configProviderCmd) ConfigResolver() cli.ConfigResolver {
-	return func(name string) (string, bool) {
-		if name == "port" {
+	return func(key cli.ConfigKey) (string, bool) {
+		if key.Name == "port" {
 			return "4000", true
 		}
 		return "", false
@@ -1411,8 +1411,8 @@ func (c *configProviderCmd) ConfigResolver() cli.ConfigResolver {
 func TestExecute_ConfigProvider_OverridesGlobal(t *testing.T) {
 	t.Parallel()
 
-	global := cli.ConfigResolver(func(name string) (string, bool) {
-		if name == "port" {
+	global := cli.ConfigResolver(func(key cli.ConfigKey) (string, bool) {
+		if key.Name == "port" {
 			return "9090", true
 		}
 		return "", false

flags.go

@@ -139,6 +139,7 @@ func flagTypeName(t reflect.Type) string {
 type fieldInfo struct {
 	index    []int // field path for nested structs (e.g. [0, 2] for embedded.Field)
 	def      FlagDef
+	parts    []string // decomposed flag name: prefix segments + base (e.g. ["db", "host"])
 	provided bool
 	envOnly  bool // standalone env field — not a CLI flag, only env/config/default
 }
@@ -239,27 +240,28 @@ func collectProvided(fields map[string]*fieldInfo) map[string]bool {
 
 func buildFieldMap(t reflect.Type) map[string]*fieldInfo {
 	fields := make(map[string]*fieldInfo)
-	buildFieldMapRecurse(t, fields, nil, "")
+	buildFieldMapRecurse(t, fields, nil, "", nil)
 	return fields
 }
 
-func buildFieldMapRecurse(t reflect.Type, fields map[string]*fieldInfo, indexPath []int, prefix string) {
+func buildFieldMapRecurse(t reflect.Type, fields map[string]*fieldInfo, indexPath []int, prefix string, parts []string) {
 	for i := range t.NumField() {
 		f := t.Field(i)
 		currentPath := append(append([]int{}, indexPath...), i)
 
 		// Named struct with prefix tag: recurse with prefix.
 		if f.Type.Kind() == reflect.Struct && !f.Anonymous {
 			if pfx := f.Tag.Get("prefix"); pfx != "" {
-				buildFieldMapRecurse(f.Type, fields, currentPath, prefix+pfx)
+				part := strings.TrimRight(pfx, "-._/")
+				buildFieldMapRecurse(f.Type, fields, currentPath, prefix+pfx, append(parts, part))
 				continue
 			}
 			// Fall through: may be a custom type with flag tag (e.g. FlagUnmarshaler).
 		}
 
 		// Anonymous embedded struct (non-pointer): promote fields.
 		if f.Anonymous && f.Type.Kind() == reflect.Struct {
-			buildFieldMapRecurse(f.Type, fields, currentPath, prefix)
+			buildFieldMapRecurse(f.Type, fields, currentPath, prefix, parts)
 			continue
 		}
 
@@ -281,6 +283,7 @@ func buildFieldMapRecurse(t reflect.Type, fields map[string]*fieldInfo, indexPat
 		}
 
 		fullName := prefix + name
+		fieldParts := append(append([]string{}, parts...), name)
 
 		var aliases []string
 		if raw := f.Tag.Get("alt"); raw != "" {
@@ -301,6 +304,7 @@ func buildFieldMapRecurse(t reflect.Type, fields map[string]*fieldInfo, indexPat
 
 		fi := &fieldInfo{
 			index:   currentPath,
+			parts:   fieldParts,
 			envOnly: envOnly,
 			def: FlagDef{
 				Name:        fullName,
@@ -360,7 +364,7 @@ func applyConfig(v reflect.Value, fields map[string]*fieldInfo, resolver ConfigR
 		return nil
 	}
 	for _, fi := range fields {
-		val, found := resolver(fi.def.Name)
+		val, found := resolver(ConfigKey{Name: fi.def.Name, Parts: fi.parts})
 		if !found {
 			continue
 		}

interfaces.go

@@ -128,10 +128,21 @@ type Suggester interface {
 
 // --- Config interfaces (all optional) ---
 
+// ConfigKey identifies a flag for config resolution. Name is the full
+// prefixed flag name (e.g. "db-host"). Parts decomposes the name into
+// prefix segments and base name (e.g. ["db", "host"]), useful for
+// resolvers backed by nested configuration formats (YAML, TOML).
+// For unprefixed flags, Parts contains a single element equal to Name.
+type ConfigKey struct {
+	Name  string
+	Parts []string
+}
+
 // ConfigResolver resolves flag values from an external source such as a
-// config file. Given a flag name, it returns the string value and whether
-// the flag was found. The framework handles type conversion.
-type ConfigResolver func(flagName string) (value string, found bool)
+// config file. Given a [ConfigKey], it returns the string value and whether
+// the flag was found. The framework handles type conversion. Use
+// [ConfigKey.Name] for flat lookups or [ConfigKey.Parts] for nested lookups.
+type ConfigResolver func(key ConfigKey) (value string, found bool)
 
 // ConfigProvider is implemented by commands that supply their own resolver.
 // Checked before the global resolver set via [WithConfigResolver].