ios-app-review-plugin 1.0.0

package/docs/BADGES.md

@@ -0,0 +1,130 @@
+# Badge Generation
+
+The plugin generates shields.io-style SVG badges that display the review readiness score.
+
+## Generating a Badge
+
+### CLI
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj --badge
+```
+
+This writes `badge.svg` to the current directory. When combined with `--output`, the badge is written next to the report file:
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj --badge --output reports/review.json
+# Creates reports/badge.svg
+```
+
+### MCP Tool
+
+The `generate_report` tool does not directly produce a badge, but the CLI `--badge` flag calls the badge generator after the report is created.
+
+## Badge Appearance
+
+The badge has two sections:
+- **Label** (left): "app review" in gray (`#555`)
+- **Status** (right): score and pass/fail state, color-coded
+
+### Color Rules
+
+| Condition | Color | Hex |
+|-----------|-------|-----|
+| Passed, score >= 80 | Green | `#44cc11` |
+| Passed, score >= 50 | Yellow | `#dfb317` |
+| Passed, score < 50 | Red | `#e05d44` |
+| Failed (any errors) | Red | `#e05d44` |
+
+### Status Text
+
+- Passing: `85/100`
+- Failing: `fail 72/100`
+
+### Example SVG Output
+
+A passing badge with score 85 renders as:
+
+```
+[ app review | 85/100 ]
+     gray      green
+```
+
+A failing badge with score 60 renders as:
+
+```
+[ app review | fail 60/100 ]
+     gray         red
+```
+
+## Embedding in README
+
+### Direct File Reference
+
+```markdown
+![App Review](./badge.svg)
+```
+
+### With Link to Report
+
+```markdown
+[![App Review](./badge.svg)](./reports/review.html)
+```
+
+### From CI Artifact
+
+If your CI uploads the badge as an artifact, reference it from your repo's raw URL:
+
+```markdown
+![App Review](https://raw.githubusercontent.com/yourorg/yourapp/main/badge.svg)
+```
+
+## CI Integration
+
+### GitHub Actions: Commit Badge Back to Repo
+
+```yaml
+      - name: Generate badge
+        run: |
+          ios-app-review scan ./MyApp.xcodeproj --badge --format json --output report.json
+
+      - name: Commit badge
+        run: |
+          git config user.name "github-actions"
+          git config user.email "github-actions@github.com"
+          git add badge.svg
+          git diff --staged --quiet || git commit -m "Update review badge [skip ci]"
+          git push
+```
+
+### GitHub Actions: Upload as Artifact
+
+```yaml
+      - name: Upload badge
+        uses: actions/upload-artifact@v4
+        with:
+          name: review-badge
+          path: badge.svg
+```
+
+### Fastlane
+
+```ruby
+lane :update_badge do
+  sh("ios-app-review scan ../MyApp.xcodeproj --badge")
+  # badge.svg is created in the current directory
+end
+```
+
+## Customization
+
+The badge generator accepts an optional `label` parameter (used internally). The default label is "app review". The badge dimensions scale automatically based on label and status text length.
+
+## SVG Details
+
+- Font: Verdana, Geneva, DejaVu Sans
+- Height: 20px
+- Corner radius: 3px
+- Includes ARIA attributes for accessibility (`role="img"`, `aria-label`)
+- Uses `<linearGradient>` for subtle depth
+- Shadow text offset for legibility

package/docs/CI_CD.md

