swift-code-reviewer-skill 1.0.0

package/references/custom-guidelines.md

@@ -0,0 +1,852 @@
+# Custom Project Guidelines Integration
+
+This guide explains how to read, parse, and validate code against project-specific standards defined in `.claude/CLAUDE.md` and related architecture documents.
+
+---
+
+## 1. Overview
+
+### Purpose
+
+Project-specific guidelines allow teams to:
+- Define custom coding standards
+- Document architecture decisions
+- Establish testing requirements
+- Define design system usage
+- Set project-specific error handling patterns
+- Document navigation patterns
+
+### Common Locations
+
+```
+.claude/
+├── CLAUDE.md                           # Main coding standards
+├── DependencyInjection-Architecture.md # DI patterns
+├── Design System Structure.md          # Design system usage
+├── Navigation-Architecture.md          # Navigation patterns
+├── Testing-Guidelines.md               # Testing requirements
+├── Error-Handling.md                   # Error handling patterns
+└── API-Guidelines.md                   # API design standards
+```
+
+---
+
+## 2. Reading .claude/CLAUDE.md
+
+### 2.1 Locating the File
+
+**Check for:**
+- [ ] `.claude/CLAUDE.md` exists in repository root
+- [ ] Related architecture docs in `.claude/` directory
+- [ ] Project-specific subdirectories
+
+**Example Commands:**
+```bash
+# Check if .claude/CLAUDE.md exists
+if [ -f .claude/CLAUDE.md ]; then
+    echo "Project guidelines found"
+fi
+
+# List all .claude files
+ls -la .claude/
+
+# Find all markdown files in .claude
+find .claude -name "*.md"
+```
+
+### 2.2 Common Sections in CLAUDE.md
+
+**Typical Structure:**
+
+```markdown
+# Project Coding Standards
+
+## Architecture
+- Architecture pattern (MVVM, MVI, TCA, etc.)
+- Layer organization
+- Module structure
+
+## Swift Style Guide
+- Naming conventions
+- Code formatting
+- Documentation requirements
+
+## SwiftUI Patterns
+- State management approach
+- Property wrapper usage
+- View composition guidelines
+
+## Dependency Injection
+- DI approach (constructor, environment, etc.)
+- Service location rules
+
+## Error Handling
+- Error type patterns
+- Error reporting strategy
+- User-facing error messages
+
+## Testing
+- Test coverage requirements
+- Testing patterns
+- Mock/stub conventions
+
+## Design System
+- Color palette usage
+- Typography standards
+- Spacing system
+- Component library
+
+## Navigation
+- Navigation pattern
+- Deep linking approach
+- State restoration
+
+## Performance
+- Performance benchmarks
+- Optimization priorities
+
+## Security
+- Authentication approach
+- Data storage rules
+- API security
+```
+
+### 2.3 Parsing Sections
+
+**Strategy:**
+
+1. **Read entire file**
+2. **Identify sections** (markdown headers)
+3. **Extract rules and patterns** from each section
+4. **Create checklist** for validation
+
+**Example Parsing Logic:**
+
+```swift
+struct ProjectGuidelines {
+    let architecture: ArchitectureGuidelines
+    let swiftStyle: SwiftStyleGuidelines
+    let swiftUIPatterns: SwiftUIGuidelines
+    let dependencyInjection: DIGuidelines
+    let errorHandling: ErrorHandlingGuidelines
+    let testing: TestingGuidelines
+    let designSystem: DesignSystemGuidelines
+    let navigation: NavigationGuidelines
+
+    static func parse(from markdown: String) -> ProjectGuidelines {
+        // Parse markdown sections into structured guidelines
+    }
+}
+```
+
+---
+
+## 3. Extracting Coding Standards
+
+### 3.1 Architecture Patterns
+
+**What to Extract:**
+
+```markdown
+## Architecture
+
+We use **MVVM with Coordinators**:
+
+- Views: SwiftUI views, presentation only
+- ViewModels: @Observable classes, business logic
+- Models: Data structures and domain logic
+- Coordinators: Navigation flow management
+- Repositories: Data access abstraction
+- Use Cases: Single business operations
+
+### Rules
+1. ViewModels MUST use @Observable (iOS 17+)
+2. All dependencies MUST be injected via constructor
+3. Views MUST NOT contain business logic
+4. Navigation MUST go through Coordinator
+```
+
+**Extracted Rules:**
+- ✅ ViewModels use @Observable
+- ✅ Constructor injection required
+- ✅ No business logic in views
+- ✅ Coordinator-based navigation
+
+**Validation:**
+```swift
+// Check: ViewModel uses @Observable
+// ❌ Violation
+class UserViewModel: ObservableObject { }
+
+// ✅ Compliant
+@Observable
+final class UserViewModel { }
+
+// Check: Dependencies injected
+// ❌ Violation
+class ViewModel {
+    let service = NetworkService.shared
+}
+
+// ✅ Compliant
+class ViewModel {
+    let service: NetworkService
+    init(service: NetworkService) {
+        self.service = service
+    }
+}
+```
+
+### 3.2 Swift Style Guidelines
+
+**What to Extract:**
+
+```markdown
+## Swift Style Guide
+
+### Naming Conventions
+- Types: `UpperCamelCase`
+- Properties/Methods: `lowerCamelCase`
+- Protocols describing capabilities: `-able` or `-ing` suffix
+- Bool properties: Prefix with `is`, `has`, `should`
+
+### Code Organization
+- Maximum file length: 400 lines
+- Maximum method length: 50 lines
+- Use MARK comments for sections
+
+### Access Control
+- Default to `private`
+- Mark `internal` explicitly
+- Public API requires DocC comments
+
+### Error Handling
+- Custom error types conform to `AppError` protocol
+- Use typed throws (Swift 6+)
+- No force try except for bundled resources
+```
+
+**Extracted Rules:**
+- ✅ Naming conventions enforced
+- ✅ File length < 400 lines
+- ✅ Method length < 50 lines
+- ✅ MARK comments required
+- ✅ Explicit access control
+- ✅ Custom errors conform to AppError
+- ✅ No force try
+
+**Validation:**
+```swift
+// Check: Custom error conforms to AppError
+// ❌ Violation
+enum LoginError: Error {
+    case invalidCredentials
+}
+
+// ✅ Compliant
+enum LoginError: AppError {
+    case invalidCredentials
+
+    var message: String {
+        switch self {
+        case .invalidCredentials: return "Invalid email or password"
+        }
+    }
+
+    var code: Int {
+        switch self {
+        case .invalidCredentials: return 1001
+        }
+    }
+}
+```
+
+### 3.3 SwiftUI Patterns
+
+**What to Extract:**
+
+```markdown
+## SwiftUI Patterns
+
+### State Management
+- Use @Observable for all ViewModels (iOS 17+)
+- @State for view-local state only
+- @Binding for parent-child communication
+- @Environment for dependency injection
+- NO @StateObject or @ObservedObject with @Observable
+
+### View Composition
+- Maximum view body: 50 lines
+- Extract subviews for reusability
+- Use private struct for local subviews
+
+### Property Wrappers
+| Use Case | Property Wrapper |
+|----------|-----------------|
+| ViewModel | @Observable class |
+| View-local state | @State |
+| Two-way binding | @Binding |
+| Dependency | @Environment |
+```
+
+**Extracted Rules:**
+- ✅ @Observable for ViewModels
+- ✅ No @StateObject with @Observable
+- ✅ View body < 50 lines
+- ✅ Proper property wrapper usage
+
+### 3.4 Design System
+
+**What to Extract:**
+
+```markdown
+## Design System
+
+### Colors
+Use AppColors enum only. No hardcoded colors.
+
+```swift
+// ✅ Correct
+.foregroundColor(AppColors.primary)
+
+// ❌ Wrong
+.foregroundColor(.blue)
+```
+
+### Typography
+Use AppFonts enum only.
+
+```swift
+// ✅ Correct
+.font(AppFonts.title)
+
+// ❌ Wrong
+.font(.system(size: 24))
+```
+
+### Spacing
+Use AppSpacing for all padding and spacing.
+
+```swift
+// ✅ Correct
+.padding(AppSpacing.medium)
+
+// ❌ Wrong
+.padding(16)
+```
+```
+
+**Extracted Rules:**
+- ✅ Use AppColors, no hardcoded colors
+- ✅ Use AppFonts, no system fonts
+- ✅ Use AppSpacing, no magic numbers
+
+**Validation:**
+```swift
+// Check: No hardcoded colors
+// Search for:
+.foregroundColor(.red)      // ❌ Violation
+.background(.blue)          // ❌ Violation
+Color(red: 0.5, ...)       // ❌ Violation
+
+// Expected:
+.foregroundColor(AppColors.primary)  // ✅ Compliant
+```
+
+### 3.5 Testing Requirements
+
+**What to Extract:**
+
+```markdown
+## Testing Guidelines
+
+### Requirements
+- Minimum test coverage: 80%
+- All ViewModels MUST have unit tests
+- All Use Cases MUST have unit tests
+- Critical user flows MUST have UI tests
+
+### Testing Patterns
+- Arrange-Act-Assert pattern
+- Mock all dependencies
+- One assertion per test (when possible)
+- Descriptive test names: `test[Method]_[Scenario]_[ExpectedOutcome]`
+
+### Example
+```swift
+func testLogin_withValidCredentials_succeeds() async {
+    // Arrange
+    mockAuthService.loginResult = .success(user)
+    viewModel.email = "test@example.com"
+    viewModel.password = "password"
+
+    // Act
+    await viewModel.login()
+
+    // Assert
+    XCTAssertNil(viewModel.error)
+}
+```
+```
+
+**Extracted Rules:**
+- ✅ 80% test coverage minimum
+- ✅ ViewModels tested
+- ✅ Use Cases tested
+- ✅ Arrange-Act-Assert pattern
+- ✅ Descriptive test names
+
+---
+
+## 4. Validation Against Custom Guidelines
+
+### 4.1 Architecture Validation
+
+**Checklist:**
+
+```markdown
+Architecture Compliance:
+- [ ] Follows defined pattern (MVVM, etc.)
+- [ ] Layer separation enforced
+- [ ] Dependencies injected properly
+- [ ] No architecture violations
+```
+
+**Example Validation:**
+
+```swift
+// File: LoginViewModel.swift
+
+// Check 1: Uses @Observable (project requirement)
+@Observable  // ✅ Compliant
+final class LoginViewModel {
+
+    // Check 2: Dependencies injected via constructor
+    private let authService: AuthService  // ✅ Protocol
+    private let loginUseCase: LoginUseCase
+
+    init(authService: AuthService, loginUseCase: LoginUseCase) {  // ✅ Injected
+        self.authService = authService
+        self.loginUseCase = loginUseCase
+    }
+
+    // Check 3: Business logic in ViewModel, not View
+    func login() async {  // ✅ Business logic here
+        // Implementation
+    }
+}
+
+// File: LoginView.swift
+struct LoginView: View {
+    let viewModel: LoginViewModel  // ✅ ViewModel injected
+
+    var body: some View {
+        // ✅ Only presentation code, no business logic
+        VStack {
+            TextField("Email", text: $viewModel.email)
+            Button("Login") {
+                Task { await viewModel.login() }  // ✅ Delegates to ViewModel
+            }
+        }
+    }
+}
+```
+
+### 4.2 Error Handling Validation
+
+**Project Standard:**
+```markdown
+## Error Handling
+
+All errors MUST conform to AppError protocol:
+
+```swift
+protocol AppError: Error {
+    var message: String { get }
+    var code: Int { get }
+}
+```
+
+Error codes:
+- 1000-1999: Authentication errors
+- 2000-2999: Network errors
+- 3000-3999: Database errors
+- 4000-4999: Validation errors
+```
+
+**Validation:**
+
+```swift
+// ❌ Violation: Doesn't conform to AppError
+enum LoginError: Error {
+    case invalidCredentials
+}
+
+// ✅ Compliant: Conforms to AppError with correct code range
+enum LoginError: AppError {
+    case invalidCredentials
+    case accountLocked
+
+    var message: String {
+        switch self {
+        case .invalidCredentials: return "Invalid email or password"
+        case .accountLocked: return "Account locked"
+        }
+    }
+
+    var code: Int {
+        switch self {
+        case .invalidCredentials: return 1001  // ✅ In auth range (1000-1999)
+        case .accountLocked: return 1002
+        }
+    }
+}
+```
+
+### 4.3 Design System Validation
+
+**Automated Checks:**
+
+```bash
+# Search for hardcoded colors
+grep -r "\.foregroundColor(\." --include="*.swift" | grep -v "AppColors"
+
+# Search for hardcoded font sizes
+grep -r "\.font(\.system(size:" --include="*.swift"
+
+# Search for magic numbers in padding
+grep -r "\.padding([0-9]" --include="*.swift"
+```
+
+**Example Violations:**
+
+```swift
+// ❌ Violation: Hardcoded color
+Text("Hello")
+    .foregroundColor(.blue)
+
+// ✅ Compliant: Uses design system
+Text("Hello")
+    .foregroundColor(AppColors.primary)
+
+// ❌ Violation: Hardcoded spacing
+VStack(spacing: 16) { }
+
+// ✅ Compliant: Uses design system
+VStack(spacing: AppSpacing.medium) { }
+```
+
+---
+
+## 5. Reporting Custom Guideline Violations
+
+### 5.1 Violation Template
+
+```markdown
+🔴 **Violates Project Standard: [Standard Name]** ([file]:[line])
+**Severity**: [Critical/High/Medium]
+**Category**: Project Standards
+
+**Project Guideline**: [Quote from .claude/CLAUDE.md]
+
+**Violation**: [What doesn't comply]
+
+**Current Code:**
+```swift
+[Code that violates]
+```
+
+**Expected Code:**
+```swift
+[Code that complies]
+```
+
+**Reference**: .claude/CLAUDE.md:[section]
+```
+
+### 5.2 Example Violation Report
+
+```markdown
+🔴 **Violates Project Standard: Error Handling** (LoginViewModel.swift:45)
+**Severity**: High
+**Category**: Project Standards
+
+**Project Guideline**: "All errors MUST conform to AppError protocol" (.claude/CLAUDE.md:Error Handling)
+
+**Violation**: LoginError does not conform to AppError protocol
+
+**Current Code:**
+```swift
+enum LoginError: Error {
+    case invalidCredentials
+}
+```
+
+**Expected Code:**
+```swift
+enum LoginError: AppError {
+    case invalidCredentials
+
+    var message: String {
+        switch self {
+        case .invalidCredentials: return "Invalid email or password"
+        }
+    }
+
+    var code: Int {
+        switch self {
+        case .invalidCredentials: return 1001
+        }
+    }
+}
+```
+
+**Reference**: .claude/CLAUDE.md:Error Handling
+```
+
+---
+
+## 6. Integration with Review Process
+
+### 6.1 Review Checklist
+
+**Step-by-Step:**
+
+1. **Load Project Guidelines**
+   ```
+   - Read .claude/CLAUDE.md
+   - Read related architecture docs
+   - Extract all rules and patterns
+   ```
+
+2. **Create Validation Checklist**
+   ```
+   - Architecture compliance
+   - Coding style adherence
+   - Error handling patterns
+   - Design system usage
+   - Testing requirements
+   ```
+
+3. **Validate Code**
+   ```
+   - Compare code against each rule
+   - Flag violations
+   - Acknowledge compliance
+   ```
+
+4. **Generate Report**
+   ```
+   - List all violations with references to .claude/CLAUDE.md
+   - Provide positive feedback for compliance
+   - Include specific line numbers and fixes
+   ```
+
+### 6.2 Prioritization
+
+**Severity Based on Impact:**
+
+| Violation Type | Severity | Example |
+|----------------|----------|---------|
+| Architecture violation | High | Business logic in View |
+| Security pattern violation | Critical | Credentials in UserDefaults |
+| Error handling violation | High | No AppError conformance |
+| Design system violation | Medium | Hardcoded colors |
+| Style guide violation | Low | Naming convention |
+| Testing requirement | Medium | Missing tests |
+
+---
+
+## 7. Example Project Guidelines
+
+### 7.1 Complete .claude/CLAUDE.md Example
+
+```markdown
+# MyApp Coding Standards
+
+## Architecture
+
+We use **MVVM with Coordinators and Repositories**.
+
+### Layers
+- **View**: SwiftUI views, presentation only
+- **ViewModel**: @Observable classes, business logic
+- **Coordinator**: Navigation management
+- **Repository**: Data access abstraction
+- **Use Case**: Single business operations
+
+### Rules
+1. ViewModels MUST use @Observable (iOS 17+)
+2. All dependencies MUST be injected via constructor
+3. Views MUST NOT contain business logic
+4. Navigation MUST go through Coordinator
+
+## Error Handling
+
+All errors MUST conform to AppError:
+
+```swift
+protocol AppError: Error {
+    var message: String { get }
+    var code: Int { get }
+}
+```
+
+Error code ranges:
+- 1000-1999: Authentication
+- 2000-2999: Network
+- 3000-3999: Database
+
+## Design System
+
+### Colors
+Use `AppColors` enum ONLY. No hardcoded colors.
+
+### Typography
+Use `AppFonts` enum ONLY. No system fonts.
+
+### Spacing
+Use `AppSpacing` enum ONLY. No magic numbers.
+
+## Testing
+
+### Requirements
+- Minimum coverage: 80%
+- All ViewModels MUST have unit tests
+- All Use Cases MUST have unit tests
+- Critical flows MUST have UI tests
+
+### Patterns
+- Arrange-Act-Assert
+- Mock all dependencies
+- Descriptive names: `test[Method]_[Scenario]_[Expected]`
+
+## SwiftUI Patterns
+
+- @Observable for ViewModels
+- @State for view-local state
+- @Environment for dependencies
+- View body < 50 lines
+- Extract reusable subviews
+```
+
+### 7.2 Validation Example
+
+**Code to Review:**
+
+```swift
+// LoginViewModel.swift
+@Observable
+final class LoginViewModel {
+    private let loginUseCase: LoginUseCase
+
+    var email: String = ""
+    var password: String = ""
+    var isLoading: Bool = false
+
+    init(loginUseCase: LoginUseCase) {
+        self.loginUseCase = loginUseCase
+    }
+
+    func login() async {
+        // Implementation
+    }
+}
+
+// LoginError.swift
+enum LoginError: AppError {
+    case invalidCredentials
+
+    var message: String {
+        switch self {
+        case .invalidCredentials: return "Invalid email or password"
+        }
+    }
+
+    var code: Int {
+        switch self {
+        case .invalidCredentials: return 1001  // Auth range
+        }
+    }
+}
+
+// LoginView.swift
+struct LoginView: View {
+    let viewModel: LoginViewModel
+
+    var body: some View {
+        VStack(spacing: AppSpacing.medium) {
+            TextField("Email", text: $viewModel.email)
+                .textFieldStyle(.roundedBorder)
+
+            SecureField("Password", text: $viewModel.password)
+                .textFieldStyle(.roundedBorder)
+
+            Button("Login") {
+                Task { await viewModel.login() }
+            }
+            .buttonStyle(.borderedProminent)
+        }
+        .padding(AppSpacing.large)
+    }
+}
+```
+
+**Review Report:**
+
+```markdown
+## Project Standards Compliance
+
+✅ **Excellent Architecture Adherence**
+- LoginViewModel uses @Observable (required for iOS 17+)
+- Dependencies injected via constructor
+- No business logic in LoginView
+- Clear layer separation
+
+✅ **Error Handling Compliance**
+- LoginError conforms to AppError protocol
+- Error code in correct range (1000-1999 for auth)
+- Descriptive error messages
+
+✅ **Design System Usage**
+- Uses AppSpacing for all spacing
+- No hardcoded values
+- Consistent design token usage
+
+✅ **SwiftUI Best Practices**
+- Proper property wrapper usage (@Observable)
+- View body is concise (< 50 lines)
+- Clear separation of concerns
+
+**Overall**: Fully compliant with project coding standards
+```
+
+---
+
+## 8. Quick Reference
+
+### Files to Check
+1. `.claude/CLAUDE.md` - Main standards
+2. `.claude/DependencyInjection-Architecture.md` - DI patterns
+3. `.claude/Design System Structure.md` - Design system
+4. `.claude/Testing-Guidelines.md` - Testing standards
+
+### Key Validation Points
+- [ ] Architecture pattern followed
+- [ ] Error handling conforms to project standard
+- [ ] Design system used (no hardcoded values)
+- [ ] Testing requirements met
+- [ ] Naming conventions followed
+- [ ] Dependency injection pattern used
+
+### Severity Guidelines
+- **Critical**: Security, architecture violations
+- **High**: Error handling, major patterns
+- **Medium**: Design system, testing
+- **Low**: Style, naming
+
+---
+
+## Version
+**Last Updated**: 2026-02-10
+**Version**: 1.0.0