Add lists and maps as types the CLI and environment variables can hold

[nolag]

Note, the readme already has this documented. I missed splitting it out into this PR.

I originally had maps and lists in the prior PR, but pulled them out.

[github-actions]

📊 API Diff Results

No changes detected for module github.com/smartcontractkit/chainlink-common

View full report

[Copilot]

Copilot review overview

🟡 Changes recommended

Pointer collections can panic, recursive types can overflow, and several supported values do not round-trip correctly.

Review effort: Balanced
Findings: 5 · 3

Open (8)

• Map key conversion bypasses collision detection · New
• Recursive types cause unbounded conversion recursion · New
• Pointer list elements cause reflect.Append panics · New
• Pointer map values cause SetMapIndex panics · New
• Composite map keys can bypass pointer rejection · New
• Nested maps in structs and arrays are not converted · New
• Empty string list defaults serialize ambiguously · New
• String map keys containing equals are corrupted · New

What changed in this PR

Adds list and map support to CLI flags and environment-backed configuration.

Changes:

• Adds CSV list and key-value map parsing.
• Merges maps across defaults, files, environment, and flags.
• Adds validation, documentation, and tests for composite types.

File	Description
x/​config/​cli/​walk.go	Rejects pointer-keyed maps.
x/​config/​cli/​register.go	Registers list and map flags.
x/​config/​cli/​maps.go	Implements map parsing and merging.
x/​config/​cli/​list.go	Implements CSV list parsing.
x/​config/​cli/​entry.go	Decodes file values and merges maps.
x/​config/​cli/​decode.go	Converts textual map keys from files.
x/​config/​cli/​binder.go	Integrates transformed file value types.
x/​config/​cli/​binder_test.go	Tests list and map behavior.
x/​config/​cli/​examples/​simple/​README.md	Demonstrates list inputs.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

CSV truncation, unsafe interface-based map keys, and bypassed key conversion can produce incorrect configuration or panics.

Review effort: Balanced
Findings: 1 · 2

Open (3)

• Interface-containing map keys can cause panics or unsafe pointer keys · New
• Anonymous fields bypass conversion of unrelated exported fields · New
• Reject additional CSV records instead of silently truncating values · New

Resolved since last review (8)

• Composite map keys can bypass pointer rejection
• Pointer map values cause SetMapIndex panics
• Pointer list elements cause reflect.Append panics
• Recursive types cause unbounded conversion recursion
• Map key conversion bypasses collision detection
• String map keys containing equals are corrupted
• Empty string list defaults serialize ambiguously
• Nested maps in structs and arrays are not converted

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 2.

Benchmark suite	Current: a2c647f	Previous: 0ad8a5f	Ratio
BenchmarkKeystore_Sign/nop/out-of-process	92204 ns/op	23754 ns/op	3.88
BenchmarkKeystore_Sign/hex/out-of-process	93343 ns/op	24071 ns/op	3.88
BenchmarkKeystore_Sign/ed25519/out-of-process	140247 ns/op	44601 ns/op	3.14

This comment was automatically generated by workflow using github-action-benchmark.

[Copilot]

Copilot review overview

🟡 Changes recommended

Recursive non-string map keys and non-reflexive keys such as NaN can bypass the intended conversion and merge semantics.

Review effort: Balanced
Findings: 1

Open (1)

• Recursive map types bypass nested key conversion · New

Resolved since last review (3)

• Interface-containing map keys can cause panics or unsafe pointer keys
• Reject additional CSV records instead of silently truncating values
• Anonymous fields bypass conversion of unrelated exported fields

[Copilot]

Copilot review overview

🟡 Changes recommended

Map-key validation rejects valid opaque leaves while missing channel and composite-NaN identity hazards.

Review effort: Balanced
Findings: 3

Open (3)

• Reject nested NaN values in comparable map keys · New
• Avoid traversing opaque markup leaf internals · New
• Reject channel and unsafe pointer identity map keys · New

