swift-code-reviewer-skill 1.0.0 → 1.1.1

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: swift-code-reviewer
-description: Perform thorough code reviews for Swift/SwiftUI code, analyzing code quality, architecture, performance, security, and adherence to Swift 6+ best practices, SwiftUI patterns, iOS/macOS platform guidelines, and project-specific coding standards from .claude/CLAUDE.md. Use when reviewing code changes, performing quality audits, or providing structured feedback on Swift codebases with all severity levels and positive feedback.
+description: Perform thorough code reviews for Swift/SwiftUI code, analyzing code quality, architecture, performance, security, and adherence to Swift 6+ best practices, SwiftUI patterns, navigation architecture, sheet routing, theming, async state, iOS/macOS platform guidelines, and project-specific coding standards from .claude/CLAUDE.md. Use when reviewing code changes, performing quality audits, or providing structured feedback on Swift codebases with all severity levels and positive feedback.
 ---
 
 # Swift/SwiftUI Code Review Skill
@@ -30,6 +30,7 @@ Use this skill when you need to:
 - Provide structured feedback to team members
 
 **Trigger patterns:**
+
 - "Review this PR"
 - "Review [filename].swift"
 - "Review my changes"
@@ -69,6 +70,7 @@ The skill follows a **four-phase workflow** to ensure comprehensive and actionab
 Execute checks across **six core categories**:
 
 #### 1. Swift Best Practices
+
 Reference: `swift-best-practices` skill knowledge base
 
 - **Concurrency Safety**
@@ -91,6 +93,7 @@ Reference: `swift-best-practices` skill knowledge base
   - Proper use of optionals
 
 #### 2. SwiftUI Quality
+
 Reference: `swiftui-expert-skill` knowledge base
 
 - **State Management**
@@ -118,6 +121,7 @@ Reference: `swiftui-expert-skill` knowledge base
   - Keyboard navigation
 
 #### 3. Performance
+
 Reference: `swiftui-performance-audit` knowledge base
 
 - **View Optimization**
@@ -256,7 +260,7 @@ Reference: `swiftui-performance-audit` knowledge base
    - Comparison with project guidelines
 
 3. **Provide Context**
-   - Explain *why* something is an issue
+   - Explain _why_ something is an issue
    - Reference best practices or standards
    - Suggest specific fixes with examples
    - Link to learning resources
@@ -266,6 +270,7 @@ Reference: `swiftui-performance-audit` knowledge base
 ### 1. Swift Language Quality
 
 **What to Check:**
+
 - Concurrency patterns (actors, async/await, Sendable)
 - Error handling (typed throws, Result type)
 - Optionals handling (avoid force unwrapping)
@@ -279,6 +284,7 @@ Reference: `swiftui-performance-audit` knowledge base
 ### 2. SwiftUI Patterns
 
 **What to Check:**
+
 - Property wrapper selection and usage
 - State management patterns
 - View lifecycle understanding
@@ -292,6 +298,7 @@ Reference: `swiftui-performance-audit` knowledge base
 ### 3. Performance Optimization
 
 **What to Check:**
+
 - View update optimization
 - ForEach identity and performance
 - Heavy work in view body
@@ -305,6 +312,7 @@ Reference: `swiftui-performance-audit` knowledge base
 ### 4. Security & Safety
 
 **What to Check:**
+
 - Force unwrap detection (`!`, `as!`, `try!`)
 - Input validation and sanitization
 - Sensitive data handling (passwords, tokens)
@@ -318,6 +326,7 @@ Reference: `swiftui-performance-audit` knowledge base
 ### 5. Architecture & Design
 
 **What to Check:**
+
 - MVVM, MVI, TCA, or other architecture compliance
 - Dependency injection patterns
 - Separation of concerns
@@ -331,6 +340,7 @@ Reference: `swiftui-performance-audit` knowledge base
 ### 6. Project-Specific Standards
 
 **What to Check:**
+
 - `.claude/CLAUDE.md` compliance
 - Custom architecture patterns
 - Design system usage
