ios-app-review-plugin 1.0.0

package/src/analyzers/asc-metadata.ts

@@ -0,0 +1,326 @@
+/**
+ * App Store Connect Metadata Analyzer
+ *
+ * Validates app metadata from ASC including app name, subtitle,
+ * description, keywords, URLs, and checks for placeholder text.
+ */
+
+import type {
+  Analyzer,
+  AnalysisResult,
+  AnalyzerOptions,
+  Issue,
+  XcodeProject,
+} from '../types/index.js';
+import {
+  hasCredentials,
+  getAppWithInfo,
+  isASCError,
+  type AppInfoLocalization,
+} from '../asc/index.js';
+
+/**
+ * Metadata length limits from App Store Connect
+ */
+const LIMITS = {
+  appName: 30,
+  subtitle: 30,
+  description: 4000,
+  keywords: 100,
+  promotionalText: 170,
+  whatsNew: 4000,
+};
+
+/**
+ * Placeholder text patterns
+ */
+const PLACEHOLDER_PATTERNS = [
+  /lorem\s+ipsum/i,
+  /^todo/i,
+  /^fixme/i,
+  /^\[.*\]$/,
+  /^<.*>$/,
+  /^placeholder/i,
+  /your\s+(app\s+)?description/i,
+  /enter\s+(your\s+)?description/i,
+  /add\s+(your\s+)?description/i,
+  /sample\s+text/i,
+  /example\s+text/i,
+  /test\s+(app|description)/i,
+];
+
+/**
+ * Check if text contains placeholder content
+ */
+function isPlaceholder(text: string): boolean {
+  return PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(text.trim()));
+}
+
+/**
+ * Validate a URL format
+ */
+function isValidUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === 'https:' || parsed.protocol === 'http:';
+  } catch {
+    return false;
+  }
+}
+
+export class ASCMetadataAnalyzer implements Analyzer {
+  name = 'ASC Metadata Analyzer';
+  description = 'Validates app metadata in App Store Connect';
+
+  async analyze(project: XcodeProject, options?: AnalyzerOptions): Promise<AnalysisResult> {
+    const startTime = Date.now();
+    const issues: Issue[] = [];
+
+    // Check if credentials are configured
+    if (!hasCredentials()) {
+      issues.push({
+        id: 'asc-credentials-not-configured',
+        title: 'App Store Connect credentials not configured',
+        description:
+          'ASC credentials are not configured. Set ASC_KEY_ID, ASC_ISSUER_ID, and ASC_PRIVATE_KEY_PATH (or ASC_PRIVATE_KEY) environment variables to enable ASC validation.',
+        severity: 'info',
+        category: 'metadata',
+        suggestion:
+          'See documentation for setting up App Store Connect API credentials.',
+      });
+
+      return {
+        analyzer: this.name,
+        passed: true,
+        issues,
+        duration: Date.now() - startTime,
+      };
+    }
+
+    // Get bundle ID from project
+    const bundleId = options?.bundleId ?? this.getBundleIdFromProject(project);
+    if (!bundleId) {
+      issues.push({
+        id: 'asc-no-bundle-id',
+        title: 'No bundle ID found',
+        description: 'Could not determine bundle ID from project to query App Store Connect.',
+        severity: 'warning',
+        category: 'metadata',
+      });
+
+      return {
+        analyzer: this.name,
+        passed: true,
+        issues,
+        duration: Date.now() - startTime,
+      };
+    }
+
+    try {
+      const appData = await getAppWithInfo(bundleId);
+
+      // Validate app info localizations
+      for (const localization of appData.localizations) {
+        const locIssues = this.validateLocalization(localization, appData.app.attributes.primaryLocale);
+        issues.push(...locIssues);
+      }
+
+      // Check for missing primary locale
+      const primaryLocale = appData.app.attributes.primaryLocale;
+      const hasPrimaryLocale = appData.localizations.some(
+        (loc) => loc.attributes.locale === primaryLocale
+      );
+
+      if (!hasPrimaryLocale && appData.localizations.length > 0) {
+        issues.push({
+          id: 'asc-missing-primary-locale',
+          title: 'Missing primary locale metadata',
+          description: `App info localization for primary locale "${primaryLocale}" not found.`,
+          severity: 'warning',
+          category: 'metadata',
+        });
+      }
+    } catch (error) {
+      if (isASCError(error)) {
+        issues.push({
+          id: error.code,
+          title: error.name,
+          description: error.message,
+          severity: 'error',
+          category: 'metadata',
+        });
+      } else {
+        issues.push({
+          id: 'asc-api-error',
+          title: 'App Store Connect API Error',
+          description: error instanceof Error ? error.message : String(error),
+          severity: 'error',
+          category: 'metadata',
+        });
+      }
+    }
+
+    return {
+      analyzer: this.name,
+      passed: issues.filter((i) => i.severity === 'error').length === 0,
+      issues,
+      duration: Date.now() - startTime,
+    };
+  }
+
+  /**
+   * Validate a single localization
+   */
+  private validateLocalization(localization: AppInfoLocalization, primaryLocale: string): Issue[] {
+    const issues: Issue[] = [];
+    const locale = localization.attributes.locale;
+    const isPrimary = locale === primaryLocale;
+
+    // Validate app name
+    const name = localization.attributes.name;
+    if (name) {
+      if (name.length > LIMITS.appName) {
+        issues.push({
+          id: 'asc-name-too-long',
+          title: `App name too long (${locale})`,
+          description: `App name is ${name.length} characters, maximum is ${LIMITS.appName}.`,
+          severity: 'error',
+          category: 'metadata',
+          suggestion: `Shorten the app name to ${LIMITS.appName} characters or less.`,
+        });
+      }
+
+      if (isPlaceholder(name)) {
+        issues.push({
+          id: 'asc-name-placeholder',
+          title: `Placeholder app name detected (${locale})`,
+          description: `App name "${name}" appears to be placeholder text.`,
+          severity: 'error',
+          category: 'metadata',
+          guideline: 'Guideline 2.3.7 - Accurate Metadata',
+        });
+      }
+    } else if (isPrimary) {
+      issues.push({
+        id: 'asc-missing-name',
+        title: 'Missing app name',
+        description: `App name is not set for primary locale "${locale}".`,
+        severity: 'error',
+        category: 'metadata',
+      });
+    }
+
+    // Validate subtitle
+    const subtitle = localization.attributes.subtitle;
+    if (subtitle) {
+      if (subtitle.length > LIMITS.subtitle) {
+        issues.push({
+          id: 'asc-subtitle-too-long',
+          title: `Subtitle too long (${locale})`,
+          description: `Subtitle is ${subtitle.length} characters, maximum is ${LIMITS.subtitle}.`,
+          severity: 'error',
+          category: 'metadata',
+        });
+      }
+
+      if (isPlaceholder(subtitle)) {
+        issues.push({
+          id: 'asc-subtitle-placeholder',
+          title: `Placeholder subtitle detected (${locale})`,
+          description: `Subtitle "${subtitle}" appears to be placeholder text.`,
+          severity: 'error',
+          category: 'metadata',
+        });
+      }
+    }
+
+    // Validate privacy policy URL
+    const privacyUrl = localization.attributes.privacyPolicyUrl;
+    if (!privacyUrl && isPrimary) {
+      issues.push({
+        id: 'asc-missing-privacy-policy',
+        title: 'Missing privacy policy URL',
+        description: 'Privacy policy URL is required for App Store submission.',
+        severity: 'error',
+        category: 'metadata',
+        guideline: 'Guideline 5.1.1 - Data Collection and Storage',
+        suggestion: 'Add a privacy policy URL to your app metadata.',
+      });
+    } else if (privacyUrl && !isValidUrl(privacyUrl)) {
+      issues.push({
+        id: 'asc-invalid-privacy-url',
+        title: `Invalid privacy policy URL (${locale})`,
+        description: `Privacy policy URL "${privacyUrl}" is not a valid URL.`,
+        severity: 'error',
+        category: 'metadata',
+      });
+    }
+
+    return issues;
+  }
+
+  /**
+   * Standalone metadata validation by bundle ID
+   */
+  async validateByBundleId(bundleId: string): Promise<AnalysisResult> {
+    const startTime = Date.now();
+    const issues: Issue[] = [];
+
+    if (!hasCredentials()) {
+      return {
+        analyzer: this.name,
+        passed: false,
+        issues: [
+          {
+            id: 'asc-credentials-not-configured',
+            title: 'App Store Connect credentials not configured',
+            description:
+              'Set ASC_KEY_ID, ASC_ISSUER_ID, and ASC_PRIVATE_KEY_PATH environment variables.',
+            severity: 'error',
+            category: 'metadata',
+          },
+        ],
+        duration: Date.now() - startTime,
+      };
+    }
+
+    try {
+      const appData = await getAppWithInfo(bundleId);
+
+      for (const localization of appData.localizations) {
+        const locIssues = this.validateLocalization(
+          localization,
+          appData.app.attributes.primaryLocale
+        );
+        issues.push(...locIssues);
+      }
+    } catch (error) {
+      if (isASCError(error)) {
+        issues.push({
+          id: error.code,
+          title: error.name,
+          description: error.message,
+          severity: 'error',
+          category: 'metadata',
+        });
+      } else {
+        throw error;
+      }
+    }
+
+    return {
+      analyzer: this.name,
+      passed: issues.filter((i) => i.severity === 'error').length === 0,
+      issues,
+      duration: Date.now() - startTime,
+    };
+  }
+
+  /**
+   * Get bundle ID from project targets
+   */
+  private getBundleIdFromProject(project: XcodeProject): string | undefined {
+    const appTarget = project.targets.find((t) => t.type === 'application');
+    return appTarget?.bundleIdentifier;
+  }
+}

