Project Migration

/**
 * Migrates existing projects to TypeScript support
 * Handles dependency updates and Vue version-specific transformations
 * @param api - Migrator API instance providing project modification methods
 * @param options - Migration configuration options
 * @param rootOptions - Root project options including Vue version information
 */
function migrator(api, options: any, rootOptions: RootOptions): void;

interface RootOptions {
  vueVersion?: number;         // Vue major version (2 or 3)
  [key: string]: any;          // Additional project configuration
}

// Applied automatically during Vue CLI plugin migration
const migrator = require('@vue/cli-plugin-typescript/migrator');

// Called during project upgrade or migration
migrator(api, {}, { vueVersion: 3 });

/**
 * Dependency configuration for migration
 * Ensures TypeScript is added without version conflicts
 */
const migrationDependencies = {
  devDependencies: {
    typescript: string  // Version from plugin's package.json
  }
};

// Installation options
const installOptions = {
  warnIncompatibleVersions: false  // Suppress version warnings during migration
};

/**
 * Vue 3 specific migration logic
 * Updates Vue component type declarations for Vue 3 compatibility
 */
if (rootOptions.vueVersion === 3) {
  // Apply Vue 3 component type migration
  api.transformScript('src/shims-vue.d.ts', codemod);
}

/**
 * Component type migration using AST transformations
 * Updates outdated Vue 3 component type patterns
 * @param filePath - Path to the file being transformed
 * @param codemod - JSCodeshift transformation function
 */
api.transformScript(
  'src/shims-vue.d.ts', 
  require('../codemods/migrateComponentType')
);

/**
 * Migrates Vue 3 component type definitions from outdated patterns
 * Transforms ReturnType<typeof defineComponent> to DefineComponent
 * @param file - File AST and source information
 * @param api - JSCodeshift API instance
 * @returns Transformed source code
 */
function migrateComponentType(file, api): string;

// Before migration (outdated pattern)
declare module '*.vue' {
  import { defineComponent } from 'vue';
  const component: ReturnType<typeof defineComponent>;
  export default component;
}

// After migration (current pattern)  
declare module '*.vue' {
  import { DefineComponent } from 'vue';
  const component: DefineComponent<{}, {}, any>;
  export default component;
}

/**
 * AST transformation configuration for component type migration
 * Identifies and replaces specific TypeScript type patterns
 */
const transformationConfig = {
  // Target pattern: ReturnType<typeof defineComponent>
  targetPattern: {
    typeName: { name: 'ReturnType' },
    typeParameters: {
      params: [{
        exprName: { name: 'defineComponent' }
      }]
    }
  },
  
  // Replacement pattern: DefineComponent<{}, {}, any>
  replacementPattern: {
    typeName: 'DefineComponent',
    typeParameters: ['{}', '{}', 'any']
  }
};

/**
 * Import statement management during component type migration
 * Updates Vue imports to include DefineComponent type
 */
const importManagement = {
  // Add DefineComponent to existing Vue imports
  addImport: 'DefineComponent',
  
  // Remove unused defineComponent import (if no other usage)
  removeUnusedImport: 'defineComponent'
};

/**
 * Parser configuration for TypeScript file transformations
 * Ensures proper TypeScript AST parsing
 */
migrateComponentType.parser = 'ts';

/**
 * Code formatting preservation during transformation
 * Maintains original code style and formatting preferences
 */
const formattingConfig = {
  lineTerminator: '\n',        // Preserve line endings
  quote: 'single' | 'double'   // Detect and preserve quote style
};

/**
 * Import usage detection for safe transformations
 * Prevents removal of imports that are still needed
 */
const usageDetection = {
  // Find all references to defineComponent
  findUsages: (ast, identifier) => {
    // Filter out import/export statements
    // Return actual usage locations
  },
  
  // Safe to remove import if no usages found
  canRemoveImport: boolean
};

// Input file (src/shims-vue.d.ts)
declare module '*.vue' {
  import { defineComponent } from 'vue';
  const component: ReturnType<typeof defineComponent>;
  export default component;
}

// Output after migration
declare module '*.vue' {
  import { DefineComponent } from 'vue';
  const component: DefineComponent<{}, {}, any>;
  export default component;
}

// Before - defineComponent not used elsewhere
import { defineComponent } from 'vue';

// After - defineComponent removed, DefineComponent added
import { DefineComponent } from 'vue';

// Migration only applies to specific patterns
// Files without target pattern remain unchanged
if (componentDecl.length !== 1) {
  return file.source; // No changes made
}