iOS Code Quality Auditor

Comprehensive code quality auditing for iOS/Swift projects covering memory management, thread safety, optional handling, SwiftUI patterns, accessibility, and more.

When to Use This Skill

• Pre-release audits - Before submitting to App Store
• Code review preparation - Before team reviews
• Refactoring guidance - Identifying technical debt
• Quality baselines - Establishing project standards
• Bug prevention - Catching issues before they reach production
• Learning tool - Understanding Swift best practices

Quick Start

Option 1: Automated Scan (Fastest)

For quick automated analysis:

python3 scripts/scan_code_quality.py /path/to/project code_quality_report.md
python3 scripts/detect_infinite_loops.py /path/to/project loop_risks_report.md

This generates reports on:

• Force unwraps and force casts
• Thread safety violations
• Memory management issues
• SwiftUI anti-patterns
• Infinite loop risks
• Calculation overflow potential

Option 2: Manual Review (Most Thorough)

For comprehensive human-guided audits, follow the workflows below.

Audit Workflows

Workflow 1: Full Project Audit

Use when reviewing entire codebase or establishing quality baseline.

1. Run automated scans first (if desired for quick wins)

   python3 scripts/scan_code_quality.py /path/to/project
   python3 scripts/detect_infinite_loops.py /path/to/project
   

2. Review scan results - Fix critical issues immediately

3. Deep dive by category - Use reference checklists:

   • Memory management → Read references/memory-management.md
   • Thread safety → Read references/thread-safety.md
   • SwiftUI patterns → Read references/swiftui-antipatterns.md
   • Optional safety → Read references/optional-safety.md
   • Accessibility → Read references/accessibility-localization.md

4. Compile findings - Create prioritized issue list

5. Create action plan - Organize by severity and effort

Workflow 2: Pre-Release Checklist

Use before major releases or App Store submissions.

Critical items only (these can crash or severely impact users):

1. Memory leaks - Run automated scan, check for:

   • Timers without invalidation
   • Delegates without weak reference
   • Closures without [weak self] in stored properties

2. Thread safety - Verify:

   • All UI updates on @MainActor or DispatchQueue.main
   • No data races on shared mutable state
   • No main thread deadlocks

3. Force unwraps - Search and eliminate:

   • No ! in production code (except IBOutlets)
   • No as! force casts
   • No try! without justification

4. Accessibility - Validate:

   • VoiceOver labels on all buttons/images
   • Touch targets ≥44x44 points
   • Text contrast meets WCAG 2.0

Workflow 3: Focused Category Audit

Use when addressing specific issues or learning a domain.

Pick a category:

• Memory Management → Read references/memory-management.md
• Thread Safety → Read references/thread-safety.md
• SwiftUI Patterns → Read references/swiftui-antipatterns.md
• Optional Safety → Read references/optional-safety.md
• Accessibility → Read references/accessibility-localization.md

Then:

1. Read the reference guide completely
2. Search codebase for patterns mentioned
3. Document findings with file:line references
4. Prioritize by severity levels in guide
5. Create remediation plan

Workflow 4: New Feature Review

Use when reviewing pull requests or new features.

1. Run automated scan on changed files

   # Scan specific files
   python3 scripts/scan_code_quality.py /path/to/feature-branch
   

2. Quick checklist for new code:

   • No force unwraps introduced
   • Closures have proper capture lists
   • UI updates on main thread
   • SwiftUI state management correct
   • Accessibility labels added
   • Strings localized

3. Review against anti-patterns - Check relevant reference

4. Verify tests - New code should have tests

Reference Guides

Each reference provides comprehensive checklists with examples:

references/memory-management.md

• Retain cycles in closures
• Delegate pattern leaks
• Timer and observer cleanup
• SwiftUI ObservableObject lifecycle
• Combine subscriptions
• Task and async/await patterns

references/thread-safety.md

• @MainActor usage and violations
• Data race detection
• DispatchQueue patterns
• Actor reentrancy issues
• Sendable conformance
• Swift concurrency patterns

references/swiftui-antipatterns.md

• State management (@State, @StateObject, @ObservedObject)
• View performance issues
• Navigation patterns
• Binding anti-patterns
• Modifier ordering
• Memory and lifecycle issues

references/optional-safety.md

• Force unwrapping dangers
• Implicitly unwrapped optionals
• Array and dictionary safety
• Optional chaining patterns
• Type casting safety
• Failable initializers

references/accessibility-localization.md

• VoiceOver support
• Dynamic Type
• Color contrast
• Touch target sizing
• String localization
• RTL language support

Automated Scripts

scripts/scan_code_quality.py

Scans Swift files for common issues.

Usage:

python3 scripts/scan_code_quality.py <project_path> [output_file]

Detects:

• Force unwraps (!)
• Force casts (as!)
• Force try (try!)
• Implicitly unwrapped optionals
• Potential MainActor violations
• Retain cycle risks
• SwiftUI anti-patterns

Output: Markdown report with severity levels and suggestions

scripts/detect_infinite_loops.py

Detects loop and calculation risks.

Usage:

python3 scripts/detect_infinite_loops.py <project_path> [output_file]

Detects:

