feat(config): explain why a setting has the value it has

[jdx]

config explain for every adopter, as a renderer rather than a reimplementation. Second PR of stack #858; depends on #856 only for sitting on top of it.

hk's version is the best of its kind in the fleet — it names the winning source and the exact identifier, and does per-item provenance for lists. It also costs about two hundred lines, and it is written against a second merge function that exists only to answer this question. Two merges can disagree, and when they do the explanation describes a resolution that never happened. Here there is one merge and its provenance is the answer, so this module reads what the merge recorded and formats it.

jobs = 8
  set by  HK_JOBS
  type    uint
          How many jobs to run at once

  also considered, lowest precedence first:
    the default
    hk.toml#jobs

  environment  HK_JOBS, HK_JOB
  also         git hk.jobs

What the wording is careful about

Each of these sends a user to the wrong place if it is careless:

• A default is not something anybody set, and neither is a post-merge rewrite — default and derived rather than set by. mise's raw implying jobs = 1 must not read as though a file said so, or the user goes looking for the file.
• The winner is not repeated among the things it beat.
• Asking after an old name answers about both, and reads the deprecation notice from the declaration that has one — the old one. Reading it off the setting that replaced it printed nothing for the only case where it matters, which the test caught.
• The type is the spec's spelling (uint, list<string>), not the prose an error message uses. A reader searching the docs for "a positive integer" finds nothing. That is a new Ty::name, distinct from the existing describe.

Also warnings, pairing each message with the place that caused it, and list for a config ls — sorted by key, because a registry's order is the order somebody wrote a TOML file in, and excluding hidden settings and old names, which are documented nowhere and would surface here for the first time.

Plain text on purpose: a CLI that wants JSON has the same Resolved this reads, and better taste than a library about what its own output should look like.

Eight tests, five mutations — the verbs, the winner appearing among the also-considereds, the deprecation source, hidden settings in the listing, and the sort — each verified to fail without its fix.

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

---

Note

Low Risk
User-facing text and warning formatting only; resolution merge logic is unchanged aside from clearer type-error strings.

Overview
Adds shared config explain rendering on top of existing merge provenance in Resolved—no second merge path. New explain, warnings, and list format plain text for one key, resolution warnings, and config ls (sorted keys, hidden/renamed keys omitted).

explain prints the winning value with shown, provenance verbs (default / derived / set by), spec types via new Ty::name, lower-precedence contributors, env/bindings hints, and deprecation along rename chains.

Supporting changes: one_line / shown in value.rs keep line-oriented output safe (newlines, empty [] / "" / {}); layer type-coercion warnings drop duplicated origin text so explain::warnings can append (origin) once; Ty coercion errors quote values with shown.