Resolved since last review (1)

• Recursive map types bypass nested key conversion

[Copilot]

Copilot review overview

🟡 Changes recommended

Atomic map types and ignored fields currently receive incorrect merge or conversion behavior.

Review effort: Balanced
Findings: 2

Open (2)

• Skip ignored fields during conversion and identity traversal · New
• Replace atomic map leaves instead of merging them · New

Resolved since last review (3)

• Reject channel and unsafe pointer identity map keys
• Avoid traversing opaque markup leaf internals
• Reject nested NaN values in comparable map keys

[Copilot]

Copilot review overview

🟡 Changes recommended

CSV whitespace trimming corrupts valid list and map values and prevents defaults from round-tripping.

Review effort: Balanced
Findings: 2

Open (2)

• Preserve trailing whitespace in CSV values · New
• Preserve whitespace in quoted map keys and values · New

Resolved since last review (2)

• Replace atomic map leaves instead of merging them
• Skip ignored fields during conversion and identity traversal

[Copilot]

Copilot review overview

🟡 Changes recommended

Collection defaults can produce misleading, non-round-trippable help values for UnmarshalText-only types.

Review effort: Balanced
Findings: 1

Open (1)

• Collection defaults may not round-trip for UnmarshalText-only types · New

Resolved since last review (2)

• Preserve whitespace in quoted map keys and values
• Preserve trailing whitespace in CSV values

[Copilot]

Copilot review overview

🟡 Changes recommended

Interface-typed list or map elements can currently cause a runtime panic during flag parsing.

Review effort: Balanced
Findings: 1

Open (1)

• Exclude encoding.TextUnmarshaler interface elements to prevent panics · New

Resolved since last review (1)

• Collection defaults may not round-trip for UnmarshalText-only types

[Copilot]

Copilot review overview

🔵 Needs a closer look

The reflection-based recursive type conversion and multi-source map merging warrant final human validation.

Review effort: Balanced
Findings: 1

Open (1)

• Document newFlag restrictions for unsupported pointer, interface, and map types · New

Resolved since last review (1)

• Exclude encoding.TextUnmarshaler interface elements to prevent panics

[Copilot]

Copilot review overview

🔵 Needs a closer look

NaN map keys produce displayed defaults that cannot be parsed back.

Review effort: Balanced
Findings: None

Resolved since last review (1)

• Document newFlag restrictions for unsupported pointer, interface, and map types

Previously missed (1)

In code that hasn't changed since last review

Suppress defaults containing NaN map keys that cannot round-trip

x/​config/​cli/​maps.go:69

A default map can already contain a NaN key, but this serializes it as NaN=value even though mapKey rejects that text at lines 318-320. Passing the displayed default back therefore fails. Treat a key that does not equal itself as unwritable and suppress the map default, as is already done for other non-round-trippable entries.

[nolag]

Change not strictly needed, but lines it up better with the rest of the tests and allows us to avoid file writes

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation is coherent, documented, and comprehensively tested across supported sources and edge cases.

Review effort: Balanced
Findings: None

[jmank88]

Is an empty entry valid?

[jmank88]

I think you can use Seq2() here?

Suggested change

	for iter := v.MapRange(); iter.Next(); {
	pairs = append(pairs, textOf(iter.Key())+mapKVSep+textOf(iter.Value()))
	for key, val := range v.Seq2() {
	pairs = append(pairs, textOf(key)+mapKVSep+textOf(val))

[jmank88]

Since the check is based on Kind, maybe include that in the name?

Suggested change

	func holdsIdentity(t reflect.Type) bool {
	func isIdentityKind(t reflect.Type) bool {

[jmank88]

nit/ maybe worth naming these params more descriptively:

Suggested change

	func mapKey(t reflect.Type, text string, seen map[any]string) (reflect.Value, error) {
	func mapKey(mapType reflect.Type, keyText string, seen map[any]string) (reflect.Value, error) {