Copilot instructions

1---
2applyTo: "**/*.swift"
3---
4 
5# Swift Coding Style
6 
7> This file extends [common/coding-style.md](../common/coding-style.md) with Swift specific content.
8 
9## Formatting
10 
11- **SwiftFormat** for auto-formatting, **SwiftLint** for style enforcement
12- `swift-format` is bundled with Xcode 16+ as an alternative
13 
14## Immutability
15 
16- Prefer `let` over `var` — define everything as `let` and only change to `var` if the compiler requires it
17- Use `struct` with value semantics by default; use `class` only when identity or reference semantics are needed
18 
19## Naming
20 
21Follow [Apple API Design Guidelines](https://www.swift.org/documentation/api-design-guidelines/):
22 
23- Clarity at the point of use — omit needless words
24- Name methods and properties for their roles, not their types
25- Use `static let` for constants over global constants
26 
27## Error Handling
28 
29Use typed throws (Swift 6+) and pattern matching:
30 
31```swift
32func load(id: String) throws(LoadError) -> Item {
33    guard let data = try? read(from: path) else {
34        throw .fileNotFound(id)
35    }
36    return try decode(data)
37}
38```
39 
40## Concurrency
41 
42Enable Swift 6 strict concurrency checking. Prefer:
43 
44- `Sendable` value types for data crossing isolation boundaries
45- Actors for shared mutable state
46- Structured concurrency (`async let`, `TaskGroup`) over unstructured `Task {}`
47 
48 
49# Swift Patterns
50 
51> This file extends [common/patterns.md](../common/patterns.md) with Swift specific content.
52 
53## Protocol-Oriented Design
54 
55Define small, focused protocols. Use protocol extensions for shared defaults:
56 
57```swift
58protocol Repository: Sendable {
59    associatedtype Item: Identifiable & Sendable
60    func find(by id: Item.ID) async throws -> Item?
61    func save(_ item: Item) async throws
62}
63```
64 
65## Value Types
66 
67- Use structs for data transfer objects and models
68- Use enums with associated values to model distinct states:
69 
70```swift
71enum LoadState<T: Sendable>: Sendable {
72    case idle
73    case loading
74    case loaded(T)
75    case failed(Error)
76}
77```
78 
79## Actor Pattern
80 
81Use actors for shared mutable state instead of locks or dispatch queues:
82 
83```swift
84actor Cache<Key: Hashable & Sendable, Value: Sendable> {
85    private var storage: [Key: Value] = [:]
86 
87    func get(_ key: Key) -> Value? { storage[key] }
88    func set(_ key: Key, value: Value) { storage[key] = value }
89}
90```
91 
92## Dependency Injection
93 
94Inject protocols with default parameters — production uses defaults, tests inject mocks:
95 
96```swift
97struct UserService {
98    private let repository: any UserRepository
99 
100    init(repository: any UserRepository = DefaultUserRepository()) {
101        self.repository = repository
102    }
103}
104```
105 
106## References
107 
108See skill: `swift-actor-persistence` for actor-based persistence patterns.
109See skill: `swift-protocol-di-testing` for protocol-based DI and testing.
110 
111 
112# Swift Security
113 
114> This file extends [common/security.md](../common/security.md) with Swift specific content.
115 
116## Secret Management
117 
118- Use **Keychain Services** for sensitive data (tokens, passwords, keys) — never `UserDefaults`
119- Use environment variables or `.xcconfig` files for build-time secrets
120- Never hardcode secrets in source — decompilation tools extract them trivially
121 
122```swift
123let apiKey = ProcessInfo.processInfo.environment["API_KEY"]
124guard let apiKey, !apiKey.isEmpty else {
125    fatalError("API_KEY not configured")
126}
127```
128 
129## Transport Security
130 
131- App Transport Security (ATS) is enforced by default — do not disable it
132- Use certificate pinning for critical endpoints
133- Validate all server certificates
134 
135## Input Validation
136 
137- Sanitize all user input before display to prevent injection
138- Use `URL(string:)` with validation rather than force-unwrapping
139- Validate data from external sources (APIs, deep links, pasteboard) before processing
140 
141 
142# Swift Testing
143 
144> This file extends [common/testing.md](../common/testing.md) with Swift specific content.
145 
146## Framework
147 
148Use **Swift Testing** (`import Testing`) for new tests. Use `@Test` and `#expect`:
149 
150```swift
151@Test("User creation validates email")
152func userCreationValidatesEmail() throws {
153    #expect(throws: ValidationError.invalidEmail) {
154        try User(email: "not-an-email")
155    }
156}
157```
158 
159## Test Isolation
160 
161Each test gets a fresh instance — set up in `init`, tear down in `deinit`. No shared mutable state between tests.
162 
163## Parameterized Tests
164 
165```swift
166@Test("Validates formats", arguments: ["json", "xml", "csv"])
167func validatesFormat(format: String) throws {
168    let parser = try Parser(format: format)
169    #expect(parser.isValid)
170}
171```
172 
173## Coverage
174 
175```bash
176swift test --enable-code-coverage
177```
178 
179## Reference
180 
181See skill: `swift-protocol-di-testing` for protocol-based dependency injection and mock patterns with Swift Testing.