package/src/analyzers/asc-screenshots.ts

@@ -0,0 +1,310 @@
+/**
+ * App Store Connect Screenshot Analyzer
+ *
+ * Validates screenshots in ASC including required device sizes,
+ * screenshot counts, processing status, and localized presence.
+ */
+
+import type {
+  Analyzer,
+  AnalysisResult,
+  AnalyzerOptions,
+  Issue,
+  XcodeProject,
+} from '../types/index.js';
+import {
+  hasCredentials,
+  getAppByBundleId,
+  getEditableVersion,
+  getVersionLocalizations,
+  getScreenshotSetsWithScreenshots,
+  REQUIRED_IPHONE_DISPLAY_TYPES,
+  REQUIRED_IPAD_DISPLAY_TYPES,
+  getDisplayTypeDescription,
+  validateScreenshotSet,
+  isASCError,
+  type ScreenshotDisplayType,
+  type AppStoreVersionLocalization,
+} from '../asc/index.js';
+
+/**
+ * Screenshot requirements
+ */
+const MAX_SCREENSHOTS = 10;
+
+export class ASCScreenshotAnalyzer implements Analyzer {
+  name = 'ASC Screenshot Analyzer';
+  description = 'Validates screenshots in App Store Connect';
+
+  async analyze(project: XcodeProject, options?: AnalyzerOptions): Promise<AnalysisResult> {
+    const startTime = Date.now();
+    const issues: Issue[] = [];
+
+    if (!hasCredentials()) {
+      issues.push({
+        id: 'asc-credentials-not-configured',
+        title: 'App Store Connect credentials not configured',
+        description:
+          'ASC credentials are not configured. Set environment variables to enable screenshot validation.',
+        severity: 'info',
+        category: 'screenshots',
+      });
+
+      return {
+        analyzer: this.name,
+        passed: true,
+        issues,
+        duration: Date.now() - startTime,
+      };
+    }
+
+    const bundleId = options?.bundleId ?? this.getBundleIdFromProject(project);
+    if (!bundleId) {
+      issues.push({
+        id: 'asc-no-bundle-id',
+        title: 'No bundle ID found',
+        description: 'Could not determine bundle ID from project.',
+        severity: 'warning',
+        category: 'screenshots',
+      });
+
+      return {
+        analyzer: this.name,
+        passed: true,
+        issues,
+        duration: Date.now() - startTime,
+      };
+    }
+
+    try {
+      const screenshotIssues = await this.validateScreenshotsForBundleId(bundleId);
+      issues.push(...screenshotIssues);
+    } catch (error) {
+      if (isASCError(error)) {
+        issues.push({
+          id: error.code,
+          title: error.name,
+          description: error.message,
+          severity: 'error',
+          category: 'screenshots',
+        });
+      } else {
+        issues.push({
+          id: 'asc-api-error',
+          title: 'App Store Connect API Error',
+          description: error instanceof Error ? error.message : String(error),
+          severity: 'error',
+          category: 'screenshots',
+        });
+      }
+    }
+
+    return {
+      analyzer: this.name,
+      passed: issues.filter((i) => i.severity === 'error').length === 0,
+      issues,
+      duration: Date.now() - startTime,
+    };
+  }
+
+  /**
+   * Validate screenshots for a bundle ID
+   */
+  async validateByBundleId(bundleId: string): Promise<AnalysisResult> {
+    const startTime = Date.now();
+    const issues: Issue[] = [];
+
+    if (!hasCredentials()) {
+      return {
+        analyzer: this.name,
+        passed: false,
+        issues: [
+          {
+            id: 'asc-credentials-not-configured',
+            title: 'App Store Connect credentials not configured',
+            description: 'Set ASC environment variables to enable validation.',
+            severity: 'error',
+            category: 'screenshots',
+          },
+        ],
+        duration: Date.now() - startTime,
+      };
+    }
+
+    try {
+      const screenshotIssues = await this.validateScreenshotsForBundleId(bundleId);
+      issues.push(...screenshotIssues);
+    } catch (error) {
+      if (isASCError(error)) {
+        issues.push({
+          id: error.code,
+          title: error.name,
+          description: error.message,
+          severity: 'error',
+          category: 'screenshots',
+        });
+      } else {
+        throw error;
+      }
+    }
+
+    return {
+      analyzer: this.name,
+      passed: issues.filter((i) => i.severity === 'error').length === 0,
+      issues,
+      duration: Date.now() - startTime,
+    };
+  }
+
+  /**
+   * Internal screenshot validation
+   */
+  private async validateScreenshotsForBundleId(bundleId: string): Promise<Issue[]> {
+    const issues: Issue[] = [];
+
+    const app = await getAppByBundleId(bundleId);
+    const version = await getEditableVersion(app.id);
+
+    if (!version) {
+      issues.push({
+        id: 'asc-no-editable-version',
+        title: 'No editable version found',
+        description:
+          'No app version in editable state (PREPARE_FOR_SUBMISSION, etc.) found in App Store Connect.',
+        severity: 'info',
+        category: 'screenshots',
+      });
+      return issues;
+    }
+
+    const localizations = await getVersionLocalizations(version.id);
+
+    if (localizations.length === 0) {
+      issues.push({
+        id: 'asc-no-localizations',
+        title: 'No version localizations found',
+        description: 'No localizations configured for the current app version.',
+        severity: 'warning',
+        category: 'screenshots',
+      });
+      return issues;
+    }
+
+    // Check each localization
+    for (const localization of localizations) {
+      const locIssues = await this.validateLocalizationScreenshots(localization);
+      issues.push(...locIssues);
+    }
+
+    return issues;
+  }
+
+  /**
+   * Validate screenshots for a single localization
+   */
+  private async validateLocalizationScreenshots(
+    localization: AppStoreVersionLocalization
+  ): Promise<Issue[]> {
+    const issues: Issue[] = [];
+    const locale = localization.attributes.locale;
+
+    const screenshotSets = await getScreenshotSetsWithScreenshots(localization.id);
+
+    // Track which required types are present
+    const presentTypes = new Set<ScreenshotDisplayType>(
+      screenshotSets.map((s) => s.set.attributes.screenshotDisplayType)
+    );
+
+    // Check required iPhone sizes
+    const missingIPhoneTypes = REQUIRED_IPHONE_DISPLAY_TYPES.filter(
+      (type) => !presentTypes.has(type)
+    );
+
+    if (missingIPhoneTypes.length > 0) {
+      // At least one iPhone size is required
+      const hasAnyIPhoneScreenshots = REQUIRED_IPHONE_DISPLAY_TYPES.some((type) =>
+        presentTypes.has(type)
+      );
+
+      if (!hasAnyIPhoneScreenshots) {
+        issues.push({
+          id: 'asc-missing-iphone-screenshots',
+          title: `Missing iPhone screenshots (${locale})`,
+          description: `No iPhone screenshots found. At least one of these sizes is required: ${missingIPhoneTypes.map(getDisplayTypeDescription).join(', ')}`,
+          severity: 'error',
+          category: 'screenshots',
+          suggestion: 'Upload screenshots for at least iPhone 6.5" or 5.5" display.',
+        });
+      } else {
+        issues.push({
+          id: 'asc-incomplete-iphone-screenshots',
+          title: `Incomplete iPhone screenshot sizes (${locale})`,
+          description: `Missing screenshots for: ${missingIPhoneTypes.map(getDisplayTypeDescription).join(', ')}`,
+          severity: 'warning',
+          category: 'screenshots',
+        });
+      }
+    }
+
+    // Check iPad sizes if app supports iPad
+    const missingIPadTypes = REQUIRED_IPAD_DISPLAY_TYPES.filter(
+      (type) => !presentTypes.has(type)
+    );
+
+    if (missingIPadTypes.length === REQUIRED_IPAD_DISPLAY_TYPES.length) {
+      // No iPad screenshots - this might be intentional if app is iPhone-only
+      issues.push({
+        id: 'asc-no-ipad-screenshots',
+        title: `No iPad screenshots (${locale})`,
+        description:
+          'No iPad screenshots found. If your app supports iPad, screenshots are required for iPad Pro 12.9".',
+        severity: 'info',
+        category: 'screenshots',
+      });
+    }
+
+    // Validate each screenshot set
+    for (const { set, screenshots } of screenshotSets) {
+      const validation = validateScreenshotSet(set, screenshots);
+
+      // Check count
+      if (screenshots.length === 0) {
+        issues.push({
+          id: 'asc-empty-screenshot-set',
+          title: `Empty screenshot set (${locale})`,
+          description: `Screenshot set for ${getDisplayTypeDescription(set.attributes.screenshotDisplayType)} has no screenshots.`,
+          severity: 'warning',
+          category: 'screenshots',
+        });
+      } else if (screenshots.length > MAX_SCREENSHOTS) {
+        issues.push({
+          id: 'asc-too-many-screenshots',
+          title: `Too many screenshots (${locale})`,
+          description: `Screenshot set for ${getDisplayTypeDescription(set.attributes.screenshotDisplayType)} has ${screenshots.length} screenshots (max ${MAX_SCREENSHOTS}).`,
+          severity: 'error',
+          category: 'screenshots',
+        });
+      }
+
+      // Check processing errors
+      if (validation.hasProcessingErrors) {
+        for (const issue of validation.issues) {
+          issues.push({
+            id: 'asc-screenshot-processing-error',
+            title: `Screenshot processing error (${locale})`,
+            description: issue,
+            severity: 'error',
+            category: 'screenshots',
+          });
+        }
+      }
+    }
+
+    return issues;
+  }
+
+  private getBundleIdFromProject(project: XcodeProject): string | undefined {
+    const appTarget = project.targets.find((t) => t.type === 'application');
+    return appTarget?.bundleIdentifier;
+  }
+}