@pilllesss/yorn 1.0.182 → 1.0.183

package/dist/skills/code-review/reference/swift.md

@@ -0,0 +1,936 @@
+# Swift Code Review Guide
+
+A code review checklist for modern Swift (5.9+/6), covering SwiftUI, Swift Concurrency, and the Swift API Design Guidelines.
+
+## Quick Review Checklist
+
+### Must-Check Items
+- [ ] Are force-unwraps (`!`) and `try!` avoided in favor of safe unwrapping
+- [ ] Do closures that capture `self` use `[weak self]` to avoid retain cycles
+- [ ] Is the value vs reference type choice intentional (struct vs class)
+- [ ] Are errors propagated with `throws`/`Result` instead of being swallowed
+- [ ] Are concurrency boundaries data-race-safe (`Sendable`, `@MainActor`, actors)
+
+### Common Issues
+- [ ] Fire-and-forget `Task {}` that leaks or is never cancelled
+- [ ] Wrong SwiftUI property wrapper (`@ObservedObject` where `@StateObject` is needed)
+- [ ] O(n^2) lookups in loops that could use a `Set` or `Dictionary`
+- [ ] Implicitly unwrapped optionals (`var x: T!`) outside of IBOutlets
+- [ ] Over-broad access control (`public`/`open` where `internal` suffices)
+- [ ] Naming that ignores the Swift API Design Guidelines
+
+---
+
+## 1. Optionals and Unwrapping
+
+### 1.1 Avoid Force-Unwrapping
+
+```swift
+// ❌ Wrong: crashes at runtime if nil
+let name = user.name!
+let url = URL(string: urlString)!
+
+// ✅ Correct: bind with guard let / if let
+guard let name = user.name else {
+    return
+}
+
+if let url = URL(string: urlString) {
+    load(url)
+}
+```
+
+### 1.2 Use Nil-Coalescing for Defaults
+
+```swift
+// ❌ Wrong: verbose and crash-prone
+let count: Int
+if let c = dictionary["count"] {
+    count = c
+} else {
+    count = 0
+}
+
+// ✅ Correct: nil-coalescing
+let count = dictionary["count"] ?? 0
+```
+
+### 1.3 Prefer guard let for Early Exit
+
+```swift
+// ❌ Wrong: deep nesting (pyramid of doom)
+func process(_ input: String?) {
+    if let input = input {
+        if let value = Int(input) {
+            if value > 0 {
+                handle(value)
+            }
+        }
+    }
+}
+
+// ✅ Correct: guard keeps the happy path unindented
+func process(_ input: String?) {
+    guard let input,
+          let value = Int(input),
+          value > 0 else {
+        return
+    }
+    handle(value)
+}
+```
+
+### 1.4 Avoid Implicitly Unwrapped Optionals
+
+```swift
+// ❌ Wrong: T! is a hidden force-unwrap on every access
+class ViewModel {
+    var service: NetworkService!
+}
+
+// ✅ Correct: inject a non-optional dependency
+class ViewModel {
+    private let service: NetworkService
+
+    init(service: NetworkService) {
+        self.service = service
+    }
+}
+```
+
+### 1.5 Use Optional Chaining and map/flatMap
+
+```swift
+// ❌ Wrong: manual unwrapping just to transform
+var initial: String?
+if let name = user.name {
+    initial = String(name.prefix(1))
+}
+
+// ✅ Correct: optional chaining + map
+let initial = user.name.map { String($0.prefix(1)) }
+
+// ✅ Correct: flatMap to avoid double optionals
+let port: Int? = components.port.flatMap { Int(exactly: $0) }
+```
+
+---
+
+## 2. Memory Management and Retain Cycles
+
+### 2.1 Use [weak self] in Escaping Closures
+
+```swift
+// ❌ Wrong: closure strongly captures self, creating a retain cycle
+class ImageLoader {
+    var onComplete: (() -> Void)?
+
+    func load() {
+        service.fetch { data in
+            self.cache = data   // self is retained by the closure
+            self.onComplete?()
+        }
+    }
+}
+
+// ✅ Correct: capture self weakly and guard
+class ImageLoader {
+    var onComplete: (() -> Void)?
+
+    func load() {
+        service.fetch { [weak self] data in
+            guard let self else { return }
+            self.cache = data
+            self.onComplete?()
+        }
+    }
+}
+```
+
+### 2.2 weak vs unowned
+
+```swift
+// ✅ Use weak when the reference can legitimately become nil
+class Controller {
+    weak var delegate: ControllerDelegate?
+}
+
+// ✅ Use unowned only when the captured object is guaranteed to
+//    outlive the closure (e.g. self owns the closure tightly).
+//    unowned crashes if accessed after deallocation.
+class Owner {
+    lazy var describe: () -> String = { [unowned self] in
+        self.name
+    }
+    let name = "owner"
+}
+
+// ❌ Wrong: unowned on something that can outlive self -> crash
+networkClient.onResponse = { [unowned self] in self.update() }
+// Prefer [weak self] here, since onResponse may fire after self is gone.
+```
+
+### 2.3 Break Delegate Retain Cycles
+
+```swift
+// ❌ Wrong: strong delegate keeps both objects alive forever
+protocol DataSourceDelegate: AnyObject {}
+
+class DataSource {
+    var delegate: DataSourceDelegate?   // strong by default
+}
+
+// ✅ Correct: delegates should be weak (and protocol AnyObject-bound)
+class DataSource {
+    weak var delegate: DataSourceDelegate?
+}
+```
+
+### 2.4 Closures Stored as Properties
+
+```swift
+// ❌ Wrong: stored closure captures self strongly -> permanent cycle
+class Timer {
+    var tick: (() -> Void)!
+    func configure() {
+        tick = { self.count += 1 }
+    }
+    var count = 0
+}
+
+// ✅ Correct: weak capture for stored closures referencing self
+class Timer {
+    var tick: (() -> Void)?
+    func configure() {
+        tick = { [weak self] in self?.count += 1 }
+    }
+    var count = 0
+}
+```
+
+---
+
+## 3. Value vs Reference Types
+
+### 3.1 Prefer Structs by Default
+
+```swift
+// ✅ Use a struct for data/models with value semantics
+struct Coordinate {
+    var latitude: Double
+    var longitude: Double
+}
+
+// Copies are independent; no shared mutable state, thread-friendly.
+var a = Coordinate(latitude: 1, longitude: 2)
+var b = a
+b.latitude = 99   // a is unchanged
+```
+
+### 3.2 Use a Class for Identity or Shared State
+
+```swift
+// ✅ Use a class when instances have identity or must be shared/mutated
+//    by reference, or when you need inheritance / Objective-C interop.
+final class DatabaseConnection {
+    private(set) var isOpen = false
+    func open() { isOpen = true }
+}
+
+// Two references point to the same connection.
+let conn1 = DatabaseConnection()
+let conn2 = conn1
+conn1.open()
+// conn2.isOpen == true
+```
+
+### 3.3 Mark Classes final When Not Subclassed
+
+```swift
+// ❌ Wrong: open to subclassing unintentionally (slower dispatch, fragile API)
+class UserViewModel {}
+
+// ✅ Correct: final enables static dispatch and signals intent
+final class UserViewModel {}
+```
+
+### 3.4 Beware Reference Types Inside Structs
+
+```swift
+// ❌ Surprising: struct copy still shares the inner class instance
+final class Box { var value = 0 }
+struct Container { var box = Box() }
+
+var x = Container()
+var y = x
+y.box.value = 42   // x.box.value is also 42 (shared reference!)
+
+// ✅ Correct: use value semantics throughout, or copy on write deliberately
+struct Container {
+    var value = 0   // plain value type, copies are independent
+}
+```
+
+---
+
+## 4. Error Handling
+
+> 📖 For cross-language error handling principles, see [Error Handling Guide](cross-cutting/error-handling-principles.md)
+
+### 4.1 Avoid try! and try?
+
+```swift
+// ❌ Wrong: try! crashes on any thrown error
+let data = try! Data(contentsOf: url)
+
+// ❌ Often wrong: try? silently discards the error and the cause
+let data = try? Data(contentsOf: url)   // data is nil, you lose "why"
+
+// ✅ Correct: propagate or handle with do-catch
+do {
+    let data = try Data(contentsOf: url)
+    process(data)
+} catch {
+    log.error("failed to read \(url): \(error)")
+}
+```
+
+### 4.2 Define Meaningful Error Types
+
+```swift
+// ✅ Recommended: an Error enum communicates failure modes precisely
+enum NetworkError: Error {
+    case invalidURL
+    case unauthorized
+    case server(statusCode: Int)
+    case decoding(underlying: Error)
+}
+
+func fetch(_ path: String) throws -> Data {
+    guard let url = URL(string: path) else {
+        throw NetworkError.invalidURL
+    }
+    // ...
+}
+```
+
+### 4.3 Use Result for Stored or Deferred Outcomes
+
+```swift
+// ✅ Result is useful at callback boundaries or when storing an outcome
+func load(completion: @escaping (Result<User, NetworkError>) -> Void) {
+    // completion(.success(user)) or completion(.failure(.unauthorized))
+}
+
+// ✅ Convert between Result and throws as needed
+let user = try result.get()
+```
+
+### 4.4 Typed Throws (Swift 6)
+
+```swift
+// ✅ Typed throws constrains the error type when it is fully known.
+//    Use it for closed, exhaustive error domains; prefer untyped
+//    `throws` for library APIs that may grow new error cases.
+func parse(_ raw: String) throws(ParsingError) -> Token {
+    guard let token = Token(raw) else {
+        throw ParsingError.malformed
+    }
+    return token
+}
+
+do {
+    let token = try parse(input)
+} catch {
+    // `error` is statically known to be ParsingError
+    handle(error)
+}
+```
+
+### 4.5 Don't Catch and Rethrow Without Value
+
+```swift
+// ❌ Wrong: catch that adds nothing but obscures the trace
+do {
+    try work()
+} catch {
+    throw error   // pointless
+}
+
+// ✅ Correct: only catch to add context or recover
+do {
+    try work()
+} catch {
+    throw AppError.workFailed(underlying: error)
+}
+```
+
+---
+
+## 5. Swift Concurrency
+
+> 📖 For cross-language concurrency patterns, see [Async & Concurrency Guide](cross-cutting/async-concurrency-patterns.md)
+
+### 5.1 Prefer async/await Over Nested Callbacks
+
+```swift
+// ❌ Wrong: callback pyramid, error handling scattered
+func loadProfile(completion: @escaping (Result<Profile, Error>) -> Void) {
+    fetchUser { userResult in
+        switch userResult {
+        case .success(let user):
+            fetchAvatar(user) { avatarResult in /* ... */ }
+        case .failure(let error):
+            completion(.failure(error))
+        }
+    }
+}
+
+// ✅ Correct: linear async/await
+func loadProfile() async throws -> Profile {
+    let user = try await fetchUser()
+    let avatar = try await fetchAvatar(user)
+    return Profile(user: user, avatar: avatar)
+}
+```
+
+### 5.2 Use @MainActor for UI State
+
+```swift
+// ❌ Wrong: mutating UI state from a background context (data race / crash)
+func refresh() async {
+    let items = try? await api.load()
+    self.items = items ?? []   // may run off the main thread
+}
+
+// ✅ Correct: isolate UI-facing types to the main actor
+@MainActor
+final class FeedViewModel: ObservableObject {
+    @Published var items: [Item] = []
+
+    func refresh() async {
+        let loaded = (try? await api.load()) ?? []
+        items = loaded   // guaranteed on the main actor
+    }
+}
+```
+
+### 5.3 Protect Mutable State with Actors
+
+```swift
+// ❌ Wrong: shared mutable state without synchronization (data race)
+final class Counter {
+    var value = 0
+    func increment() { value += 1 }
+}
+
+// ✅ Correct: an actor serializes access to its mutable state
+actor Counter {
+    private(set) var value = 0
+    func increment() { value += 1 }
+}
+
+let counter = Counter()
+await counter.increment()   // access is awaited and serialized
+```
+
+### 5.4 Conform Shared Types to Sendable
+
+```swift
+// ❌ Wrong: passing a non-Sendable class across actors (Swift 6 error)
+final class Config {        // mutable, not Sendable
+    var retries = 3
+}
+
+// ✅ Correct: make shared types Sendable (immutable value type is ideal)
+struct Config: Sendable {
+    let retries: Int
+}
+
+// ✅ For reference types, use final + immutable stored properties,
+//    or @unchecked Sendable only with manual synchronization.
+final class Cache: @unchecked Sendable {
+    private let lock = NSLock()
+    private var storage: [String: Data] = [:]
+    // all access guarded by lock
+}
+```
+
+### 5.5 Handle Task Cancellation
+
+```swift
+// ❌ Wrong: ignores cancellation, keeps working after the view is gone
+func search(_ query: String) async -> [Result] {
+    var results: [Result] = []
+    for page in 0..<100 {
+        results += await fetchPage(query, page)   // never stops
+    }
+    return results
+}
+
+// ✅ Correct: check for cancellation cooperatively
+func search(_ query: String) async throws -> [Result] {
+    var results: [Result] = []
+    for page in 0..<100 {
+        try Task.checkCancellation()
+        results += try await fetchPage(query, page)
+    }
+    return results
+}
+```
+
+### 5.6 Don't Leak Fire-and-Forget Tasks
+
+```swift
+// ❌ Wrong: unstructured Task with no handle, never cancelled
+final class ViewModel {
+    func onAppear() {
+        Task {
+            await self.stream()   // runs forever even after dismissal
+        }
+    }
+}
+
+// ✅ Correct: retain the handle and cancel it (or use .task in SwiftUI)
+final class ViewModel {
+    private var streamTask: Task<Void, Never>?
+
+    func onAppear() {
+        streamTask = Task { [weak self] in
+            await self?.stream()
+        }
+    }
+
+    func onDisappear() {
+        streamTask?.cancel()
+    }
+}
+```
+
+### 5.7 Use Structured Concurrency for Parallelism
+
+```swift
+// ❌ Wrong: sequential awaits where work could run concurrently
+let a = await loadA()
+let b = await loadB()   // waits for A to finish first
+
+// ✅ Correct: async let runs them concurrently
+async let a = loadA()
+async let b = loadB()
+let (resultA, resultB) = await (a, b)
+
+// ✅ For a dynamic number of children, use a task group
+try await withThrowingTaskGroup(of: Item.self) { group in
+    for id in ids {
+        group.addTask { try await fetch(id) }
+    }
+    for try await item in group {
+        store(item)
+    }
+}
+```
+
+---
+
+## 6. SwiftUI
+
+### 6.1 Choose the Right State Wrapper
+
+```swift
+// ✅ @State: simple value-type state owned by this view
+struct Toggle: View {
+    @State private var isOn = false
+    var body: some View { /* ... */ }
+}
+
+// ✅ @StateObject: the view CREATES and OWNS a reference-type model
+struct ProfileScreen: View {
+    @StateObject private var model = ProfileViewModel()
+    var body: some View { /* ... */ }
+}
+
+// ✅ @ObservedObject: the model is OWNED elsewhere and passed in
+struct ProfileHeader: View {
+    @ObservedObject var model: ProfileViewModel
+    var body: some View { /* ... */ }
+}
+
+// ✅ @Binding: a two-way reference to state owned by a parent
+struct SearchField: View {
+    @Binding var text: String
+    var body: some View { /* ... */ }
+}
+```
+
+### 6.2 @StateObject vs @ObservedObject
+
+```swift
+// ❌ Wrong: @ObservedObject for an object the view itself creates.
+//    SwiftUI may recreate the view, re-instantiating the model and
+//    losing its state on every re-render.
+struct CounterView: View {
+    @ObservedObject var model = CounterModel()   // recreated unexpectedly
+}
+
+// ✅ Correct: @StateObject ties the model's lifetime to the view
+struct CounterView: View {
+    @StateObject private var model = CounterModel()
+}
+```
+
+### 6.3 Preserve View Identity
+
+```swift
+// ❌ Wrong: index-based id reuses identity when the array reorders,
+//    causing wrong animations and stale state.
+ForEach(0..<items.count, id: \.self) { i in
+    ItemRow(item: items[i])
+}
+
+// ✅ Correct: use a stable, unique identifier
+ForEach(items) { item in   // Item: Identifiable
+    ItemRow(item: item)
+}
+
+// ✅ Use .id(...) to deliberately reset a view's state
+ProfileView(user: user)
+    .id(user.id)   // new identity per user -> fresh state
+```
+
+### 6.4 Avoid Over-Rendering
+
+```swift
+// ❌ Wrong: a single huge body re-renders everything on any change
+struct Dashboard: View {
+    @ObservedObject var model: DashboardModel
+    var body: some View {
+        VStack {
+            // header + heavy chart + list all recompute together
+        }
+    }
+}
+
+// ✅ Correct: extract subviews so only the affected part re-renders.
+//    Each child observes only the state it needs.
+struct Dashboard: View {
+    var body: some View {
+        VStack {
+            HeaderView()
+            ChartView()
+            ItemList()
+        }
+    }
+}
+```
+
+### 6.5 Do Async Work with .task
+
+```swift
+// ❌ Wrong: kicking off work in onAppear without cancellation
+.onAppear {
+    Task { await model.load() }   // not cancelled when view disappears
+}
+
+// ✅ Correct: .task is tied to the view's lifetime and auto-cancels
+.task {
+    await model.load()
+}
+
+// ✅ Re-run when an input changes
+.task(id: query) {
+    await model.search(query)
+}
+```
+
+---
+
+## 7. Protocols and Generics
+
+### 7.1 Protocol-Oriented Design
+
+```swift
+// ✅ Compose behavior with protocols and default implementations
+protocol Identifiable2 {
+    var id: String { get }
+}
+
+protocol Describable {
+    var description: String { get }
+}
+
+extension Describable {
+    var description: String { "no description" }   // default
+}
+```
+
+### 7.2 Prefer some Over any
+
+```swift
+// ❌ Slower: `any` is an existential box with dynamic dispatch
+func makeShape() -> any Shape { Circle() }
+
+// ✅ Faster: `some` is an opaque type resolved at compile time,
+//    preserving the concrete type and enabling static dispatch.
+func makeShape() -> some Shape { Circle() }
+
+// Use `any` only when you genuinely need heterogeneous values:
+let shapes: [any Shape] = [Circle(), Square()]
+```
+
+### 7.3 Generic Constraints Over Existentials
+
+```swift
+// ❌ Wrong: existential parameter loses the concrete type and is slower
+func logTotal(_ items: [any Numeric]) {
+    // awkward: the concrete numeric type is erased, so arithmetic needs casts
+}
+
+// ✅ Correct: a generic constraint keeps full type information
+func total<T: Numeric>(_ items: [T]) -> T {
+    items.reduce(.zero, +)
+}
+```
+
+### 7.4 Associated Types with Primary Associated Types
+
+```swift
+// ✅ Primary associated types (Swift 5.7+) allow lightweight constraints
+protocol Container<Item> {
+    associatedtype Item
+    var count: Int { get }
+    subscript(_ index: Int) -> Item { get }
+}
+
+// Constrain the element type without a where-clause:
+func first(in container: some Container<Int>) -> Int {
+    container[0]
+}
+```
+
+---
+
+## 8. Access Control and API Design
+
+### 8.1 Use the Narrowest Access Level
+
+```swift
+// ❌ Wrong: everything public exposes internal details as API surface
+public class Service {
+    public var cache: [String: Data] = [:]
+    public func reset() {}
+}
+
+// ✅ Correct: expose only the intended API; hide the rest
+public final class Service {
+    private var cache: [String: Data] = [:]
+    public func reset() { cache.removeAll() }
+}
+```
+
+### 8.2 private vs fileprivate vs internal vs public/open
+
+```swift
+// private:     visible only within the enclosing declaration (and its extensions in the same file)
+// fileprivate: visible within the same source file
+// internal:    visible within the module (the default)
+// public:      visible outside the module, but not subclassable/overridable
+// open:        visible outside the module AND subclassable/overridable
+
+// ✅ Use private(set) to expose read-only state
+public final class Account {
+    public private(set) var balance: Decimal = 0
+}
+```
+
+### 8.3 Follow the Swift API Design Guidelines
+
+```swift
+// ❌ Wrong: redundant words, unclear argument roles
+func insertObject(_ object: Element, atIndex index: Int)
+list.removeElement(at: 0)
+
+// ✅ Correct: read at the call site like a phrase; omit needless words
+func insert(_ element: Element, at index: Int)
+list.insert(item, at: 0)        // reads as "insert item at 0"
+list.remove(at: 0)
+
+// ✅ Boolean properties read as assertions
+var isEmpty: Bool
+var hasChanges: Bool
+```
+
+### 8.4 Name Methods by Side Effects
+
+```swift
+// ✅ Mutating verb vs non-mutating noun pairs (the "ed/ing" rule)
+var sorted = array.sorted()   // returns a new value (non-mutating)
+array.sort()                  // mutates in place (imperative verb)
+
+let reversed = text.reversed()
+text.reverse()
+```
+
+---
+
+## 9. Collections and Functional Style
+
+### 9.1 Prefer map/filter/compactMap
+
+```swift
+// ❌ Verbose: manual loop with mutable accumulator
+var names: [String] = []
+for user in users {
+    if user.isActive {
+        names.append(user.name)
+    }
+}
+
+// ✅ Correct: declarative transform
+let names = users.filter(\.isActive).map(\.name)
+```
+
+### 9.2 compactMap to Drop nils
+
+```swift
+// ❌ Wrong: map leaves an [Int?] you then have to unwrap
+let numbers = strings.map { Int($0) }   // [Int?]
+
+// ✅ Correct: compactMap removes nils and unwraps
+let numbers = strings.compactMap { Int($0) }   // [Int]
+```
+
+### 9.3 Avoid O(n^2) Membership Checks
+
+```swift
+// ❌ Wrong: contains on an Array is O(n); the loop is O(n*m)
+let result = candidates.filter { blocked.contains($0) }   // blocked: [ID]
+
+// ✅ Correct: a Set makes membership O(1)
+let blockedSet = Set(blocked)
+let result = candidates.filter { blockedSet.contains($0) }
+```
+
+### 9.4 reduce and Dictionary Grouping
+
+```swift
+// ✅ Group with Dictionary(grouping:)
+let byFirstLetter = Dictionary(grouping: words) { $0.first }
+
+// ❌ Wrong: reduce(into:) is preferred over reduce that copies each step
+let total = numbers.reduce(0) { $0 + $1 }   // fine for scalars
+
+// ✅ Use reduce(into:) when accumulating into a collection (avoids copies)
+let counts = words.reduce(into: [:]) { acc, word in
+    acc[word, default: 0] += 1
+}
+```
+
+### 9.5 Use lazy for Chained Transforms on Large Sequences
+
+```swift
+// ❌ Wrong: each step allocates an intermediate array
+let firstMatch = bigArray.map(expensive).filter(isValid).first
+
+// ✅ Correct: lazy avoids intermediate arrays and stops early
+let firstMatch = bigArray.lazy.map(expensive).filter(isValid).first
+```
+
+---
+
+## 10. Testing
+
+### 10.1 Arrange-Act-Assert with XCTest
+
+```swift
+import XCTest
+@testable import MyApp
+
+final class PriceCalculatorTests: XCTestCase {
+    func testDiscountApplied() {
+        // Arrange
+        let calculator = PriceCalculator(discount: 0.1)
+        // Act
+        let total = calculator.total(for: 100)
+        // Assert
+        XCTAssertEqual(total, 90, accuracy: 0.001)
+    }
+}
+```
+
+### 10.2 Testing async Code
+
+```swift
+// ✅ Mark the test method async and await directly
+func testFetchUser() async throws {
+    let service = UserService(client: MockClient())
+    let user = try await service.fetchUser(id: "42")
+    XCTAssertEqual(user.id, "42")
+}
+
+// ✅ Assert that an async call throws the expected error
+func testFetchUserUnauthorized() async {
+    let service = UserService(client: UnauthorizedClient())
+    do {
+        _ = try await service.fetchUser(id: "42")
+        XCTFail("expected to throw")
+    } catch NetworkError.unauthorized {
+        // expected
+    } catch {
+        XCTFail("unexpected error: \(error)")
+    }
+}
+```
+
+### 10.3 Inject Dependencies via Protocols
+
+```swift
+// ✅ Depend on a protocol so tests can substitute a mock
+protocol HTTPClient {
+    func get(_ url: URL) async throws -> Data
+}
+
+struct MockClient: HTTPClient {
+    var result: Result<Data, Error>
+    func get(_ url: URL) async throws -> Data {
+        try result.get()
+    }
+}
+```
+
+### 10.4 Avoid Sleeps; Await Expectations or Values
+
+```swift
+// ❌ Wrong: arbitrary sleep makes tests slow and flaky
+func testCallback() {
+    var done = false
+    object.run { done = true }
+    Thread.sleep(forTimeInterval: 1)
+    XCTAssertTrue(done)
+}
+
+// ✅ Correct: use XCTestExpectation for callback APIs
+func testCallback() {
+    let expectation = expectation(description: "callback fired")
+    object.run { expectation.fulfill() }
+    wait(for: [expectation], timeout: 1.0)
+}
+
+// ✅ Better: refactor to async and await the value directly
+func testCallback() async {
+    let value = await object.run()
+    XCTAssertEqual(value, expected)
+}
+```
+
+---
+
+## References
+
+- [Swift API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/)
+- [The Swift Programming Language](https://docs.swift.org/swift-book/)
+- [Swift Concurrency (TSPL)](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency/)
+- [Migrating to Swift 6](https://www.swift.org/migration/documentation/migrationguide/)
+- [Apple: Managing Model Data in Your App (SwiftUI)](https://developer.apple.com/documentation/swiftui/managing-model-data-in-your-app)
+- [Apple: Automatic Reference Counting](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/automaticreferencecounting/)
+- [WWDC: Protocol-Oriented Programming in Swift](https://developer.apple.com/videos/play/wwdc2015/408/)
+- [Swift Evolution](https://github.com/apple/swift-evolution)