SubMiner/backlog/tasks/task-69 - Harden-legacy-config-migration-validation-and-deprecation-handling.md

id, title, status, assignee, created_date, updated_date, labels, dependencies, priority, ordinal

id	title	status	assignee	created_date	updated_date	labels	dependencies	priority	ordinal
TASK-69	Harden legacy config migration validation and deprecation handling	Done	codex-main	2026-02-18 11:35	2026-02-19 23:18	config validation safety		high	65000

Description

src/config/service.ts still applies many legacy ankiConnect keys via unchecked casts (as string|number|boolean) in the mapLegacy block. Invalid legacy values can enter resolved runtime config without warnings and break downstream behavior.

Action Steps

1. Inventory every legacy key currently handled in mapLegacy.
2. Replace unchecked assignment with typed validators (asString, asNumber, asBoolean, enum guards).
3. Emit deprecation warnings for accepted legacy keys and validation warnings for invalid values.
4. Preserve backward compatibility for valid legacy configs.
5. Add regression tests for invalid legacy value types and accepted legacy values.
6. Update configuration docs with migration/deprecation notes.

Acceptance Criteria

• #1 No legacy key path writes directly to resolved config without type validation
• #2 Invalid legacy values produce warnings and safe fallback behavior
• #3 Valid legacy configs still map to equivalent resolved config
• #4 Config test suite includes legacy-invalid regression coverage

Implementation Plan

Implementation plan saved at docs/plans/2026-02-19-task-69-legacy-config-migration-hardening.md.

Execution breakdown:

1. Add failing regression tests for invalid legacy ankiConnect migration values and valid-legacy compatibility behavior.
2. Replace unchecked mapLegacy casts in src/config/service.ts with typed validators using asString/asBoolean/asNumber plus enum/range checks; warn on invalid legacy input and keep deprecation warnings.
3. Preserve modern key precedence and existing ankiConnect.openRouter deprecation behavior.
4. Run bun run build && bun run test:config:dist to verify.
5. Update docs/configuration.md only if migration/deprecation behavior clarification is needed.
6. Append notes and acceptance progress back into TASK-69.

Implementation Notes

Implemented legacy migration hardening in src/config/service.ts by filtering top-level legacy keys out of broad ankiConnect merge and replacing unchecked mapLegacy casts with parser-backed legacy mapping (asString/asBoolean/range+enum validators). Invalid legacy values now emit warnings and keep safe fallback values; valid legacy values still map when modern key is absent.

Added regression tests in src/config/config.test.ts: falls back and warns when legacy ankiConnect migration values are invalid and maps valid legacy ankiConnect values to equivalent modern config.

Updated docs in docs/configuration.md to clarify that legacy top-level ankiConnect migration keys are compatibility-only, validated, and ignored with warnings when invalid.

Verification: bun run build && bun run test:config:dist passed (32/32).

Definition of Done

• #1 bun run test:config:dist passes
• #2 Any doc changes for migration/deprecation are committed