4.0.0

Release SpecificationCore - standalone platform independent SPM with basic features, protocols, classes and macros support.

Version 2.0.0

SpecificationKit v2.0.0 Release Notes

Release Date: September 11, 2025

SpecificationKit v2.0.0 represents a major evolution of the Specification Pattern framework for Swift, introducing powerful macro capabilities, comprehensive async support, SwiftUI integration, and an expanded collection of built-in specifications. This release significantly enhances developer productivity through declarative APIs and compile-time code generation.

🎯 Highlights

• Complete Macro System: @specs and @AutoContext macros for automatic code generation
• Async-First Design: Full async/await support with AsyncSpecification protocol
• SwiftUI Integration: Reactive specifications with @ObservedSatisfies and environment providers
• Decision Specifications: Beyond boolean results with typed decision making
• Rich Specification Library: 7 new built-in specifications for common use cases
• Comprehensive Documentation: Complete DocC documentation with GitHub Pages deployment

🚀 New Features

Macro System

The headline feature of v2.0.0 is a complete macro infrastructure that eliminates boilerplate:

@specs Macro: Automatically generates composite specifications

@specs(MaxCountSpec.self, CooldownIntervalSpec.self)
struct UserActionSpec: Specification {
    typealias T = UserAction
}
// Generates: composite property, initializer, isSatisfiedBy(_:), and async bridge

@AutoContext Macro: Automatic context provider injection

@AutoContext
@specs(FeatureFlagSpec.self, UserSegmentSpec.self)  
struct PremiumFeatureSpec: Specification {
    typealias T = User
}
// Generates: static contextProvider, default initializer, async isSatisfied property

Advanced Macro Features:

• Comprehensive compile-time diagnostics with helpful error messages
• Type safety validation across specification arguments
• Generic type support with associated types
• Automatic async bridge generation

Asynchronous Specifications

Complete async/await support throughout the framework:

• AsyncSpecification Protocol: For async specification evaluation
• AnyAsyncSpecification: Type-erased async wrapper
• @AsyncSatisfies: Property wrapper for async evaluation
• Async Context Access: currentContextAsync() method on providers
• Bridge Methods: evaluateAsync() on synchronous wrappers

Decision Specification System

Move beyond boolean results with typed decision making:

• DecisionSpec Protocol: Return typed results from specifications
• @Decides Property Wrapper: Non-optional decisions with fallback values
• @Maybe Property Wrapper: Optional decision results
• FirstMatchSpec: Priority-based decision evaluation
• Builder Patterns: Fluent APIs for complex decision logic

SwiftUI Integration

Native SwiftUI support with reactive specifications:

• EnvironmentContextProvider: Bridge @Environment/@AppStorage to EvaluationContext
• @ObservedSatisfies: Automatic UI updates on context changes
• Observation System: Combine publishers and AsyncStream support
• Environment Integration: Complete SwiftUI examples in demo app

New Built-in Specifications

Seven new specifications for common business logic:

1. DateRangeSpec: Date range validation
2. DateComparisonSpec: Event-based date comparisons
3. FeatureFlagSpec: Feature flag evaluation
4. UserSegmentSpec: User segment targeting
5. SubscriptionStatusSpec: Subscription state validation
6. FirstMatchSpec: Priority-based decision making

All new specifications include comprehensive unit tests and conform to the enhanced Specification protocol with explicit context types.

Enhanced Demo Application

The demo app showcases all new features:

• Macro Usage Examples: Real-world @specs and @AutoContext demonstrations
• Async Demo Screen: Delay/error toggles and async evaluation
• Observation Demo: Live-updating specifications with SwiftUI
• SwiftUI Environment Integration: Complete environment provider examples

Comprehensive Documentation

Professional documentation suite:

• Complete DocC Documentation: All public APIs with rich examples
• GitHub Pages Deployment: Automated documentation publishing
• Cross-References: Modern DocC linking and Swift patterns
• Performance Guides: Best practices and optimization considerations

🔄 Breaking Changes

Context Provider Protocol

• Enhanced ContextProviding: Added currentContextAsync() method for async context access
• Migration: Implement async context methods or use default implementations

