ios-app-review-plugin 1.0.0

package/docs/REPORTS.md

@@ -0,0 +1,212 @@
+# Report Formats
+
+The plugin generates reports in three formats: Markdown, HTML, and JSON. All share the same underlying data -- an `EnrichedAnalysisReport` that includes a readiness score, enriched issues with guideline cross-references, and optional historical comparison.
+
+## Markdown Format
+
+Selected with `--format markdown` (the default).
+
+### Structure
+
+```
+# App Store Review Readiness Report
+
+**Project:** `/path/to/MyApp.xcodeproj`
+**Date:** 1/15/2025, 3:42:00 PM
+**Status:** ISSUES FOUND
+
+## Review Readiness Score
+
+**Score: 72/100** [=======---]
+
+## Summary
+
+| Metric | Count |
+| ------ | ----- |
+| Total Issues | 8 |
+| Errors | 2 |
+| Warnings | 4 |
+| Info | 2 |
+| Duration | 342ms |
+
+## Historical Comparison          <-- only if includeHistory=true
+
+| Metric | Value |
+| ------ | ----- |
+| Previous Score | 65/100 |
+| Current Score | 72/100 |
+| Delta | +7 |
+| Trend | Improving |
+| New Issues | 1 |
+| Resolved Issues | 3 |
+| Ongoing Issues | 5 |
+
+## Priority Remediation            <-- only if errors exist
+
+1. **Hardcoded API key** -- This appears to be a hardcoded API key or secret.
+   - Guideline: [Security Best Practice](https://...)
+
+## Issues by Category
+
+### Info.plist
+
+#### [ERROR] Missing required key: CFBundleExecutable
+...
+
+### Code Quality
+
+#### [WARN] Hardcoded IPv4 address
+...
+```
+
+### Score Bar
+
+The score bar is a 10-character ASCII gauge:
+
+- Score 85 -> `[=========- ]`
+- Score 50 -> `[=====-----]`
+- Score 10 -> `[=---------]`
+
+### Issue Rendering
+
+Each issue includes:
+- Severity badge: `[ERROR]`, `[WARN]`, or `[INFO]`
+- Title and description
+- File location (path:line) when available
+- Guideline link when matched
+- Suggestion when available
+
+---
+
+## HTML Format
+
+Selected with `--format html`.
+
+### Features
+
+- Self-contained single HTML file (no external CSS/JS)
+- Dark mode support via `prefers-color-scheme` media query
+- Circular score gauge with color coding (green >= 80, orange >= 50, red < 50)
+- Collapsible issue categories using `<details>` elements
+- Severity badges with color-coded pill labels
+- Monospace font for file locations
+- Trend arrows (SVG) for historical comparison
+- Mobile responsive via viewport meta tag
+
+### Color Scheme
+
+| Element | Light Mode | Dark Mode |
+|---------|------------|-----------|
+| Background | `#ffffff` | `#1a1a2e` |
+| Text | `#1a1a1a` | `#e0e0e0` |
+| Card background | `#f8f9fa` | `#16213e` |
+| Border | `#dee2e6` | `#2a2a4a` |
+
+### Severity Badge Colors
+
+| Severity | Color |
+|----------|-------|
+| error | `#dc3545` (red) |
+| warning | `#fd7e14` (orange) |
+| info | `#0d6efd` (blue) |
+
+---
+
+## JSON Format
+
+Selected with `--format json`.
+
+### Schema
+
+```json
+{
+  "schemaVersion": "1.0",
+  "exitCode": 0,
+  "score": 85,
+  "timestamp": "2025-01-15T15:42:00.000Z",
+  "projectPath": "/path/to/MyApp.xcodeproj",
+  "summary": {
+    "totalIssues": 3,
+    "errors": 0,
+    "warnings": 2,
+    "info": 1,
+    "passed": true,
+    "duration": 342
+  },
+  "issues": [
+    {
+      "id": "hardcoded-ipv4",
+      "title": "Hardcoded IPv4 address",
+      "description": "Hardcoded IPv4 addresses may cause issues on IPv6-only networks.\n\nFound: `\"192.168.1.1\"`",
+      "severity": "warning",
+      "category": "code",
+      "filePath": "/path/to/NetworkManager.swift",
+      "lineNumber": 42,
+      "guideline": "Guideline 2.5.1 - IPv6 Compatibility",
+      "suggestion": "Use hostnames instead of hardcoded IP addresses for IPv6 compatibility.",
+      "guidelineUrl": "https://developer.apple.com/app-store/review/guidelines/#software-requirements",
+      "guidelineExcerpt": "Apps must use public APIs and run on the currently shipping OS...",
+      "severityScore": 9
+    }
+  ],
+  "comparison": {
+    "previousScanId": "abc123",
+    "previousTimestamp": "2025-01-10T11:20:00.000Z",
+    "previousScore": 72,
+    "currentScore": 85,
+    "scoreDelta": 13,
+    "trend": "improving",
+    "newIssuesCount": 0,
+    "resolvedIssuesCount": 3,
+    "ongoingIssuesCount": 2
+  }
+}
+```
+
+### Field Reference
+
+**Top level:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `schemaVersion` | string | Always `"1.0"` |
+| `exitCode` | 0 or 1 | 0 if passed, 1 if errors exist |
+| `score` | number | 0-100 review readiness score |
+| `timestamp` | string | ISO 8601 timestamp |
+| `projectPath` | string | Analyzed project path |
+| `summary` | object | Aggregate counts |
+| `issues` | array | All enriched issues |
+| `comparison` | object or undefined | Present only when history is included |
+
+**Issue object:**
+
+| Field | Type | Present |
+|-------|------|---------|
+| `id` | string | always |
+| `title` | string | always |
+| `description` | string | always |
+| `severity` | `"error"` / `"warning"` / `"info"` | always |
+| `category` | string | always |
+| `filePath` | string | when applicable |
+| `lineNumber` | number | when applicable |
+| `guideline` | string | when matched |
+| `suggestion` | string | when available |
+| `guidelineUrl` | string | when matched by GuidelineMatcher |
+| `guidelineExcerpt` | string | when matched |
+| `severityScore` | number | when matched (0-10) |
+
+### Parsing in CI
+
+```bash
+# Check pass/fail
+PASSED=$(cat report.json | jq '.summary.passed')
+
+# Count errors
+ERRORS=$(cat report.json | jq '.summary.errors')
+
+# Get score
+SCORE=$(cat report.json | jq '.score')
+
+# List error-severity issue titles
+cat report.json | jq -r '.issues[] | select(.severity == "error") | .title'
+```

package/docs/ROADMAP.md

@@ -0,0 +1,267 @@
+# Project Roadmap
+
+This document outlines the development phases, milestones, and detailed tasks for the iOS App Store Review Plugin.
+
+## Phase 1: Foundation & Codebase Analysis (MVP) :white_check_mark:
+
+**Goal**: Create a working MCP server that can analyze iOS project files locally without requiring App Store Connect access.
+
+**Milestone**: `v0.1.0 - MVP Release`
+
+### 1.1 Project Setup
+- [x] Initialize TypeScript project with strict configuration
+- [x] Set up ESLint and Prettier
+- [x] Configure Jest for testing
+- [x] Set up build pipeline
+- [x] Create MCP server skeleton
+- [x] Add GitHub Actions for CI/CD
+
+### 1.2 Xcode Project Parser
+- [x] Parse `.xcodeproj` directory structure
+- [x] Extract build settings
+- [x] Identify targets and schemes
+- [x] Parse `Info.plist` files
+- [x] Parse entitlements files
+- [x] Handle workspace (`.xcworkspace`) files
+
+### 1.3 Info.plist Analyzer
+- [x] Check required keys (bundle identifier, version, etc.)
+- [x] Validate privacy usage descriptions:
+  - NSCameraUsageDescription
+  - NSPhotoLibraryUsageDescription
+  - NSLocationWhenInUseUsageDescription
+  - NSMicrophoneUsageDescription
+  - NSContactsUsageDescription
+  - (20+ more privacy keys)
+- [x] Check App Transport Security configuration
+- [x] Validate URL schemes
+- [x] Check required device capabilities
+- [x] Verify launch storyboard/XIB configuration
+
+### 1.4 Privacy Manifest Analyzer (iOS 17+)
+- [x] Check for `PrivacyInfo.xcprivacy` presence
+- [x] Validate required reason APIs:
+  - File timestamp APIs
+  - System boot time APIs
+  - Disk space APIs
+  - Active keyboard APIs
+  - User defaults APIs
+- [x] Check tracking domains declaration
+- [x] Validate data collection declarations
+- [x] Cross-reference with actual API usage in code
+
+### 1.5 Entitlements Analyzer
+- [x] Parse entitlements file
+- [x] Validate against declared capabilities
+- [x] Check for debugging entitlements in release
+- [x] Validate App Groups configuration
+- [x] Check Push Notification entitlements
+- [x] Validate Keychain sharing groups
+
+### 1.6 Basic Code Scanner
+- [x] Detect hardcoded IP addresses (IPv6 compliance)
+- [x] Find TODO/FIXME comments
+- [x] Detect hardcoded API keys/secrets
+- [x] Find test/debug code patterns
+- [x] Check for `#if DEBUG` usage
+- [x] Detect print/NSLog statements in release
+
+---
+
+## Phase 2: App Store Connect Integration :white_check_mark:
+
+**Goal**: Add ability to fetch and validate app metadata from App Store Connect.
+
+**Milestone**: `v0.2.0 - ASC Integration`
+
+### 2.1 API Client Setup
+- [x] Implement JWT authentication
+- [x] Create API client with rate limiting
+- [x] Handle token refresh
+- [x] Add error handling and retries
+- [x] Create typed API responses
+
+### 2.2 App Metadata Validation
+- [x] Fetch app information
+- [x] Validate app name length (30 chars)
+- [x] Check subtitle (30 chars)
+- [x] Validate description length and content
+- [x] Check keywords (100 chars total)
+- [x] Validate promotional text
+- [x] Check support URL validity
+- [x] Validate privacy policy URL
+- [x] Verify marketing URL
+
+### 2.3 Screenshot & Preview Validation
+- [x] Fetch screenshot metadata
+- [x] Check required device sizes
+- [x] Validate screenshot count (1-10 per size)
+- [x] Check app preview videos
+- [x] Verify localized screenshots
+
+### 2.4 Version & Build Checks
+- [x] Compare local vs. submitted version
+- [x] Check build number incrementing
+- [x] Validate version string format
+- [x] Check for pending submissions
+
+### 2.5 In-App Purchase Validation
+- [x] List configured IAPs
+- [x] Validate IAP metadata
+- [x] Check pricing configuration
+- [x] Verify review screenshots for IAPs
+
+---
+
+## Phase 3: Advanced Analysis :white_check_mark:
+
+**Goal**: Add sophisticated analysis capabilities and better integration.
+
+**Milestone**: `v0.3.0 - Advanced Analysis`
+
+### 3.1 Deprecated API Detection
+- [x] Build deprecated API database
+- [x] Scan Swift files for deprecated calls
+- [x] Scan Objective-C files
+- [x] Check minimum deployment target compatibility
+- [x] Identify APIs removed in target iOS version
+- [x] Generate migration suggestions
+
+### 3.2 Private API Detection
+- [x] Create private API signature database
+- [x] Scan for known private selectors
+- [x] Check for undocumented frameworks
+- [x] Detect runtime API usage
+- [x] Scan for private URL schemes
+
+### 3.3 Security Analysis
+- [x] Check for insecure HTTP connections
+- [x] Detect weak cryptography usage
+- [x] Find insecure data storage patterns
+- [x] Check for jailbreak detection bypasses
+- [x] Validate SSL pinning implementation
+- [x] Check keychain access configuration
+
+### 3.4 UI/UX Compliance
+- [x] Check for required launch screen
+- [x] Validate icon sizes and presence
+- [x] Check accessibility support
+- [x] Detect placeholder/lorem ipsum text
+- [x] Verify iPad support if universal
+
+---
+
+## Phase 4: Intelligence & Reporting :white_check_mark:
+
+**Goal**: Add smart analysis and comprehensive reporting.
+
+**Milestone**: `v0.4.0 - Smart Analysis`
+
+### 4.1 Guidelines Cross-Reference
+- [x] Map issues to specific guidelines
+- [x] Provide guideline excerpts
+- [x] Link to Apple documentation
+- [x] Track guideline version changes
+- [x] Add severity scoring
+
+### 4.2 Report Generation
+- [x] Generate markdown reports
+- [x] Create HTML reports
+- [x] Add JSON export for CI/CD
+- [x] Include remediation suggestions
+- [x] Add code location references
+- [x] Generate summary statistics
+
+### 4.3 Historical Comparison
+- [x] Store previous scan results
+- [x] Compare between scans
+- [x] Track issue resolution
+- [x] Generate trend reports
+
+### 4.4 Custom Rules
+- [x] Allow user-defined rules
+- [x] Support regex-based rules
+- [x] Add rule severity configuration
+- [x] Create rule disable comments
+- [x] Support per-project configuration
+
+---
+
+## Phase 5: CI/CD & Polish :white_check_mark:
+
+**Goal**: Production-ready release with CI/CD integration.
+
+**Milestone**: `v1.0.0 - Production Release`
+
+### 5.1 CI/CD Integration
+- [x] Create GitHub Action
+- [x] Add Fastlane plugin
+- [x] Create Xcode Cloud integration guide
+- [x] Add Bitrise step
+- [x] Support exit codes for CI
+- [x] Create badge generation
+
+### 5.2 Performance Optimization
+- [x] Add caching layer
+- [x] Implement incremental scanning
+- [x] Optimize large project handling
+- [x] Add progress reporting
+- [x] Implement parallel analysis
+
+### 5.3 Documentation
+- [x] Complete API documentation
+- [x] Add video tutorials
+- [x] Create troubleshooting guide
+- [x] Document all rules
+- [x] Add example configurations
+
+### 5.4 Testing & Quality
+- [x] Achieve 80%+ code coverage
+- [x] Add integration tests
+- [x] Test with real-world projects
+- [x] Security audit
+- [x] Performance benchmarks
+
+---
+
+## Future Considerations
+
+### Potential Phase 6+ Features
+- [ ] Watch app analysis
+- [ ] tvOS app support
+- [ ] macOS (Catalyst) support
+- [ ] App Clips validation
+- [ ] SwiftUI-specific checks
+- [ ] Storyboard/XIB analysis
+- [ ] Localization validation
+- [ ] Accessibility audit
+- [ ] Memory/performance predictions
+- [ ] AI-powered rejection prediction
+
+---
+
+## Success Metrics
+
+| Metric | Target |
+|--------|--------|
+| Detection accuracy | >95% for common issues |
+| False positive rate | <5% |
+| Scan time (avg project) | <30 seconds |
+| Guideline coverage | 80% of rejection reasons |
+| User satisfaction | 4.5+ rating |
+
+## Timeline Estimates
+
+| Phase | Duration |
+|-------|----------|
+| Phase 1 | 4-6 weeks |
+| Phase 2 | 3-4 weeks |
+| Phase 3 | 4-5 weeks |
+| Phase 4 | 3-4 weeks |
+| Phase 5 | 2-3 weeks |
+
+**Total estimated development time**: 16-22 weeks
+
+---
+
+*This roadmap is subject to change based on community feedback and Apple's guideline updates.*