@@ -345,9 +355,11 @@ Reference: `swiftui-performance-audit` knowledge base
 This skill **references** (not duplicates) three foundational skills for domain expertise:
 
 ### 1. swift-best-practices
+
 **When to Use:** Reviewing Swift language usage, concurrency patterns, API design, or Swift 6+ migration
 
 **What it Provides:**
+
 - Swift 6+ concurrency patterns (actors, async/await, Sendable)
 - API design guidelines compliance
 - Availability pattern validation
@@ -355,14 +367,17 @@ This skill **references** (not duplicates) three foundational skills for domain
 - Modern Swift feature adoption
 
 **How to Leverage:**
+
 - Read `~/.claude/skills/swift-best-practices/references/concurrency.md` for concurrency checks
 - Reference `swift6-features.md` for Swift 6 migration patterns
 - Use `api-design.md` for naming and parameter validation
 
 ### 2. swiftui-expert-skill
+
 **When to Use:** Reviewing SwiftUI views, state management, or UI code
 
 **What it Provides:**
+
 - State management patterns (@Observable, @State, @Binding)
 - Modern SwiftUI API guidance (iOS 17+, macOS 14+)
 - View composition best practices
@@ -370,14 +385,17 @@ This skill **references** (not duplicates) three foundational skills for domain
 - Accessibility patterns
 
 **How to Leverage:**
+
 - Read `~/.claude/skills/swiftui-expert-skill/references/state-management.md` for property wrapper checks
 - Reference `modern-apis.md` for deprecation detection
 - Use `view-composition.md` for component structure validation
 
 ### 3. swiftui-performance-audit
+
 **When to Use:** Performance concerns identified or mentioned in PR description
 
 **What it Provides:**
+
 - View update optimization patterns
 - ForEach performance analysis
 - Layout thrash detection
@@ -385,11 +403,33 @@ This skill **references** (not duplicates) three foundational skills for domain
 - Memory management
 
 **How to Leverage:**
+
 - Read `~/.claude/skills/swiftui-performance-audit/SKILL.md` for performance audit workflow
 - Reference performance-specific checks when reviewing view code
 - Apply recommendations from the skill to performance-sensitive paths
 
+### 4. swiftui-ui-patterns
+
+**When to Use:** Reviewing navigation architecture, sheet/modal routing, TabView setup, theming, async state management, focus handling, or API client patterns
+
+**What it Provides:**
+
+- Navigation architecture (route enums, RouterPath, centralized navigationDestination)
+- Sheet/modal routing (item-driven sheets, SheetDestination enum)
+- TabView with independent per-tab navigation history
+- Theming with semantic colors via `@Environment(Theme.self)`
+- Async state patterns (`.task(id:)`, LoadState enum, CancellationError handling)
+- Focus chaining with FocusField enum and `.onSubmit`
+- Lightweight API client pattern (closure-based structs, `.live()` / `.mock()` factories)
+
+**How to Leverage:**
+
+- Read `~/.claude/skills/swiftui-ui-patterns/references/navigation.md` for route enum and RouterPath checks
+- Reference `sheets-modals.md` for sheet routing validation
+- Use `theming.md` for semantic color enforcement
+
 **Integration Strategy:**
+
 1. Load relevant reference files from these skills as needed
 2. Apply their checklist items to the review
 3. Reference their documentation in feedback
@@ -398,6 +438,7 @@ This skill **references** (not duplicates) three foundational skills for domain
 ## Platform Support
 
 ### GitHub Pull Requests
+
 Use `gh` CLI for fetching PR data:
 
 ```bash
@@ -415,6 +456,7 @@ gh pr view <PR-number> --json comments
 ```
 
 ### GitLab Merge Requests
+
 Use `glab` CLI for fetching MR data:
 
 ```bash
@@ -432,6 +474,7 @@ glab mr note list <MR-number>
 ```
 
 ### Local Git Changes