@@ -0,0 +1,283 @@
+# CI/CD Integration
+
+The CLI exits with code 0 (pass) or 1 (errors found), making it a natural CI gate. This guide covers GitHub Actions, Fastlane, Bitrise, and Xcode Cloud.
+
+---
+
+## GitHub Actions
+
+### Basic Gate
+
+```yaml
+# .github/workflows/app-review.yml
+name: App Store Review Check
+
+on:
+  pull_request:
+    paths:
+      - '**/*.swift'
+      - '**/*.m'
+      - '**/*.mm'
+      - '**/Info.plist'
+      - '**/PrivacyInfo.xcprivacy'
+      - '**/*.entitlements'
+
+jobs:
+  review-check:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - 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
+
+      - name: Upload report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: review-report
+          path: report.json
+```
+
+### With ASC Validation and Badge
+
+```yaml
+jobs:
+  review-check:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install ios-app-review
+        run: npm install -g ios-app-review-plugin
+
+      - name: Run full review
+        env:
+          ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}
+          ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
+          ASC_PRIVATE_KEY_PATH: ${{ runner.temp }}/AuthKey.p8
+        run: |
+          echo "${{ secrets.ASC_PRIVATE_KEY }}" > "$ASC_PRIVATE_KEY_PATH"
+          ios-app-review scan ./MyApp.xcodeproj \
+            --include-asc \
+            --badge \
+            --save-history \
+            --format json \
+            --output report.json
+
+      - name: Upload artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: review-report
+          path: |
+            report.json
+            badge.svg
+```
+
+### Incremental Scanning on PRs
+
+```yaml
+      - name: Incremental scan
+        run: |
+          ios-app-review scan ./MyApp.xcodeproj \
+            --changed-since origin/main \
+            --format json \
+            --output report.json
+```
+
+### PR Comment with Results
+
+```yaml
+      - name: Post results to PR
+        if: always()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const report = JSON.parse(fs.readFileSync('report.json', 'utf8'));
+            const status = report.summary.passed ? 'PASSED' : 'FAILED';
+            const body = `## App Review Check: ${status}
+
+            **Score:** ${report.score}/100
+            **Errors:** ${report.summary.errors} | **Warnings:** ${report.summary.warnings} | **Info:** ${report.summary.info}
+
+            ${report.issues.filter(i => i.severity === 'error').map(i => `- ${i.title}: ${i.filePath || ''}:${i.lineNumber || ''}`).join('\n')}`;
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body
+            });
+```
+
+---
+
+## Fastlane
+
+### Fastfile Lane
+
+```ruby
+# fastlane/Fastfile
+desc "Run App Store review compliance check"
+lane :review_check do
+  sh("ios-app-review scan ../MyApp.xcodeproj --format json --output ../review-report.json")
+
+  report = JSON.parse(File.read("../review-report.json"))
+
+  if report["summary"]["errors"] > 0
+    UI.user_error!("App Store review check failed with #{report['summary']['errors']} error(s). Score: #{report['score']}/100")
+  else
+    UI.success("App Store review check passed! Score: #{report['score']}/100")
+  end
+end
+
+desc "Full review with ASC validation"
+lane :full_review do
+  review_check
+
+  sh(
+    "ios-app-review scan ../MyApp.xcodeproj " \
+    "--include-asc --format html --output ../review-report.html --badge"
+  )
+end
+```
+
+### Run Before Submit
+
+```ruby
+lane :submit do
+  review_check
+  build_app(scheme: "MyApp")
+  upload_to_app_store
+end
+```
+
+---
+
+## Bitrise
+
+### bitrise.yml Step
+
+```yaml
+workflows:
+  review-check:
+    steps:
+      - git-clone@8: {}
+
+      - nvm@1:
+          inputs:
+            - node_version: "20"
+
+      - script@1:
+          title: Install ios-app-review
+          inputs:
+            - content: npm install -g ios-app-review-plugin
+
+      - script@1:
+          title: Run review check
+          inputs:
+            - content: |
+                ios-app-review scan ./MyApp.xcodeproj \
+                  --format json \
+                  --output "$BITRISE_DEPLOY_DIR/review-report.json" \
+                  --badge
+
+                # Copy badge to deploy dir
+                cp badge.svg "$BITRISE_DEPLOY_DIR/" 2>/dev/null || true
+
+      - deploy-to-bitrise-io@2:
+          inputs:
+            - deploy_path: "$BITRISE_DEPLOY_DIR/review-report.json"
+```
+
+### With ASC Secrets
+
+Add `ASC_KEY_ID`, `ASC_ISSUER_ID`, and `ASC_PRIVATE_KEY` (base64-encoded) as Bitrise secrets, then:
+
+```yaml
+      - script@1:
+          title: Run full review
+          inputs:
+            - content: |
+                echo "$ASC_PRIVATE_KEY" | base64 -d > /tmp/AuthKey.p8
+                export ASC_PRIVATE_KEY_PATH=/tmp/AuthKey.p8
+
+                ios-app-review scan ./MyApp.xcodeproj \
+                  --include-asc \
+                  --format json \
+                  --output "$BITRISE_DEPLOY_DIR/review-report.json"
+```
+
+---
+
+## Xcode Cloud
+
+Xcode Cloud runs custom scripts at specific phases. Add a post-clone or post-build script.
+
+### ci_scripts/ci_post_clone.sh
+
+```bash
+#!/bin/bash
+set -e
+
+# Install Node.js if not available
+if ! command -v node &> /dev/null; then
+  brew install node
+fi
+
+# Install the tool
+npm install -g ios-app-review-plugin
+
+# Run the scan
+ios-app-review scan "$CI_PRIMARY_REPOSITORY_PATH/MyApp.xcodeproj" \
+  --format json \
+  --output "$CI_PRIMARY_REPOSITORY_PATH/review-report.json"
+
+# Print summary to build log
+SCORE=$(cat "$CI_PRIMARY_REPOSITORY_PATH/review-report.json" | python3 -c "import sys,json; print(json.load(sys.stdin)['score'])")
+ERRORS=$(cat "$CI_PRIMARY_REPOSITORY_PATH/review-report.json" | python3 -c "import sys,json; print(json.load(sys.stdin)['summary']['errors'])")
+
+echo "App Review Score: $SCORE/100"
+echo "Errors: $ERRORS"
+
+if [ "$ERRORS" -gt 0 ]; then
+  echo "::error::App Store review check failed with $ERRORS error(s)"
+  exit 1
+fi
+```
+
+Make the script executable:
+
+```bash
+chmod +x ci_scripts/ci_post_clone.sh
+```
+
+### ASC Credentials in Xcode Cloud
+
+Xcode Cloud provides App Store Connect credentials automatically for certain operations. For the plugin's ASC validation, store the API key as a custom environment variable:
+
+1. In Xcode Cloud workflow settings, add environment variables for `ASC_KEY_ID` and `ASC_ISSUER_ID`.
+2. Store the private key content as a secret and write it to a temp file in the script.
+
+---
+
+## Tips for All Platforms
+
+1. **Use JSON output** for machine parsing. Markdown and HTML are better for human-readable artifacts.
+2. **Cache node_modules** to speed up repeated installs.
+3. **Incremental scanning** (`--changed-since`) significantly reduces scan time on PRs.
+4. **Save history** (`--save-history`) to track score trends across builds.
+5. **Exit code 2** indicates invalid arguments or crashes -- handle this separately from exit code 1 (issues found).

