[PR #373] [MERGED] test(config): fail when the reference or bundled config drifts from cfg.rs #383

New issue

Closed

opened 2026-10-29 14:22:51 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 14:22:51 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/373
Author: @yingdi-shan
Created: 10/12/2026
Status: ✅ Merged
Merged: 10/13/2026
Merged by: @yingdi-shan

Base: main ← Head: refactor/config-reference-check

📝 Commits (1)

f0f102b test(config): fail when the reference or bundled config drifts from cfg.rs

📊 Changes

2 files changed (+158 additions, -0 deletions)

View changed files

📝 docs/src/configuration/reference.md (+28 -0)
📝 src/cfg.rs (+130 -0)

📄 Description

What

Two tests in src/cfg.rs walk the confique schema (AppConfig::META):

configuration_reference_documents_every_key: every config key must appear in docs/src/configuration/reference.md, and every key the reference lists must exist in the schema.
bundled_default_config_sets_only_known_keys: config/default.toml may only set keys that the schema reads.

The first test found 11 undocumented keys. This PR documents them.

Why

Each config key is defined in src/cfg.rs and repeated by hand in config/default.toml and the reference doc. Seven of the 15 largest recent PRs edited all three. The only existing check was that the bundled file parses. confique ignores unknown keys, so a misspelled or removed key in default.toml loads without complaint, and a key missing from the reference goes unnoticed.

N/A. Follow-up to the review behind #367.

Scope and non-goals

Tests and docs only. No config behavior changes.
Not included: generating the reference from cfg.rs. Many fields have no doc comments, and the reference holds richer prose (validation rules, examples, cross-links). Generating it would rewrite the whole document. With the tests in place, drift fails CI instead.
Not included: removing unused keys. pool.network.startup_prewarm is never read. pool.block.maintenance_enabled is ignored, because the block pool always refills at request time. Both are documented as they behave; removing them is a separate decision.

Design and behavior changes

Newly documented keys:

Section	Keys
`[image.resolver]`	`convert_standard_oci`
`[machine.disk_rate_limit]` (new section)	`enabled`, `bandwidth_bytes_per_sec`, `bandwidth_burst_bytes`, `iops`, `iops_burst`
`[pool.network]`	`enabled`, `startup_prewarm`
`[pool.block]`	`maintenance_enabled`
`[ublk.overlaybd]`	`remote_io_workers`
`[overlaybd]` (new section)	`version`, `package_url`, `url`

How the reference parser reads the doc:

A ## `[section]` heading sets the key prefix, and ## Global Settings means top-level keys.
A row may name its subsection in the first column, as the [pool] component table does.
[protoc] is skipped, because it documents config/deps_manifest.toml.
A schema leaf that deserializes a whole table (backend.oss, backend.posix_fs, overlaybd) counts as documented through its subkeys.

Compatibility and operations

Public API or generated protocol: none.
Configuration or defaults: none.
Snapshot manifest, artifact layout, or storage format: none.
Upgrade and rollback: none.
Host requirements, permissions, ports, or dependencies: none.

Validation

make fmt
make clippy
make test-unit
Relevant Rust integration tests
make -C services test (required when services/ changes)
Generated clients/server regenerated with the documented make target
Documentation updated
Benchmarks or performance comparison completed

Commands and results:

make fmt                                            # clean
make clippy                                         # clean
cargo test -p agentenv -p envd -p linux-cap --lib   # agentenv: 964 passed, 4 ignored; envd: 3 passed

Checks that the new tests catch drift:

Deleting the remote_io_workers row from the reference fails with missing keys: ["ublk.overlaybd.remote_io_workers"].
Renaming it to remote_io_worker in config/default.toml fails with config/default.toml sets keys that src/cfg.rs does not read: ["ublk.overlaybd.remote_io_worker"]. bundled_default_config_loads still passes in that case.

Skipped checks and reasons:

make test-unit capability tests (--ignored) and integration suites: tests and docs only.

Risks and reviewer notes

The new doc rows describe current code. Please check the wording for [overlaybd] (from src/setup/overlaybd.rs) and [machine.disk_rate_limit] (from its field docs and validate_disk_rate_limit).
From now on, a PR that adds a config key must add a reference row in the same PR, or CI fails.

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by tests, or I explained why testing is impractical.
Logs and examples contain no credentials, tokens, or private registry information.
I did not manually edit generated code without updating its source and regenerating it.

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/373 **Author:** [@yingdi-shan](https://github.com/yingdi-shan) **Created:** 10/12/2026 **Status:** ✅ Merged **Merged:** 10/13/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `refactor/config-reference-check` --- ### 📝 Commits (1) - [`f0f102b`](https://github.com/kvcache-ai/AgentENV/commit/f0f102bb0f4ee1296f8eec438390eb87f65de614) test(config): fail when the reference or bundled config drifts from cfg.rs ### 📊 Changes **2 files changed** (+158 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `docs/src/configuration/reference.md` (+28 -0) 📝 `src/cfg.rs` (+130 -0) </details> ### 📄 Description ## What Two tests in `src/cfg.rs` walk the confique schema (`AppConfig::META`): - **`configuration_reference_documents_every_key`:** every config key must appear in `docs/src/configuration/reference.md`, and every key the reference lists must exist in the schema. - **`bundled_default_config_sets_only_known_keys`:** `config/default.toml` may only set keys that the schema reads. The first test found 11 undocumented keys. This PR documents them. ## Why Each config key is defined in `src/cfg.rs` and repeated by hand in `config/default.toml` and the reference doc. Seven of the 15 largest recent PRs edited all three. The only existing check was that the bundled file parses. confique ignores unknown keys, so a misspelled or removed key in `default.toml` loads without complaint, and a key missing from the reference goes unnoticed. ## Related issue N/A. Follow-up to the review behind #367. ## Scope and non-goals - Tests and docs only. No config behavior changes. - **Not included: generating the reference from `cfg.rs`.** Many fields have no doc comments, and the reference holds richer prose (validation rules, examples, cross-links). Generating it would rewrite the whole document. With the tests in place, drift fails CI instead. - **Not included: removing unused keys.** `pool.network.startup_prewarm` is never read. `pool.block.maintenance_enabled` is ignored, because the block pool always refills at request time. Both are documented as they behave; removing them is a separate decision. ## Design and behavior changes Newly documented keys: | Section | Keys | |---|---| | `[image.resolver]` | `convert_standard_oci` | | `[machine.disk_rate_limit]` (new section) | `enabled`, `bandwidth_bytes_per_sec`, `bandwidth_burst_bytes`, `iops`, `iops_burst` | | `[pool.network]` | `enabled`, `startup_prewarm` | | `[pool.block]` | `maintenance_enabled` | | `[ublk.overlaybd]` | `remote_io_workers` | | `[overlaybd]` (new section) | `version`, `package_url`, `url` | How the reference parser reads the doc: - A `` ## `[section]` `` heading sets the key prefix, and `## Global Settings` means top-level keys. - A row may name its subsection in the first column, as the `[pool]` component table does. - `[protoc]` is skipped, because it documents `config/deps_manifest.toml`. - A schema leaf that deserializes a whole table (`backend.oss`, `backend.posix_fs`, `overlaybd`) counts as documented through its subkeys. ## Compatibility and operations - Public API or generated protocol: none. - Configuration or defaults: none. - Snapshot manifest, artifact layout, or storage format: none. - Upgrade and rollback: none. - Host requirements, permissions, ports, or dependencies: none. ## Validation - [x] `make fmt` - [x] `make clippy` - [ ] `make test-unit` - [ ] Relevant Rust integration tests - [ ] `make -C services test` (required when `services/` changes) - [ ] Generated clients/server regenerated with the documented `make` target - [x] Documentation updated - [ ] Benchmarks or performance comparison completed Commands and results: ```text make fmt # clean make clippy # clean cargo test -p agentenv -p envd -p linux-cap --lib # agentenv: 964 passed, 4 ignored; envd: 3 passed ``` Checks that the new tests catch drift: - Deleting the `remote_io_workers` row from the reference fails with `missing keys: ["ublk.overlaybd.remote_io_workers"]`. - Renaming it to `remote_io_worker` in `config/default.toml` fails with `config/default.toml sets keys that src/cfg.rs does not read: ["ublk.overlaybd.remote_io_worker"]`. `bundled_default_config_loads` still passes in that case. Skipped checks and reasons: - `make test-unit` capability tests (`--ignored`) and integration suites: tests and docs only. ## Risks and reviewer notes - The new doc rows describe current code. Please check the wording for `[overlaybd]` (from `src/setup/overlaybd.rs`) and `[machine.disk_rate_limit]` (from its field docs and `validate_disk_rate_limit`). - From now on, a PR that adds a config key must add a reference row in the same PR, or CI fails. ## Checklist - [x] The PR contains one coherent change and no unrelated formatting or refactoring. - [x] New behavior is covered by tests, or I explained why testing is impractical. - [x] Logs and examples contain no credentials, tokens, or private registry information. - [x] I did not manually edit generated code without updating its source and regenerating it. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 14:22:51 +00:00