ios-app-review-plugin 1.0.0

package/docs/tutorials/GETTING_STARTED.md

@@ -0,0 +1,226 @@
+# Getting Started
+
+This tutorial walks through installing the plugin, running your first scan, understanding the results, and fixing common issues.
+
+## Prerequisites
+
+- Node.js >= 18
+- An iOS project (`.xcodeproj` or `.xcworkspace`)
+- (Optional) App Store Connect API key for ASC validation
+
+## Step 1: Install
+
+```bash
+git clone https://github.com/ahmetsina/ios-app-review-plugin.git
+cd ios-app-review-plugin
+npm install
+npm run build
+```
+
+To use the CLI globally:
+
+```bash
+npm link
+# or
+npm install -g .
+```
+
+Verify:
+
+```bash
+ios-app-review version
+```
+
+## Step 2: Run Your First Scan
+
+Point the tool at your Xcode project:
+
+```bash
+ios-app-review scan /path/to/MyApp.xcodeproj
+```
+
+This runs all 8 core analyzers and prints a Markdown report to stdout. A typical first run takes 1-5 seconds depending on project size.
+
+### What Happens During a Scan
+
+1. The Xcode project file (`.pbxproj`) is parsed to discover targets, source files, Info.plist paths, and entitlements paths.
+2. Each analyzer runs in parallel against the relevant files.
+3. Issues are collected and enriched with guideline cross-references.
+4. A readiness score (0-100) is calculated.
+5. The formatted report is printed.
+
+## Step 3: Understand the Results
+
+The report has these sections:
+
+### Review Readiness Score
+
+A number from 0 to 100. Higher is better. The score is calculated based on the number and severity of issues found, weighted by the corresponding App Store Review Guideline importance.
+
+- **80-100:** Ready for submission. Minor tweaks may help.
+- **50-79:** Several issues to address. Likely rejection if errors remain.
+- **0-49:** Significant problems. Address all errors before submitting.
+
+### Summary Table
+
+Quick counts of errors, warnings, and info items plus total scan duration.
+
+### Priority Remediation
+
+Error-severity issues sorted by guideline severity weight. Fix these first -- they are the most likely rejection causes.
+
+### Issues by Category
+
+All issues grouped by category (Info.plist, Privacy, Code Quality, Security, etc.). Each issue includes:
+
+- **Severity badge** -- `[ERROR]` must be fixed, `[WARN]` should be fixed, `[INFO]` is advisory
+- **Title** -- Brief description
+- **Description** -- Details and the code/pattern that triggered it
+- **Location** -- File path and line number
+- **Guideline** -- Link to the relevant Apple guideline
+- **Suggestion** -- How to fix it
+
+## Step 4: Fix Common Issues
+
+### Errors (Must Fix)
+
+**Missing required Info.plist keys:**
+
+```xml
+<!-- Add to Info.plist -->
+<key>CFBundleExecutable</key>
+<string>$(EXECUTABLE_NAME)</string>
+```
+
+**Hardcoded API keys:**
+
+```swift
+// BAD
+let apiKey = "sk-1234567890abcdef"
+
+// GOOD
+let apiKey = ProcessInfo.processInfo.environment["API_KEY"] ?? ""
+```
+
+**UIWebView usage:**
+
+Replace all `UIWebView` instances with `WKWebView`:
+
+```swift
+// BAD
+let webView = UIWebView()
+
+// GOOD
+import WebKit
+let webView = WKWebView()
+```
+
+**Missing privacy manifest:**
+
+Create `PrivacyInfo.xcprivacy` in your project and declare Required Reason APIs:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "...">
+<plist version="1.0">
+<dict>
+  <key>NSPrivacyAccessedAPITypes</key>
+  <array>
+    <dict>
+      <key>NSPrivacyAccessedAPIType</key>
+      <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
+      <key>NSPrivacyAccessedAPITypeReasons</key>
+      <array>
+        <string>CA92.1</string>
+      </array>
+    </dict>
+  </array>
+</dict>
+</plist>
+```
+
+### Warnings (Should Fix)
+
+**ATS allows arbitrary loads:**
+
+Remove the global bypass and use exception domains for specific servers:
+
+```xml
+<key>NSAppTransportSecurity</key>
+<dict>
+  <key>NSExceptionDomains</key>
+  <dict>
+    <key>legacy-api.example.com</key>
+    <dict>
+      <key>NSExceptionAllowsInsecureHTTPLoads</key>
+      <true/>
+    </dict>
+  </dict>
+</dict>
+```
+
+**Hardcoded IPv4 addresses:**
+
+```swift
+// BAD
+let server = "192.168.1.100"
+
+// GOOD
+let server = "api.myapp.com"
+```
+
+**Short permission descriptions:**
+
+```xml
+<!-- BAD -->
+<key>NSCameraUsageDescription</key>
+<string>Camera</string>
+
+<!-- GOOD -->
+<key>NSCameraUsageDescription</key>
+<string>MyApp uses the camera to scan QR codes for quick login.</string>
+```
+
+## Step 5: Re-scan and Track Progress
+
+After fixing issues, run the scan again:
+
+```bash
+ios-app-review scan /path/to/MyApp.xcodeproj --save-history
+```
+
+On subsequent scans with `--save-history`, you can compare progress:
+
+```bash
+ios-app-review scan /path/to/MyApp.xcodeproj --save-history
+```
+
+Use the `view_scan_history` MCP tool or compare scans to see your score trend over time.
+
+## Step 6: Set Up as MCP Server (Optional)
+
+To use the plugin from Claude Code as an MCP server, add to `~/.claude/mcp_servers.json`:
+
+```json
+{
+  "ios-app-review": {
+    "command": "node",
+    "args": ["/path/to/ios-app-review-plugin/dist/index.js"]
+  }
+}
+```
+
+Then in Claude Code, simply ask:
+
+```
+Analyze my iOS app at /path/to/MyApp.xcodeproj for App Store compliance
+```
+
+Claude will call the `analyze_ios_app` tool and present the results conversationally.
+
+## Next Steps
+
+- [CI Integration Tutorial](./CI_INTEGRATION.md) -- Automate scans in your build pipeline
+- [Custom Rules Tutorial](./CUSTOM_RULES.md) -- Add team-specific checks
+- [ASC Setup Tutorial](./ASC_SETUP.md) -- Validate App Store Connect metadata
+- [Analyzers Reference](../ANALYZERS.md) -- Full list of checks performed

package/docs/video-scripts/01-introduction.md

@@ -0,0 +1,106 @@
+# Video Script: Introduction to iOS App Review Plugin
+
+**Duration:** 3 minutes
+**Audience:** iOS developers who submit apps to the App Store
+**Goal:** Explain the problem, show the tool, and demonstrate a first scan
+
+---
+
+## Opening (0:00 - 0:30)
+
+**Hook:** "If you have ever had an app rejected by Apple, you know the frustration. A single missing privacy description or a leftover debug URL can cost you days."
+
+**Problem statement:**
+- App Store rejections are time-consuming.
+- Apple checks dozens of criteria: privacy manifests, deprecated APIs, metadata completeness, icon sizes, security patterns.
+- Manual checks are error-prone and tedious.
+
+**Transition:** "The iOS App Review Plugin automates these checks before you submit."
+
+---
+
+## What It Does (0:30 - 1:15)
+
+**Overview narration with on-screen text/graphics:**
+
+The plugin is two things:
+1. A CLI tool you run locally or in CI.
+2. An MCP server that integrates with Claude Code.
+
+**On screen: Show the architecture diagram.**
+
+It runs 12 analyzers across two domains:
+
+**Codebase (8 analyzers):**
+- Info.plist validation
+- Privacy manifest (iOS 17+)
+- Entitlements
+- Code scanning (secrets, debug code, IPv6)
+- Deprecated APIs
+- Private APIs
+- Security vulnerabilities
+- UI/UX compliance (icons, launch screen, accessibility)
+
+**App Store Connect (4 analyzers):**
+- Metadata completeness
+- Screenshot validation
+- Version comparison
+- In-app purchase readiness
+
+**Transition:** "Let me show you what it looks like in practice."
+
+---
+
+## Demo: First Scan (1:15 - 2:30)
+
+**Terminal recording:**
+
+```bash
+# Install
+npm install -g ios-app-review-plugin
+
+# Run a scan
+ios-app-review scan ./SampleApp.xcodeproj
+```
+
+**Narrate the output as it appears:**
+
+1. "The report starts with a readiness score -- 68 out of 100."
+2. "The summary shows 2 errors, 5 warnings, and 3 info items."
+3. "Priority Remediation lists the errors that will most likely cause rejection."
+4. "Scrolling down, issues are grouped by category."
+5. "Each issue includes the file, line number, Apple guideline reference, and a fix suggestion."
+
+**Show fixing one issue:**
+
+```bash
+# The scan found a hardcoded API key
+# Fix it, then re-scan
+ios-app-review scan ./SampleApp.xcodeproj
+# Score improved to 78/100
+```
+
+---
+
+## What's Next (2:30 - 3:00)
+
+**Closing narration:**
+
+- "You can run this in CI to block PRs with errors."
+- "Add --include-asc to validate your App Store Connect metadata too."
+- "Custom rules let you enforce your team's own conventions."
+- "Check the docs for setup guides on GitHub Actions, Fastlane, Bitrise, and Xcode Cloud."
+
+**Call to action:**
+- Link to GitHub repository
+- Link to Getting Started tutorial
+- "Star the repo if you find it useful."
+
+---
+
+## Production Notes
+
+- Use a real sample project with deliberate issues for the demo.
+- Terminal should use a large font (24pt+) with dark background.
+- Highlight key parts of the output with colored overlays.
+- Keep the pace brisk -- this is a 3-minute overview, not a deep dive.

package/docs/video-scripts/02-cli-usage.md

@@ -0,0 +1,120 @@
+# Video Script: CLI Usage
+
+**Duration:** 2 minutes
+**Audience:** Developers who have installed the plugin and want to learn the CLI
+**Goal:** Cover the main CLI options through practical examples
+
+---
+
+## Opening (0:00 - 0:15)
+
+"Let me walk through the CLI options you will use most often. The tool has one main command: scan."
+
+---
+
+## Basic Scan (0:15 - 0:35)
+
+**Terminal:**
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj
+```
+
+"By default, this runs all 8 core analyzers and prints a Markdown report to the terminal."
+
+"The exit code is 0 for pass, 1 for errors found."
+
+---
+
+## Output Formats (0:35 - 0:55)
+
+**Terminal:**
+
+```bash
+# JSON for CI parsing
+ios-app-review scan ./MyApp.xcodeproj --format json --output report.json
+
+# HTML for sharing with the team
+ios-app-review scan ./MyApp.xcodeproj --format html --output report.html
+```
+
+"JSON is best for CI pipelines. HTML gives you a styled report with dark mode support and collapsible sections."
+
+**Quick flash of the HTML report in a browser.**
+
+---
+
+## Selective Analyzers (0:55 - 1:10)
+
+**Terminal:**
+
+```bash
+# Only run code and security checks
+ios-app-review scan ./MyApp.xcodeproj --analyzers code,security
+
+# Only check privacy manifest
+ios-app-review scan ./MyApp.xcodeproj --analyzers privacy
+```
+
+"Use --analyzers with a comma-separated list to focus on specific areas. Useful when you are working on a targeted fix."
+
+---
+
+## Incremental Scanning (1:10 - 1:25)
+
+**Terminal:**
+
+```bash
+# Only scan files changed since main branch
+ios-app-review scan ./MyApp.xcodeproj --changed-since main
+```
+
+"This is the key option for CI. It scans only the files you changed, so PR checks run in seconds instead of minutes on large projects."
+
+---
+
+## Badge and History (1:25 - 1:40)
+
+**Terminal:**
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj --badge --save-history
+
+# badge.svg is created
+# Scan is saved for future comparison
+```
+
+"The --badge flag generates an SVG badge you can embed in your README. The --save-history flag persists the scan so you can track your score over time."
+
+**Show the badge image.**
+
+---
+
+## ASC Validation (1:40 - 1:55)
+
+**Terminal:**
+
+```bash
+export ASC_KEY_ID="..."
+export ASC_ISSUER_ID="..."
+export ASC_PRIVATE_KEY_PATH="..."
+
+ios-app-review scan ./MyApp.xcodeproj --include-asc
+```
+
+"Add --include-asc to also validate your App Store Connect metadata, screenshots, and in-app purchases. You need an API key from App Store Connect."
+
+---
+
+## Closing (1:55 - 2:00)
+
+"That covers the main CLI options. For the full reference, check docs/CLI.md in the repository."
+
+---
+
+## Production Notes
+
+- All commands should be executed live (not simulated).
+- Use a sample project that produces diverse output.
+- Split-screen: terminal on left, brief explanation text on right.
+- Keep each section snappy -- under 20 seconds per option.

package/docs/video-scripts/03-ci-integration.md

@@ -0,0 +1,198 @@
+# Video Script: CI Integration
+
+**Duration:** 5 minutes
+**Audience:** iOS developers setting up automated review checks in CI
+**Goal:** Walk through GitHub Actions setup end-to-end, then briefly cover other platforms
+
+---
+
+## Opening (0:00 - 0:20)
+
+"Catching App Store issues before they reach code review saves everyone time. In this video, I will set up automated review checks in GitHub Actions from scratch, then show how to adapt this for Fastlane, Bitrise, and Xcode Cloud."
+
+---
+
+## Part 1: GitHub Actions (0:20 - 3:00)
+
+### Create the Workflow (0:20 - 0:50)
+
+**Editor (VS Code or similar):**
+
+"Create a new file at .github/workflows/app-review.yml."
+
+```yaml
+name: App Store Review Check
+on:
+  pull_request:
+    branches: [main]
+```
+
+"This triggers on pull requests to main."
+
+### Add the Job (0:50 - 1:30)
+
+```yaml
+jobs:
+  review-check:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install ios-app-review
+        run: npm install -g ios-app-review-plugin
+
+      - name: Run review check
+        run: |
+          ios-app-review scan ./MyApp.xcodeproj \
+            --format json \
+            --output report.json
+```
+
+"fetch-depth 0 gives us full git history, which we need for incremental scanning."
+
+### Add Artifact Upload (1:30 - 1:50)
+
+```yaml
+      - name: Upload report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: review-report
+          path: report.json
+```
+
+"'if: always()' ensures the report is uploaded even when the check fails."
+
+### Push and Test (1:50 - 2:15)
+
+**Terminal:**
+
+```bash
+git add .github/workflows/app-review.yml
+git commit -m "Add App Store review CI check"
+git push
+```
+
+"Now I will open a PR to trigger it."
+
+**Show GitHub PR checks tab with the workflow running. Show it completing with pass or fail.**
+
+### Add Incremental Scanning (2:15 - 2:35)
+
+"For faster PR checks, scan only changed files:"
+
+```yaml
+      - name: Incremental scan
+        run: |
+          ios-app-review scan ./MyApp.xcodeproj \
+            --changed-since origin/main \
+            --format json \
+            --output report.json
+```
+
+"This typically finishes in under 5 seconds."
+
+### Make It a Required Check (2:35 - 3:00)
+
+**Browser -- GitHub Settings:**
+
+1. Settings > Branches > Branch protection rules
+2. Edit rule for `main`
+3. Enable "Require status checks"
+4. Select "App Store Review Check"
+
+"Now PRs cannot merge until the review check passes."
+
+---
+
+## Part 2: Other Platforms (3:00 - 4:30)
+
+### Fastlane (3:00 - 3:30)
+
+**Editor:**
+
+```ruby
+# fastlane/Fastfile
+lane :review_check do
+  sh("ios-app-review scan ../MyApp.xcodeproj --format json --output ../report.json")
+
+  report = JSON.parse(File.read("../report.json"))
+  if report["summary"]["errors"] > 0
+    UI.user_error!("Review check failed")
+  end
+end
+
+lane :release do
+  review_check   # gate before submit
+  build_app
+  upload_to_app_store
+end
+```
+
+"Put it before upload_to_app_store so it gates your release lane."
+
+### Bitrise (3:30 - 3:55)
+
+**Editor:**
+
+```yaml
+- script@1:
+    title: Run ios-app-review
+    inputs:
+      - content: |
+          npm install -g ios-app-review-plugin
+          ios-app-review scan ./MyApp.xcodeproj \
+            --format json \
+            --output "$BITRISE_DEPLOY_DIR/report.json"
+```
+
+"Bitrise deploys the report artifact automatically with the deploy-to-bitrise-io step."
+
+### Xcode Cloud (3:55 - 4:20)
+
+**Editor:**
+
+```bash
+# ci_scripts/ci_post_clone.sh
+#!/bin/bash
+set -e
+brew install node 2>/dev/null || true
+npm install -g ios-app-review-plugin
+ios-app-review scan "$CI_PRIMARY_REPOSITORY_PATH/MyApp.xcodeproj" \
+  --format json --output "$CI_PRIMARY_REPOSITORY_PATH/report.json"
+```
+
+"Xcode Cloud runs scripts in the ci_scripts directory automatically. Just make it executable and commit it."
+
+---
+
+## Part 3: Best Practices (4:20 - 4:50)
+
+"Quick tips from running this in production:"
+
+1. "Use incremental scanning on PRs, full scans on main."
+2. "Save history on main branch pushes to track your score over time."
+3. "Start with errors-only blocking. The tool already only returns exit code 1 for errors, not warnings."
+4. "Cache node_modules to speed up installs."
+5. "Keep ASC credentials in your CI platform's secrets manager."
+
+---
+
+## Closing (4:50 - 5:00)
+
+"That is CI integration in 5 minutes. All of these configurations are in the docs/CI_CD.md file in the repository. Check the links in the description."
+
+---
+
+## Production Notes
+
+- Pre-record the GitHub Actions run to avoid waiting on CI during the video.
+- Show the actual PR checks UI -- green check or red X.
+- For the Fastlane/Bitrise/Xcode Cloud sections, show the config file briefly (10-15 seconds each).
+- End card: link to repo, docs, and the Getting Started tutorial.

package/eslint.config.js

@@ -0,0 +1,33 @@
+const typescript = require('@typescript-eslint/eslint-plugin');
+const parser = require('@typescript-eslint/parser');
+
+module.exports = [
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parser: parser,
+      parserOptions: {
+        ecmaVersion: 2022,
+        sourceType: 'module',
+        project: './tsconfig.json',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': typescript,
+    },
+    rules: {
+      ...typescript.configs['recommended'].rules,
+      '@typescript-eslint/explicit-function-return-type': 'warn',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/prefer-nullish-coalescing': 'warn',
+      '@typescript-eslint/prefer-optional-chain': 'warn',
+      'no-console': ['warn', { allow: ['warn', 'error'] }],
+      'eqeqeq': ['error', 'always'],
+      'curly': ['error', 'all'],
+    },
+  },
+  {
+    ignores: ['dist/**', 'node_modules/**', 'coverage/**', '*.js'],
+  },
+];