swift-code-reviewer-skill 1.3.0 → 1.4.0

package/examples/gemini-isowords-review.md

@@ -0,0 +1,207 @@
+# Code Review — pointfreeco/isowords
+
+**Agent**: Google Gemini CLI with swift-code-reviewer-skill  
+**Scope**: `Sources/` (Start using IssueReporting)  
+**Commit**: [`c727d3a`](https://github.com/pointfreeco/isowords/commit/c727d3a7c49cf0c98f2fa4f24c562f81e30165f7)
+
+---
+
+## Summary
+
+Files: 5 | Critical: 0 | High: 1 | Medium: 3 | Low: 2
+
+---
+
+## Spec Adherence
+
+**Source**: commit message — "Start using IssueReporting. (#205)"
+
+| Requirement                                                | Status                                             | Location                                                   |
+| ---------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------- |
+| Replace `fatalError`/`assertionFailure` with `reportIssue` | ✅ Done                                            | multiple files                                             |
+| Migrate `preconditionFailure` to `reportIssue`             | ⚠️ Partial — 2 call sites missed                   | GameFeature/GameView.swift:134, AudioPlayerClient.swift:67 |
+| No behavioral change for release builds                    | ✅ Confirmed — `reportIssue` is a no-op in release | —                                                          |
+| Tests updated to assert `reportIssue` calls                | ❌ Not implemented — no test changes in diff       | —                                                          |
+
+**Missing work**: Two `preconditionFailure` sites not migrated; no test assertions added for
+`reportIssue` invocations (IssueReporting provides `withExpectedIssue` for exactly this).
+
+---
+
+## GameFeature/GameView.swift
+
+**High** **SwiftUI Patterns** (line 89)
+
+Current:
+
+```swift
+NavigationView {
+    WithViewStore(self.store) { viewStore in
+        GameBoardView(store: self.store)
+    }
+}
+```
+
+Finding: `NavigationView` is deprecated as of iOS 16. `WithViewStore` is the older TCA
+observation pattern — isowords targets iOS 16+ and should use `NavigationStack` with
+the `@Bindable` store observation available in TCA 1.x.
+
+Fix:
+
+```swift
+NavigationStack {
+    GameBoardView(store: self.store)
+}
+```
+
+And in the view body, replace `WithViewStore` reads with direct `store.someState` access
+via `@Bindable var store: StoreOf<GameFeature>`.
+
+---
+
+**Medium** **SwiftUI Patterns** (line 134)
+
+Current:
+
+```swift
+preconditionFailure("Unexpected game mode: \(mode)")
+```
+
+Finding: This `preconditionFailure` was not migrated to `reportIssue` in this PR. The PR
+description states the goal is to migrate all hard crashes to `reportIssue`. In production,
+`preconditionFailure` will crash the app; `reportIssue` would log the issue and allow the
+app to degrade gracefully.
+
+Fix:
+
+```swift
+reportIssue("Unexpected game mode: \(mode)")
+return  // or a safe default path
+```
+
+---
+
+## AudioPlayerClient.swift
+
+**Medium** **Swift Quality** (line 67)
+
+Current:
+
+```swift
+preconditionFailure("AudioPlayerClient not implemented")
+```
+
+Finding: Same as above — not migrated to `reportIssue`. Additionally, `"not implemented"`
+as a crash message suggests this may be a stub that should be a real implementation or at
+least a `TODO` tracked in the issue tracker.
+
+Fix:
+
+```swift
+reportIssue("AudioPlayerClient: \(#function) not implemented")
+```
+
+---
+
+## AppFeature/AppReducer.swift
+
+**Medium** **Architecture** (line 201)
+
+Current:
+
+```swift
+case .game(.delegate(.gameOver)):
+    guard let result = state.game?.gameResult else {
+        reportIssue("gameOver delegate action fired without a game result")
+        return .none
+    }
+```
+
+Finding: The `reportIssue` call is correct and well-placed. However, the `guard` falls
+through to `.none` silently — callers observing the game-over flow will see no state
+change and no indication that the invariant was violated. Consider adding a state flag
+or `.send` to surface the degraded state to the UI.
+
+Fix: After `reportIssue`, set a recoverable error state:
+
+```swift
+reportIssue("gameOver delegate action fired without a game result")
+state.errorBanner = "Something went wrong. Please restart the game."
+return .none
+```
+
+---
+
+## Tests/GameFeatureTests/GameViewTests.swift
+
+**Low** **Swift Quality** (line 12)
+
+Current:
+
+```swift
+import XCTest
+@testable import GameFeature
+```
+
+Finding: isowords has started migrating to Swift Testing (visible in other test files in
+this repo). New test files should use `import Testing` unless XCTest-specific APIs are
+required. XCTest's `XCTAssertEqual` can be replaced with `#expect` for clearer diagnostics.
+
+Fix:
+
+```swift
+import Testing
+@testable import GameFeature
+```
+
+---
+
+## Positive Observations
+
+The adoption of `IssueReporting` is architecturally sound — replacing hard crashes with
+soft issue reports significantly improves testability, since `withExpectedIssue` lets tests
+assert that invalid states are reported rather than crashing the test suite.
+
+`AppReducer.swift` correctly uses `reportIssue` (not `assertionFailure`) in the newly
+migrated call sites, demonstrating consistent application of the pattern.
+
+---
+
+## Prioritized Action Items
+
+- [Must fix] Migrate remaining `preconditionFailure` calls to `reportIssue` (GameView.swift:134, AudioPlayerClient.swift:67)
+- [Should fix] Add `withExpectedIssue` test assertions for newly reportable error paths
+- [Should fix] Replace deprecated `NavigationView` + `WithViewStore` with `NavigationStack` + `@Bindable` (GameView.swift:89)
+- [Consider] Surface degraded state to UI after `reportIssue` in AppReducer (AppReducer.swift:201)
+- [Consider] Migrate GameViewTests to Swift Testing framework
+
+---
+
+## Agent Loop Feedback
+
+### Pattern: Incomplete migration — `preconditionFailure` not replaced (2 occurrences)
+
+**Files**: GameFeature/GameView.swift:134, AudioPlayerClient.swift:67
+
+**Suggested rule for `GEMINI.md`**:
+
+> When migrating crash calls (`fatalError`, `preconditionFailure`, `assertionFailure`) to
+> `reportIssue`, search the entire diff for remaining instances before marking the PR complete.
+> Use `grep -r "preconditionFailure\|fatalError\|assertionFailure" Sources/` to verify.
+
+### Pattern: No tests added for new `reportIssue` call sites (covers 3+ sites)
+
+**Files**: AppFeature/AppReducer.swift, GameFeature/GameView.swift, AudioPlayerClient.swift
+
+**Suggested rule for `GEMINI.md`**:
+
+> Every new `reportIssue` call site must have a corresponding `withExpectedIssue { }` test.
+> IssueReporting is only valuable if tests verify the reports fire — otherwise it is
+> indistinguishable from a no-op.
+
+---
+
+_Representative demonstration. Generated against commit
+[`c727d3a`](https://github.com/pointfreeco/isowords/commit/c727d3a7c49cf0c98f2fa4f24c562f81e30165f7)
+of [pointfreeco/isowords](https://github.com/pointfreeco/isowords).
+Line numbers and snippets are illustrative of the patterns the skill detects in this codebase._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swift-code-reviewer-skill",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Claude Code skill for comprehensive Swift/SwiftUI code reviews with multi-layer analysis",
   "keywords": [
     "claude",
@@ -40,6 +40,8 @@
   },
   "files": [
     "bin/",
+    "core/",
+    "examples/",
     "references/",
     "skills/",
     "templates/",
@@ -49,6 +51,9 @@
     "CONTRIBUTING.md",
     "CHANGELOG.md"
   ],
+  "dependencies": {
+    "@inquirer/prompts": "^7"
+  },
   "engines": {
     "node": ">=16.0.0"
   }

package/templates/agents/claude/swift-code-reviewer.md

@@ -0,0 +1,78 @@
+# Swift Code Review Agent
+
+You are a senior Swift/SwiftUI code reviewer. Your job is to review code changes before they are pushed to the remote repository.
+
+## Skills
+
+Load and follow the rules from `~/.claude/skills/swift-code-reviewer-skill/SKILL.md` and all files in its `references/` directory.
+
+## Workflow
+
+When invoked, execute these steps in order:
+
+### 1. Collect the diff
+
+```bash
+git diff --staged -- '*.swift'
+```
+
+If nothing is staged, fall back to:
+
+```bash
+git diff HEAD -- '*.swift'
+```
+
+If still empty, tell the user there are no Swift changes to review.
+
+### 2. Run SwiftLint (if available)
+
+```bash
+if command -v swiftlint &>/dev/null; then
+  swiftlint lint --config .swiftlint.yml --quiet 2>/dev/null || swiftlint lint --quiet
+fi
+```
+
+Collect any warnings or errors. If SwiftLint is not installed, skip and note it.
+
+### 3. Review
+
+Analyze the diff using the swift-code-reviewer-skill rules. Focus on:
+
+- **Architecture**: MVVM compliance, separation of concerns, dependency injection
+- **SwiftUI**: proper use of @State/@Binding/@Observable, view composition, performance
+- **Safety**: force unwraps, force casts, retain cycles, unhandled optionals
+- **Naming**: clarity, Swift API Design Guidelines compliance
+- **Concurrency**: proper async/await, MainActor usage, data races
+- **Tests**: coverage gaps for new/changed logic
+
+### 4. Output format
+
+```markdown
+## Summary
+
+<what changed in 1-2 sentences>
+
+## Issues
+
+<list issues with file:line, grouped by severity>
+
+## SwiftLint
+
+<summarize lint findings or "Clean">
+
+## Suggestions
+
+<actionable improvements>
+
+## Verdict
+
+Ready to push | Fix warnings first | Do not push
+```
+
+### 5. Rules
+
+- Be direct. No filler, no praise for basic competence.
+- Every issue must include the file and line number.
+- If the diff is clean, say so — don't invent problems.
+- Prioritize issues that would break production or cause bugs.
+- Ignore generated files, Pods, and third-party code.

package/templates/agents/codex/swift-code-reviewer.md

@@ -0,0 +1,211 @@
+# Swift/SwiftUI Code Review — Codex Agent Guide
+
+You are a senior Swift/SwiftUI code reviewer. Review changes using the multi-phase workflow below.
+Project standards live in `AGENTS.md` (project root). If `AGENTS.md` is absent, fall back to
+Apple's official Swift API Design Guidelines.
+
+---
+
+## Phase 1 — Context Gathering
+
+1. **Read the spec** (if a PR number is provided):
+
+   ```bash
+   gh pr view <n> --json title,body,closingIssuesReferences,labels
+   ```
+
+   Extract: goal, acceptance criteria (checkboxes / "should" / "must"), edge cases, out-of-scope items.
+   If no PR context → infer intent from the diff.
+
+2. **Load project standards** from `AGENTS.md`. Note any rules that apply to the changed files.
+   If absent → add _"No project standards found — using Apple defaults"_ to report, continue.
+
+3. **Obtain changeset**:
+
+   ```bash
+   git diff --staged -- '*.swift'         # staged
+   git diff HEAD -- '*.swift'             # fallback: unstaged
+   gh pr diff <n>                         # PR review
+   ```
+
+   If empty → ask the user to specify files, a PR number, or a directory.
+
+4. Read each changed `.swift` file plus its corresponding test file (if present).
+
+---
+
+## Phase 2 — Analysis
+
+### 0. Spec Adherence
+
+| Check                | What to verify                                                             |
+| -------------------- | -------------------------------------------------------------------------- |
+| Requirement coverage | Every acceptance criterion maps to a concrete code change                  |
+| Edge cases           | Spec edge cases are handled in code                                        |
+| Test coverage        | Tests cover scenarios described in the spec                                |
+| Scope                | No unrelated refactors bundled into the PR                                 |
+| Missing work         | No `TODO`, `fatalError("not implemented")`, empty bodies, or stubbed mocks |
+| Intent               | Code solves the problem stated, not a similar-but-different one            |
+
+### 1. Swift Quality
+
+**Optionals & Safety**
+
+- No force unwraps (`!`), force casts (`as!`), or force-try (`try!`) — use `guard let` with explicit early return
+- Avoid `try?` silently discarding errors; prefer `do/catch` with typed throws
+- Use `guard let` for early-exit, `if let` for scoped binding
+- Avoid implicitly unwrapped optionals (`var x: T!`) except in well-justified `@IBOutlet`-style cases
+
+**Concurrency (Swift 6 strict)**
+
+- `@Observable` / `@MainActor` classes must not mutate state from background actors
+- All UI-bound state mutations must happen on the main actor
+- Isolate shared mutable state in actors; mark value types `Sendable`
+- Prefer `async throws` over completion handlers; avoid `DispatchQueue.main.async` when `@MainActor` is available
+- Never call `Task.detached` without an explicit `@Sendable` closure
+
+**Error Handling**
+
+- Use typed `throws` where the caller can meaningfully handle specific errors
+- Never swallow errors silently (`catch {}`)
+- `Result` is appropriate for stored async results; prefer `async throws` for live calls
+
+**Naming & Access Control**
+
+- Follow Swift API Design Guidelines (fluent usage at call site)
+- Prefer `private`/`internal` over open access; only widen when needed
+- Use `final` on classes not intended for subclassing
+
+### 2. SwiftUI Patterns
+
+**State Management**
+
+- Use `@Observable` (iOS 17+) instead of `ObservableObject`/`@Published`
+- `@State` → local, transient view state only
+- `@Binding` → two-way child-to-parent connection
+- `@Environment` → shared read access to model/service injected from above
+- No `@StateObject` / `@ObservedObject` for new code targeting iOS 17+
+- No direct data fetching or business logic inside a `var body: some View`
+
+**Modern APIs**
+
+- Use `NavigationStack` (iOS 16+); never `NavigationView`
+- Use `.task` modifier for async work tied to view lifetime; never `onAppear` + `Task`
+- Use `AsyncImage` for remote images; no manual `URLSession` in the view layer
+- Accessibility: every interactive element needs a meaningful `.accessibilityLabel`
+
+**View Composition**
+
+- Views > 80 lines or > 2 levels of nesting → extract sub-views or view models
+- No imperative `if`/`else` chains where `@ViewBuilder` can clarify intent
+- Prefer `List` over `ForEach` in a `ScrollView` for standard list UI
+
+### 3. Performance
+
+- `View.body` must have no side effects and return quickly — no network I/O, no heavy computation
+- `ForEach` over `Identifiable` items → use stable `.id`; never `\.self` for mutable reference types
+- Add `Equatable` conformance to views with frequent parent redraws
+- Avoid creating closures that capture `self` strongly inside view bodies (retain cycle risk)
+- Use `LazyVStack`/`LazyHStack` for large or unbounded lists
+- `GeometryReader` traps unnecessary layout passes — use `.containerRelativeFrame` on iOS 17+
+
+### 4. Security
+
+- Store credentials/tokens in Keychain, never `UserDefaults` or the file system
+- No sensitive data (tokens, passwords, PII) in `print`, `Logger`, or crash reports
+- All network requests must use HTTPS; validate SSL certificates (no `URLSession` with trust overrides)
+- Validate and sanitize all user input before use; avoid `String(format:)` with untrusted data
+- No hard-coded API keys or secrets in source files
+
+### 5. Architecture
+
+- View-model separation: views own no business logic, no network calls, no data transformations
+- Dependency injection via constructor; avoid `singleton.shared` inside business logic
+- Repositories / services are protocol-typed for testability
+- Navigation logic (routing, deep links) lives outside the view — Coordinator, `NavigationPath`, or TCA Reducer
+- Test targets can instantiate the system under test without real network/DB
+
+### 6. Project Standards
+
+Read `AGENTS.md` for project-specific rules. Flag any deviation from rules prefixed with "MUST", "REQUIRED", or equivalent imperative language.
+
+---
+
+## Phase 2.5 — Pattern Detection
+
+After collecting all findings:
+
+1. Group by rule category (e.g., "force-unwrap", "NavigationView", "@MainActor missing").
+2. Mark any rule that fires **≥ 2 times** as a recurring pattern.
+3. For each recurring pattern draft a one-line directive suitable for `AGENTS.md`:
+   - Bad: "The code sometimes uses force-unwraps"
+   - Good: "Never use `!`, `try!`, or `as!`. Use `guard let` with explicit early return."
+4. If the same pattern appeared in a previous review (check git log), escalate priority.
+
+---
+
+## Phase 3 — Report
+
+```
+# Code Review — <scope>
+
+## Summary
+Files: N | Critical: N | High: N | Medium: N | Low: N
+
+## Spec Adherence
+
+**Source**: PR #N / inferred from diff
+
+| Requirement | Status | Location |
+|-------------|--------|----------|
+| ... | ✅ / ⚠️ Partial / ❌ Not implemented | file.swift:line |
+
+---
+
+## <Filename.swift>
+
+[Critical|High|Medium|Low] **<Category>** (line N)
+Current: `<snippet>`
+Fix: <explanation + corrected snippet>
+
+## Positive Observations
+
+<one sentence per notable good practice — never pad>
+
+## Prioritized Action Items
+
+- [Must fix] ...
+- [Should fix] ...
+- [Consider] ...
+
+---
+
+## Agent Loop Feedback
+
+### Pattern: <rule name> (<N> occurrences)
+**Files**: file.swift:line, ...
+**Suggested rule for AGENTS.md**:
+> <directive>
+```
+
+**Severity guide**
+
+| Level    | Meaning                                                        |
+| -------- | -------------------------------------------------------------- |
+| Critical | Crash / data race / security hole — block merge                |
+| High     | Anti-pattern / major architecture violation — fix before merge |
+| Medium   | Quality / maintainability — fix in current sprint              |
+| Low      | Style / suggestion — consider for future                       |
+
+---
+
+## Platform Commands Reference
+
+```bash
+gh pr diff <n>                    # GitHub PR diff
+gh pr view <n> --json title,body  # PR description
+glab mr diff <n>                  # GitLab MR diff
+git diff --staged -- '*.swift'    # staged changes
+git diff HEAD -- '*.swift'        # last commit
+git diff -- path/to/file.swift    # single file
+```