Specification Protocol Updates

• Explicit Context Types: All built-in specifications now use explicit Context associated types
• Migration: Update custom specifications to specify context types explicitly

Property Wrapper Changes

• Async Support: Property wrappers now support both sync and async evaluation patterns
• Migration: Existing synchronous usage remains compatible; async methods are additive

Macro-Generated Code

• Associated Type Usage: @specs macro generates members using associated type T
• Migration: Ensure specifications define typealias T for their candidate type

🐛 Bug Fixes

• Feature Flag Handling: FeatureFlagSpec now properly treats missing flags as failures
• Thread Safety: Enhanced thread safety in DefaultContextProvider state mutations
• Macro Reliability: Improved macro expansion reliability and error reporting
• Type Safety: Enhanced macro diagnostics for better compile-time validation

🔒 Security

• Thread-Safe Operations: All context providers implement safe concurrent access
• No Data Exposure: No sensitive data logging during specification evaluation
• Safe State Management: Protected context provider state mutations

📈 Performance

• Optimized Composition: Efficient specification composition with type erasure
• Macro Efficiency: Compile-time code generation reduces runtime overhead
• Async Efficiency: Native async/await patterns without blocking threads

🔧 Developer Experience

Enhanced Tooling

• Rich Diagnostics: Compile-time errors with actionable suggestions
• Type Safety: Full generic type support with compile-time validation
• IDE Integration: Complete code completion and documentation in Xcode

Testing Improvements

• Macro Testing: Swift-macro-testing framework integration
• Mock Providers: Enhanced testing utilities with controlled scenarios
• Async Testing: Comprehensive async behavior validation

CI/CD Pipeline

• GitHub Actions: Automated building, testing, and documentation deployment
• Multi-Platform: macOS testing with future iOS/tvOS/watchOS support
• Documentation: Automated DocC publishing to GitHub Pages

📋 Migration Guide

From v0.2.0 to v2.0.0

1. Update Context Providers: Implement currentContextAsync() or use default implementations
2. Add Context Types: Specify explicit context types in custom specifications
3. Adopt Macros: Replace manual composite specifications with @specs macro
4. Update Property Wrappers: Take advantage of new async evaluation methods
5. SwiftUI Integration: Migrate to @ObservedSatisfies for reactive UI updates

Recommended Upgrade Path

1. Update dependencies to v2.0.0
2. Run existing tests to identify breaking changes
3. Implement required context provider methods
4. Gradually adopt macros for new specifications
5. Explore async and SwiftUI features for enhanced functionality

🎯 What's Next

SpecificationKit v2.0.0 establishes a solid foundation for advanced specification patterns in Swift. Future releases will focus on:

• Swift Package Index: Official package registry submission
• Performance Optimization: Benchmarking and optimization of critical paths
• Advanced Macros: Experimental macro prototypes for specialized use cases
• Extended Platform Support: iOS, tvOS, and watchOS CI integration

📚 Resources

• Documentation: SpecificationKit DocC
• Source Code: GitHub Repository
• Demo Application: Complete examples in DemoApp/ directory
• Migration Guide: Detailed migration instructions in documentation

---

SpecificationKit v2.0.0 represents our commitment to making specification patterns accessible, powerful, and delightful to use in modern Swift development. The macro system, async support, and SwiftUI integration provide the foundation for building robust, maintainable applications with clear business logic separation.

0.2.0

Release 0.2.0 - Swift Macros and Composite Specifications

This release introduces initial support for Swift macros with the new @specs macro for defining composite specifications in a concise and declarative manner. Key highlights include:

• Added macro plugin target and registration to enable macro expansions.
• Integrated macros in the demo application to showcase usage.
• Enhanced the core specification pattern with reusable specs and composite capabilities.
• Introduced the @Satisfies property wrapper for declarative evaluation of specifications.
• Updated documentation with macro usage examples.
• Improved test coverage for macro expansions and core specifications.

This release builds upon the foundational core specification protocols and reusable specs introduced in 0.1.0, providing a more powerful and ergonomic API for specification composition and evaluation.