config-validation-and-normalization

Config Validation and Normalization

Responsibilities are split across exactly three places. Keep them there.

defineConfig() — normalize and stamp, never throw

defineConfig (in @internal/config/config-types) is the ONLY place normalization happens. It applies defaults (e.g. contract.output), stamps the non-enumerable config-format version marker, and returns the normalized config. It does NOT validate structure and never throws — a throw here happens at module-evaluation time, which would turn every structural problem into an all-commands-fail evaluation error and defeat per-section diagnostics.

The marker does not survive spreads: configs must export the defineConfig result directly. The loader rejects unmarked configs with CONFIG.VERSION_MARKER_MISSING.

Loader — validate into per-section diagnostics

loadConfig (in @internal/config-loader) returns Result<{ config, diagnostics }, CliStructuredError>:

• Failures that prevent evaluation entirely are the Result failure: CONFIG.FILE_NOT_FOUND, CONFIG.EVALUATION_FAILED, CONFIG.VERSION_MARKER_MISSING. Every command fails early with these.
• Structural problems inside an evaluated config never fail the load. collectConfigIssues (in @internal/config/config-validation) returns every problem, each tagged with the top-level section it concerns; the loader wraps them as CONFIG.VALIDATION_FAILED diagnostics with meta.section and meta.field.

Commands — declare the sections they read

Commands access config only through loadConfigForSections(configPath, sections) (or requireConfigSections when they need the diagnostics list). A command fails (exit 2, rendering the diagnostic) only when a diagnostic concerns a section it declared; broken unrelated sections don't block it.

const configResult = await loadConfigForSections(options.config, [
  'family', 'target', 'adapter', 'driver', 'extensions', 'db',
]);
if (!configResult.ok) {
  return configResult;
}
const config = configResult.value;