package/docs/CLI.md

@@ -0,0 +1,140 @@
+# CLI Reference
+
+The iOS App Review Plugin ships as a dual-mode binary. When invoked with arguments it runs as a CLI tool; without arguments it starts the MCP server.
+
+## Installation
+
+```bash
+# Global install
+npm install -g ios-app-review-plugin
+
+# Or run directly after building
+npm run build
+node dist/index.js scan ./MyApp.xcodeproj
+```
+
+The CLI binary is named `ios-app-review`.
+
+## Commands
+
+### scan
+
+Analyze an iOS project for App Store review compliance.
+
+```
+ios-app-review scan <path> [options]
+```
+
+**Positional argument:**
+
+- `<path>` -- Path to the `.xcodeproj`, `.xcworkspace`, or project directory. Required.
+
+**Options:**
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--format <fmt>` | `-f` | `markdown` | Output format: `markdown`, `html`, or `json` |
+| `--output <path>` | `-o` | stdout | Write report to a file |
+| `--analyzers <list>` | `-a` | all | Comma-separated analyzer names |
+| `--include-asc` | | false | Run App Store Connect validators |
+| `--changed-since <ref>` | | | Git ref for incremental scanning |
+| `--config <path>` | `-c` | auto | Path to `.ios-review-rules.json` |
+| `--badge` | | false | Generate `badge.svg` alongside the report |
+| `--save-history` | | false | Persist results for `compare_scans` |
+
+**Analyzer names:** `info-plist`, `privacy`, `entitlements`, `code`, `deprecated-api`, `private-api`, `security`, `ui-ux`, `asc-metadata`, `asc-screenshots`, `asc-version`, `asc-iap`.
+
+### help
+
+```
+ios-app-review help
+ios-app-review --help
+ios-app-review -h
+```
+
+Print usage information and exit.
+
+### version
+
+```
+ios-app-review version
+ios-app-review --version
+ios-app-review -v
+```
+
+Print the version number and exit.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | All checks passed -- no errors found |
+| `1` | One or more error-severity issues detected |
+| `2` | Invalid arguments or a runtime error |
+
+## Examples
+
+**Basic scan with default settings (markdown to stdout):**
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj
+```
+
+**Generate an HTML report file:**
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj --format html --output reports/review.html
+```
+
+**JSON report for CI pipeline parsing:**
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj --format json --output report.json
+```
+
+**Run only code and security analyzers:**
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj --analyzers code,security
+```
+
+**Incremental scan (only changed files since main branch):**
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj --changed-since main
+```
+
+**Full scan with ASC validation, badge, and history:**
+
+```bash
+export ASC_KEY_ID="XXXXXXXXXX"
+export ASC_ISSUER_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+export ASC_PRIVATE_KEY_PATH="$HOME/.appstoreconnect/AuthKey_XXXXXXXXXX.p8"
+
+ios-app-review scan ./MyApp.xcodeproj \
+  --include-asc \
+  --badge \
+  --save-history \
+  --format json \
+  --output report.json
+```
+
+**Scan with custom rules:**
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj --config ./team-rules.json
+```
+
+**Use in a CI gate (rely on exit code):**
+
+```bash
+ios-app-review scan ./MyApp.xcodeproj --format json --output report.json
+# exit code 0 = pass, 1 = fail, 2 = error
+```
+
+## Output Behavior
+
+- When `--output` is specified, the formatted report is written to that file and a confirmation message is printed to stderr.
+- When `--output` is omitted, the report is printed to stdout.
+- When `--badge` is specified, `badge.svg` is written next to the output file (or in the current directory if no `--output`).
+- Diagnostic/progress messages are always written to stderr so they do not interfere with piped stdout.