Repository navigation
fix(config): warn when a section key looks like a misspelled field - #19032
Conversation
UX Review (Opus 5.5, fork) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Check before merge: a key that an older build wrote under a since-renamed field (e.g. What this change shipsInventory (5 items) — 5 justifiedIntent: an operator who misspells a key inside a config section is told at load which field they probably meant. This is a FIX: today the typo does nothing and only logs at DEBUG.
[FIRST-PRINCIPLES-REVIEWED] 0b5f152 Description read[DESCRIPTION-READ] 49854c184af1480a01e5702174fa950370c2dee17dd3cdaf4c23f9a4a50d1ce2 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5, fork) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS A field renamed with a small edit leaves its old key close to the new name, so the warning may fire on every disk read about a key the product itself kept. Watch
[DESIGN-REVIEWED] 0b5f152 Description read[DESCRIPTION-READ] 49e03e19ed261c95e23225a93d7af17055cc9389e186cba815c2b9b54467334e That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
Symptom: a key inside a modelled section that no field reads, such as agent.subagent_timeout_sec beside the real subagent_timeout_secs, loaded with no warning. The setting kept its default, and the only trace was a DEBUG line. A misspelled top-level section is reported at WARNING. Root cause: the unknown nested keys are found by capture_extra_section_keys, which keeps them for the save round-trip and logs them at DEBUG only. Change: on a disk read, build_config calls warn_misspelled_section_keys over the merged document. It logs one WARNING naming each unknown key that is close to a real field of its section (difflib), with that field. Keys with no close field stay at DEBUG, and the round-trip capture is unchanged.
2ede38c to
0b5f152
Compare
iamwhatever
left a comment
There was a problem hiding this comment.
This PR logs one WARNING per disk read when an unknown key inside a modelled config section (or inside a named record such as agents.<name>) is within difflib 0.8 of a real field, and names the field it resembles. That fixes the root cause: today a typo has no effect and leaves only a DEBUG trace. I read the full diff. The classification moves into _collect_extra_section_keys with the DEBUG lines unchanged, so the round-trip capture behaves exactly as before. The warning reads the merged view, so an overlay typo is caught. It runs only when ConfigDocument.disk_read is true, which is the same cadence as the top-level warning. I checked the Design lane's concern that renamed keys would be called typos. Renames the product still reads, such as knowledge.auto_ingest_doc_links and agent.yolo, are in _SECTION_KEYS_EMITTED_ELSEWHERE/_DELIBERATELY_DROPPED and are never collected, so they cannot warn. Any other near-match key really has no effect, so "kept in the file but not in effect" is a true statement. The message logs key names only, never values, so nothing secret leaks. The tests fail on main and pass here. The cache test changes the file size, so it does not depend on mtime resolution. One non-blocking nit: AGENTS.md asks for docs/system-specs/modules/config.md (around lines 1316-1333) to describe the new warning and its disk-read-only timing in the same commit. Please add that, and answer the open Design CONCERNS items on the PR. — crew-pr-reviewer (deep re-check)
Problem / Motivation
Goal: A key inside a config section that looks like a misspelled field is reported at load, naming the field it resembles.
A key inside a modelled section that no field reads loads with no warning. For example,
agent.subagent_timeout_secsits beside the real fieldagent.subagent_timeout_secs.The setting the operator meant keeps its default, and the only trace is a DEBUG line from
capture_extra_section_keys(src/kiro_crew/config/resolution.py).A misspelled top-level section, by contrast, is reported at WARNING (
Config: unrecognized top-level keys: ...).Why it matters
A typo in a hand edit (
kirocrew config edit, any editor) or inconfig set --locallooks like a setting that does nothing, with no signal to the operator.The dashboard settings view hides unknown keys on purpose (
drop_extra_section_keys), so the typo cannot be spotted there either.Not a goal
src/kiro_crew/tests_fixturescarriesdashboard.host, for example, and warning about those would report the product's own bookkeeping as an operator mistake.capture_extra_section_keysstill keeps every unknown key, andsave()still writes it back.kirocrew config set --localpath (src/kiro_crew/cli_config.py). It checks only the top-level section name before writing. A misspelled key it writes is now reported on the next load, and refusing it at the CLI is a separate change.What changed (motivation → approach → change)
capture_extra_section_keys, which keeps them forsave()and logs them at DEBUG._collect_extra_section_keys, whichcapture_extra_section_keyscalls with its DEBUG lines unchanged.warn_misspelled_section_keys(data, cfg)logs ONE WARNING per load that reads the files, naming each unknown key whose closest field in the same section passes adifflibratio of 0.8 (_MISSPELLING_CUTOFF), with that field:Config: unrecognized keys inside known sections, kept in the file but not in effect: agent.subagent_timeout_sec (did you mean agent.subagent_timeout_secs?). Named records are covered the same way (agents.<name>.<key>).build_configcalls it over the merged document, so a misspelling inconfig.local.jsonis reported as well, only when the newConfigDocument.disk_readfield is true (config/loader.py:5687).read_config_documentsets it on its disk-read return; a cache hit leaves it false, so a cached load does not repeat the warning. That is the same cadence as the top-level warning, which runs in validation on the disk-read path only.src/kiro_crew/tests_fixtures/*/config.json) carrydashboard.host, a key no field ofdashboardreads, so that rule would fire on each of them. Evidence: loading each fixture and listing whatcapture_extra_section_keyscaptures returnsdashboard.hostfor all 13. Reporting only keys close to a real field keeps the warning to likely typos.additionalProperties: falsein the schema. Validation would strip the key and break the round-trip.Backwards compatibility
Compatible: the loaded config and the saved file are unchanged; the change adds one WARNING line on loads that read a file with a likely misspelling.
Security: no redaction, auth, sandbox, permission or deny code changes (none in this branch's diff).
Removes nothing: no key, value or log line is removed; the DEBUG lines of
capture_extra_section_keyskeep their text.Tests
Added to
test/test_config_extra_keys.py, beside the round-trip tests:test_a_misspelled_section_key_is_reported_with_the_field_it_resembles: one WARNING namesagent.subagent_timeout_secand suggestsagent.subagent_timeout_secs; the real field keeps its default and the key is still captured for the round-trip.test_the_misspelling_warning_fires_once_per_disk_read: a cache-hit load adds no warning; a changed file is read again and reported again.test_an_unknown_key_with_no_close_field_is_not_reported(control):agent.retired_knobstays quiet and is still captured.test_a_misspelling_in_the_overlay_is_reported: a misspelling inconfig.local.jsonis reported.test_a_misspelled_key_inside_a_named_record_is_reported:agents.my-agent.modlesuggestsagents.my-agent.model.The tests count matching records, so they do not depend on log order.
Red on
origin/main7bb9d57 (this branch'stest/test_config_extra_keys.pycopied into a detached checkout of it),pytest test/test_config_extra_keys.py -p no:cacheprovider -q -n 0, RC=1 in 3 of 3 runs: 4 failed (the no-close-field test passes on both sides by design).Green on this branch, rebased onto 7bb9d57, the same command, RC=0 in 3 of 3 runs:
The 35 test files that name
capture_extra_section_keys,read_config_document,ConfigDocumentorbuild_config, with everytest_config_*.pyfile andtest_session_control.py, lesstest/test_config_loader.py, which reads the real home directory, run serially: 1735 passed, 1 skipped, exit 0. Gates exit 0: mypy, flake8, isort --check-only, black --check,scripts/check_black_formatting.py,COMMENT_HISTORY_BASE_REF=origin/main scripts/check_comment_history.py,scripts/check_harness_parity.py,scripts/docs-lint.sh.Manual verification
N/A — unit coverage sufficient: the tests drive
KiroCrewConfig.load()over real files intmp_path, including the cache-hit path.Related Issues
No existing issue found (GitHub search for
unrecognized top-level keys,unmodelled,_extra_keys,capture_extra_section_keys,misspelled config key).Related, merged: #8946 added the nested-key capture for the round-trip. #11729, #17365 and #17847 removed false positives from the top-level warning, which is why this one reports only likely misspellings.
Pattern harvest
Rule candidate: review-prompt
Pattern: a value preserved for round-trip but never read, with no WARNING-level signal that it has no effect.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)