ios-app-review-plugin 1.0.0

package/src/rules/engine.ts

@@ -0,0 +1,121 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import fg from 'fast-glob';
+import type { AnalysisResult, Issue, Severity } from '../types/index.js';
+import type { CompiledRule, CustomRuleConfig } from './types.js';
+
+const SOURCE_EXTENSIONS = ['.swift', '.m', '.mm', '.h', '.c', '.cpp'];
+const DISABLE_COMMENT_PATTERN = /\/\/\s*ios-review-disable-next-line\s+([\w-]+(?:\s*,\s*[\w-]+)*)/;
+
+export class CustomRuleEngine {
+  private disabledRules: Set<string>;
+  private severityOverrides: Record<string, Severity>;
+
+  constructor(config?: CustomRuleConfig) {
+    this.disabledRules = new Set(config?.disabledRules ?? []);
+    this.severityOverrides = config?.severityOverrides ?? {};
+  }
+
+  isRuleDisabled(ruleId: string): boolean {
+    return this.disabledRules.has(ruleId);
+  }
+
+  getSeverityOverride(ruleId: string): Severity | undefined {
+    return this.severityOverrides[ruleId];
+  }
+
+  async scan(scanPath: string, compiledRules: CompiledRule[]): Promise<AnalysisResult> {
+    const startTime = Date.now();
+    const issues: Issue[] = [];
+
+    // Filter out disabled rules
+    const activeRules = compiledRules.filter((r) => !this.isRuleDisabled(r.id));
+
+    if (activeRules.length === 0) {
+      return {
+        analyzer: 'Custom Rules',
+        passed: true,
+        issues: [],
+        duration: Date.now() - startTime,
+      };
+    }
+
+    // Determine files to scan
+    const stat = await fs.stat(scanPath);
+    let files: string[];
+
+    if (stat.isFile()) {
+      files = [scanPath];
+    } else {
+      const patterns = SOURCE_EXTENSIONS.map((ext) => `**/*${ext}`);
+      files = await fg(patterns, {
+        cwd: scanPath,
+        absolute: true,
+        ignore: ['**/node_modules/**', '**/Pods/**', '**/build/**', '**/.build/**'],
+      });
+    }
+
+    for (const filePath of files) {
+      const ext = path.extname(filePath);
+      const content = await fs.readFile(filePath, 'utf-8');
+      const lines = content.split('\n');
+
+      for (const rule of activeRules) {
+        // Check fileTypes filter
+        if (rule.fileTypes && rule.fileTypes.length > 0 && !rule.fileTypes.includes(ext)) {
+          continue;
+        }
+
+        // Reset regex lastIndex for global patterns
+        rule.regex.lastIndex = 0;
+
+        let match: RegExpExecArray | null;
+        while ((match = rule.regex.exec(content)) !== null) {
+          // Find line number
+          const upToMatch = content.substring(0, match.index);
+          const lineNumber = upToMatch.split('\n').length;
+
+          // Check for disable comment on previous line
+          if (lineNumber >= 2) {
+            const prevLine = lines[lineNumber - 2]; // -2 because lineNumber is 1-based and we want prev line
+            if (prevLine) {
+              const disableMatch = DISABLE_COMMENT_PATTERN.exec(prevLine);
+              if (disableMatch?.[1]) {
+                const disabledIds = disableMatch[1].split(',').map((s) => s.trim());
+                if (disabledIds.includes(rule.id)) {
+                  continue;
+                }
+              }
+            }
+          }
+
+          const severity = this.getSeverityOverride(rule.id) ?? rule.severity;
+
+          issues.push({
+            id: rule.id,
+            title: rule.title,
+            description: rule.description,
+            severity,
+            filePath,
+            lineNumber,
+            guideline: rule.guideline,
+            suggestion: rule.suggestion,
+            category: rule.category ?? 'custom',
+          });
+
+          // For non-global regex, break after first match
+          if (!rule.regex.global) {
+            break;
+          }
+        }
+      }
+    }
+
+    return {
+      analyzer: 'Custom Rules',
+      passed: issues.every((i) => i.severity !== 'error'),
+      issues,
+      duration: Date.now() - startTime,
+    };
+  }
+}