package/docs/RULES.md

@@ -0,0 +1,182 @@
+# Custom Rules
+
+Create a `.ios-review-rules.json` file in your project root (or any parent directory) to define team-specific or project-specific rules.
+
+## Config Format
+
+```json
+{
+  "version": 1,
+  "rules": [
+    {
+      "id": "my-rule-id",
+      "title": "Short title",
+      "description": "Longer description shown in reports",
+      "severity": "error",
+      "pattern": "regex-pattern-string",
+      "flags": "gi",
+      "fileTypes": [".swift"],
+      "guideline": "Guideline 2.5.4",
+      "suggestion": "How to fix this",
+      "category": "custom"
+    }
+  ],
+  "disabledRules": ["built-in-rule-id"],
+  "severityOverrides": {
+    "hardcoded-ipv4": "error"
+  }
+}
+```
+
+### Top-level Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `version` | `1` (literal) | yes | Schema version. Must be `1`. |
+| `rules` | array | yes | Custom rule definitions. |
+| `disabledRules` | string[] | no | IDs of rules to skip (built-in or custom). |
+| `severityOverrides` | object | no | Override severity for any rule by ID. Keys are rule IDs, values are `"error"`, `"warning"`, or `"info"`. |
+
+### Rule Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Unique identifier (e.g., `team-no-force-cast`). |
+| `title` | string | yes | Short title for reports. |
+| `description` | string | yes | Detailed description shown in issue output. |
+| `severity` | string | yes | One of `error`, `warning`, `info`. |
+| `pattern` | string | yes | JavaScript regex pattern (without delimiters). |
+| `flags` | string | no | Regex flags. Default: `"g"`. Use `"gi"` for case-insensitive. |
+| `fileTypes` | string[] | no | File extensions to scan (e.g., `[".swift", ".m"]`). Default: all source files. |
+| `guideline` | string | no | Related App Store guideline reference. |
+| `suggestion` | string | no | Remediation guidance. |
+| `category` | string | no | Issue category. Default: `"custom"`. |
+
+## Pattern Syntax
+
+Patterns use JavaScript `RegExp` syntax. Common examples:
+
+| Pattern | Matches |
+|---------|---------|
+| `\\bUIWebView\\b` | Word-boundary match for `UIWebView` |
+| `print\\s*\\(` | `print(` calls |
+| `["'\`]http://[^"'\`]+["'\`]` | HTTP URLs in string literals |
+| `\\bTODO\\b` | TODO markers |
+| `force_cast` | Literal string `force_cast` |
+
+Backslashes must be double-escaped in JSON (`\\b` for `\b`).
+
+When the `g` flag is present, the engine finds all matches in each file. Without `g`, it reports only the first match per file.
+
+## Inline Suppression
+
+Suppress a specific rule on the next line with a comment:
+
+```swift
+// ios-review-disable-next-line my-rule-id
+let x = unsafeOperation() // this line won't trigger my-rule-id
+```
+
+Multiple rule IDs can be comma-separated:
+
+```swift
+// ios-review-disable-next-line my-rule-id, another-rule
+```
+
+## Disabling Built-in Rules
+
+Use `disabledRules` to turn off any built-in rule by its ID:
+
+```json
+{
+  "version": 1,
+  "rules": [],
+  "disabledRules": [
+    "print-statement",
+    "todo-comment",
+    "force-unwrap"
+  ]
+}
+```
+
+## Severity Overrides
+
+Promote or demote any rule (built-in or custom):
+
+```json
+{
+  "version": 1,
+  "rules": [],
+  "severityOverrides": {
+    "hardcoded-ipv4": "error",
+    "placeholder-text": "info"
+  }
+}
+```
+
+## Complete Example
+
+```json
+{
+  "version": 1,
+  "rules": [
+    {
+      "id": "team-no-swiftui-preview",
+      "title": "SwiftUI preview in production code",
+      "description": "SwiftUI #Preview macros should only appear in dedicated preview files.",
+      "severity": "warning",
+      "pattern": "#Preview\\s*\\{",
+      "flags": "g",
+      "fileTypes": [".swift"],
+      "suggestion": "Move #Preview blocks to separate preview files or wrap in #if DEBUG."
+    },
+    {
+      "id": "team-no-print-release",
+      "title": "Print statement in non-debug code",
+      "description": "Use os_log or Logger instead of print() for production logging.",
+      "severity": "error",
+      "pattern": "\\bprint\\s*\\(",
+      "flags": "g",
+      "fileTypes": [".swift"],
+      "suggestion": "Replace print() with Logger from the os module."
+    },
+    {
+      "id": "team-copyright-header",
+      "title": "Missing copyright header",
+      "description": "All source files must include the team copyright header.",
+      "severity": "info",
+      "pattern": "^(?!.*Copyright.*ACME Corp)",
+      "flags": "",
+      "fileTypes": [".swift"],
+      "suggestion": "Add '// Copyright ACME Corp' to the top of the file."
+    }
+  ],
+  "disabledRules": ["force-unwrap"],
+  "severityOverrides": {
+    "insecure-http": "error"
+  }
+}
+```
+
+## Validating Rules
+
+Use the `validate_custom_rules` MCP tool or verify manually:
+
+```bash
+# The tool will parse, compile, and report any errors
+# in the rules file without running a full scan.
+```
+
+From Claude Code, ask:
+
+```
+Validate my custom rules at ./MyApp.xcodeproj
+```
+
+The tool will report the config path, version, rule count, compiled regex patterns, and whether validation passed.
+
+## Scanned File Types
+
+The custom rules engine scans files with these extensions by default: `.swift`, `.m`, `.mm`, `.h`, `.c`, `.cpp`. Narrow this per-rule with the `fileTypes` field.
+
+Directories excluded: `node_modules`, `Pods`, `build`, `.build`.