Upgrade to Scala 3.7.4 and Modernization Audit

[hakimjonas]

Summary

This PR upgrades Valar to Scala 3.7.4 and Scala Native 0.5.9, and includes a comprehensive modernization audit analyzing opportunities to leverage recent Scala 3 improvements.

Changes

Upgrades

• ✅ Scala version: 3.7.1 → 3.7.4
• ✅ Scala Native: 0.5.8 → 0.5.9
• ✅ All tests passing (JVM + Native)
• ✅ Full compatibility maintained

New Documentation

• 📄 MODERNIZATION_AUDIT.md - Comprehensive analysis of modernization opportunities

Test Results

✅ JVM Tests: 88/88 passing
✅ Native Tests: 88/88 passing
✅ Compilation: Clean
✅ mdoc: Passing

Modernization Audit Highlights

Current State: Already Modern ✨

The audit confirms that Valar's metaprogramming architecture is already quite modern and well-designed:

• ✅ Clean quotes reflection API usage
• ✅ Strategic inline usage for zero-cost abstractions
• ✅ Well-structured macro derivation
• ✅ Excellent separation of concerns

Identified Opportunities

The opportunities are evolutionary, not revolutionary - focused on refinement rather than rewrites.

Phase 1: Quick Wins (v0.5.1) - ~8-10 hours

1. Transparent Inline for Better Type Inference

   • Add transparent inline to MacroHelper.upcastTo
   • Effort: 30 minutes | Risk: Very Low
   • Benefit: Better type inference at call sites

2. Enhanced Error Messages with Source Positions

   • Add source positions to macro error reports
   • Effort: 1 hour | Risk: Very Low
   • Benefit: Better developer experience and IDE integration

3. Split Macro Implementation

   • Refactor deriveValidatorImpl into separate sync/async macros
   • Effort: 6-8 hours | Risk: Low
   • Benefit: Better maintainability and compile-time performance

Total Estimated Effort: 8-10 hours

Phase 2: Type-Level Enhancements (v0.6.0) - 1-2 months

1. Inline Match Types for Field Analysis

   • More idiomatic Scala 3 style
   • Research branch required for validation

2. Compile-Time Validator Validation

   • Catch configuration errors at compile time
   • Enhanced user experience

3. Type-Level Field Path Construction

   • Zero runtime overhead
   • Better IDE integration
   • Major feature candidate

Phase 3: Future Exploration (v0.7.0+) - 6-12 months

1. Explicit Nulls Support (Scala 3.8+)

   • Eliminate runtime null checks
   • Major safety improvement

2. Capture Checking for Async Validation

   • Prevent reference escape bugs
   • Enhanced type safety

Scala 3.7.x Improvements Leveraged

The audit analyzed Scala 3.7.x release improvements:

• Enhanced inline method handling
• Improved metaprogramming and macro capabilities
• Better type class derivation
• More robust reflection API
• Better error messages and tooling

Inline Metaprogramming Analysis

Current inline usage is optimal:

// Zero-cost abstraction - perfect use case ✓
inline given noOpObserver: ValidationObserver with {
  def onResult[A](result: ValidationResult[A]): Unit = ()
}

// Enables dead-code elimination ✓
inline def observe()(using observer: ValidationObserver): ValidationResult[A] = {
  observer.onResult(vr)
  vr
}

// Minimal necessary casting ✓
inline def upcastTo[T](x: Any): T = x.asInstanceOf[T]

Performance & Compatibility

• ✅ Zero runtime performance impact
• ✅ Binary compatibility maintained (MiMa checks)
• ✅ TASTy compatibility maintained
• ✅ All documentation builds successfully

Recommendations

Immediate Next Steps

1. Merge this PR - Safe upgrade with no breaking changes
2. Plan v0.5.1 release - Implement Phase 1 quick wins (~2 weeks)
3. Create experimental branches - Validate Phase 2 enhancements

Long-term Strategy

The upgrade validates that Valar's architecture is forward-compatible and robust. Focus should be on:

• Incremental refinements for optimal performance
• Enhanced developer experience
• Monitoring Scala ecosystem for stabilized features

Breaking Changes

None. This is a fully backward-compatible upgrade.

Migration Guide

No changes required for library users. Simply update your Scala version to 3.7.4+ if desired.

Documentation

The MODERNIZATION_AUDIT.md document includes:

• Detailed analysis of current architecture
• Scala 3.7.x improvements assessment
• Prioritized modernization opportunities
• Phased implementation roadmap
• Testing strategy
• Performance optimization analysis

Review Focus Areas

1. ✅ Test results (all passing)
2. ✅ Build configuration changes
3. 📄 Modernization audit document completeness
4. 🎯 Phase 1 quick wins feasibility

---

Assessment: The codebase is in excellent shape. This upgrade confirms the architecture is modern, performant, and ready for future Scala improvements.