• While loops without condition modifications
• Suspicious for loop patterns
• Unbounded recursion
• Overflow-prone calculations
• Division by zero risks
• Exponential growth patterns

Output: Markdown report with risk levels

Report Format

All reports follow this structure:

# Issue Category

**File:** `path/to/File.swift:123`
**Issue:** Description of the problem
**Code:**
```swift
// Problematic code snippet

Suggestion: How to fix it

Severity Levels:

• 🔴 CRITICAL - Must fix (crashes, security, data loss)
• 🟡 IMPORTANT - Should fix (bugs, poor UX, tech debt)
• 🔵 INFO - Nice to have (optimization, style)

## Tips for Effective Audits

### For Large Projects

1. **Start with automated scans** - Get quick overview
2. **Prioritize by severity** - Fix critical issues first
3. **Batch similar issues** - More efficient remediation
4. **Create tracking issues** - Don't lose track of findings

### For New Projects

1. **Run early and often** - Catch issues when easy to fix
2. **Set up CI integration** - Automated checks on PRs
3. **Create team guidelines** - Document decisions
4. **Use as learning tool** - Teach team best practices

### For Legacy Code

1. **Focus on hot paths** - Audit code that runs frequently
2. **Prioritize user-facing** - Fix what users encounter
3. **Document known issues** - Track technical debt
4. **Incremental improvement** - Don't try to fix everything at once

## False Positives

Some patterns the automated scanners flag are actually acceptable:

### Acceptable Force Unwraps
- `@IBOutlet weak var tableView: UITableView!`
- `let url = URL(string: "https://known-valid.com")!`
- `let image = UIImage(systemName: "star")!` (system symbols)
- Test assertions: `let result = try! sut.parse(validInput)`

### Acceptable Implicitly Unwrapped
- IBOutlets in view controllers
- Test mock properties
- Framework-required patterns

### Acceptable Strong Self
- Non-escaping closures
- GCD sync operations
- SwiftUI view builders

**Always review flagged issues** - Automated tools aren't perfect.

## Integration with Development Workflow

### Pre-commit Hook
```bash
#!/bin/bash
python3 .skills/ios-code-quality-auditor/scripts/scan_code_quality.py . /tmp/audit.md
if grep -q "CRITICAL" /tmp/audit.md; then
    echo "❌ Critical code quality issues found"
    cat /tmp/audit.md
    exit 1
fi

CI/CD Integration

- name: Code Quality Audit
  run: |
    python3 scripts/scan_code_quality.py . audit_report.md
    # Upload artifact or fail on critical issues

Code Review Template

## Code Quality Checklist
- [ ] No force unwraps introduced
- [ ] Proper memory management
- [ ] Thread-safe UI updates
- [ ] SwiftUI patterns correct
- [ ] Accessibility labels added
- [ ] Strings localized

Common Patterns to Address

High-Priority Fixes

Pattern 1: Timer retain cycle

// Bad
timer = Timer.scheduledTimer(target: self, selector: #selector(tick), ...)

// Good
timer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self] _ in
    self?.tick()
}

Pattern 2: UI update from background

// Bad
Task {
    let data = await fetchData()
    tableView.reloadData() // ⚠️ May not be on main thread
}

// Good
Task {
    let data = await fetchData()
    await MainActor.run {
        tableView.reloadData()
    }
}

Pattern 3: Force unwrap in production

// Bad
let user = currentUser! // ⚠️ Crash if nil

// Good
guard let user = currentUser else { return }

Medium-Priority Improvements

Pattern 4: SwiftUI state management

// Bad
@ObservedObject var viewModel = ViewModel() // Recreated on render

// Good
@StateObject private var viewModel = ViewModel()

Pattern 5: Optional chaining

// Bad
if let user = user {
    if let address = user.address {
        if let city = address.city {
            print(city)
        }
    }
}

// Good
if let city = user?.address?.city {
    print(city)
}

Customizing for Your Team

Create Team-Specific Rules

1. Document exceptions - When force unwraps are OK
2. Set severity thresholds - What's critical vs. nice-to-have
3. Add custom patterns - Project-specific anti-patterns
4. Define code style - Consistent optional handling

Extend the Scripts

The Python scripts are starting points. Consider adding:

• Project-specific checks
• Custom severity levels
• Integration with your CI/CD
• Slack/email notifications
• Metrics tracking over time

Continuous Improvement

Metrics to Track

• Total issues by severity
• Issues per 1000 lines of code
• Time to fix by category
• New issues introduced per PR
• Test coverage correlation

Regular Cadence

• Daily: PR-level scans for new code
• Weekly: Team review of open issues
• Monthly: Full project audit
• Quarterly: Update audit rules and patterns

Getting the Most Value

1. Start small - Don't try to fix everything at once
2. Automate - Use scripts and CI integration
3. Educate - Use findings as teaching moments
4. Measure - Track improvement over time
5. Iterate - Update your rules and patterns

Remember

The goal isn't perfect code - it's robust, maintainable code that serves users well. Use these audits to:

• Prevent crashes - Catch issues before users do
• Reduce bugs - Proactive problem solving
• Improve UX - Better accessibility and performance
• Build knowledge - Learn Swift best practices
• Ship faster - Fewer production issues

Happy auditing! 🔍✨