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! only in tests or guaranteed paths.
• Add LocalizedError conformance for user-facing error messages.

Protocol-Oriented Design

• Define capabilities as protocols: protocol Fetchable { func fetch() async throws -> Data }.
• Use protocol extensions for default implementations.
• Use protocol composition: func process(_ item: Sendable & Codable).
• Use associated types for generic protocols: associatedtype Output.
• Use some Protocol (opaque types) for return types hiding concrete implementations.

Async/Await

• Use async functions for all asynchronous operations.
• Use async let for concurrent, independent operations.
• Use TaskGroup for dynamic parallelism with collected results.
• Use Task { } to bridge sync to async. Avoid .task { } in views for complex logic.
• Use withThrowingTaskGroup for concurrent operations that can fail.

Actors

• Use actor for thread-safe mutable state (replaces manual locks).
• Use @MainActor for UI-related state and methods.
• Use nonisolated for actor methods that do not access mutable state.
• Use GlobalActor for custom isolation domains.
• Minimize await calls on actors to reduce suspension points.

SwiftUI Patterns

• Use @State for view-local mutable state.
• Use @Binding for child-to-parent state communication.
• Use @Observable (Observation framework) for model objects (preferred over @ObservedObject).
• Use @Environment for dependency injection: @Environment(\.modelContext).
• Use ViewModifier for reusable view transformations.
• Extract subviews into separate structs for readability and performance.

Codable

• Use Codable for JSON serialization/deserialization.
• Use CodingKeys enum for custom key mapping.
• Use JSONDecoder with .convertFromSnakeCase for API compatibility.
• Use @propertyWrapper for custom decoding strategies (e.g., date formats).
• Use nestedContainer for flattening nested JSON structures.

Dependency Injection

• Use initializer injection for required dependencies.
• Use @Environment in SwiftUI for framework-provided values.
• Use swift-dependencies library for testable, controlled dependency management.
• Use @Dependency(\.apiClient) var apiClient for automatic resolution.

Anti-Patterns

• Force-unwrapping optionals: use guard let or ??.
• Massive view controllers/views: split into subviews and view models.
• Reference cycles: use [weak self] in closures capturing self.
• Blocking the main thread: use Task or DispatchQueue.global().
• Stringly-typed APIs: use enums, protocols, and strong types.

Swift Security

Keychain

• Use Keychain Services for storing passwords, tokens, and cryptographic keys.
• Use kSecAttrAccessibleWhenUnlockedThisDeviceOnly for sensitive items.
• Use KeychainAccess or similar wrapper libraries for cleaner API.
• Never store secrets in UserDefaults (unencrypted plist on disk).
• Delete keychain items on user logout.

App Transport Security (ATS)

• Use HTTPS for all network connections. ATS enforces this by default.
• Never add blanket NSAllowsArbitraryLoads exception.
• Use per-domain exceptions only when connecting to legacy servers.
• Implement certificate pinning for high-security connections.
• Validate server certificates in URLSessionDelegate for custom pinning.

Input Validation

• Validate all user input before processing or displaying.
• Use NSRegularExpression or Swift Regex for pattern validation.
• Sanitize strings before using in URL construction, SQL, or HTML.
• Validate deep link URL parameters before navigation.
• Limit input lengths in UITextField / TextField to prevent abuse.

Data Protection

• Use Data Protection API: set FileProtectionType.complete on sensitive files.
• Use CryptoKit for hashing (SHA256), encryption (AES.GCM), and signing.
• Use SecureEnclave for hardware-backed key storage on supported devices.
• Zero sensitive data in memory after use: withUnsafeMutableBytes { $0.initializeMemory(as: UInt8.self, repeating: 0) }.
• Use @Sendable closures to prevent data races in concurrent access.

Authentication

• Use AuthenticationServices for Sign in with Apple and passkeys.
• Use LocalAuthentication (Face ID / Touch ID) for biometric auth.
• Store authentication tokens in Keychain, not in memory or UserDefaults.
• Use short-lived access tokens with refresh token rotation.
• Implement session timeout for inactive users.

Network Security

• Use URLSession with certificate pinning for sensitive API calls.
• Validate response Content-Type headers before parsing.
• Use Codable for structured deserialization (prevents injection).
• Set request timeouts to prevent hanging connections.
• Do not log request/response bodies containing sensitive data.

Code Security

• Use [weak self] in closures to prevent retain cycles and memory leaks.
• Use @Sendable and actor isolation for thread-safe concurrent code.
• Avoid UnsafePointer / UnsafeMutablePointer unless absolutely necessary.
• Use #if DEBUG guards for debug-only code. Never ship debug features.
• Enable Xcode hardened runtime for macOS apps.

Dependency Security

• Audit SPM dependencies before adding. Check maintainer reputation.
• Pin dependency versions in Package.resolved.
• Review Package.swift of dependencies for unusual build plugins.
• Prefer dependencies with active security response and disclosure processes.
• Minimize third-party dependencies for security-critical modules.

Swift Testing

Framework

• Use Swift Testing (import Testing) for new projects (Swift 5.10+).
• Use XCTest for existing projects and UIKit-based UI tests.
• Use swift-snapshot-testing for visual regression testing.
• Use swift-dependencies for controlled dependency injection in tests.

File Naming

• Test files: FooTests.swift in Tests/ target.
• Mirror source module structure in test target.
• Use @Test attribute (Swift Testing) or test prefix (XCTest) for test methods.
• Use @Suite (Swift Testing) for test grouping.

Structure (Swift Testing)

• Use @Test("description") for individual test cases.
• Use @Test(arguments: [...]) for parameterized tests.
• Use #expect(condition) for assertions. Use #require(condition) for preconditions.
• Use #expect(throws: FooError.self) { try riskyOperation() } for error testing.
• Use @Suite structs for grouping. Properties serve as shared setup.

Structure (XCTest)

• Use setUp() / tearDown() for per-test initialization and cleanup.
• Use setUpWithError() for throwing setup code.
• Use XCTAssertEqual, XCTAssertTrue, XCTAssertNil for assertions.
• Use XCTAssertThrowsError for exception testing.
• Use expectation(description:) + wait(for:timeout:) for async assertions.

Async Testing

• Use async test functions: @Test func fetchUser() async throws { ... }.
• Use confirmation() (Swift Testing) for event-based async assertions.
• XCTest: use XCTestExpectation with fulfillment() for callback-based async.
• Test AsyncSequence with for await loops and assertion on collected values.

Mocking

• Use protocol-based dependency injection for testability.
• Create manual mock implementations conforming to protocols.
• Use swift-dependencies for environment-controlled dependency overrides.
• Use @Dependency property wrapper for automatic mock injection in tests.
• Avoid mocking frameworks when protocol mocks are straightforward.

UI Testing (XCTest)

• Use XCUIApplication for UI automation tests.
• Use accessibility identifiers for reliable element lookup.
• Use app.buttons["Submit"].tap() for interaction simulation.
• Use waitForExistence(timeout:) for async UI element appearance.
• Keep UI tests focused on critical user flows only (slow to run).

Best Practices

• Test behavior through public API. Avoid @testable import when possible.
• Use @testable import Module only when testing internal members is necessary.
• Use withDependencies { } for scoped dependency overrides in tests.
• Test on multiple platforms (iOS, macOS) when shipping cross-platform.
• Run tests with swift test or xcodebuild test in CI.