/swift-rules

name: swift-rules
description: "Swift coding rules: style, patterns, security, testing. Triggers: .swift, Package.swift, .xcodeproj, SwiftUI, Combine, async/await, XCTest."
effort: medium
user-invocable: false
allowed-tools: Read

Swift Rules

These rules come from `app/rules/swift/` in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in Swift. Apply them when writing or reviewing Swift code.

Swift Coding Style

Naming

• PascalCase: types, protocols, enums, struct, class.
• camelCase: functions, methods, properties, variables, enum cases.
• No prefixes: Swift has module namespacing (no `NS` or `UI` prefix for your types).
• Use descriptive names: `removeElement(at:)` not `remove(i:)`.
• Boolean properties read as assertions: `isEmpty`, `hasChildren`, `canSubmit`.

Types

• Prefer `struct` over `class` by default (value semantics, no reference cycles).
• Use `class` only when reference semantics or inheritance is required.
• Use `enum` with associated values for modeling finite states.
• Use `protocol` for defining capabilities. Prefer protocol composition.
• Use `typealias` for complex generic signatures for readability.

Optionals

• Use `guard let` for early exit on nil. Use `if let` for conditional binding.
• Never force-unwrap (`!`) unless failure is a programming error.
• Use `??` for default values: `let name = user?.name ?? "Unknown"`.
• Use optional chaining: `user?.address?.city`.
• Use `map` / `flatMap` on optionals for transformations.

Properties

• Use `let` by default. Use `var` only when mutation is required.
• Use computed properties for derived values: `var fullName: String { ... }`.
• Use property observers (`willSet`, `didSet`) for side effects on change.
• Use `lazy var` for expensive initialization deferred until first access.
• Use `@Published` (Combine) for observable properties in classes.

Functions

• Use argument labels for clarity: `func move(from source: Int, to destination: Int)`.
• Omit argument labels when the function name makes the role clear: `func contains(_ element: T)`.
• Use default parameter values instead of multiple overloads.
• Use `throws` / `async throws` for fallible operations.
• Use trailing closure syntax for the last closure parameter.

Access Control

• Use `private` for implementation details. Use `fileprivate` sparingly.
• Use `internal` (default) for module-scoped access.
• Use `public` for framework API. Use `open` only when subclassing is intended.
• Prefer `private(set)` for read-only external access with internal mutation.

Formatting

• Use SwiftLint for automated style enforcement.
• Use SwiftFormat for automated code formatting.
• Commit `.swiftlint.yml` and `.swiftformat` to the repository.
• Max line length: 120 characters (SwiftLint default).
• Use trailing commas in multi-line arrays and dictionaries.

Swift Frameworks

SwiftUI

• Use `VStack`, `HStack`, `ZStack` for layout composition.
• Use `List` with `ForEach` for dynamic content. Use `LazyVStack` for large lists.
• Use `NavigationStack` (iOS 16+) with `navigationDestination(for:)` for type-safe navigation.
• Use `.task { }` modifier for async data loading tied to view lifecycle.
• Use `@ViewBuilder` for conditional view composition in custom containers.
• Use `PreviewProvider` or `#Preview` macro for rapid UI iteration.

UIKit (Legacy / Hybrid)

• Use `UIHostingController` to embed SwiftUI views in UIKit.
• Use `UIViewRepresentable` to wrap UIKit views in SwiftUI.
• Use Auto Layout with constraints or `UIStackView` for layout.
• Use `UICollectionViewCompositionalLayout` for complex collection layouts.
• Use `Coordinator` pattern for delegate-based UIKit interop in SwiftUI.

Combine

• Use `Publisher` / `Subscriber` for reactive data streams.
• Use `sink` for subscribing. Store cancellables in `Set<AnyCancellable>`.
• Use `map`, `filter`, `flatMap`, `combineLatest` for stream transformation.
• Use `@Published` on class properties for automatic publisher generation.
• Prefer `AsyncSequence` (async/await) over Combine for new code.

Swift Data

• Use `@Model` macro for persistent model definitions.
• Use `@Query` in SwiftUI views for automatic fetching and observation.
• Use `ModelContext` for CRUD operations: `context.insert(item)`, `context.delete(item)`.
• Use `#Predicate` macro for type-safe query filtering.
• Use `ModelConfiguration` for custom store locations and migration options.

Core Data (Legacy)

• Use `NSPersistentContainer` for stack setup.
• Use `NSFetchRequest` with `NSPredicate` for querying.
• Use `performBackgroundTask` for background context operations.
• Use lightweight migrations for schema changes when possible.
• Prefer SwiftData for new projects (iOS 17+).

Vapor (Server-Side)

• Use `routes.get("users")` for route definitions.
• Use `Content` protocol for request/response body codable conformance.
• Use Fluent ORM with migrations for database access.
• Use middleware for authentication, CORS, and error handling.
• Use `async`/`await` natively (Vapor 4+ is fully async).

Networking

• Use `URLSession` with `async/await` for HTTP requests.
• Use `Codable` with `JSONDecoder` for response parsing.
• Use `URLCache` and `ETag` for response caching.
• Set `timeoutIntervalForRequest` on `URLSessionConfiguration`.
• Use `TaskLocal` for request-scoped values (tracing, auth context).

Package Management

• Use Swift Package Manager (SPM) for dependency management.
• Define dependencies in `Package.swift` with exact version or version ranges.
• Use `Package.resolved` committed to the repository for reproducible builds.
• Prefer SPM over CocoaPods/Carthage for new projects.

Swift Patterns

Error Handling

• Use `enum AppError: Error` for typed, exhaustive error handling.
• Use `throws` functions with `do-catch` for recoverable errors.
• Use `Result<Success, Failure>` for asynchronous error propagation.
• Use `try?` for optional conversion. Use `try!`