package/src/rules/index.ts

@@ -0,0 +1,3 @@
+export { RuleLoader } from './loader.js';
+export { CustomRuleEngine } from './engine.js';
+export type { CustomRule, CustomRuleConfig, CompiledRule } from './types.js';

package/src/rules/loader.ts

@@ -0,0 +1,83 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { z } from 'zod';
+import type { CustomRuleConfig, CompiledRule } from './types.js';
+
+const CustomRuleSchema = z.object({
+  id: z.string().min(1),
+  title: z.string().min(1),
+  description: z.string().min(1),
+  severity: z.enum(['error', 'warning', 'info']),
+  pattern: z.string().min(1),
+  flags: z.string().optional(),
+  fileTypes: z.array(z.string()).optional(),
+  guideline: z.string().optional(),
+  suggestion: z.string().optional(),
+  category: z.string().optional(),
+});
+
+const CustomRuleConfigSchema = z.object({
+  version: z.literal(1),
+  rules: z.array(CustomRuleSchema),
+  disabledRules: z.array(z.string()).optional(),
+  severityOverrides: z.record(z.enum(['error', 'warning', 'info'])).optional(),
+});
+
+const CONFIG_FILENAME = '.ios-review-rules.json';
+
+export class RuleLoader {
+  /**
+   * Find config file by walking up from the given directory
+   */
+  async findConfig(startDir: string): Promise<string | null> {
+    let dir = path.resolve(startDir);
+    const root = path.parse(dir).root;
+
+    while (dir !== root) {
+      const configPath = path.join(dir, CONFIG_FILENAME);
+      try {
+        await fs.access(configPath);
+        return configPath;
+      } catch {
+        dir = path.dirname(dir);
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Load and validate a config file
+   */
+  async loadConfig(configPath: string): Promise<CustomRuleConfig> {
+    const raw = await fs.readFile(configPath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return CustomRuleConfigSchema.parse(parsed) as CustomRuleConfig;
+  }
+
+  /**
+   * Compile regex patterns from rules
+   */
+  compileRules(config: CustomRuleConfig): CompiledRule[] {
+    const compiled: CompiledRule[] = [];
+
+    for (const rule of config.rules) {
+      const flags = rule.flags ?? 'g';
+      const regex = new RegExp(rule.pattern, flags);
+      compiled.push({ ...rule, regex });
+    }
+
+    return compiled;
+  }
+
+  /**
+   * Find, load, validate, and compile rules from project directory
+   */
+  async loadFromProject(projectDir: string): Promise<{ config: CustomRuleConfig; rules: CompiledRule[] } | null> {
+    const configPath = await this.findConfig(projectDir);
+    if (!configPath) return null;
+
+    const config = await this.loadConfig(configPath);
+    const rules = this.compileRules(config);
+    return { config, rules };
+  }
+}

package/src/rules/types.ts

@@ -0,0 +1,25 @@
+import type { Severity, IssueCategory } from '../types/index.js';
+
+export interface CustomRule {
+  id: string;
+  title: string;
+  description: string;
+  severity: Severity;
+  pattern: string;
+  flags?: string | undefined;
+  fileTypes?: string[] | undefined;
+  guideline?: string | undefined;
+  suggestion?: string | undefined;
+  category?: IssueCategory | 'custom' | undefined;
+}
+
+export interface CustomRuleConfig {
+  version: 1;
+  rules: CustomRule[];
+  disabledRules?: string[] | undefined;
+  severityOverrides?: Record<string, Severity> | undefined;
+}
+
+export interface CompiledRule extends CustomRule {
+  regex: RegExp;
+}

package/src/types/index.ts

@@ -0,0 +1,247 @@
+import { z } from 'zod';
+
+/**
+ * Severity levels for analysis issues
+ */
+export type Severity = 'error' | 'warning' | 'info';
+
+/**
+ * An issue found during analysis
+ */
+export interface Issue {
+  /** Unique identifier for the issue type */
+  id: string;
+  /** Human-readable title */
+  title: string;
+  /** Detailed description of the issue */
+  description: string;
+  /** Severity level */
+  severity: Severity;
+  /** File path where the issue was found (if applicable) */
+  filePath?: string | undefined;
+  /** Line number in the file (if applicable) */
+  lineNumber?: number | undefined;
+  /** Related App Store Guideline (if applicable) */
+  guideline?: string | undefined;
+  /** Suggested fix or remediation */
+  suggestion?: string | undefined;
+  /** Category of the issue */
+  category: IssueCategory;
+  /** URL to the relevant App Store Review Guideline */
+  guidelineUrl?: string | undefined;
+  /** Excerpt from the relevant guideline */
+  guidelineExcerpt?: string | undefined;
+  /** Calculated severity score based on guideline weight */
+  severityScore?: number | undefined;
+}
+
+/**
+ * Categories for grouping issues
+ */
+export type IssueCategory =
+  | 'info-plist'
+  | 'privacy'
+  | 'entitlements'
+  | 'code'
+  | 'security'
+  | 'metadata'
+  | 'screenshots'
+  | 'version'
+  | 'iap'
+  | 'asc'
+  | 'deprecated-api'
+  | 'private-api'
+  | 'ui-ux'
+  | 'custom';
+
+/**
+ * Result from an analyzer
+ */
+export interface AnalysisResult {
+  /** Name of the analyzer */
+  analyzer: string;
+  /** Whether the analysis passed (no errors) */
+  passed: boolean;
+  /** List of issues found */
+  issues: Issue[];
+  /** Time taken in milliseconds */
+  duration: number;
+}
+
+/**
+ * Complete analysis report
+ */
+export interface AnalysisReport {
+  /** Project path that was analyzed */
+  projectPath: string;
+  /** Timestamp of the analysis */
+  timestamp: string;
+  /** Results from each analyzer */
+  results: AnalysisResult[];
+  /** Summary statistics */
+  summary: AnalysisSummary;
+}
+
+/**
+ * Summary statistics for an analysis
+ */
+export interface AnalysisSummary {
+  /** Total number of issues */
+  totalIssues: number;
+  /** Number of errors */
+  errors: number;
+  /** Number of warnings */
+  warnings: number;
+  /** Number of info items */
+  info: number;
+  /** Overall pass/fail status */
+  passed: boolean;
+  /** Total analysis duration in milliseconds */
+  duration: number;
+}
+
+/**
+ * Xcode project information
+ */
+export interface XcodeProject {
+  /** Path to the .xcodeproj directory */
+  path: string;
+  /** Project name */
+  name: string;
+  /** Build targets */
+  targets: XcodeTarget[];
+  /** Build configurations */
+  configurations: string[];
+}
+
+/**
+ * Xcode build target
+ */
+export interface XcodeTarget {
+  /** Target name */
+  name: string;
+  /** Target type (app, framework, extension, etc.) */
+  type: TargetType;
+  /** Bundle identifier */
+  bundleIdentifier?: string | undefined;
+  /** Path to Info.plist */
+  infoPlistPath?: string | undefined;
+  /** Path to entitlements file */
+  entitlementsPath?: string | undefined;
+  /** Minimum deployment target */
+  deploymentTarget?: string | undefined;
+  /** Source files */
+  sourceFiles: string[];
+}
+
+export type TargetType =
+  | 'application'
+  | 'framework'
+  | 'staticLibrary'
+  | 'dynamicLibrary'
+  | 'appExtension'
+  | 'watchApp'
+  | 'watchExtension'
+  | 'tvExtension'
+  | 'unitTest'
+  | 'uiTest'
+  | 'unknown';
+
+/**
+ * Parsed Info.plist contents
+ */
+export interface InfoPlist {
+  /** Bundle identifier */
+  CFBundleIdentifier?: string;
+  /** Bundle name */
+  CFBundleName?: string;
+  /** Bundle display name */
+  CFBundleDisplayName?: string;
+  /** Bundle version (build number) */
+  CFBundleVersion?: string;
+  /** Short version string (marketing version) */
+  CFBundleShortVersionString?: string;
+  /** Minimum iOS version */
+  MinimumOSVersion?: string;
+  /** Privacy usage descriptions */
+  [key: `NS${string}UsageDescription`]: string | undefined;
+  /** App Transport Security settings */
+  NSAppTransportSecurity?: {
+    NSAllowsArbitraryLoads?: boolean;
+    NSExceptionDomains?: Record<string, unknown>;
+  };
+  /** All other properties */
+  [key: string]: unknown;
+}
+
+/**
+ * Privacy manifest (PrivacyInfo.xcprivacy) contents
+ */
+export interface PrivacyManifest {
+  /** Privacy tracking enabled */
+  NSPrivacyTracking?: boolean;
+  /** Tracking domains */
+  NSPrivacyTrackingDomains?: string[];
+  /** Collected data types */
+  NSPrivacyCollectedDataTypes?: PrivacyCollectedDataType[];
+  /** Accessed API types */
+  NSPrivacyAccessedAPITypes?: PrivacyAccessedAPIType[];
+}
+
+export interface PrivacyCollectedDataType {
+  NSPrivacyCollectedDataType: string;
+  NSPrivacyCollectedDataTypeLinked: boolean;
+  NSPrivacyCollectedDataTypeTracking: boolean;
+  NSPrivacyCollectedDataTypePurposes: string[];
+}
+
+export interface PrivacyAccessedAPIType {
+  NSPrivacyAccessedAPIType: string;
+  NSPrivacyAccessedAPITypeReasons: string[];
+}
+
+/**
+ * Input schema for the analyze tool
+ */
+export const AnalyzeInputSchema = z.object({
+  projectPath: z.string().describe('Path to the .xcodeproj or .xcworkspace directory'),
+  analyzers: z
+    .array(z.enum(['all', 'info-plist', 'privacy', 'entitlements', 'code', 'deprecated-api', 'private-api', 'security', 'ui-ux', 'asc-metadata', 'asc-screenshots', 'asc-version', 'asc-iap']))
+    .optional()
+    .describe('Specific analyzers to run (default: all)'),
+  targetName: z.string().optional().describe('Specific target to analyze'),
+  includeASC: z.boolean().optional().describe('Include App Store Connect validation (requires ASC credentials)'),
+  bundleId: z.string().optional().describe('Bundle ID for ASC validation (auto-detected if not provided)'),
+  format: z
+    .enum(['markdown', 'html', 'json'])
+    .optional()
+    .describe('Report output format (default: markdown)'),
+  saveToHistory: z.boolean().optional().describe('Save scan results to history for future comparison'),
+  customRulesPath: z.string().optional().describe('Path to custom rules config file (.ios-review-rules.json)'),
+  changedSince: z.string().optional().describe('Git ref to compare against for incremental scanning'),
+});
+
+export type AnalyzeInput = z.infer<typeof AnalyzeInputSchema>;
+
+/**
+ * Analyzer interface that all analyzers must implement
+ */
+export interface Analyzer {
+  /** Unique name of the analyzer */
+  name: string;
+  /** Description of what the analyzer checks */
+  description: string;
+  /** Run the analysis on a project */
+  analyze(project: XcodeProject, options?: AnalyzerOptions): Promise<AnalysisResult>;
+}
+
+export interface AnalyzerOptions {
+  /** Specific target to analyze */
+  targetName?: string | undefined;
+  /** Base path for resolving relative paths */
+  basePath: string;
+  /** Bundle ID for ASC validation (auto-detected from project if not provided) */
+  bundleId?: string | undefined;
+  /** List of changed files for incremental scanning */
+  changedFiles?: string[] | undefined;
+}

package/tests/analyzer.test.ts

@@ -0,0 +1,142 @@
+import type { ProgressEvent } from '../src/progress/types.js';
+
+// Mock the Xcode project parser
+jest.mock('../src/parsers/xcodeproj.js', () => ({
+  parseXcodeProject: jest.fn().mockResolvedValue({
+    path: '/test/TestApp.xcodeproj',
+    name: 'TestApp',
+    targets: [
+      {
+        name: 'TestApp',
+        type: 'application',
+        bundleIdentifier: 'com.test.app',
+        deploymentTarget: '15.0',
+        sourceFiles: [],
+      },
+    ],
+    configurations: ['Debug', 'Release'],
+  }),
+}));
+
+// Mock the git module
+jest.mock('../src/git/diff.js', () => ({
+  getChangedFiles: jest.fn().mockReturnValue([]),
+}));
+
+// Mock the rules module
+jest.mock('../src/rules/index.js', () => ({
+  RuleLoader: jest.fn().mockImplementation(() => ({
+    loadFromProject: jest.fn().mockResolvedValue(null),
+  })),
+  CustomRuleEngine: jest.fn(),
+}));
+
+// Mock the guidelines module
+jest.mock('../src/guidelines/index.js', () => ({
+  GuidelineMatcher: jest.fn().mockImplementation(() => ({
+    enrichReport: jest.fn().mockImplementation((report) => ({
+      ...report,
+      score: 85,
+      enrichedIssues: [],
+      guidelinesCited: [],
+    })),
+  })),
+}));
+
+// Use require to avoid dynamic import issues with jest
+const { runAnalysis } = require('../src/analyzer.js') as typeof import('../src/analyzer.js');
+
+describe('runAnalysis', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should run all core analyzers by default', async () => {
+    const report = await runAnalysis({
+      projectPath: '/test/TestApp.xcodeproj',
+    });
+
+    // Should have results from all 8 core analyzers
+    expect(report.results.length).toBe(8);
+  });
+
+  it('should run specific analyzers when specified', async () => {
+    const report = await runAnalysis({
+      projectPath: '/test/TestApp.xcodeproj',
+      analyzers: ['code', 'security'],
+    });
+
+    expect(report.results.length).toBe(2);
+    const analyzerNames = report.results.map((r) => r.analyzer);
+    expect(analyzerNames).toContain('Code Scanner');
+    expect(analyzerNames).toContain('Security Analyzer');
+  });
+
+  it('should calculate summary correctly', async () => {
+    const report = await runAnalysis({
+      projectPath: '/test/TestApp.xcodeproj',
+      analyzers: ['code'],
+    });
+
+    expect(report.summary).toBeDefined();
+    expect(typeof report.summary.totalIssues).toBe('number');
+    expect(typeof report.summary.errors).toBe('number');
+    expect(typeof report.summary.warnings).toBe('number');
+    expect(typeof report.summary.info).toBe('number');
+    expect(typeof report.summary.passed).toBe('boolean');
+    expect(typeof report.summary.duration).toBe('number');
+  });
+
+  it('should report progress when callback provided', async () => {
+    const events: ProgressEvent[] = [];
+    await runAnalysis(
+      { projectPath: '/test/TestApp.xcodeproj', analyzers: ['code'] },
+      { onProgress: (e: ProgressEvent) => events.push(e) }
+    );
+
+    const types = events.map((e) => e.type);
+    expect(types).toContain('scan:start');
+    expect(types).toContain('analyzer:start');
+    expect(types).toContain('analyzer:complete');
+    expect(types).toContain('scan:complete');
+  });
+
+  it('should handle analyzer failures gracefully', async () => {
+    const report = await runAnalysis({
+      projectPath: '/test/TestApp.xcodeproj',
+    });
+
+    expect(report).toBeDefined();
+    expect(report.summary).toBeDefined();
+  });
+
+  it('should enrich report with score', async () => {
+    const report = await runAnalysis({
+      projectPath: '/test/TestApp.xcodeproj',
+      analyzers: ['code'],
+    });
+
+    expect(report.score).toBeDefined();
+    expect(typeof report.score).toBe('number');
+  });
+
+  it('should set passed to true when no errors', async () => {
+    const report = await runAnalysis({
+      projectPath: '/test/TestApp.xcodeproj',
+      analyzers: ['code'],
+    });
+
+    // With mocked empty project, code scanner should find no issues
+    expect(report.summary.passed).toBe(true);
+  });
+
+  it('should include timestamp', async () => {
+    const report = await runAnalysis({
+      projectPath: '/test/TestApp.xcodeproj',
+      analyzers: ['code'],
+    });
+
+    expect(report.timestamp).toBeDefined();
+    expect(typeof report.timestamp).toBe('string');
+  });
+});