Diagnostics

/**
 * Doctor diagnostic system with validation functions
 */
const doctor: {
  /** Array of validation functions for comprehensive project checking */
  validators: Array<(args?: any) => Promise<void> | void>;
};

import { doctor } from "@tarojs/cli";

// Access all validators
const allValidators = doctor.validators;

// Run specific validator
const envValidator = doctor.validators[0];
await envValidator();

// Run configuration validator
const configValidator = doctor.validators[1];
await configValidator({
  projectConfig: myProjectConfig,
  helper: helperUtils
});

/**
 * Environment validation - checks Node.js version, system requirements
 * @returns Promise resolving when validation completes
 */
function validateEnv(): Promise<void>;

/**
 * Configuration validation - validates Taro project configuration
 * @param projectConfig - Project configuration object
 * @param helper - Helper utilities object
 * @returns Promise resolving when validation completes
 */
function validateConfig(
  projectConfig: IProjectConfig,
  helper: HelperUtils
): Promise<void>;

/**
 * Package validation - checks dependencies and package integrity
 * @param appPath - Application root path
 * @param nodeModulesPath - Node modules directory path
 * @returns Promise resolving when validation completes
 */
function validatePackage(
  appPath: string,
  nodeModulesPath: string
): Promise<void>;

/**
 * Recommendations validation - provides optimization suggestions
 * @param appPath - Application root path
 * @returns Promise resolving when validation completes
 */
function validateRecommend(appPath: string): Promise<void>;

/**
 * ESLint validation - checks linting configuration and rules
 * @param projectConfig - Project configuration object
 * @param chalk - Chalk utility for colored output
 * @returns Promise resolving when validation completes
 */
function validateEslint(
  projectConfig: IProjectConfig,
  chalk: ChalkInstance
): Promise<void>;

/**
 * Environment diagnostic results
 */
interface EnvironmentDiagnostic {
  nodeVersion: {
    current: string;
    required: string;
    compatible: boolean;
  };
  npmVersion: {
    current: string;
    compatible: boolean;
  };
  operatingSystem: {
    platform: string;
    arch: string;
    supported: boolean;
  };
  globalPackages: {
    taroCliVersion: string;
    otherGlobalPackages: string[];
  };
}

/**
 * Configuration diagnostic results
 */
interface ConfigurationDiagnostic {
  configFile: {
    exists: boolean;
    path: string;
    syntax: 'valid' | 'invalid';
  };
  projectSettings: {
    framework: string;
    compiler: string;
    outputRoot: string;
    sourceRoot: string;
  };
  pluginConfiguration: {
    validPlugins: string[];
    invalidPlugins: string[];
    missingPlugins: string[];
  };
}

/**
 * Package diagnostic results
 */
interface PackageDiagnostic {
  dependencies: {
    missing: string[];
    outdated: Array<{
      name: string;
      current: string;
      latest: string;
    }>;
    conflicting: Array<{
      name: string;
      versions: string[];
    }>;
  };
  peerDependencies: {
    missing: string[];
    incompatible: string[];
  };
  lockFile: {
    exists: boolean;
    type: 'package-lock.json' | 'yarn.lock' | 'pnpm-lock.yaml';
  };
}

/**
 * Diagnostic result severity levels
 */
type DiagnosticSeverity = 'error' | 'warning' | 'info' | 'success';

/**
 * Individual diagnostic result
 */
interface DiagnosticResult {
  /** Diagnostic category */
  category: 'environment' | 'configuration' | 'packages' | 'recommendations' | 'eslint';
  /** Result severity */
  severity: DiagnosticSeverity;
  /** Diagnostic message */
  message: string;
  /** Detailed description */
  description?: string;
  /** Suggested fix or action */
  fix?: string;
  /** Commands to resolve the issue */
  commands?: string[];
  /** Related documentation links */
  docs?: string[];
}

/**
 * Complete diagnostic report
 */
