swift-code-reviewer-skill 1.0.0 → 1.1.1

package/README.md

@@ -1,502 +1,155 @@
 # Swift Code Reviewer Agent Skill
 
-A comprehensive code review skill for Claude that performs multi-layer analysis of Swift and SwiftUI code, combining Apple's best practices with project-specific coding standards.
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/Viniciuscarvalho?style=social)](https://github.com/sponsors/Viniciuscarvalho)
+[![npm version](https://img.shields.io/npm/v/swift-code-reviewer-skill)](https://www.npmjs.com/package/swift-code-reviewer-skill)
 
-## Features
+A code review skill for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) that performs multi-layer analysis of Swift and SwiftUI code, combining Apple's best practices with your project-specific coding standards.
 
-- 🔍 **Multi-Layer Analysis**: Combines Swift 6+ best practices, SwiftUI patterns, performance optimization, and security checks
-- 📋 **Project-Aware Reviews**: Reads `.claude/CLAUDE.md` to validate against project-specific standards and architecture patterns
-- 🎯 **Comprehensive Feedback**: Provides Critical/High/Medium/Low severity issues, positive feedback, and refactoring suggestions
-- 🔗 **Skill Integration**: Leverages existing `swift-best-practices`, `swiftui-expert-skill`, and `swiftui-performance-audit` skills
-- 📊 **Actionable Output**: Structured reports with file:line references, code examples, and prioritized action items
-- 🚀 **Platform Support**: Works with GitHub PRs, GitLab MRs, and local git changes
-
-## What It Reviews
-
-### Swift Quality
-- **Concurrency Safety**: Actor isolation, MainActor usage, Sendable conformance, data race prevention
-- **Error Handling**: Typed throws, Result types, proper error propagation
-- **Optionals**: Safe unwrapping, guard statements, no force unwraps
-- **Access Control**: Explicit access modifiers, minimal API surface
-- **Naming**: Swift API Design Guidelines compliance
-
-### SwiftUI Patterns
-- **State Management**: @Observable, @State, @Binding, @Environment usage
-- **Property Wrappers**: Correct wrapper selection for each use case
-- **Modern APIs**: NavigationStack, .task, latest SwiftUI features
-- **View Composition**: Extracted subviews, ViewBuilder patterns
-- **Accessibility**: Labels, hints, Dynamic Type support
-
-### Performance
-- **View Optimization**: Unnecessary updates, Equatable conformance
-- **ForEach Performance**: Stable identity, lazy loading
-- **Layout Efficiency**: GeometryReader usage, layout thrash
-- **Resource Management**: Image loading, memory leaks, async patterns
-
-### Security & Safety
-- **Input Validation**: Sanitization, bounds checking, type safety
-- **Sensitive Data**: Keychain storage, biometric authentication, secure logging
-- **Network Security**: HTTPS enforcement, certificate pinning, API key protection
-- **Permissions**: Privacy descriptions, permission timing, graceful handling
-
-### Architecture
-- **Pattern Compliance**: MVVM, MVI, TCA adherence
-- **Dependency Injection**: Constructor injection, protocol-based dependencies
-- **Code Organization**: File structure, MARK comments, logical grouping
-- **Testability**: Unit test coverage, mock usage, test structure
-
-### Project Standards
-- **Custom Guidelines**: Validates against `.claude/CLAUDE.md` rules
-- **Design System**: Color palette, typography, spacing token usage
-- **Error Patterns**: Custom error type conformance
-- **Testing Requirements**: Coverage thresholds, testing patterns
-
-## Installation
-
-### Option 1: NPX (Recommended)
-
-The fastest way to install - no cloning required:
+## Quick Start
 
 ```bash
 npx swift-code-reviewer-skill
 ```
 
-This automatically installs the skill to `~/.claude/skills/swift-code-reviewer-skill/`
-
-To uninstall:
-
-```bash
-npx swift-code-reviewer-skill uninstall
-```
-
-### Option 2: Clone This Repository
-
-```bash
-# Clone the skill
-git clone https://github.com/Viniciuscarvalho/swift-code-reviewer-skill.git ~/.claude/skills/swift-code-reviewer-skill
-
-# The skill is now ready to use!
-```
-
-### Option 3: Manual Installation
-
-1. Create the skill directory:
-```bash
-mkdir -p ~/.claude/skills/swift-code-reviewer-skill/references
-```
-
-2. Download the files from this repository into the directory
+That's it. The skill is installed and ready to use. Run it again anytime to update to the latest version.
 
-3. Restart Claude or reload skills
-
-### Verify Installation
-
-```bash
-ls ~/.claude/skills/swift-code-reviewer-skill/
-# Should show: SKILL.md, README.md, references/, and more
-```
+> No cloning, no manual setup. NPX always fetches the latest version automatically.
 
 ## Usage
 
-### Basic Usage
+![Swift Code Reviewer in action](assets/demo.png)
 
-The skill automatically activates when you ask Claude to review Swift/SwiftUI code:
+Just ask Claude to review your code:
 
 ```
 Review this PR
-
 Review LoginView.swift
-
 Review my uncommitted changes
-
-Check if this follows our coding standards
-```
-
-### Review Specific Files
-
-```
-Review UserProfileView.swift
-```
-
-**What it does:**
-1. Reads `.claude/CLAUDE.md` for project standards
-2. Analyzes the file against all quality dimensions
-3. Provides structured feedback with severity levels
-4. Includes positive feedback and refactoring suggestions
-
-### Review Git Changes
-
-```
-Review my uncommitted changes
-```
-
-**What it does:**
-1. Runs `git diff` to identify changes
-2. Analyzes modified files
-3. Focuses on changed lines for efficiency
-4. Generates comprehensive review report
-
-### Review Pull Requests (GitHub)
-
-```
-Review PR #123
-```
-
-**What it does:**
-1. Fetches PR details using `gh pr view 123`
-2. Gets diff using `gh pr diff 123`
-3. Reads all changed files for context
-4. Generates detailed review with file:line references
-
-### Review Merge Requests (GitLab)
-
-```
-Review MR #456
-```
-
-**What it does:**
-1. Fetches MR details using `glab mr view 456`
-2. Gets diff and changed files
-3. Performs multi-layer analysis
-4. Generates actionable feedback
-
-### Review Against Custom Standards
-
-```
-Review LoginViewModel.swift against our coding standards
-```
-
-**What it does:**
-1. Reads `.claude/CLAUDE.md` and related architecture docs
-2. Extracts project-specific rules
-3. Validates code against both Apple and project standards
-4. Reports compliance and violations
-
-### Review Multiple Files
-
-```
 Review all ViewModels in the Features folder
+Check if this follows our coding standards
 ```
 
-**What it does:**
-1. Finds all matching files
-2. Analyzes each against architecture patterns
-3. Provides file-by-file review
-4. Summarizes common patterns and issues
+The skill automatically activates, reads your `.claude/CLAUDE.md` for project standards, and generates a structured report with severity levels, code examples, and prioritized action items.
 
-## How It Works
-
-The skill follows a **four-phase workflow**:
-
-### Phase 1: Context Gathering
-
-1. **Read Project Guidelines**
-   - Loads `.claude/CLAUDE.md` if it exists
-   - Reads related architecture documents
-   - Extracts custom coding standards
-
-2. **Identify Review Scope**
-   - Determines files to review (user-specified, git diff, PR/MR)
-   - Categorizes changes by type (UI, logic, tests)
-
-3. **Gather Context**
-   - Reads all files completely
-   - Understands broader context
-   - Identifies component relationships
-
-### Phase 2: Automated Analysis
-
-Runs parallel checks across **six core categories**:
-
-1. **Swift Best Practices** (leverages `swift-best-practices` skill)
-   - Concurrency safety and actor isolation
-   - API design and naming conventions
-   - Swift 6+ feature adoption
-
-2. **SwiftUI Quality** (leverages `swiftui-expert-skill`)
-   - State management patterns
-   - Modern API usage
-   - View composition
-
-3. **Performance** (leverages `swiftui-performance-audit`)
-   - View update optimization
-   - ForEach performance
-   - Resource management
-
-4. **Security & Safety**
-   - Force unwrap detection
-   - Sensitive data handling
-   - Network security
-
-5. **Architecture & Maintainability**
-   - Pattern compliance
-   - Dependency injection
-   - Testability
-
-6. **Project-Specific Standards**
-   - `.claude/CLAUDE.md` compliance
-   - Design system usage
-   - Custom error patterns
-
-### Phase 3: Report Generation
-
-1. **Categorizes findings** by severity (Critical, High, Medium, Low)
-2. **Includes positive feedback** for good practices
-3. **Adds refactoring suggestions** for improvements
-4. **Groups by file** and category
-5. **Provides code examples** for all issues
-
-### Phase 4: Delivery
-
-Generates a structured markdown report:
+### Example Output
 
 ```markdown
 # Code Review Report
 
 ## Summary
-- Files Reviewed: 5
-- Critical: 0
-- High: 2
-- Medium: 5
-- Low: 3
-- Positive Feedback: 8
 
-## Detailed Findings
+- Files Reviewed: 3 | Critical: 0 | High: 1 | Medium: 2 | Low: 1
+
+## File: LoginViewModel.swift
 
-### File: LoginView.swift
+✅ **Excellent Modern API Usage** (line 12)
 
-#### ✅ Positive Feedback
-1. Excellent use of @Observable for state management
+- Using @Observable instead of ObservableObject
 
-#### 🟡 High Priority
-1. Force unwrap detected at line 89 (potential crash)
+🟡 **Force Unwrap Detected** (line 89)
+Current: `let user = repository.currentUser!`
+Fix:
+guard let user = repository.currentUser else {
+logger.error("No current user")
+return
+}
 
-#### 💡 Refactoring Suggestions
-1. Consider extracting login form into separate view
+🔴 **Violates Design System Standard** (line 45)
+Current: `.foregroundColor(.blue)`
+Fix: `.foregroundColor(AppColors.primary)`
 
 ## Prioritized Action Items
-[Must fix, should fix, consider items]
-```
 
-## Review Report Structure
+1. [Must fix] Remove force unwrap at line 89
+2. [Should fix] Use design system colors at line 45
+```
 
-### Severity Levels
+## What It Reviews
 
-| Severity | Icon | Description | Response Time |
-|----------|------|-------------|---------------|
-| **Critical** | 🔴 | Security vulnerabilities, crashes, data races | Must fix before merge |
-| **High** | 🟡 | Performance issues, anti-patterns, major violations | Should fix before merge |
-| **Medium** | 🟠 | Code quality, documentation, minor violations | Fix in current sprint |
-| **Low** | 🔵 | Style, suggestions, minor improvements | Consider for future |
+| Category              | Checks                                                                                                    |
+| --------------------- | --------------------------------------------------------------------------------------------------------- |
+| **Swift Quality**     | Concurrency safety, actor isolation, Sendable, error handling, optionals, access control, naming          |
+| **SwiftUI Patterns**  | @Observable, state management, property wrappers, NavigationStack, .task, view composition, accessibility |
+| **Performance**       | View updates, Equatable, ForEach identity, GeometryReader, lazy loading, memory leaks                     |
+| **Security**          | Keychain, input validation, HTTPS, certificate pinning, API key protection, sensitive data logging        |
+| **Architecture**      | MVVM/MVI/TCA compliance, dependency injection, code organization, testability                             |
+| **Project Standards** | `.claude/CLAUDE.md` rules, design system, custom error patterns, testing requirements                     |
 
-### Feedback Types
+### Severity Levels
 
-**Positive Feedback** ✅
-- Acknowledges good practices
-- Highlights excellent implementations
-- Recognizes proper patterns
+| Icon | Severity | Action                  |
+| ---- | -------- | ----------------------- |
+| 🔴   | Critical | Must fix before merge   |
+| 🟡   | High     | Should fix before merge |
+| 🟠   | Medium   | Fix in current sprint   |
+| 🔵   | Low      | Consider for future     |
 
-**Issues** 🔴🟡🟠🔵
-- File and line references
-- Code examples (before/after)
-- Specific fixes with explanations
-- Links to documentation
+## Platform Support
 
-**Refactoring Suggestions** 💡
-- Proactive improvements
-- Modernization opportunities
-- Code simplification ideas
+- Works with **GitHub PRs** (`gh`), **GitLab MRs** (`glab`), and **local git changes**
+- Swift 6.0+ | iOS 17+ | macOS 14+ | watchOS 10+ | tvOS 17+ | visionOS 1+
 
 ## Project-Specific Standards
 
-The skill reads `.claude/CLAUDE.md` to understand your project's:
-
-- Architecture pattern (MVVM, MVI, TCA, etc.)
-- Dependency injection approach
-- Error handling patterns
-- Testing requirements
-- Design system guidelines
-- Navigation patterns
-- Custom naming conventions
-
-### Example .claude/CLAUDE.md
+Add a `.claude/CLAUDE.md` to your project and the skill will validate against your rules:
 
 ```markdown
-# MyApp Coding Standards
+# MyApp Standards
 
 ## Architecture
-We use **MVVM with Coordinators**:
+
 - ViewModels MUST use @Observable (iOS 17+)
 - All dependencies MUST be injected via constructor
 - Views MUST NOT contain business logic
 
-## Error Handling
-All errors MUST conform to AppError:
-```swift
-protocol AppError: Error {
-    var message: String { get }
-    var code: Int { get }
-}
-```
-
 ## Design System
+
 - Use AppColors enum ONLY
 - Use AppFonts enum ONLY
-- Use AppSpacing for all padding
 
 ## Testing
+
 - Minimum coverage: 80%
 - All ViewModels MUST have unit tests
 ```
 
-The skill will validate your code against these standards and report violations.
-
-## Reference Documentation
-
-The skill includes comprehensive reference guides:
-
-- **review-workflow.md**: Step-by-step review process and git commands
-- **swift-quality-checklist.md**: Swift 6+ concurrency, error handling, optionals
-- **swiftui-review-checklist.md**: State management, property wrappers, modern APIs
-- **performance-review.md**: View optimization, ForEach performance, layout efficiency
-- **security-checklist.md**: Input validation, sensitive data, network security
-- **architecture-patterns.md**: MVVM, Repository, DI, Use Case, Coordinator patterns
-- **feedback-templates.md**: Review comment templates and severity guidelines
-- **custom-guidelines.md**: How to parse and validate `.claude/CLAUDE.md`
-
-## Integration with Other Skills
-
-This skill **leverages** three foundational skills:
-
-### swift-best-practices
-For Swift 6+ language patterns, concurrency, and API design
-- Loads when reviewing Swift language usage
-- References: `concurrency.md`, `swift6-features.md`, `api-design.md`
-
-### swiftui-expert-skill
-For SwiftUI state management and modern APIs
-- Loads when reviewing SwiftUI views
-- References: `state-management.md`, `modern-apis.md`, `view-composition.md`
-
-### swiftui-performance-audit
-For performance analysis
-- Loads when performance concerns identified
-- Runs focused audit on performance-sensitive paths
-
-**Note**: These skills should be installed separately for full functionality, but the code reviewer works independently with its own comprehensive checklists.
-
-## Examples
-
-### Example 1: Review Uncommitted Changes
-
-**Input:**
-```
-Review my uncommitted changes
-```
-
-**Output:**
-```markdown
-# Code Review Report
-
-## Summary
-- Files Reviewed: 3
-- Critical: 0
-- High: 1
-- Medium: 2
-- Low: 1
-- Positive Feedback: 5
-
-## File: LoginViewModel.swift
-
-✅ **Excellent Modern API Usage** (line 12)
-- Using @Observable instead of ObservableObject
-- Clean, modern pattern for iOS 17+
+## Alternative Installation
 
-🟡 **Force Unwrap Detected** (line 89)
-**Severity**: High
-**Issue**: Force unwrapping can crash if data is nil
+<details>
+<summary>Clone this repository</summary>
 
-Current Code:
-```swift
-let user = repository.currentUser!
+```bash
+git clone https://github.com/Viniciuscarvalho/swift-code-reviewer-skill.git ~/.claude/skills/swift-code-reviewer-skill
 ```
 
-Recommended Fix:
-```swift
-guard let user = repository.currentUser else {
-    logger.error("No current user")
-    return
-}
-```
-```
+</details>
 
-### Example 2: Review Against Project Standards
+<details>
+<summary>Manual installation</summary>
 
-**Input:**
-```
-Review LoginView.swift against our coding standards
+```bash
+mkdir -p ~/.claude/skills/swift-code-reviewer-skill/references
 ```
 
-**Output:**
-```markdown
-# Project Standards Review
+Download the files from this repository into the directory, then restart Claude.
 
-## .claude/CLAUDE.md Compliance
+</details>
 
-✅ **Architecture Adherence**
-- Follows MVVM pattern correctly
-- No business logic in view
-- Dependencies injected properly
+<details>
+<summary>Uninstall</summary>
 
-🔴 **Violates Design System Standard** (line 45)
-**Project Guideline**: "Use AppColors enum ONLY. No hardcoded colors"
-
-Current Code:
-```swift
-.foregroundColor(.blue)  // ❌ Hardcoded
-```
-
-Expected Code:
-```swift
-.foregroundColor(AppColors.primary)  // ✅ Design system
-```
-
-Reference: .claude/CLAUDE.md:Design System
+```bash
+npx swift-code-reviewer-skill uninstall
 ```
 
-## Requirements
+</details>
 
-- Claude Code CLI
-- Git (for reviewing diffs and PRs)
-- Optional: `gh` CLI for GitHub integration
-- Optional: `glab` CLI for GitLab integration
-- Swift 6.0+
-- iOS 17+, macOS 14+, watchOS 10+, tvOS 17+, or visionOS 1+
-
-## Limitations
-
-- Cannot execute code or run tests (static analysis only)
-- Cannot access external systems or APIs
-- Limited to analyzing provided code or git-accessible code
-- Cannot detect runtime issues requiring execution
-- Performance analysis based on patterns, not profiling data
+## Integration with Other Skills
 
-For runtime analysis, use Instruments or other profiling tools alongside this skill.
+This skill optionally leverages **swift-best-practices**, **swiftui-expert-skill**, and **swiftui-performance-audit** for deeper analysis. It works independently with its own comprehensive checklists.
 
 ## Contributing
 
-Contributions are welcome! Here's how you can help:
-
-1. **Report Issues**: Found a bug or have a suggestion? Open an issue
-2. **Improve Checklists**: Add new patterns or update existing checks
-3. **Add Examples**: Contribute real-world review examples
-4. **Update Documentation**: Improve clarity and add use cases
-5. **Add Templates**: Create new feedback templates
-
-### Development
-
-To modify the skill:
-
 1. Edit `SKILL.md` for main skill logic
 2. Update reference files in `references/` for specific checklists
 3. Test with real Swift/SwiftUI code
@@ -504,33 +157,12 @@ To modify the skill:
 
 ## License
 
-MIT License - See [LICENSE](LICENSE) file for details
-
-## Acknowledgments
-
-- Inspired by Apple's Swift API Design Guidelines
-- Leverages best practices from the Swift and SwiftUI communities
-- Built on top of Claude's code analysis capabilities
-- Designed to complement existing Swift development skills
-
-## Support
-
-- **Issues**: [GitHub Issues](https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/discussions)
-
-## Version History
-
-### 1.0.0 (2026-02-10)
-- Initial release
-- Comprehensive Swift 6+ and SwiftUI review capabilities
-- Project-specific standards integration
-- Multi-layer analysis (6 categories)
-- Structured feedback with all severity levels
-- Integration with existing skills
-- 7,700+ lines of comprehensive documentation
+MIT License - See [LICENSE](LICENSE) file for details.
 
 ---
 
 **Made with ❤️ for the Swift community**
 
-If this skill helps improve your code reviews, please ⭐️ star the repository!
+If this skill helps your code reviews, please star the repository!
+
+- [Issues](https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/issues) | [Discussions](https://github.com/Viniciuscarvalho/swift-code-reviewer-skill/discussions)