refactor(config): implement three-phase Parse → Validate → Complete architecture

[markphelps]

Config Refactor

1. Clear Three-Phase Architecture (Parse → Validate → Complete)

Before (main): Config loading was a monolithic process where parsing, validation, and CUDA resolution were interleaved and hard to follow.

After: Clean separation of concerns:

• Parse (parse.go) - Only YAML parsing, no side effects
• Validate (validate.go) - Semantic validation with typed errors
• Complete (config.go) - CUDA resolution, requirements loading

This makes the code easier to understand, test, and maintain.

2. Typed Error System

Before: Generic error returns with string formatting, hard to programmatically handle different error types.

After: Rich error types in errors.go:

• ParseError - YAML parsing failures
• SchemaError - Schema validation issues
• ValidationError - Semantic validation failures
• DeprecationWarning - Deprecated field usage
• CompatibilityError - Version incompatibilities

Callers can use errors.As() to handle specific error types differently.

3. Separation of Raw Config from Completed Config

Before: Single Config struct used for both raw YAML and completed config, with nullable fields mixed with populated fields.

After:

• configFile (unexported) - Raw YAML with pointer fields to distinguish "not set" from "zero value"
• Config - Completed config with resolved values

4. Better Deprecation Handling

Before: Deprecation warnings were ad-hoc and mixed with errors.

After: ValidationResult separates errors from warnings:

type ValidationResult struct {
    Errors   []error
    Warnings []DeprecationWarning
}

Can optionally treat deprecations as errors with WithStrictDeprecations().

5. Functional Options Pattern for Validation

Before: Hard-coded validation behavior.

After: Flexible configuration:

ValidateConfigFile(cfg,
    WithProjectDir(dir),
    WithRequirementsFS(fsys),
    WithStrictDeprecations(),
)

6. Bug Fixes

• Fixed Python version check for concurrency (now checks major version)
• Fixed path handling for Windows compatibility (filepath.Join vs path.Join)
• Removed dead code paths

7. Reduced API Surface

• Unexported internal types (configFile, buildFile, etc.)
• Unexported internal functions (validateCudaVersion, cudaBaseImageFor)
• Removed unused code (Example, Version, Stats structs)

8. Better Testability

• Each phase can be tested independently
• WithRequirementsFS() allows testing without real filesystem
• Typed errors make assertions clearer

9. Idiomatic Go

• Lowercase error messages
• Proper error wrapping with %w
• Marker interfaces for error types
• Functional options pattern
• Replaces internal slices package with stdlib
• Uses io.Reader where applicable instead of filenames as args for testability

[tempusfrangit]

This seems pretty reasonable. Please make sure wip is removed from the PR title. I'd also like @michaeldwan 's review on this before we merge.

[tempusfrangit]

Maybe it's time to drop this and error. we're doing a TON of big restructuring and this has been deprecated for a while. We can do this as a separate PR before release. I expect 0.17.0 can include this PR and the future removal of deprecated things.

[bfirsh]

Love this sentiment. Let's delete more things!