@coralai/sps-cli 0.42.0 → 0.43.0

package/skills/swift/references/concurrency.md

@@ -0,0 +1,280 @@
+# Swift — Concurrency
+
+`async/await`, `Task`, actors, `@MainActor`, `AsyncSequence`, cancellation.
+
+## `async/await`
+
+```swift
+func fetchUser(id: String) async throws -> User {
+    let (data, _) = try await URLSession.shared.data(from: url(id))
+    return try JSONDecoder().decode(User.self, from: data)
+}
+
+// Caller
+let u = try await fetchUser(id: "u1")
+```
+
+`async` functions suspend at `await` without blocking a thread. `throws` propagates errors.
+
+## `Task`
+
+`Task` creates a new concurrent context.
+
+```swift
+// Fire-and-forget
+Task {
+    await sendAnalytics()
+}
+
+// Get a result
+let task = Task {
+    try await fetchUser(id: "u1")
+}
+let user = try await task.value
+
+// Detached — no inherited context, rare
+Task.detached(priority: .background) { await heavyWork() }
+```
+
+Prefer structured `Task {}` (inherits parent's priority, cancellation, actor). `Task.detached` only when you genuinely need to break the hierarchy.
+
+## Structured concurrency — `async let`
+
+```swift
+func loadScreen() async throws -> Screen {
+    async let user  = fetchUser(id: id)
+    async let feed  = fetchFeed()
+    async let prefs = fetchPrefs()
+    return Screen(user: try await user, feed: try await feed, prefs: try await prefs)
+}
+```
+
+All three requests start concurrently; `await` collects them. If one throws, the others are cancelled.
+
+## Task groups — dynamic parallelism
+
+```swift
+func loadAll(ids: [String]) async throws -> [User] {
+    try await withThrowingTaskGroup(of: User.self) { group in
+        for id in ids {
+            group.addTask { try await fetchUser(id: id) }
+        }
+        var users: [User] = []
+        for try await u in group { users.append(u) }
+        return users
+    }
+}
+```
+
+On error: cancel the group or rethrow. Siblings complete (or get cancelled if you throw).
+
+### Bounded concurrency
+
+```swift
+try await withThrowingTaskGroup(of: User.self) { group in
+    let limit = 10
+    var inFlight = 0
+    var iter = ids.makeIterator()
+
+    while let id = iter.next(), inFlight < limit {
+        group.addTask { try await fetchUser(id: id) }
+        inFlight += 1
+    }
+
+    var out: [User] = []
+    while let u = try await group.next() {
+        out.append(u)
+        if let id = iter.next() {
+            group.addTask { try await fetchUser(id: id) }
+        }
+    }
+    return out
+}
+```
+
+## Cancellation
+
+Cancellation is cooperative. A cancelled task continues unless it checks.
+
+```swift
+func work() async throws {
+    for item in bigList {
+        try Task.checkCancellation()     // throws CancellationError if cancelled
+        process(item)
+    }
+}
+```
+
+Most stdlib `async` calls check cancellation (`URLSession`, `Task.sleep`). Your own loops must opt in.
+
+## Timeouts
+
+```swift
+func withTimeout<T>(_ seconds: Double, _ op: @escaping () async throws -> T) async throws -> T {
+    try await withThrowingTaskGroup(of: T.self) { group in
+        group.addTask { try await op() }
+        group.addTask {
+            try await Task.sleep(nanoseconds: UInt64(seconds * 1e9))
+            throw CancellationError()
+        }
+        guard let first = try await group.next() else { throw CancellationError() }
+        group.cancelAll()
+        return first
+    }
+}
+```
+
+(In Swift 6, `ContinuousClock` / `withTaskGroup`'s timeouts are cleaner.)
+
+## Actors — shared mutable state
+
+An actor serializes access. Only one method runs at a time; readers wait.
+
+```swift
+actor Cache {
+    private var data: [String: Data] = [:]
+
+    func get(_ key: String) -> Data? { data[key] }
+
+    func set(_ key: String, _ value: Data) {
+        data[key] = value
+    }
+}
+
+let cache = Cache()
+let v = await cache.get("u1")     // await — crossing actor boundary
+```
+
+From outside, calls are `await`; inside the actor, they're synchronous. Don't expose internal mutable state; return values, not references to the actor's storage.
+
+## `@MainActor` — UI-thread isolation
+
+```swift
+@MainActor
+class ViewModel: ObservableObject {
+    @Published var state: State = .loading
+
+    func load() async {
+        state = .loading
+        do {
+            let u = try await service.fetch()    // hops off main for network
+            state = .loaded(u)                    // back on main — safe
+        } catch {
+            state = .error(error)
+        }
+    }
+}
+```
+
+Any view model / UI code runs on `MainActor` by default. `await` on non-MainActor code hops off the main thread; results return via `await`, preserving main-thread safety.
+
+Individual functions: `@MainActor func update(...) { ... }`.
+
+## `Sendable`
+
+Types crossing actor / Task boundaries must be `Sendable` — "safe to transfer across concurrency domains".
+
+```swift
+struct User: Sendable { ... }                 // struct of Sendable fields is Sendable
+final class Foo: Sendable { ... }             // needs: final, immutable, or internal sync
+```
+
+Swift 6 enforces Sendable at the compiler level. Common fixes:
+- Make the type a `struct` (value type, usually Sendable automatically).
+- Make reference types `final` and all fields `let` + `Sendable`.
+- For mutable types crossing boundaries, wrap in an `actor`.
+
+## `AsyncSequence` — streams
+
+```swift
+for try await line in fileHandle.bytes.lines {
+    process(line)
+}
+
+// Build your own
+struct Counter: AsyncSequence {
+    typealias Element = Int
+    struct Iterator: AsyncIteratorProtocol {
+        var i = 0
+        mutating func next() async -> Int? {
+            guard i < 10 else { return nil }
+            try? await Task.sleep(nanoseconds: 100_000_000)
+            defer { i += 1 }
+            return i
+        }
+    }
+    func makeAsyncIterator() -> Iterator { Iterator() }
+}
+
+for await n in Counter() { print(n) }
+```
+
+Great for paginated APIs, file reads, WebSocket messages.
+
+## Continuations — bridging callback APIs
+
+```swift
+func legacy(id: String, completion: @escaping (User?, Error?) -> Void) { ... }
+
+func fetch(id: String) async throws -> User {
+    try await withCheckedThrowingContinuation { continuation in
+        legacy(id: id) { user, error in
+            if let user = user { continuation.resume(returning: user) }
+            else if let error = error { continuation.resume(throwing: error) }
+            else { continuation.resume(throwing: URLError(.unknown)) }
+        }
+    }
+}
+```
+
+**Call `resume` exactly once.** Calling twice crashes; not calling leaks the coroutine. Use `withCheckedContinuation` during development (crashes on misuse); switch to `withUnsafeContinuation` in release if you need the perf.
+
+## Priority & throttling
+
+Task priorities: `.userInitiated`, `.userInteractive`, `.utility`, `.background`. Lower priority in background tasks; the scheduler throttles.
+
+```swift
+Task(priority: .background) { await indexDatabase() }
+```
+
+## Avoiding blocking
+
+Don't call blocking APIs from async code.
+
+```swift
+// ❌
+Task { sleep(5); await doThing() }
+
+// ✅
+Task { try await Task.sleep(nanoseconds: 5_000_000_000); await doThing() }
+```
+
+File I/O: use `URLSession` for network, `FileHandle.bytes` for async reads, or `Task.detached(priority: .utility)` for genuinely blocking calls.
+
+## Bridging to / from main thread
+
+```swift
+// From background, update UI on main
+Task { @MainActor in
+    self.state = .loaded
+}
+
+// Call a MainActor method from non-MainActor
+await viewModel.update()
+```
+
+Don't use `DispatchQueue.main.async` in new Swift code — `@MainActor` / `Task { @MainActor in ... }` is the native way.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `DispatchSemaphore.wait` to bridge async → sync | Restructure caller as async; semaphores deadlock the runtime |
+| `Task { await ... }.value` from sync code to "await" | Don't; make the caller `async` |
+| `DispatchQueue.main.sync` from background | `await MainActor.run { ... }` or `@MainActor` |
+| Unchecked continuations with complex flow | Use `withCheckedContinuation` during development |
+| Shared mutable struct state across tasks | Use an actor |
+| Detached tasks for everything | Structured `Task {}` inherits context; detached is an escape hatch |
+| Ignoring `Task.isCancelled` / `checkCancellation` in loops | Cancellation is cooperative |
+| `async` on sync functions "for consistency" | `async` has a cost; don't add without reason |
+| Storing `Task` references without cancellation story | Keep a handle; cancel on deinit / view disappearance |

package/skills/swift/references/idioms.md

@@ -0,0 +1,334 @@
+# Swift — Idioms
+
+Value types, optionals, protocols, closures, `guard`, pattern matching.
+
+## `let` / `var`
+
+`let` (constant) by default. `var` only when mutating.
+
+```swift
+let name = "A"
+var count = 0
+```
+
+## Value vs. reference types
+
+- `struct`, `enum`, `tuple` — value types; copied on assignment.
+- `class`, `actor` — reference types; shared.
+
+Default to `struct`. Use `class` when you need inheritance (`UIView` subclasses, for framework integration) or shared identity with mutable state. Use `actor` for shared mutable state across concurrency.
+
+```swift
+struct User {                          // value type
+    let id: String
+    var email: String
+}
+
+var a = User(id: "u1", email: "a@x.com")
+var b = a                              // copy
+b.email = "b@x.com"                    // a unchanged
+```
+
+## Optionals
+
+Optional = "value or nothing". Different from `null`.
+
+```swift
+var name: String? = nil
+name.count                             // ❌ compile error
+
+// Unwrap
+if let n = name {
+    print(n.count)
+}
+guard let n = name else { return }    // unwrap or exit scope
+print(n.count)
+
+name?.count                            // optional chaining → Int?
+name ?? "unknown"                      // nil-coalescing
+```
+
+`!` is a compile-time assertion that the value is non-nil. Crash at runtime if wrong. Avoid in normal code.
+
+## `guard`
+
+Fail-fast at the top of a function; flat code after.
+
+```swift
+func process(user: User?) {
+    guard let user = user, user.active else { return }
+    // user is now non-optional and active
+    work(user)
+}
+```
+
+Prefer `guard` over nested `if let`s. It keeps the happy path at the outermost scope.
+
+## Structs with behaviour
+
+Structs can have methods, computed properties, and satisfy protocols.
+
+```swift
+struct Email {
+    let raw: String
+    var isValid: Bool { raw.contains("@") }
+    func normalized() -> Email { Email(raw: raw.lowercased()) }
+}
+```
+
+## Enums with associated values
+
+Swift enums carry data. Discriminated unions, like Rust.
+
+```swift
+enum Result<T> {
+    case success(T)
+    case failure(Error)
+}
+
+switch result {
+case .success(let value):
+    use(value)
+case .failure(let error):
+    log(error)
+}
+```
+
+Enums are exhaustive — the compiler forces every case. Add a case → every `switch` fails until updated.
+
+## Protocols — small, composable
+
+```swift
+protocol Identifiable { var id: String { get } }
+protocol Timestamped { var createdAt: Date { get } }
+
+struct User: Identifiable, Timestamped {
+    let id: String
+    let createdAt: Date
+}
+```
+
+### Protocol extensions — default implementations
+
+```swift
+protocol Named { var name: String { get } }
+
+extension Named {
+    func greet() -> String { "Hello \(name)" }
+}
+
+struct User: Named { let name: String }
+User(name: "A").greet()                // "Hello A"
+```
+
+Default methods via extensions. Implementers can override.
+
+### Existentials vs. generics
+
+```swift
+// Existential — heterogeneous collection
+func renderAll(_ items: [any Renderable]) { ... }
+
+// Generic — homogeneous; faster (static dispatch)
+func renderAll<T: Renderable>(_ items: [T]) { ... }
+```
+
+Swift 5.6+ requires `any` keyword for existentials. Prefer generics unless you need heterogeneity.
+
+## Closures
+
+```swift
+let double: (Int) -> Int = { $0 * 2 }
+
+users.map { $0.email }
+users.filter { $0.active }
+
+users.sorted { $0.name < $1.name }
+```
+
+Trailing closure syntax is idiomatic. Name parameters when the closure is longer than one line:
+
+```swift
+users.sorted { a, b in
+    a.name.compare(b.name, options: .caseInsensitive) == .orderedAscending
+}
+```
+
+## `@escaping` closures
+
+When a closure is stored or called after the function returns, it must be `@escaping`.
+
+```swift
+func load(onComplete: @escaping (Result<User, Error>) -> Void) { ... }
+```
+
+Inside an `@escaping` closure, `self` must be explicit — which is the language's way of nudging you to think about retain cycles.
+
+```swift
+load { [weak self] result in
+    guard let self else { return }
+    self.update(result)
+}
+```
+
+For new code, prefer `async` over callbacks whenever possible.
+
+## Extensions
+
+Add methods to existing types without subclassing.
+
+```swift
+extension String {
+    func toSlug() -> String {
+        lowercased().replacingOccurrences(of: " ", with: "-")
+    }
+}
+
+"Hello World".toSlug()                // "hello-world"
+```
+
+Organize by feature. Common pattern:
+
+```swift
+// File: User+Formatting.swift
+extension User { func displayName() -> String { ... } }
+```
+
+Don't add methods with generic names (`.isValid`) that collide across extensions.
+
+## Pattern matching
+
+Beyond `switch` on enum cases:
+
+```swift
+let pair = (1, 2)
+switch pair {
+case (0, 0): print("origin")
+case (_, 0): print("x-axis")
+case (0, _): print("y-axis")
+case (x, y) where x == y: print("diagonal")
+case let (x, y): print("(\(x), \(y))")
+}
+
+// if case / for case
+if case .success(let v) = result { use(v) }
+for case .success(let v) in results { use(v) }
+```
+
+Use `where` clauses inside `switch` for guards.
+
+## Error handling — throwing functions
+
+```swift
+enum ValidationError: Error {
+    case emptyEmail
+    case invalidAge(Int)
+}
+
+func validate(user: User) throws {
+    guard !user.email.isEmpty else { throw ValidationError.emptyEmail }
+    guard user.age >= 0 else { throw ValidationError.invalidAge(user.age) }
+}
+
+do {
+    try validate(user: u)
+} catch ValidationError.emptyEmail {
+    show("email required")
+} catch let e as ValidationError {
+    show("invalid: \(e)")
+} catch {
+    log.error("unexpected: \(error)")
+}
+```
+
+`try?` → `Optional`, `try!` → crash on error (tests only).
+
+## `Result` type
+
+For async callbacks and stored outcomes.
+
+```swift
+func fetch(_ url: URL) async -> Result<Data, URLError> { ... }
+
+switch await fetch(url) {
+case .success(let data): use(data)
+case .failure(let e):    log(e)
+}
+```
+
+With `async throws`, you usually don't need `Result` — throws flows naturally.
+
+## Access control
+
+| Level | Reach |
+|---|---|
+| `private` | Declaring scope only |
+| `fileprivate` | Whole file |
+| `internal` (default) | Module |
+| `public` | Cross-module, not subclassable |
+| `open` | Cross-module, subclassable |
+
+Default to most-restrictive. Libraries: prefer `public` for API surface; `open` only when subclassing is a designed extension point.
+
+## Property wrappers
+
+Encapsulate storage with behaviour: `@Published`, `@State`, `@AppStorage`, `@UserDefault`.
+
+```swift
+@propertyWrapper
+struct Clamped<V: Comparable> {
+    var wrappedValue: V {
+        didSet { wrappedValue = min(max(wrappedValue, range.lowerBound), range.upperBound) }
+    }
+    let range: ClosedRange<V>
+    init(wrappedValue: V, _ range: ClosedRange<V>) {
+        self.range = range
+        self.wrappedValue = min(max(wrappedValue, range.lowerBound), range.upperBound)
+    }
+}
+
+struct Config { @Clamped(1...10) var threads: Int = 4 }
+```
+
+Used heavily in SwiftUI; write your own sparingly.
+
+## Strings
+
+- `String` — Unicode-correct by default. Subscripting requires `Index`, not `Int`.
+- `Character` — a grapheme cluster (may be multiple code points).
+- Use `.count` for grapheme count (slow-ish); `.unicodeScalars.count` for code points.
+
+```swift
+let s = "héllo"
+s.count                                // 5
+s[s.startIndex]                        // "h"
+
+// Index arithmetic
+let i = s.index(s.startIndex, offsetBy: 2)
+s[i]                                    // "l"
+```
+
+Avoid `.utf8.count` unless you're measuring bytes for serialization.
+
+## Collections — lazy vs. eager
+
+```swift
+users.map { $0.email }                  // eager, allocates
+users.lazy.map { $0.email }.filter { $0.contains("@x") }.first(where: ...)
+```
+
+Use `.lazy` for chained operations on large collections where you only need a subset.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `!` force-unwrap | Use `if let` / `guard let` / `??` |
+| `try!` outside tests | `try` + error handling |
+| Force-casting `as!` | Use `as?` and handle `nil`; test types you trust |
+| `[String: Any]` in public API | Model a type |
+| Class for a pure data type | Use `struct` |
+| Storing closures without `[weak self]` | Retain cycle; always think capture semantics |
+| `print()` for logging | `Logger` (`os.Logger`) in new code |
+| `NSString` / `NSArray` in Swift code | Use native types; bridge at Objective-C boundary |
+| `Error` protocol conformance without `LocalizedError` for user-facing errors | Implement `errorDescription` if you surface it in UI |