^{Reviewed by Cursor Bugbot for commit 59e00a7. 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: 33adb9d7-9c03-47cb-b9c6-7acfac937d69

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

Adds configuration explanation, warning, and listing renderers backed by the existing resolution provenance.

• Reports winning values, origins, contributors, declared types, metadata, bindings, and rename-chain deprecations.
• Adds stable one-line rendering for values and metadata while preserving literal path separators.
• Separates warning messages from their structured origins and adds sorted, visibility-aware configuration listings.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
config/src/explain.rs	Adds provenance-based explain, warning, and listing renderers; the previously reported line-boundary and path-rendering issues are addressed.
config/src/value.rs	Adds one-line and empty-value display helpers while deliberately preserving literal backslashes.
config/src/layer.rs	Removes duplicated origin text from warning messages while retaining the structured warning origin.
config/src/ty.rs	Adds specification-style type names and uses the new shown-value representation in coercion errors.
config/src/lib.rs	Exposes the new explanation module and its primary explain function.

_{Reviews (15): Last reviewed commit: "feat(config): explain why a setting has ..." | Re-trigger Greptile}

[cursor]

Bindings label assumes environment section

Low Severity

The bindings line is labeled also and has no leading blank line of its own, so it only reads as a continuation of environment. A setting with git or pkl bindings but no env vars gets a dangling also jammed against the type or help text.

 

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

[jdx]

Both real, and both about output that lies about its own shape.

A newline in a value broke the record boundary. Both renderers here are line-oriented — one setting per line for a listing, one fact per line for an explanation — and a multi-line string is a perfectly ordinary thing to put in a TOML file. Its continuation read as another setting, or as provenance. Values now render with newlines (and carriage returns, and the backslashes that would be ambiguous) escaped.

A setting with bindings and no environment variable had a dangling also. The blank line belonged to the environment section, so a git- or pkl-bound setting with no variables had its also line jammed against the type or help above it. The blank line now opens whichever section comes first.

Three mutations, each verified. The listing test asserts the line count as well as the content, so a value that splits into two records fails rather than merely looking odd.

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

Dismissed because a newer commit was pushed; Greptile will re-review the current head.

[jdx]

Right, and the fix belongs on the message rather than the renderer: a type error named the place in its own text and the Warning carried it, so the rendered line said the same file twice — for exactly the warnings that had bothered to be specific.

The message now says what is wrong and the renderer says where, which also means every warning renders the same way instead of two kinds needing two treatments. Test asserts the place appears exactly once; mutation-verified by putting it back.

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

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▁▁▁▁▂▂▂██	175,245,063 → 175,068,442	-0.10%	16.93 → 15.89ms	-6.17%
startup	▁▁▁▁▁▁▁▁██	1,222,129 → 1,222,055	-0.01%	1.00 → 0.98ms	-1.16%

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                             839 ns      0.84 µs
clap: build tree + parse -> struct             502684 ns    502.68 µs
clap: parse -> struct, tree reused              23512 ns     23.51 µs
clap: build tree only                          313841 ns    313.84 µs

_{59e00a7b2b56 vs fe13b0b9c7d8 · measured on the runner, not pushed to the history.}

[jdx]

Both right, and both the same class as the value fix — applied to the other two things interpolated into a line-oriented output.

An origin can carry a newline (a path may contain one), and a warning message quotes the value it rejected, which comes out of a file and can hold anything. Either one splitting its line makes the remainder read as another record; for warnings it hides every warning after it. So the escaping moved off the value and onto the shared helper, and all three go through it.

Two things about the verification. My first test covered only one of the two places an origin is rendered — the winner's line and the also-considered list are different branches — and the mutation for the other survived; both paths now carry a newline in the test. And I pushed once with a clippy failure in between (an import left unused by the change), because my gate command let the push run after the check reported. Caught on the next pass and fixed before this push; the branch is clean now.

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

[jdx]

Right, and worse than the problem it was solving: C:\Users\me\hk.toml came out with doubled separators, so a reader copying the path lands nowhere. The escaping now covers newlines and carriage returns only. The ambiguity that buys — a literal \n in text is indistinguishable from an escaped newline — is the right trade for output a human reads, whose one requirement is that a record stays on its line.

Test asserts a Windows path round-trips as written, and the mutation that reintroduces backslash doubling fails.

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

[jdx]

Right — same class again, and this time for the string most likely to contain a newline: an adopter's help is a doc comment, and a doc comment with a second paragraph is the ordinary case rather than an exotic one. Help, the deprecation notice, and the joined environment and binding lists all go through the helper now.

The test asserts the line count of a whole explanation rather than only the content, so anything splitting a record fails whether or not I thought to look for it. Both mutations verified.

That is four rounds on one small renderer, each finding a different string I had not routed through the escaping — which is a fair signal that the helper should have been applied at the point where a line is written rather than at each interpolation. If a fifth turns up I will restructure it that way instead of patching another call site.

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

[jdx]

Right, and it is the shape I only half-handled. Reading the notice off the replacement printed
nothing for the case that matters (a rename with a notice on the old name); reading it off the
asked-about name alone prints nothing when the notice sits further along — threads renamed to
concurrency, and concurrency the step carrying "use jobs instead". A rename is not itself an
explanation of what to do instead, so the notice worth printing is the first one along the chain.

deprecation_along walks from the asked-about name and stops at the first notice, bounded by the
number of settings there are — the same guard Registry::lookup uses, so a registry whose renames
form a cycle stops instead of hanging. (usage-config-build will refuse that registry outright;
until then, nothing here can be made to loop.)

Also in this commit: one_line moved to value.rs as a crate-internal helper, because #862 needs
the same rule for its failure lines and one rule shared by every renderer is one rule.

79 tests. Mutation: restoring the old lookup_exact-only read fails the new test.

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

[jdx]

One real, one I am going to leave as it is with the reasoning.

The padding was aligning a column that does not exist. Real, and worse than trailing
whitespace: the doc example above explain shows each contributor with its value beside it —
the default 4 — and the code cannot print that, because provenance keeps origins and not
values. So the width only ever padded the last thing on the line, and a path copied out of an
explanation stopped being the path the merge recorded. The padding is gone, the doc example now
shows what the function actually prints, and the contributors test asserts no line of an
explanation ends in whitespace.

The \n ambiguity I am keeping. It is real — a rendered newline and a literal backslash-n
look the same — but it is the deliberate trade recorded in the comment on one_line, and I got
there by trying the alternative. Escaping backslashes too renders every Windows path with doubled
separators (C:\\Users\\me\\hk.toml), so the common case becomes a path the reader cannot copy in
order to disambiguate the pathological one (a real newline inside a path). This output is for a
human, and the property it needs is that one record stays on one line. A CLI that needs values
unambiguously has the same Resolved and can render JSON, which is the note already in the module
doc.

79 tests. Mutation: restoring the padding fails the new assertion.

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

[jdx]

Right, and my own no-trailing-space assertion from the last round did not catch it — the fixture
had no empty value in it, and an empty value is a value.

Value::display writes a value the way a user would type it, and three of them are typed as nothing
at all: the empty string, the empty list, the empty map. Interpolated into key = {} that ends the
line after the =, with a trailing space and a truncated look — for a state that is perfectly
ordinary, since clearing a list is how a declared default gets turned off (HK_EXCLUDE=). Set is
not unset, and both are worth saying:

exclude = []
  set by  HK_EXCLUDE
stash = ""

The rule is one helper, shown, beside one_line in value.rs, and it is applied everywhere a
value is quoted into a message a human reads — explain, list, and the type errors ty::coerce
builds, which the merge's warnings render and which had the same "expected a list but has ``"
problem. Deliberately not folded into display itself: that is also what `config get` prints,
where an empty setting printing nothing is exactly right and `[]` would be a value nobody wrote.

The same fix lands in #862 for the reader's own errors, since that module quotes values the same way
and is in the same stack.

80 tests. Mutation: returning the value's text unconditionally fails the new test, which covers the
empty list and the empty string, in an explanation and in a listing, and re-checks that no line ends
in whitespace.

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

[cursor]

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

There are 2 total unresolved issues (including 1 from previous review).

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

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

[jdx]

Right, and worse than the finding says: read from the text, a one-item list holding the empty
string was indistinguishable from a cleared one, and two of them came out as ,.

Emptiness is now asked of the value, not of its rendering. And the underlying problem is that a list
is joined with commas, which hides any item whose own text is empty — so when an item would
disappear, the whole list is written out instead:

exclude = []          # cleared
exclude = [""]        # one item, which is not the same thing
exclude = ["",""]     # two, which used to be `,`
exclude = [a,""]      # the item the comma form would lose
exclude = a,b         # nothing to hide, so nothing to bracket

A map keeps its plain form even when a value is empty, because its keys are in the text (k=) and
that is enough to read.

Two mutations: not writing out a list whose items would vanish, and not marking the empty list, each
killing a test — the value test directly, and the explanation test through it.

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