+
 For uncommitted changes or manual review:
 
 ```bash
@@ -452,10 +495,11 @@ git show <commit-hash>
 
 The review report follows this structure:
 
-```markdown
+````markdown
 # Code Review Report
 
 ## Summary
+
 - **Files Reviewed**: X
 - **Total Findings**: Y
 - **Critical**: 0
@@ -466,6 +510,7 @@ The review report follows this structure:
 - **Refactoring Suggestions**: 4
 
 ## Executive Summary
+
 [Brief overview of the changes and overall code quality]
 
 ---
@@ -475,6 +520,7 @@ The review report follows this structure:
 ### File: Sources/Features/Login/LoginView.swift
 
 #### ✅ Positive Feedback
+
 1. **Excellent State Management** (line 23)
    - Proper use of @Observable for view model
    - Clean separation of concerns
@@ -484,11 +530,13 @@ The review report follows this structure:
    - Proper async/await integration
 
 #### 🔴 Critical Issues
+
 1. **Data Race Risk** (line 67)
    - **Severity**: Critical
    - **Category**: Concurrency
    - **Issue**: Mutable state accessed from multiple actors without synchronization
    - **Fix**:
+
      ```swift
      // Before
      class LoginViewModel {
@@ -501,14 +549,17 @@ The review report follows this structure:
          @Published var isLoading = false
      }
      ```
+
    - **Reference**: swift-best-practices/references/concurrency.md
 
 #### 🟡 High Priority
+
 1. **Force Unwrap Detected** (line 89)
    - **Severity**: High
    - **Category**: Safety
    - **Issue**: Force unwrapping optional can cause crash
    - **Fix**:
+
      ```swift
      // Before
      let user = fetchUser()!
@@ -519,9 +570,11 @@ The review report follows this structure:
          return
      }
      ```
+
    - **Reference**: Project coding standard (.claude/CLAUDE.md:45)
 
 #### 💡 Refactoring Suggestions
+
 1. **Extract Subview** (lines 120-150)
    - Consider extracting login form into separate view
    - Improves testability and reusability
@@ -531,20 +584,24 @@ The review report follows this structure:
 ## Prioritized Action Items
 
 ### Must Fix (Critical/High)
+
 1. [ ] Fix data race in LoginViewModel.swift:67
 2. [ ] Remove force unwrap in LoginView.swift:89
 
 ### Should Fix (Medium)
+
 1. [ ] Add documentation to public APIs
 2. [ ] Improve error handling in NetworkService.swift
 
 ### Consider (Low)
+
 1. [ ] Refactor login form into separate view
 2. [ ] Add more unit tests for edge cases
 
 ---
 
 ## Positive Patterns Observed
+
 - Excellent use of @Observable for state management
 - Consistent adherence to project architecture (MVVM)
 - Comprehensive accessibility support
@@ -552,14 +609,16 @@ The review report follows this structure:
 - Good test coverage for core functionality
 
 ## References
+
 - [Swift Best Practices](~/.claude/skills/swift-best-practices/SKILL.md)
 - [SwiftUI Expert Guide](~/.claude/skills/swiftui-expert-skill/SKILL.md)
 - [Project Coding Standards](.claude/CLAUDE.md)
-```
+````
 
 ## How to Use
 
 ### Example 1: Review Specific File
+
 ```
 User: "Review UserProfileView.swift"
 
@@ -571,6 +630,7 @@ Steps:
 ```
 
 ### Example 2: Review Git Changes
+
 ```
 User: "Review my uncommitted changes"
 
@@ -583,6 +643,7 @@ Steps:
 ```
 
 ### Example 3: Review Pull Request
+
 ```
 User: "Review PR #123"
 
@@ -596,6 +657,7 @@ Steps:
 ```
 
 ### Example 4: Review Against Custom Guidelines
+
 ```
 User: "Review LoginViewModel.swift against our coding standards"
 
@@ -608,6 +670,7 @@ Steps:
 ```
 
 ### Example 5: Review Multiple Files
+
 ```
 User: "Review all ViewModels in the Features folder"
 
