BE-834: Correct source attribution in hash-config diagnostics

[TimDiekmann]

🌟 What is the purpose of this PR?

Make source attribution in hash-config content diagnostics reliable after merging layers. If store.port is missing from every layer, the error now reports the missing key without blaming the file that supplied store.host. Invalid surviving values retain their supplying file or programmatic-default call site.

🔗 Related links

• Fixes BE-834: Correct source attribution in hash-config diagnostics (internal).
• Part of H-4170: Introduce config file for HASH (internal).
• Stacked on #9566: Load optional TOML files in hash-config. The PR base is that branch, so the diff contains only this provenance slice.

🚫 Blocked by

• #9566 must merge before this change can land on main.

🔍 What does this change?

• Omit enclosing-map source metadata for missing fields while preserving the full key path and selected profile.
• Render filenames directly and describe defaults as from programmatic defaults with their Rust call site.
• Add snapshots for nested scalars, array replacement in both orders, defaults surviving sibling overrides, and missing fields after multiple file merges. Keep rejected values out of reports.
• Document that missing required fields have no supplying source.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

Content errors identify the key and supplying source but do not include TOML line/column spans. Missing fields cannot identify a supplying source because no layer supplied the value.

🐾 Next steps

Retarget this PR to main after #9566 merges. Further provenance capabilities remain a separate slice.

🛡 What tests cover this?

41 unit, integration, and example tests, including the report snapshots, and 3 executable Rustdoc tests pass via test:unit. Existing tests also verify that later valid values can replace earlier invalid ones. Clippy with warnings denied, Rustdoc, and git diff --check pass.

❓ How to test this?

yarn workspace @rust/hash-config test:unit
cargo clippy --package hash-config --all-features --all-targets --no-deps -- -D warnings
cargo doc --package hash-config --all-features --no-deps

📹 Demo

invalid type: found string, expected u16 at `store.port` in `base.toml`
invalid type: found string, expected u16 at `store.port` from programmatic defaults (src/main.rs:42:5)
missing field `store.port`

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 7, 2026 3:31pm UTC

3 Skipped Deployments

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 7, 2026 3:31pm UTC
petrinaut	Skipped		Sep 7, 2026 3:31pm UTC
petrinaut-docs	Skipped		Sep 7, 2026 3:31pm UTC

[cursor]

PR Summary

Low Risk
User-facing error message formatting only in the local hash-config library; behavior is tightened and covered by snapshot tests.

Overview
Config load errors now attribute values to the layer that actually supplied them after merging defaults, required files, and optional files—instead of blaming unrelated files or generic provider names.

Missing required fields (e.g. store.port when only store.host exists in TOML) no longer cite a config file; the message is just missing field \store.port`. Invalid values still name the key and the winning source: **in `file.toml`** for file layers, or **from programmatic defaults** with the Rust call site for with_defaults`.

The defaults Figment provider is labeled programmatic defaults (was defaults). Diagnostic rendering uses Figment’s Source type so file paths appear directly without redundant in \file` (path)` wording. Integration tests and snapshots cover scalar/array merge order, defaults vs sibling file keys, and missing-field cases.

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

[Copilot]

🟢 Approval recommended

The implementation matches the stated provenance contract and covers the relevant merge scenarios.

Pull request overview

Corrects hash-config diagnostics so merged values retain accurate provenance while missing fields remain unattributed.

Changes:

• Preserve file/default sources for surviving invalid values.
• Remove misleading source metadata from missing-field errors.
• Add comprehensive provenance tests and snapshots.

File summaries

File	Description
src/defaults.rs	Names programmatic-default provenance.
src/error.rs	Corrects source selection and rendering.
src/lib.rs	Documents missing-field attribution behavior.
tests/files.rs	Tests scalar, array, default, and missing-field provenance.
files__file_invalid_value.snap	Updates filename rendering.
files__file_missing_required_value.snap	Verifies omitted source.
files__provenance_scalar_base.snap	Captures base scalar provenance.
files__provenance_scalar_override.snap	Captures override scalar provenance.
files__provenance_array_base.snap	Captures base array provenance.
files__provenance_array_override.snap	Captures override array provenance.
files__provenance_defaults_source.snap	Captures default call-site provenance.
files__provenance_missing_field.snap	Captures unattributed missing field.

Review details

• Files reviewed: 12/12 changed files
• Comments generated: 0
• Review effort level: Balanced

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 65.94%. Comparing base (be8b00f) to head (fb9da5b).

Additional details and impacted files

@@                                   Coverage Diff                                   @@
##           t/codex/h-4170-load-optional-toml-files-in-hash-config    #9567   +/-   ##
=======================================================================================
  Coverage                                                   65.93%   65.94%           
=======================================================================================
  Files                                                        1885     1885           
  Lines                                                      198188   198192    +4     
  Branches                                                     8232     8233    +1     
=======================================================================================
+ Hits                                                       130685   130692    +7     
+ Misses                                                      65972    65969    -3     
  Partials                                                     1531     1531           

Flag	Coverage Δ
rust.hash-config	81.14% <100.00%> (+1.56%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.