Project Context
- Recent changes: !
git diff --name-only HEAD~3 2>/dev/null || echo "no git history"
- Swift version: !
swift --version 2>&1 | head -1 || echo "swift not found"
Code Analyzer (Read-Only)
Structured Swift/macOS code analysis protocol. Read-only — no file modifications.
Lifecycle Position
Phase 5 (Review). Load before swiftui-view-refactor for architectural overview. For deep line-by-line analysis, use audit-context-building.
Xcode MCP Orientation
When Xcode is available through this plugin's bundled bridge, prefer the MCP
tools over shelling out to Xcode directly:
- Use
XcodeListWindows to identify the active workspace tab.
- Use
XcodeGlob, XcodeGrep, and XcodeRead to map the codebase you are
reviewing.
- Use
XcodeRefreshCodeIssuesInFile when compiler diagnostics are relevant to
the review findings.
Analysis Protocol
Step 1 — Map the Entry Point
- Find the
@main App struct or entry point
- Identify window scenes (
WindowGroup, Settings, MenuBarExtra)
- Trace the root navigation structure (
NavigationSplitView, TabView)
Step 2 — Trace the Module Graph
- List all Swift source files grouped by directory/feature
- Identify dependencies between modules (imports, protocol conformances)
- Map state ownership: which types own
@Observable models, which receive them
- Identify services/repositories and their injection pattern
Step 3 — Identify Architecture Pattern
Classify the codebase:
- MV (Model-View): Views consume models directly via
@State, @Environment, @Query
- MVVM: Separate ViewModel classes mediate between Model and View
- TCA: Reducers, Store, Actions, State
- Hybrid: Mix of patterns across features
Note consistency — are all features using the same pattern?
Review Checklist
1. Code Organization — PASS / WARN / FAIL
| Check |
What to Look For |
| File structure |
Features grouped by domain, not by type (Views/, Models/, etc.) |
| File size |
Swift files under 300 lines; views under 100 lines |
| Naming |
Types are nouns, methods are verbs, booleans read as questions |
| Access control |
private by default, internal where needed, public only for API surface |
| Extensions |
Used to group protocol conformances and // MARK: sections |
2. State Management — PASS / WARN / FAIL
| Check |
What to Look For |
@Observable vs ObservableObject |
New code uses @Observable; legacy ObservableObject flagged |
@State visibility |
All @State and @StateObject are private |
| Ownership |
Views don't create models they should receive via injection |
@MainActor |
Observable classes and view models are @MainActor |
| Binding direction |
@Binding only where child modifies parent state |
| Nested observables |
No nested ObservableObject (pass directly or use @Observable) |
3. Error Handling — PASS / WARN / FAIL
| Check |
What to Look For |
try without catch |
Unhandled throws that could crash |
Force unwrap (!) |
Every ! must have justification comment or precondition |
Result vs throws |
Consistent error propagation strategy |
| User-facing errors |
Errors surfaced to UI with actionable messages |
| Network errors |
Retry logic, timeout handling, offline state |
4. Performance — PASS / WARN / FAIL
| Check |
What to Look For |
| View body complexity |
No object creation, heavy computation, or side effects in body |
| Lazy containers |
LazyVStack/LazyHStack for lists with >20 items |
| ForEach identity |
Stable id (never .indices for dynamic content) |
GeometryReader |
Guarded with > 0 and .isFinite; prefer containerRelativeFrame() |
| Image loading |
AsyncImage or downsampled thumbnails, not raw UIImage(data:) |
| Glass effects |
Multiple glass views wrapped in GlassEffectContainer |
5. Concurrency — PASS / WARN / FAIL
| Check |
What to Look For |
@MainActor |
UI-bound classes and properties are main actor isolated |
Sendable |
Types crossing isolation boundaries conform to Sendable |
.task modifier |
Async work uses .task {} (auto-cancels on disappear) |
| Actor isolation |
Mutable shared state protected by actors |
| Data races |
No unprotected mutable state accessed from multiple contexts |
6. Security — PASS / WARN / FAIL
| Check |
What to Look For |
| Hardcoded secrets |
No API keys, tokens, or passwords in source |
| Keychain usage |
Sensitive data stored in Keychain, not UserDefaults |
| Sandbox entitlements |
Minimal entitlements; no unnecessary capabilities |
| Input validation |
User input validated before use |
| URL handling |
External URLs validated before opening |
7. Test Coverage — PASS / WARN / FAIL
| Check |
What to Look For |
| Test file existence |
Every feature has corresponding test file |
| Model tests |
Business logic and data transformations tested |
| Edge cases |
Empty states, nil values, boundary conditions covered |
| Async tests |
async test methods with proper expectations |
| SwiftData tests |
In-memory ModelContainer for persistence tests |
Output Format
For each section, provide:
### [Section Name] — [PASS/WARN/FAIL]
**Summary:** One-line assessment.
**Findings:**
- [file_path:line] Description of issue
- [file_path:line] Description of issue
**Recommendation:** What to fix and in what order.
Cross-References
- If the
apple-design-system plugin is installed, use its swiftui-ui-patterns
review checklist for SwiftUI-specific review
- For view structure refactoring, load
swiftui-view-refactor
- For deep line-by-line analysis, load
audit-context-building
1---2name: code-analyzer-23description: Review Apple app code read-only for architecture, code quality, security, test coverage, and performance.4---56## Project Context78- Recent changes: !`git diff --name-only HEAD~3 2>/dev/null || echo "no git history"`9- Swift version: !`swift --version 2>&1 | head -1 || echo "swift not found"`1011# Code Analyzer (Read-Only)1213Structured Swift/macOS code analysis protocol. Read-only — no file modifications.1415## Lifecycle Position1617Phase 5 (Review). Load before `swiftui-view-refactor` for architectural overview. For deep line-by-line analysis, use `audit-context-building`.1819## Xcode MCP Orientation2021When Xcode is available through this plugin's bundled bridge, prefer the MCP22tools over shelling out to Xcode directly:23241. Use `XcodeListWindows` to identify the active workspace tab.252. Use `XcodeGlob`, `XcodeGrep`, and `XcodeRead` to map the codebase you are26 reviewing.273. Use `XcodeRefreshCodeIssuesInFile` when compiler diagnostics are relevant to28 the review findings.2930## Analysis Protocol3132### Step 1 — Map the Entry Point33341. Find the `@main` App struct or entry point352. Identify window scenes (`WindowGroup`, `Settings`, `MenuBarExtra`)363. Trace the root navigation structure (`NavigationSplitView`, `TabView`)3738### Step 2 — Trace the Module Graph39401. List all Swift source files grouped by directory/feature412. Identify dependencies between modules (imports, protocol conformances)423. Map state ownership: which types own `@Observable` models, which receive them434. Identify services/repositories and their injection pattern4445### Step 3 — Identify Architecture Pattern4647Classify the codebase:48- **MV (Model-View):** Views consume models directly via `@State`, `@Environment`, `@Query`49- **MVVM:** Separate ViewModel classes mediate between Model and View50- **TCA:** Reducers, Store, Actions, State51- **Hybrid:** Mix of patterns across features5253Note consistency — are all features using the same pattern?5455## Review Checklist5657### 1. Code Organization — PASS / WARN / FAIL5859| Check | What to Look For |60|-------|------------------|61| File structure | Features grouped by domain, not by type (Views/, Models/, etc.) |62| File size | Swift files under 300 lines; views under 100 lines |63| Naming | Types are nouns, methods are verbs, booleans read as questions |64| Access control | `private` by default, `internal` where needed, `public` only for API surface |65| Extensions | Used to group protocol conformances and `// MARK:` sections |6667### 2. State Management — PASS / WARN / FAIL6869| Check | What to Look For |70|-------|------------------|71| `@Observable` vs `ObservableObject` | New code uses `@Observable`; legacy `ObservableObject` flagged |72| `@State` visibility | All `@State` and `@StateObject` are `private` |73| Ownership | Views don't create models they should receive via injection |74| `@MainActor` | Observable classes and view models are `@MainActor` |75| Binding direction | `@Binding` only where child modifies parent state |76| Nested observables | No nested `ObservableObject` (pass directly or use `@Observable`) |7778### 3. Error Handling — PASS / WARN / FAIL7980| Check | What to Look For |81|-------|------------------|82| `try` without `catch` | Unhandled throws that could crash |83| Force unwrap (`!`) | Every `!` must have justification comment or precondition |84| `Result` vs throws | Consistent error propagation strategy |85| User-facing errors | Errors surfaced to UI with actionable messages |86| Network errors | Retry logic, timeout handling, offline state |8788### 4. Performance — PASS / WARN / FAIL8990| Check | What to Look For |91|-------|------------------|92| View body complexity | No object creation, heavy computation, or side effects in `body` |93| Lazy containers | `LazyVStack`/`LazyHStack` for lists with >20 items |94| ForEach identity | Stable `id` (never `.indices` for dynamic content) |95| `GeometryReader` | Guarded with `> 0` and `.isFinite`; prefer `containerRelativeFrame()` |96| Image loading | `AsyncImage` or downsampled thumbnails, not raw `UIImage(data:)` |97| Glass effects | Multiple glass views wrapped in `GlassEffectContainer` |9899### 5. Concurrency — PASS / WARN / FAIL100101| Check | What to Look For |102|-------|------------------|103| `@MainActor` | UI-bound classes and properties are main actor isolated |104| `Sendable` | Types crossing isolation boundaries conform to `Sendable` |105| `.task` modifier | Async work uses `.task {}` (auto-cancels on disappear) |106| Actor isolation | Mutable shared state protected by actors |107| Data races | No unprotected mutable state accessed from multiple contexts |108109### 6. Security — PASS / WARN / FAIL110111| Check | What to Look For |112|-------|------------------|113| Hardcoded secrets | No API keys, tokens, or passwords in source |114| Keychain usage | Sensitive data stored in Keychain, not UserDefaults |115| Sandbox entitlements | Minimal entitlements; no unnecessary capabilities |116| Input validation | User input validated before use |117| URL handling | External URLs validated before opening |118119### 7. Test Coverage — PASS / WARN / FAIL120121| Check | What to Look For |122|-------|------------------|123| Test file existence | Every feature has corresponding test file |124| Model tests | Business logic and data transformations tested |125| Edge cases | Empty states, nil values, boundary conditions covered |126| Async tests | `async` test methods with proper expectations |127| SwiftData tests | In-memory `ModelContainer` for persistence tests |128129## Output Format130131For each section, provide:132133```134### [Section Name] — [PASS/WARN/FAIL]135136**Summary:** One-line assessment.137138**Findings:**139- [file_path:line] Description of issue140- [file_path:line] Description of issue141142**Recommendation:** What to fix and in what order.143```144145## Cross-References146147- If the `apple-design-system` plugin is installed, use its `swiftui-ui-patterns`148 review checklist for SwiftUI-specific review149- For view structure refactoring, load `swiftui-view-refactor`150- For deep line-by-line analysis, load `audit-context-building`
kmshdev