@@ -619,21 +682,48 @@ Steps:
 5. Summarize common patterns and issues across all files
 ```
 
+### Example 6: Review Navigation / Routing Code
+
+```
+User: "Review our navigation setup and routing code"
+
+Steps:
+1. Read .claude/CLAUDE.md for project navigation patterns
+2. Read router/coordinator files (RouterPath, AppCoordinator, TabRouter)
+3. Read root views that set up NavigationStack and TabView
+4. Run navigation architecture checks:
+   - Route destinations use typed Hashable enum (not String/Int)
+   - RouterPath @Observable owns path (not ad-hoc @State)
+   - Single centralized .navigationDestination per stack
+   - .sheet(item:) preferred over .sheet(isPresented:) when model selected
+   - Multiple sheets use SheetDestination enum (not multiple booleans)
+   - Each tab has independent RouterPath (not shared)
+   - .onOpenURL at app root, not scattered in feature views
+5. Run async state checks:
+   - .task(id:) for input-driven async work
+   - CancellationError silenced
+   - LoadState<T> enum instead of multiple booleans
+6. Generate report with navigation-specific findings
+```
+
 ## Resources
 
 This skill includes the following reference materials:
 
 ### Core References
+
 - **review-workflow.md**: Detailed step-by-step review process, git commands, and diff parsing strategies
 - **feedback-templates.md**: Templates for positive/negative comments, severity classification guidelines
 
 ### Quality Checklists
+
 - **swift-quality-checklist.md**: Swift 6+ concurrency, error handling, optionals, access control, naming
 - **swiftui-review-checklist.md**: Property wrappers, state management, modern APIs, view composition
 - **performance-review.md**: View updates, ForEach optimization, layout efficiency, resource management
 - **security-checklist.md**: Input validation, sensitive data, keychain, network security
 
 ### Architecture & Customization
+
 - **architecture-patterns.md**: MVVM, MVI, TCA patterns, dependency injection, testing strategies
 - **custom-guidelines.md**: How to read and parse .claude/CLAUDE.md and project-specific standards
 
@@ -652,7 +742,7 @@ This skill includes the following reference materials:
 3. **Be Specific and Actionable**
    - Include exact file:line references
    - Provide code examples for fixes
-   - Explain *why* something is an issue
+   - Explain _why_ something is an issue
    - Link to relevant documentation
 
 4. **Prioritize by Severity**
@@ -685,6 +775,6 @@ For runtime analysis, recommend using Instruments or other profiling tools.
 
 ## Version
 
-**Version**: 1.0.0
-**Last Updated**: 2026-02-10
+**Version**: 1.1.1
+**Last Updated**: 2026-03-16
 **Compatible with**: Swift 6+, SwiftUI (iOS 17+, macOS 14+, watchOS 10+, tvOS 17+, visionOS 1+)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swift-code-reviewer-skill",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Claude Code skill for comprehensive Swift/SwiftUI code reviews with multi-layer analysis",
   "keywords": [
     "claude",

package/references/architecture-patterns.md

@@ -593,6 +593,281 @@ struct UserListView: View {
 
 ---
 
+## 5A. Lightweight Client Pattern (Closure-Based)
+
+### 5A.1 Overview
+
+**Purpose**: Define API clients as value-type structs with async closure properties, enabling easy swapping between live and mock implementations — especially for SwiftUI previews.
+
+**Benefits:**
+- Preview-friendly (no network calls in Xcode Previews)
+- Testable without subclassing or protocol mocking boilerplate
+- Composable: clients can be scoped per-feature
+- No shared mutable singleton state
+
+### 5A.2 Implementation Pattern
+
+**Check for:**
+- [ ] API client defined as a `struct` with `async` closure properties (not a singleton class)
+- [ ] Static factory `.live(baseURL:)` for production
+- [ ] Static factory `.mock(...)` for previews and tests
+- [ ] Store (`@Observable`) holds the client; views never call the client directly
+- [ ] Client injected via `@Environment` or constructor
+
+**Examples:**
+
+❌ **Bad: Singleton class client**
+```swift
+final class UserAPIClient {
+    static let shared = UserAPIClient()  // ❌ Singleton — untestable, preview-unfriendly
+
+    func fetchUser(id: UUID) async throws -> User {
+        let url = URL(string: "https://api.example.com/users/\(id)")!
+        let (data, _) = try await URLSession.shared.data(from: url)
+        return try JSONDecoder().decode(User.self, from: data)
+    }
+}
+
+final class UserViewModel {
+    func loadUser(id: UUID) async {
+        let user = try await UserAPIClient.shared.fetchUser(id: id)  // ❌ Hard dependency
+    }
+}
+```
+
+✅ **Good: Struct with closure properties**
+```swift
+// Client defined as a struct with closure properties
+struct UserAPIClient {
+    var fetchUser: (UUID) async throws -> User
+    var updateUser: (User) async throws -> User
+    var deleteUser: (UUID) async throws -> Void
+}
+
+// Live implementation
+extension UserAPIClient {
+    static func live(baseURL: URL) -> Self {
+        UserAPIClient(
+            fetchUser: { id in
+                let url = baseURL.appendingPathComponent("users/\(id)")
+                let (data, _) = try await URLSession.shared.data(from: url)
+                return try JSONDecoder().decode(User.self, from: data)
+            },
+            updateUser: { user in
+                var request = URLRequest(url: baseURL.appendingPathComponent("users/\(user.id)"))
+                request.httpMethod = "PUT"
+                request.httpBody = try JSONEncoder().encode(user)
+                let (data, _) = try await URLSession.shared.data(for: request)
+                return try JSONDecoder().decode(User.self, from: data)
+            },
+            deleteUser: { id in
+                var request = URLRequest(url: baseURL.appendingPathComponent("users/\(id)"))
+                request.httpMethod = "DELETE"
+                _ = try await URLSession.shared.data(for: request)
+            }
+        )
+    }
+}
+
+// Mock implementation for previews and tests
+extension UserAPIClient {
+    static func mock(
+        fetchUser: @escaping (UUID) async throws -> User = { _ in .mock },
+        updateUser: @escaping (User) async throws -> User = { $0 },
+        deleteUser: @escaping (UUID) async throws -> Void = { _ in }
+    ) -> Self {
+        UserAPIClient(
+            fetchUser: fetchUser,
+            updateUser: updateUser,
+            deleteUser: deleteUser
+        )
+    }
+}
+
+// Store holds the client — views never call it directly
+@MainActor
+@Observable
+final class UserStore {
+    private let client: UserAPIClient
+    private(set) var user: User?
+    private(set) var isLoading = false
+
+    init(client: UserAPIClient) {
+        self.client = client
+    }
+
+    func loadUser(id: UUID) async {
+        isLoading = true
+        defer { isLoading = false }
+        user = try? await client.fetchUser(id)
+    }
+}
+
+// View uses Store, not Client directly
+struct UserProfileView: View {
+    let store: UserStore
+
+    var body: some View {
+        Group {
+            if let user = store.user {
+                Text(user.name)
+            } else {
+                ProgressView()
+            }
+        }
+        .task { await store.loadUser(id: userID) }
+    }
+}
+
+// Preview uses mock client
+#Preview {
+    UserProfileView(store: UserStore(client: .mock(
+        fetchUser: { _ in User(id: UUID(), name: "Preview User") }
+    )))
+}
+
+// App uses live client
+@main
+struct MyApp: App {
+    let userStore = UserStore(client: .live(baseURL: URL(string: "https://api.example.com")!))
+
+    var body: some Scene {
+        WindowGroup {
+            UserProfileView(store: userStore)
+        }
+    }
+}
+```
+
+---
+
+## 5B. Per-Tab Navigation Architecture
+
+### 5B.1 Overview
+
+**Purpose**: Provide each tab with its own independent navigation stack and router, preserving navigation history across tab switches and supporting deep link routing to a specific tab.
+
+**Benefits:**
+- Tab navigation state preserved when switching tabs (native iOS behavior)
+- Deep links can target specific tabs without resetting all stacks
+- Decoupled tab-specific routing logic
+
+### 5B.2 Implementation Pattern
+
+**Check for:**
+- [ ] `TabRouter` (or `AppTabRouter`) owns one `RouterPath` per tab
+- [ ] `Binding(for tab:)` helper creates a `Binding<[Route]>` for each tab's stack
+- [ ] Deep links dispatched to the correct tab's router (not a global path)
+- [ ] Tab switching does not reset other tabs' navigation stacks
+
+**Examples:**
+
+❌ **Bad: Single shared path for all tabs**
+```swift
+struct MainTabView: View {
+    @State private var path = NavigationPath()  // ❌ Shared — tab switch loses history
+    @State private var selectedTab = 0
+
+    var body: some View {
+        TabView(selection: $selectedTab) {
+            NavigationStack(path: $path) { HomeView() }.tag(0)
+            NavigationStack(path: $path) { SearchView() }.tag(1)  // ❌ Same path!
+        }
+    }
+}
+```
+
+✅ **Good: Per-tab RouterPath with deep link routing**
+```swift
+@Observable
+final class RouterPath {
+    var path: [AppRoute] = []
+
+    func navigate(to route: AppRoute) { path.append(route) }
+    func pop() { if !path.isEmpty { path.removeLast() } }
+    func popToRoot() { path.removeAll() }
+
+    func handle(url: URL) -> Bool {
+        guard let route = AppRoute(url: url) else { return false }
+        navigate(to: route)
+        return true
+    }
+}
+
+enum AppTab: Int, CaseIterable, Identifiable {
+    case home, search, notifications, profile
+    var id: Int { rawValue }
+}
+
+@Observable
+final class AppTabRouter {
+    var selectedTab: AppTab = .home
+
+    var homeRouter = RouterPath()
+    var searchRouter = RouterPath()
+    var notificationsRouter = RouterPath()
+    var profileRouter = RouterPath()
+
+    // Binding helper for each tab's path
+    func pathBinding(for tab: AppTab) -> Binding<[AppRoute]> {
+        Binding(
+            get: { self.router(for: tab).path },
+            set: { self.router(for: tab).path = $0 }
+        )
+    }
+
+    func router(for tab: AppTab) -> RouterPath {
+        switch tab {
+        case .home: return homeRouter
+        case .search: return searchRouter
+        case .notifications: return notificationsRouter
+        case .profile: return profileRouter
+        }
+    }
+
+    // Route deep link to correct tab
+    func handle(url: URL) {
+        guard let route = AppRoute(url: url) else { return }
+        let targetTab = route.preferredTab
+        selectedTab = targetTab
+        router(for: targetTab).navigate(to: route)
+    }
+}
+
+struct MainTabView: View {
+    @State private var tabRouter = AppTabRouter()
+
+    var body: some View {
+        TabView(selection: $tabRouter.selectedTab) {
+            Tab("Home", systemImage: "house", value: AppTab.home) {
+                NavigationStack(path: tabRouter.pathBinding(for: .home)) {
+                    HomeView(router: tabRouter.homeRouter)
+                        .navigationDestination(for: AppRoute.self) { route in
+                            routeDestination(route, router: tabRouter.homeRouter)
+                        }
+                }
+            }
+
+            Tab("Search", systemImage: "magnifyingglass", value: AppTab.search) {
+                NavigationStack(path: tabRouter.pathBinding(for: .search)) {
+                    SearchView(router: tabRouter.searchRouter)
+                        .navigationDestination(for: AppRoute.self) { route in
+                            routeDestination(route, router: tabRouter.searchRouter)
+                        }
+                }
+            }
+
+            // ... other tabs
+        }
+        .onOpenURL { url in
+            tabRouter.handle(url: url)  // ✅ Deep link dispatched to correct tab router
+        }
+    }
+}
+```
+
+---
+
 ## 6. Testing Strategies
 
 ### 6.1 Unit Testing