feat(config): generate the settings struct a CLI reads

[jdx]

The other half of the codegen: the struct a CLI's own code reads. #864 emits the registry
resolution needs; this emits what the code needs, and between them they remove the thing the fleet
writes by hand — pitchfork's ~330 lines of key↔field match arms, written twice (once for get,
once for set), with five settings still unreachable from its own settings get.

let resolved = usage_config::resolve(SETTINGS_REGISTRY, layers)?;
let settings = Settings::read(&resolved)?;   // typed, and every failure at once
println!("{}", settings.task.output);

The decisions worth reviewing

Dotted keys are nested structs. settings.task.output is how the setting reads in the file, so
there is no reason for the code to spell it differently. Each group gets its own struct
(SettingsTask), named rather than inferred.

A field is Option<T> exactly when the resolution can come back with nothing — no declared
default, or option<T>. So a setting with a default is the value itself, with nothing to unwrap,
and there is no run-time failure for a shape the spec permits. Fold::required is still what reads
those fields, and its Missing arm is what makes the expect in generated code honest: required
returns None only when it has recorded an error, and finish has already turned any error into a
return.

An old name is not a field. Every read of a renamed key folds into the setting that replaced it,
so a field for it would be a second name for one value — config set old.key writing somewhere
nothing reads is the pitchfork bug in miniature.

Types: bool, i64, u64, f64, String, PathBuf, Vec<T> (for list and set —
the merge already dropped duplicates, and order is the meaning for a PATH), BTreeMap<String, T>,
and usage_config::Value where the spec declined to say (object, a union, a name usage does not
know). url and duration read as text: what makes a string a URL is what the CLI does with it,
and the crate that owns the duration type owns its spelling — inventing one here would put a
dependency in every adopter's binary for a value some only ever print.

Refused

• A key that is both a setting and a group — python beside python.compile: one field name
  with two things to be, a value and a table. The spec can say it; no struct can hold it.
• The four keywords Rust cannot spell (self, crate, super, Self). Every other keyword is
  fine: type and match are unremarkable names for settings, written r#type and r#match — for
  the field and for the local the reader binds it to, which is what let match: Option<String>
  taught me when the golden file stopped compiling.

Verification

The generated file is checked in and include!d, so cargo test compiles it: every field asserted
below has to exist with that type or the test target does not build. 19 tests. Four mutations —
allowing the value-and-table collision, allowing an unspellable keyword, dropping raw identifiers,
and letting an alias become a field — each killing the right test.

SettingsPartial and runtime_defaults are deliberately not here. They need the opposite
direction — a typed value turned back into layer entries — which is its own mechanism and its own
PR, not a struct with Options on it.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: unavailable.

---

Note

Medium Risk
Touches generated API surface and config read paths for every CLI adopter; validation is strong but mistakes in codegen would compile and misread settings at runtime.

