H-4170: Load optional TOML files in hash-config

[TimDiekmann]

🌟 What is the purpose of this PR?

Allow binaries to add a local TOML configuration file that may be absent. with_optional_toml_file("hash-graph.local.toml") leaves lower-priority values intact when the file is missing, while unreadable or malformed files still fail the load.

🔗 Related links

• Part of H-4170: Introduce config file for HASH (internal). This PR implements one delivery slice of that work.
• Builds on #9553: Load explicit TOML files in hash-config.

🚫 Blocked by

None.

🔍 What does this change?

• Add Loader::with_optional_toml_file. Read files at load time and skip only io::ErrorKind::NotFound; preserve other I/O causes, paths, and value redaction.
• Keep required and optional files in one ordered list above all defaults. Maps merge recursively; later scalars and arrays replace earlier values. Missing optional files contribute no values and do not waive required configuration fields.
• Add FileFormat::Toml to LoadError::ParseFile and use it in the existing error message. The selected parser determines the format, independent of the path's extension.
• Document the API with an executable example and extend the existing error snapshot tests to optional files.

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

Optional loading skips errors classified as NotFound, including missing parent directories. Automatic discovery and additional file formats remain outside this slice.

🐾 Next steps

Verify provenance for content diagnostics after merging multiple sources: attribute an invalid surviving value to its supplying source, allow later values to correct earlier ones, and avoid attributing missing required values to an arbitrary file.

🛡 What tests cover this?

37 unit, integration, and example tests, including existing report snapshots, and 3 executable Rustdoc tests pass. Coverage includes absent files and parent directories, deferred reads, removal before load, mixed file order above defaults, read/parse/deserialization errors, redaction, and explicit format selection. Clippy with warnings denied and Rustdoc also 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

The executable with_optional_toml_file Rustdoc example demonstrates a local file overriding a default port. No UI is involved.

[vercel]

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

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

3 Skipped Deployments

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

[cursor]

PR Summary

Medium Risk
Touches core configuration loading semantics for HASH binaries; behavior is well bounded (only NotFound is ignored) but mis-ordering optional vs required files could change effective settings.

Overview
Adds Loader::with_optional_toml_file so binaries can register a local TOML path that is ignored when missing (NotFound, including missing parent directories). Any other read failure, invalid UTF-8, or bad TOML still fails load, and a skipped optional file does not satisfy required config fields.

Required and optional paths now share one ordered FileSource list merged at load time (same precedence and merge rules as with_toml_file). LoadError::ParseFile carries a public FileFormat (currently TOML only) so parse errors name the selected parser, not the file extension.

Integration tests cover optional absence, deferred read/removal before load, mixed required/optional ordering, and extend existing error/redaction cases to optional layers.

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

[Copilot]

🟢 Approval recommended

The implementation matches the stated semantics and includes comprehensive coverage for precedence, absence, and error handling.

Pull request overview

Adds optional TOML configuration layers to hash-config while preserving required-file behavior and source precedence.

Changes:

• Adds Loader::with_optional_toml_file, skipping only missing files.
• Includes the selected format in parse errors.
• Expands tests for ordering, deferred reads, errors, and redaction.

File summaries

File	Description
libs/@local/config/src/lib.rs	Exposes and documents optional TOML loading.
libs/@local/config/src/file.rs	Implements required/optional file sources and format-aware errors.
libs/@local/config/src/error.rs	Adds file format details to parse errors.
libs/@local/config/tests/files.rs	Covers optional-file behavior and failure cases.

Review details

• Files reviewed: 4/4 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.93%. Comparing base (76497be) to head (be8b00f).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #9566   +/-   ##
=======================================
  Coverage   65.93%   65.93%           
=======================================
  Files        1885     1885           
  Lines      198175   198188   +13     
  Branches     8230     8232    +2     
=======================================
+ Hits       130672   130685   +13     
  Misses      65972    65972           
  Partials     1531     1531           

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

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.