swift-code-reviewer-skill 1.0.0 → 1.1.1

package/references/performance-review.md

@@ -493,6 +493,86 @@ struct WaterfallLayout: Layout {
 }
 ```
 
+### 3.5 Scroll Container Selection
+
+**Check for:**
+- [ ] Correct scroll container chosen for the use case
+- [ ] No nested scroll views on the same axis
+- [ ] `List` used for system-style rows with swipe actions; `LazyVStack` for custom layouts
+- [ ] Plain `VStack` only for small, fixed-count content
+
+**Decision Table:**
+
+| Use Case | Container | Why |
+|----------|-----------|-----|
+| System-style rows, swipe actions, sections | `List` | Built-in lazy loading, cell reuse |
+| Custom row layout, >20 items | `ScrollView + LazyVStack` | Lazy + full layout control |
+| Grid of items | `LazyVGrid` | 2D lazy loading |
+| Small static list (<10 items) | `VStack` | Simplest, no lazy overhead |
+| Horizontal scrolling carousel | `ScrollView(.horizontal) + LazyHStack` | Horizontal lazy |
+
+**Examples:**
+
+❌ **Bad: VStack for large dynamic list**
+```swift
+ScrollView {
+    VStack {  // ❌ All views created immediately — bad for 100+ items
+        ForEach(posts) { post in
+            PostRow(post: post)
+        }
+    }
+}
+```
+
+❌ **Bad: Nested ScrollViews on same axis**
+```swift
+ScrollView(.vertical) {
+    LazyVStack {
+        ForEach(sections) { section in
+            ScrollView(.vertical) {  // ❌ Nested vertical scroll — broken UX + perf
+                ForEach(section.items) { item in
+                    ItemRow(item: item)
+                }
+            }
+        }
+    }
+}
+```
+
+✅ **Good: List for system-style content**
+```swift
+List(posts) { post in  // ✅ Lazy by default, swipe actions, separators
+    PostRow(post: post)
+        .swipeActions { Button("Delete", role: .destructive) { delete(post) } }
+}
+.listStyle(.plain)
+```
+
+✅ **Good: LazyVStack for custom layout feeds**
+```swift
+ScrollView {
+    LazyVStack(spacing: 0, pinnedViews: .sectionHeaders) {  // ✅ Lazy + custom layout
+        ForEach(posts) { post in
+            PostCardView(post: post)
+                .padding(.horizontal)
+        }
+    }
+}
+```
+
+✅ **Good: LazyVGrid for photo grid**
+```swift
+let columns = [GridItem(.adaptive(minimum: 100))]
+
+ScrollView {
+    LazyVGrid(columns: columns, spacing: 2) {  // ✅ 2D lazy grid
+        ForEach(photos) { photo in
+            PhotoThumbnail(photo: photo)
+        }
+    }
+}
+```
+
 ---
 
 ## 4. Image Performance
@@ -859,6 +939,115 @@ VStack {
 
 ---
 
+## 8. Narrow Observation Scope
+
+### 8.1 Read Only What You Display
+
+**Check for:**
+- [ ] Views read only the properties they actually display (not entire `@Observable` objects passed unnecessarily)
+- [ ] Subviews receive minimal data needed (IDs or value types when possible, not full observable models)
+- [ ] `@Observable` objects not passed to descendants that don't observe them
+
+**Examples:**
+
+❌ **Bad: Passing entire observable to unrelated subview**
+```swift
+@Observable
+final class FeedViewModel {
+    var posts: [Post] = []
+    var isLoading: Bool = false
+    var currentUser: User = .placeholder
+    var unreadCount: Int = 0
+    // ... many more properties
+}
+
+struct FeedView: View {
+    let viewModel: FeedViewModel
+
+    var body: some View {
+        List(viewModel.posts) { post in
+            PostRow(viewModel: viewModel, post: post)  // ❌ Passes entire ViewModel
+        }
+    }
+}
+
+struct PostRow: View {
+    let viewModel: FeedViewModel  // ❌ Observes ALL viewModel properties, re-renders on any change
+    let post: Post
+
+    var body: some View {
+        Text(post.title)  // Only uses post, but re-renders on isLoading, unreadCount changes
+    }
+}
+```
+
+✅ **Good: Pass only what the subview needs**
+```swift
+struct FeedView: View {
+    let viewModel: FeedViewModel
+
+    var body: some View {
+        List(viewModel.posts) { post in
+            PostRow(post: post)  // ✅ Pass only the value, not the entire observable
+        }
+    }
+}
+
+struct PostRow: View {
+    let post: Post  // ✅ Only observes/depends on this post
+
+    var body: some View {
+        Text(post.title)
+    }
+}
+```
+
+### 8.2 Lazy Containers for Feeds
+
+**Check for:**
+- [ ] Feeds with >20 items use lazy containers (`List`, `LazyVStack`, `LazyVGrid`)
+- [ ] Row views are lightweight (no heavy init, no async work in init)
+- [ ] `.task` or `.onAppear` on rows used for per-row async loading (e.g., avatar images)
+
+**Examples:**
+
+❌ **Bad: Eager loading all rows**
+```swift
+ScrollView {
+    VStack {  // ❌ Instantiates all PostRow views immediately
+        ForEach(viewModel.posts) { post in
+            PostRow(post: post)
+        }
+    }
+}
+```
+
+✅ **Good: Lazy container with lightweight rows**
+```swift
+List(viewModel.posts) { post in  // ✅ Lazy — only creates visible rows
+    PostRow(post: post)
+}
+
+struct PostRow: View {
+    let post: Post
+    @State private var avatar: Image?
+
+    var body: some View {
+        HStack {
+            (avatar ?? Image(systemName: "person.circle"))
+                .resizable()
+                .frame(width: 40, height: 40)
+            Text(post.content)
+        }
+        .task {  // ✅ Load avatar lazily only when row appears
+            avatar = await loadAvatar(url: post.avatarURL)
+        }
+    }
+}
+```
+
+---
+
 ## Quick Performance Checklist
 
 ### Critical (Fix Immediately)
@@ -873,6 +1062,8 @@ VStack {
 - [ ] AsyncImage for remote images
 - [ ] LazyVStack/LazyHStack for large lists
 - [ ] Minimal GeometryReader usage
+- [ ] Correct scroll container selected (List vs LazyVStack vs LazyVGrid vs VStack)
+- [ ] No nested scroll views on the same axis
 
 ### Medium Priority
 - [ ] Computed properties for derived data
@@ -880,6 +1071,8 @@ VStack {
 - [ ] Proper task cancellation
 - [ ] Efficient image sizing
 - [ ] Resource cleanup in deinit
+- [ ] Narrow observation scope (subviews receive only needed data, not full @Observable)
+- [ ] @Observable not propagated to unrelated descendants
 
 ### Low Priority
 - [ ] Animation performance optimization

package/references/review-workflow.md

@@ -521,6 +521,127 @@ Button("Log In") {
 - [ ] Keyboard navigation support
 - [ ] VoiceOver tested (if critical UI)
 
+### Step 2.2B: Navigation & UI Architecture Check
+
+**Reference**: `swiftui-ui-patterns` skill, `references/swiftui-review-checklist.md` (Sections 8–14)
+
+Apply this step when reviewing views that contain navigation, sheets, TabView, or async state loading.
+
+#### Route Enum & RouterPath
+```swift
+// ✅ Good: Typed route enum + RouterPath
+enum AppRoute: Hashable {
+    case userDetail(userID: UUID)
+    case settings
+}
+
+@Observable final class RouterPath {
+    var path: [AppRoute] = []
+    func navigate(to route: AppRoute) { path.append(route) }
+}
+```
+
+**Checks:**
+- [ ] Route destinations defined as typed `Hashable` enum (not String/Int raw values)
+- [ ] `RouterPath` `@Observable` owns the navigation path (not ad-hoc `@State var path`)
+- [ ] Single `.navigationDestination(for: Route.self)` per `NavigationStack` (in root view, not child views)
+
+#### Sheet Routing
+```swift
+// ✅ Good: Item-driven + SheetDestination enum
+enum SheetDestination: Identifiable { case compose; case profile(UUID); var id: String { ... } }
+
+@State private var sheetDestination: SheetDestination?
+.sheet(item: $sheetDestination) { destination in
+    switch destination { case .compose: ...; case .profile(let id): ... }
+}
+```
+
+**Checks:**
+- [ ] `.sheet(item:)` preferred over `.sheet(isPresented:)` when a model is selected
+- [ ] Multiple sheets use a single `SheetDestination` `Identifiable` enum (not multiple `@State Bool`)
+- [ ] No multiple `.sheet(isPresented:)` modifiers on the same view for different destinations
+
+#### TabView Architecture
+```swift
+// ✅ Good: Independent RouterPath per tab
+@Observable final class AppTabRouter {
+    var homeRouter = RouterPath()
+    var searchRouter = RouterPath()
+    func router(for tab: AppTab) -> RouterPath { ... }
+}
+```
+
+**Checks:**
+- [ ] Each tab has its own `RouterPath` (not a single shared `NavigationPath`)
+- [ ] Tab switching preserves navigation history in each tab
+- [ ] Action tabs (compose, post) handled via side effect (modal), not actual tab destination
+
+#### Deep Link Handling
+```swift
+// ✅ Good: Centralized at root
+.onOpenURL { url in router.handle(url: url) }  // In root view only
+```
+
+**Checks:**
+- [ ] `.onOpenURL` applied at app root (not in feature views)
+- [ ] URL parsing handled in router/coordinator, not in views
+- [ ] Deep link routes to the correct tab router when per-tab navigation is used
+
+#### Theming
+```swift
+// ✅ Good: Semantic colors via Theme
+@Environment(Theme.self) private var theme
+Text(title).foregroundStyle(theme.labelPrimary)
+```
+
+**Checks:**
+- [ ] No raw `Color.blue`, `Color.white`, `Color.red` when a project `Theme` object exists
+- [ ] Colors accessed via `@Environment(Theme.self)` or equivalent design token
+- [ ] `Theme` provided at app root via `.environment(theme)`
+
+#### Async State Patterns
+```swift
+// ✅ Good: .task(id:) with debounce + CancellationError silenced
+.task(id: query) {
+    do {
+        try await Task.sleep(for: .milliseconds(300))  // Debounce
+        results = try await search(query)
+    } catch is CancellationError { }  // Silenced
+    catch { /* real error */ }
+}
+
+// ✅ Good: LoadState enum
+enum LoadState<T> { case idle, loading, loaded(T), error(Error) }
+```
+
+**Checks:**
+- [ ] `.task(id:)` used for input-driven async work (not `.onChange + Task { }`)
+- [ ] `CancellationError` silenced when using `.task(id:)` (not shown to user)
+- [ ] `LoadState<T>` enum used instead of multiple `isLoading`/`hasError` booleans
+
+#### Focus and Input
+```swift
+// ✅ Good: FocusField enum with chaining
+enum FocusField { case email, password }
+@FocusState private var focusedField: FocusField?
+
+TextField("Email", text: $email)
+    .focused($focusedField, equals: .email)
+    .onSubmit { focusedField = .password }  // Chain to next
+
+SecureField("Password", text: $password)
+    .focused($focusedField, equals: .password)
+    .onSubmit { submitForm() }  // Last field submits
+```
+
+**Checks:**
+- [ ] `FocusField` enum used with `@FocusState` (not multiple `@FocusState private var isFocused: Bool`)
+- [ ] `.onSubmit` advances focus to the next field in sequence
+- [ ] Last field's `.onSubmit` triggers the primary action (login, search, etc.)
+
+---
+
 ### Step 2.3: Performance Check
 
 **Reference**: `swiftui-performance-audit`