interface DiagnosticReport {
  /** Overall health status */
  status: 'healthy' | 'warnings' | 'errors';
  /** Individual diagnostic results */
  results: DiagnosticResult[];
  /** Summary statistics */
  summary: {
    total: number;
    errors: number;
    warnings: number;
    info: number;
    success: number;
  };
  /** Execution timestamp */
  timestamp: string;
  /** Environment context */
  environment: {
    nodeVersion: string;
    taroVersion: string;
    platform: string;
  };
}

/**
 * Common environment issues detected by diagnostics
 */
interface CommonEnvironmentIssues {
  'node-version-outdated': {
    severity: 'error';
    message: 'Node.js version is outdated';
    fix: 'Update Node.js to version 18 or higher';
    commands: ['nvm install 18', 'nvm use 18'];
  };
  'missing-global-cli': {
    severity: 'warning';
    message: 'Taro CLI not installed globally';
    fix: 'Install Taro CLI globally';
    commands: ['npm install -g @tarojs/cli'];
  };
  'incompatible-npm': {
    severity: 'warning';
    message: 'npm version may cause issues';
    fix: 'Update npm to latest version';
    commands: ['npm install -g npm@latest'];
  };
}

/**
 * Common configuration issues
 */
interface CommonConfigurationIssues {
  'missing-config-file': {
    severity: 'error';
    message: 'Taro configuration file not found';
    fix: 'Create config/index.js file';
  };
  'invalid-framework': {
    severity: 'error';
    message: 'Unsupported framework specified';
    fix: 'Use supported framework: react, vue3, preact, or solid';
  };
  'missing-platform-plugin': {
    severity: 'error';
    message: 'Platform plugin not found';
    fix: 'Install required platform plugin';
  };
}

/**
 * Common package issues
 */
interface CommonPackageIssues {
  'peer-dependency-missing': {
    severity: 'error';
    message: 'Required peer dependency is missing';
    fix: 'Install missing peer dependencies';
  };
  'version-conflict': {
    severity: 'warning';
    message: 'Package version conflicts detected';
    fix: 'Resolve version conflicts in dependencies';
  };
  'outdated-dependencies': {
    severity: 'info';
    message: 'Some dependencies are outdated';
    fix: 'Update dependencies to latest versions';
  };
}

/**
 * Run all diagnostic checks
 * @param projectPath - Path to Taro project
 * @returns Complete diagnostic report
 */
function runDiagnostics(projectPath: string): Promise<DiagnosticReport>;

/**
 * Run specific diagnostic category
 * @param category - Diagnostic category to run
 * @param projectPath - Path to Taro project
 * @returns Filtered diagnostic results
 */
function runSpecificDiagnostic(
  category: DiagnosticResult['category'],
  projectPath: string
): Promise<DiagnosticResult[]>;

/**
 * Format diagnostic results for console output
 * @param report - Diagnostic report to format
 * @returns Formatted string for console display
 */
function formatDiagnosticOutput(report: DiagnosticReport): string;

/**
 * Export diagnostic results to file
 * @param report - Diagnostic report to export
 * @param outputPath - File path for export
 * @param format - Export format
 */
function exportDiagnostics(
  report: DiagnosticReport,
  outputPath: string,
  format: 'json' | 'html' | 'markdown'
): Promise<void>;

/**
 * Diagnostic configuration options
 */
interface DiagnosticConfig {
  /** Enable or disable specific diagnostic categories */
  categories?: {
    environment?: boolean;
    configuration?: boolean;
    packages?: boolean;
    recommendations?: boolean;
    eslint?: boolean;
  };
  /** Severity threshold for reporting */
  severityThreshold?: DiagnosticSeverity;
  /** Output format preferences */
  output?: {
    format: 'console' | 'json' | 'html';
    verbose?: boolean;
    colors?: boolean;
  };
  /** Include or exclude specific checks */
  checks?: {
    include?: string[];
    exclude?: string[];
  };
}

/**
 * Apply diagnostic configuration
 * @param config - Configuration options
 */
function configureDiagnostics(config: DiagnosticConfig): void;

# Run all diagnostics
taro doctor

# Run with verbose output
taro doctor --verbose

# Export results to file
taro doctor --output report.json

# Run specific category only
taro doctor --category environment

# Skip specific checks
taro doctor --exclude eslint,packages