Overview
Extends usage-config-build so generated settings.rs includes not only the registry and prop::* ids but also a nested Settings type (dotted keys → nested structs), Settings::read(&Resolved) that reads every field via fold and reports all errors at once, and field typing rules (Option when there is no default or the spec uses option<T>, skip renamed_to keys, r# for Rust keywords).

New config-build/src/settings.rs implements the tree builder, Rust type mapping (list/set → Vec, maps → BTreeMap, open types → usage_config::Value), and build-time refusals for ambiguous shapes (setting vs group under one prefix, colliding field/struct names from -/_ or case, unspellable keywords, read_* locals to avoid shadowing fold).

usage_config gains FromValue for Value so generated union/object fields can read without inventing narrower types.

Tests and golden output cover the match keyword setting, struct reads from files, coercion errors, and the new refusal cases.

^{Reviewed by Cursor Bugbot for commit b0ddb74. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 2a6363bf-0565-423b-a676-4d0aa77fab80

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR generates a typed, nested settings hierarchy alongside the configuration registry and reads all resolved values through a generated Settings::read.

• Maps dotted configuration keys to named nested structs and declared config types to Rust types.
• Rejects field and nested-struct names that would produce invalid or duplicate Rust declarations.
• Adds identity conversion for unresolved-shape Value fields and tests generated reads, type errors, identifiers, and collision refusals.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; both previously reported generated nested-type collision paths are rejected by the current recursive module-wide uniqueness check.

Important Files Changed

Filename	Overview
config-build/src/settings.rs	Generates typed settings structs and readers; the global recursive name check now covers both previously reported nested-type collision classes.
config-build/src/emit.rs	Appends the generated typed settings API after validating all registry and settings-generation problems.
config/src/read.rs	Adds lossless FromValue support for fields intentionally represented by the generic configuration value type.
config-build/tests/refusals.rs	Exercises invalid identifiers, field collisions, case collisions, and cross-depth nested-struct collisions.
config-build/tests/generated.rs	Verifies the generated settings shape, default and optional values, nested reads, file-layer values, and aggregate type errors.

_{Reviews (9): Last reviewed commit: "feat(config): generate the settings stru..." | Re-trigger Greptile}

[jdx]

Both right, and both are one root cause: I checked the key segments and generated the names.

Two segments can differ and still translate to one field — foo-bar beside foo_bar, since a dash
and an underscore are the same character in an identifier — and two groups can differ and still
translate to one struct, since camel uppercases the first letter and a beside A both become
SettingsA. Neither was refused, and neither is caught by the prop:: const check: foo-bar.x and
foo_bar.y make two distinct consts and one field. The check now runs on the emitted names, in the
two namespaces that exist — field names at each level (leaves and subgroups share it) and struct
names among subgroups.

The value-and-table case keeps its own message rather than being folded into the generic one; "python
and python both generate the field python" is technically true and much less use than "python is
a setting and a group of settings".

A key starting with a digit was the other half: the const path prefixed _ and the field path
did not, so 2fa.token generated pub const _2FA_TOKEN beside pub 2fa:. Same prefix on both now,
so the two spellings of one key agree, and _2fa colliding with a real _2fa is caught by the check
above.

Three mutations: dropping the field-collision check, dropping the struct-name check, and dropping the
digit prefix — each killing the right test. 19 tests in the crate.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: unavailable.

[jdx]

Both real, and the first one is my last fix stopping one level short.

Struct names are not per level. I fixed the sibling case and compared siblings — but every struct
is declared in one module and its name is built by concatenation, so http.client.timeout and
http_client.retries both arrive at SettingsHttpClient from different depths. The map is threaded
through the whole walk now, keyed on the full generated name, and the message names it:

`http.client` and `http_client` are both groups named `SettingsHttpClient`: rename one of them

A local could shadow the reader's own fold. A setting called fold generated
let fold = fold.optional(…), so every read after it — and fold.finish() — stopped compiling; a
setting called SELF generated let self, since the keyword check compares the segment and not the
lowercased ident. Nothing about fold is unusual for a config file, so the fix belongs on this side:
every local is prefixed (read_fold), which is injective over already-unique consts, so no name a
spec can choose reaches either state. The fields keep the names the config file uses.

Also fixed while there: task..output produced two problems, the second being a group named after
something the author never wrote — an invalid key is refused by name and no longer builds a tree.

Three mutations: comparing siblings only, dropping the local prefix, and letting a bad key build a
tree — each killing the right test. 25 tests in the crate.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: unavailable.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit be12792. Configure here.}

[jdx]

Real, and reachable: a"b is a nameable key — it has letters in it — and the generated reader quotes
the key into an expect message. Interpolated raw, the quote ended that literal early and the rest of
the message read as code, in a file the adopter did not write. The key goes through the same escaper
PropMeta has used all along.

Doc comments are the other half and need the opposite treatment — no escapes, one line — so keys and
group names there go through one_line. That fix is in #864 as well, where the prop:: consts carry
their key in a doc comment too.

Mutation: interpolating the key raw into the message fails the new test, which checks all three
places one key lands — the literal, the PropMeta, and the comment.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: unavailable.

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▁▁▂▂▂███	175,112,529 → 175,122,691	+0.01%	15.80 → 15.88ms	+0.49%
startup	▁▁▁▁▁▁███	1,222,031 → 1,222,135	+0.01%	0.95 → 0.93ms	-1.92%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

	usage	clap	ratio
instructions, cold parse	29823	5960254	199x

usage: argv -> struct                             843 ns      0.84 µs
clap: build tree + parse -> struct             498154 ns    498.15 µs
clap: parse -> struct, tree reused              24039 ns     24.04 µs
clap: build tree only                          311212 ns    311.21 µs

_{b0ddb74af5d0 vs 7735e3540047 · measured on the runner, not pushed to the history.}

[jdx]

Real, and I had missed it in the last sweep — replying to a later finding made my "unaddressed" filter
skip it.

A Rust identifier is not "any alphanumeric character": ½ is one and cannot appear in an identifier,
and a Unicode digit cannot start one. field and camel kept anything is_alphanumeric, while the
prop:: consts were built from ASCII all along — so one key produced names from two alphabets, a const
the adopter could compile beside a field they could not. Both are ASCII now, which also means the const
and the field derive from the same rule, and a key that collapses to something already taken is caught
by the collision check that was already there.

prop "café.si½e"  ->  prop::CAF__SI_E,  settings.caf_.si_e

The key itself stays exactly as the spec wrote it in PropMeta, because there it is data rather than a
name. The test asserts that, and that every line of generated code which declares a name is ASCII.

Two mutations, one per function, each killing it.

AI-assisted — Tool: Claude Code; model: anthropic/claude-opus-5; version: unavailable.