Intermediate Issue: Validate index.yml on load, including bad types, unknown keys, and legacy array-shaped collections #58
Description
Type
Configuration improvement
Area
Configuration and YAML catalogs
Difficulty
Intermediate
Maintainer Guidance Needed
High
Problem
loadConfig() currently parses YAML and casts it directly to CollectionConfig without structural validation. That leaves room for silent misconfiguration, confusing runtime behavior, and legacy array-shaped collections values that some helpers partly support and others do not.
Why It Matters
Configuration errors should fail fast and clearly. Right now, a malformed index.yml can surface much later as odd behavior in listing, path resolution, or default-collection selection.
Scope
Add schema validation for index.yml on load, with explicit error messages for invalid shapes, unknown keys, wrong types, and legacy array-style collection configs. Preserve the current object-based config format as the supported shape.
Acceptance Criteria
- Invalid top-level config structures fail with clear, actionable error messages.
- Unknown keys are surfaced clearly rather than ignored silently.
- Legacy array-shaped
collectionsvalues no longer produce ambiguous downstream behavior. - Focused tests cover valid config, invalid types, unknown keys, and legacy array input.
Relevant Files
engine/catalogs.tsspecs/catalogs-config.test.tsCONTRIBUTING.mdorREADME.mdif the supported config shape is clarified
Testing
- Add focused config-validation tests.
- Run
npm run build. - Run the affected catalog/config tests.
Non-goals
- A full auto-migration tool for every historical config shape
- Redesigning the config format
- Adding interactive config editing
Difficulty Rationale
This is cross-cutting config hardening work that needs careful compatibility judgment and good test coverage.
Checklist
- I searched open and recently closed issues before drafting this task.
- The issue is scoped to one focused PR.
- The likely files and verification steps are listed.