refactor: Improve testability of Singleton and Builder patterns

- Refactored Singleton.createShared() to throw SingletonError instead of fatalError
  - Makes the error path testable while maintaining fatalError for production use
  - Added SingletonError enum for better error handling
- Added tests for Singleton error path and error description
- Added explicit test for ValidatingBuilderProtocol default validate() implementation
- Improved Builder coverage to 100% (from 66.67%)
- Improved Singleton function coverage to 80% (from 50%)

Overall coverage improvements:
- Regions: 87.31% → 87.75%
- Functions: 88.24% → 90.29%
- Lines: 90.91% → 91.38%

Total tests: 96 (up from 94)

Author: rickhohler

Package.resolved

@@ -13,6 +13,18 @@ public protocol Singleton {
     static var shared: Self { get }
 }
 
+/// Singleton errors
+public enum SingletonError: Error {
+    case createSharedNotImplemented(String)
+    
+    public var localizedDescription: String {
+        switch self {
+        case .createSharedNotImplemented(let typeName):
+            return "Subclass '\(typeName)' must implement createShared()"
+        }
+    }
+}
+
 /// Thread-safe singleton base class
 ///
 /// Provides a base implementation for singleton pattern with thread-safe
@@ -49,11 +61,15 @@ open class ThreadSafeSingleton {
 
     /// Create shared instance (must be implemented by subclass)
     /// - Returns: Shared singleton instance
-    open class func createShared() -> Self {
-        fatalError("Subclass must implement createShared()")
+    /// - Throws: SingletonError if not implemented by subclass
+    open class func createShared() throws -> Self {
+        let typeName = String(describing: Self.self)
+        throw SingletonError.createSharedNotImplemented(typeName)
     }
 
     /// Shared singleton instance (lazy, thread-safe)
+    /// - Note: This will call `fatalError()` if `createShared()` is not implemented,
+    ///   as this indicates a programming error that should fail fast.
     public static var shared: Self {
         lock.lock()
         defer { lock.unlock() }
@@ -64,9 +80,14 @@ open class ThreadSafeSingleton {
             return existing
         }
 
-        let newInstance = createShared()
-        instances[typeID] = newInstance
-        return newInstance
+        do {
+            let newInstance = try createShared()
+            instances[typeID] = newInstance
+            return newInstance
+        } catch {
+            // This is a programming error - fail fast
+            fatalError(error.localizedDescription)
+        }
     }
 }
 

Sources/DesignAlgorithmsKit/Creational/Singleton.swift

@@ -304,6 +304,8 @@ final class BuilderTests: XCTestCase {
             }
 
             override func build() throws -> TestObject {
+                // Explicitly call validate() to ensure default implementation is covered
+                try validate()
                 guard let value = value else {
                     throw BuilderError.missingRequiredProperty("value")
                 }
@@ -318,6 +320,37 @@ final class BuilderTests: XCTestCase {
         XCTAssertEqual(object.value, 42)
     }
 
+    func testValidatingBuilderProtocolDefaultImplementation() throws {
+        // Given - Test the default validate() implementation directly
+        struct TestObject {
+            let value: String
+        }
+        
+        class DirectValidateBuilder: BaseBuilder<TestObject>, ValidatingBuilderProtocol {
+            private var value: String?
+            
+            func setValue(_ value: String) -> Self {
+                self.value = value
+                return self
+            }
+            
+            override func build() throws -> TestObject {
+                // Call validate() explicitly to test default implementation
+                try validate() // Default implementation does nothing
+                guard let value = value else {
+                    throw BuilderError.missingRequiredProperty("value")
+                }
+                return TestObject(value: value)
+            }
+        }
+        
+        // When/Then - Default validate() should not throw
+        let object = try DirectValidateBuilder()
+            .setValue("test")
+            .build()
+        XCTAssertEqual(object.value, "test")
+    }
+    
     func testValidatingBuilderWithCustomValidation() throws {
         // Given
         struct User {

Tests/DesignAlgorithmsKitTests/Creational/BuilderTests.swift

@@ -243,22 +243,34 @@ final class SingletonTests: XCTestCase {
 
     func testThreadSafeSingletonCreateSharedNotImplemented() {
         // Given - A singleton that doesn't override createShared()
-        // Note: We can't test fatalError directly in unit tests, but we can verify
-        // the class structure is correct. In a real scenario, accessing .shared would crash
-        // with fatalError because createShared() is not implemented.
         class NoCreateSharedSingleton: ThreadSafeSingleton {
             private override init() {
                 super.init()
             }
-            // Doesn't override createShared() - would cause fatalError if .shared is accessed
+            // Doesn't override createShared() - will throw SingletonError
         }
 
-        // When/Then - Verify the class can be defined and is a ThreadSafeSingleton
-        // The fatalError in createShared() would occur at runtime when accessing .shared
+        // When/Then - Test that createShared() throws SingletonError
+        XCTAssertThrowsError(try NoCreateSharedSingleton.createShared()) { error in
+            if case SingletonError.createSharedNotImplemented(let typeName) = error {
+                XCTAssertTrue(typeName.contains("NoCreateSharedSingleton"))
+            } else {
+                XCTFail("Expected SingletonError.createSharedNotImplemented, got \(error)")
+            }
+        }
+        
+        // Verify accessing .shared still causes fatalError (programming error)
+        // Note: We can't test fatalError directly, but we verify the error path exists
         let type: ThreadSafeSingleton.Type = NoCreateSharedSingleton.self
         XCTAssertNotNil(type)
     }
 
+    func testSingletonErrorLocalizedDescription() {
+        // Test SingletonError localizedDescription
+        let error = SingletonError.createSharedNotImplemented("TestSingleton")
+        XCTAssertEqual(error.localizedDescription, "Subclass 'TestSingleton' must implement createShared()")
+    }
+    
     func testThreadSafeSingletonInit() {
         // Given - Test that init() can be called
         class InitTestSingleton: ThreadSafeSingleton {