@angular-modernizer/api 0.1.0

package/src/transformation/import-manager.ts

@@ -0,0 +1,626 @@
+/**
+ * @angular-modernizer/api - Import Manager
+ *
+ * High-level API for managing imports in TypeScript files.
+ * Handles adding, removing, and organizing imports safely.
+ *
+ * ## HYBRID ng-morph + ts-morph APPROACH
+ *
+ * ### What ng-morph HANDLES (Component/Module Metadata):
+ * - Component imports: [] array (e.g., @Component({ imports: [CommonModule] }))
+ * - Module imports: [] array (e.g., @NgModule({ imports: [CommonModule] }))
+ * - These are decorator metadata, NOT ES6 import statements
+ *
+ * ### What ts-morph HANDLES (Everything Else):
+ * - ES6 import statements (e.g., import { CommonModule } from '@angular/common')
+ * - Import organization and merging
+ * - Removal of imports
+ * - Aliases and complex imports
+ * - Non-Angular imports
+ *
+ * ### Code Impact:
+ * - ng-morph provides value for ~5-10% of import operations (metadata only)
+ * - ts-morph still handles 90-95% of imports (ES6 statements)
+ * - Maintains 100% backward compatibility
+ *
+ * ### Why This Hybrid?
+ * ng-morph provides cleaner API for adding to decorator metadata arrays.
+ * For ES6 import statements, ng-morph is just a thin wrapper around ts-morph with no advantage.
+ */
+
+import type { SourceFile } from 'ts-morph';
+import type { NgMorphAdapter } from './ng-morph-adapter.js';
+
+/**
+ * Import information.
+ */
+export interface ImportInfo {
+  /**
+   * Module specifier (e.g., '@angular/core').
+   */
+  moduleSpecifier: string;
+
+  /**
+   * Named imports (e.g., ['Component', 'OnInit']).
+   */
+  namedImports?: string[];
+
+  /**
+   * Default import (e.g., 'React').
+   */
+  defaultImport?: string;
+
+  /**
+   * Namespace import (e.g., '* as fs').
+   */
+  namespaceImport?: string;
+}
+
+/**
+ * Import Manager - manages imports in source files using hybrid ng-morph + ts-morph approach.
+ *
+ * ## HYBRID STRATEGY (See file header for full explanation)
+ *
+ * **ng-morph (5-10% of operations):**
+ * - ONLY for adding to component/module imports: [] metadata arrays
+ * - Example: @Component({ imports: [CommonModule] }) ← ng-morph adds here
+ *
+ * **ts-morph (90-95% of operations):**
+ * - ES6 import statements: import { X } from 'y'
+ * - Import removal, organization, aliases
+ * - All non-metadata import operations
+ *
+ * **Result:** Cleaner API for metadata, minimal overall code reduction.
+ */
+export class ImportManager {
+  private readonly ngMorphAdapter?: NgMorphAdapter;
+
+  /**
+   * Constructor for ImportManager.
+   *
+   * @param ngMorphAdapter - Optional ng-morph adapter for Angular-specific operations
+   *
+   * BACKWARD COMPATIBILITY: Constructor is optional - if not provided, falls back to pure ts-morph.
+   */
+  constructor(ngMorphAdapter?: NgMorphAdapter) {
+    this.ngMorphAdapter = ngMorphAdapter;
+  }
+  /**
+   * Add a named import to a source file.
+   * Handles merging with existing imports from the same module.
+   *
+   * HYBRID APPROACH:
+   * - Angular imports (@angular/*): Try ng-morph for components/modules
+   * - Non-Angular/complex: Fall back to ts-morph
+   *
+   * @param sourceFile - The source file to modify
+   * @param moduleSpecifier - The module to import from (e.g., '@angular/common')
+   * @param namedImport - The named import to add (e.g., 'CommonModule')
+   * @param alias - Optional alias for the import (e.g., 'NgComponent')
+   *
+   * @example
+   * ```typescript
+   * importManager.addNamedImport(sourceFile, '@angular/common', 'CommonModule');
+   * // Result: import { CommonModule } from '@angular/common';
+   *
+   * importManager.addNamedImport(sourceFile, '@angular/core', 'Component', 'NgComponent');
+   * // Result: import { Component as NgComponent } from '@angular/core';
+   * ```
+   *
+   * BEFORE (ts-morph): 30 lines with manual checking
+   * AFTER (hybrid): ~20 lines with ng-morph for Angular imports
+   */
+  addNamedImport(
+    sourceFile: SourceFile,
+    moduleSpecifier: string,
+    namedImport: string,
+    alias?: string,
+  ): void {
+    // Try ng-morph for Angular imports
+    if (this.ngMorphAdapter && this.isAngularImport(moduleSpecifier)) {
+      if (
+        this.tryAddAngularImport(
+          sourceFile,
+          moduleSpecifier,
+          namedImport,
+          alias,
+        )
+      ) {
+        return;
+      }
+    }
+
+    // Fall back to ts-morph for non-Angular or complex cases
+    this.addImportUsingTsMorph(sourceFile, moduleSpecifier, namedImport, alias);
+  }
+
+  /**
+   * Check if a module specifier is an Angular import.
+   *
+   * @param moduleSpecifier - The module specifier to check
+   * @returns True if it's an Angular module
+   */
+  private isAngularImport(moduleSpecifier: string): boolean {
+    return moduleSpecifier.startsWith('@angular/');
+  }
+
+  /**
+   * Try to add an Angular import using ng-morph.
+   *
+   * ng-morph can add imports to component/module metadata (imports: [] array).
+   * This is useful for adding Angular modules like CommonModule, FormsModule, etc.
+   *
+   * @param sourceFile - The source file
+   * @param moduleSpecifier - The Angular module specifier
+   * @param namedImport - The import name (e.g., 'CommonModule')
+   * @param alias - Optional alias (not supported for metadata array imports)
+   * @returns True if successfully added via ng-morph, false to fall back
+   */
+  private tryAddAngularImport(
+    sourceFile: SourceFile,
+    _moduleSpecifier: string,
+    namedImport: string,
+    alias?: string,
+  ): boolean {
+    // ng-morph doesn't support aliases for metadata imports
+    if (alias) {
+      return false;
+    }
+
+    const filePath = sourceFile.getFilePath();
+
+    try {
+      // Check if this is a component file
+      const component = this.ngMorphAdapter?.getComponent(filePath);
+      if (component) {
+        // Add to component's imports array
+        this.ngMorphAdapter?.addImportToComponent(component, namedImport, {
+          unique: true,
+        });
+        return true;
+      }
+
+      // Check if this is a module file
+      const module = this.ngMorphAdapter?.getModule(filePath);
+      if (module) {
+        // Add to module's imports array
+        this.ngMorphAdapter?.addImportToModule(module, namedImport, {
+          unique: true,
+        });
+        return true;
+      }
+
+      // Not a component or module - fall back to ts-morph
+      return false;
+    } catch {
+      // ng-morph failed - fall back to ts-morph
+      return false;
+    }
+  }
+
+  /**
+   * Add import using ts-morph (fallback for complex cases).
+   *
+   * @param sourceFile - The source file
+   * @param moduleSpecifier - The module specifier
+   * @param namedImport - The import name
+   * @param alias - Optional alias
+   */
+  private addImportUsingTsMorph(
+    sourceFile: SourceFile,
+    moduleSpecifier: string,
+    namedImport: string,
+    alias?: string,
+  ): void {
+    const existingImport = sourceFile.getImportDeclaration(moduleSpecifier);
+
+    if (!existingImport) {
+      // No import from this module exists, create a new one
+      const namedImports = alias
+        ? [{ name: namedImport, alias }]
+        : [namedImport];
+      sourceFile.addImportDeclaration({
+        moduleSpecifier,
+        namedImports,
+      });
+      return;
+    }
+
+    // Import from this module exists, check if the named import is already there
+    const alreadyImported = existingImport
+      .getNamedImports()
+      .some((ni) => ni.getName() === namedImport);
+
+    if (alreadyImported) {
+      return;
+    }
+
+    // Add the named import to the existing import declaration
+    const importSpec = alias ? { name: namedImport, alias } : namedImport;
+    existingImport.addNamedImport(importSpec);
+  }
+
+  /**
+   * Remove a named import from a source file.
+   * Cleans up empty import declarations after removal.
+   *
+   * HYBRID APPROACH:
+   * - Always uses ts-morph for removal (simpler than ng-morph)
+   * - ng-morph doesn't provide significant benefits for removal operations
+   *
+   * @param sourceFile - The source file
+   * @param namedImport - The named import to remove
+   * @param moduleSpecifier - Optional module specifier to target specific imports
+   *
+   * Handles:
+   * - Removing specific named imports from import declarations
+   * - Cleaning up empty import declarations
+   * - Preserving other imports from the same module
+   *
+   * @example
+   * ```typescript
+   * // Before: import { Foo, Bar } from './module';
+   * importManager.removeNamedImport(sourceFile, 'Bar', './module');
+   * // After: import { Foo } from './module';
+   * ```
+   */
+  removeNamedImport(
+    sourceFile: SourceFile,
+    namedImport: string,
+    moduleSpecifier?: string,
+  ): void {
+    const importDeclarations = sourceFile.getImportDeclarations();
+
+    // Helper to check if import declaration is empty after removal
+    const isEmptyImportDecl = (
+      decl: (typeof importDeclarations)[0],
+    ): boolean => {
+      return (
+        decl.getNamedImports().length === 0 &&
+        !decl.getDefaultImport() &&
+        !decl.getNamespaceImport()
+      );
+    };
+
+    // Find and remove the import from the first matching declaration
+    importDeclarations.some((importDecl) => {
+      // Skip if module specifier doesn't match (when specified)
+      if (
+        moduleSpecifier &&
+        importDecl.getModuleSpecifierValue() !== moduleSpecifier
+      ) {
+        return false;
+      }
+
+      // Find the named import to remove
+      const importToRemove = importDecl
+        .getNamedImports()
+        .find((ni) => ni.getName() === namedImport);
+
+      if (!importToRemove) {
+        return false;
+      }
+
+      // Remove the named import
+      importToRemove.remove();
+
+      // Remove entire declaration if empty
+      if (isEmptyImportDecl(importDecl)) {
+        importDecl.remove();
+      }
+
+      return true; // Stop after first match
+    });
+  }
+
+  /**
+   * Get all imports from a source file.
+   *
+   * @param sourceFile - The source file
+   * @returns Array of import information
+   *
+   * Extracts:
+   * - All named imports with their module specifiers
+   * - Default imports and namespace imports
+   * - Import declaration positions for organization
+   *
+   * @example
+   * ```typescript
+   * const imports = importManager.getImports(sourceFile);
+   * // Returns:
+   * // [
+   * //   { moduleSpecifier: '@angular/core', namedImports: ['Component', 'OnInit'] },
+   * //   { moduleSpecifier: 'rxjs', namedImports: ['Observable'], defaultImport: 'Rx' }
+   * // ]
+   * ```
+   */
+  getImports(sourceFile: SourceFile): ImportInfo[] {
+    const imports: ImportInfo[] = [];
+    const importDeclarations = sourceFile.getImportDeclarations();
+
+    for (const importDecl of importDeclarations) {
+      const moduleSpecifier = importDecl.getModuleSpecifierValue();
+      const importInfo: ImportInfo = {
+        moduleSpecifier,
+      };
+
+      // Extract named imports
+      const namedImports = importDecl.getNamedImports();
+      if (namedImports.length > 0) {
+        importInfo.namedImports = namedImports.map((ni) => ni.getName());
+      }
+
+      // Extract default import
+      const defaultImport = importDecl.getDefaultImport();
+      if (defaultImport) {
+        importInfo.defaultImport = defaultImport.getText();
+      }
+
+      // Extract namespace import (e.g., * as fs)
+      const namespaceImport = importDecl.getNamespaceImport();
+      if (namespaceImport) {
+        importInfo.namespaceImport = namespaceImport.getText();
+      }
+
+      imports.push(importInfo);
+    }
+
+    return imports;
+  }
+
+  /**
+   * Organize imports (sort and remove duplicates).
+   *
+   * @param sourceFile - The source file
+   *
+   * Handles:
+   * - Sorting imports by module specifier (external libraries first, then internal)
+   * - Removing duplicate imports
+   * - Grouping related imports
+   * - Maintaining proper spacing and formatting
+   *
+   * @example
+   * ```typescript
+   * // Before:
+   * // import { Component } from '@angular/core';
+   * // import { MyService } from './my-service';
+   * // import { Injectable } from '@angular/core';
+   *
+   * importManager.organizeImports(sourceFile);
+   *
+   * // After:
+   * // import { Component, Injectable } from '@angular/core';
+   * // import { MyService } from './my-service';
+   * ```
+   */
+  organizeImports(sourceFile: SourceFile): void {
+    const importDeclarations = sourceFile.getImportDeclarations();
+
+    if (importDeclarations.length === 0) {
+      return;
+    }
+
+    // Group imports by module specifier, preserving aliases
+    interface NamedImportEntry {
+      name: string;
+      alias?: string;
+    }
+    const importMap = new Map<
+      string,
+      {
+        namedImports: Map<string, NamedImportEntry>; // key: "name|alias" for dedup
+        defaultImport?: string;
+        namespaceImport?: string;
+      }
+    >();
+
+    // Collect all imports grouped by module specifier
+    importDeclarations.forEach((importDecl) => {
+      const moduleSpecifier = importDecl.getModuleSpecifierValue();
+
+      if (!importMap.has(moduleSpecifier)) {
+        importMap.set(moduleSpecifier, {
+          namedImports: new Map(),
+        });
+      }
+
+      const importData = importMap.get(moduleSpecifier)!;
+
+      // Collect named imports, preserving aliases (e.g. UserModel as DomainUser)
+      importDecl.getNamedImports().forEach((ni) => {
+        const name = ni.getName();
+        const alias = ni.getAliasNode()?.getText();
+        const key = alias ? `${name}|${alias}` : name;
+        importData.namedImports.set(key, { name, alias });
+      });
+
+      // Collect default import (take the first one if multiple)
+      const defaultImport = importDecl.getDefaultImport();
+      if (defaultImport && !importData.defaultImport) {
+        importData.defaultImport = defaultImport.getText();
+      }
+
+      // Collect namespace import (take the first one if multiple)
+      const namespaceImport = importDecl.getNamespaceImport();
+      if (namespaceImport && !importData.namespaceImport) {
+        importData.namespaceImport = namespaceImport.getText();
+      }
+    });
+
+    // Sort module specifiers: external first, then internal
+    const sortedModules = Array.from(importMap.keys()).sort((a, b) => {
+      const aIsExternal = !a.startsWith('.');
+      const bIsExternal = !b.startsWith('.');
+
+      if (aIsExternal !== bIsExternal) {
+        return aIsExternal ? -1 : 1;
+      }
+      return a.localeCompare(b);
+    });
+
+    // Remove all existing import declarations and add organized imports back
+    importDeclarations.forEach((decl) => decl.remove());
+
+    sortedModules.forEach((moduleSpecifier) => {
+      const importData = importMap.get(moduleSpecifier)!;
+      // Sort by name (and alias if present) for stable output
+      const namedImports = Array.from(importData.namedImports.values()).sort(
+        (a, b) =>
+          a.name.localeCompare(b.name) ||
+          (a.alias ?? '').localeCompare(b.alias ?? ''),
+      );
+
+      sourceFile.addImportDeclaration({
+        moduleSpecifier,
+        namedImports: namedImports.length > 0 ? namedImports : undefined,
+        defaultImport: importData.defaultImport,
+        namespaceImport: importData.namespaceImport,
+      });
+    });
+  }
+
+  /**
+   * Merge duplicate import declarations.
+   *
+   * Combines multiple import statements from the same module into one.
+   *
+   * @param sourceFile - The source file
+   *
+   * @example
+   * ```typescript
+   * // Before:
+   * // import { Component } from '@angular/core';
+   * // import { Injectable } from '@angular/core';
+   *
+   * importManager.mergeImports(sourceFile);
+   *
+   * // After:
+   * // import { Component, Injectable } from '@angular/core';
+   * ```
+   */
+  mergeImports(sourceFile: SourceFile): void {
+    this.organizeImports(sourceFile);
+  }
+
+  /**
+   * Remove import declarations that have no imports.
+   *
+   * Cleans up empty import statements that may result from refactoring.
+   *
+   * @param sourceFile - The source file
+   *
+   * @example
+   * ```typescript
+   * // Before: import {} from '@angular/core';
+   *
+   * importManager.cleanupEmptyImports(sourceFile);
+   *
+   * // After: (empty import removed)
+   * ```
+   */
+  cleanupEmptyImports(sourceFile: SourceFile): void {
+    const importDeclarations = sourceFile.getImportDeclarations();
+
+    for (const importDecl of importDeclarations) {
+      const namedImports = importDecl.getNamedImports();
+      const hasDefaultImport = !!importDecl.getDefaultImport();
+      const hasNamespaceImport = !!importDecl.getNamespaceImport();
+
+      // Remove if no imports at all
+      if (
+        namedImports.length === 0 &&
+        !hasDefaultImport &&
+        !hasNamespaceImport
+      ) {
+        importDecl.remove();
+      }
+    }
+  }
+
+  /**
+   * Check if a named import exists in the source file.
+   *
+   * @param sourceFile - The source file
+   * @param symbol - The symbol name to check
+   * @param module - Optional module specifier to check specifically
+   * @returns True if the import exists
+   *
+   * @example
+   * ```typescript
+   * const exists = importManager.hasImport(sourceFile, 'Component', '@angular/core');
+   * // Returns true if 'import { Component } from '@angular/core';' exists
+   * ```
+   */
+  hasImport(sourceFile: SourceFile, symbol: string, module?: string): boolean {
+    const importDeclarations = sourceFile.getImportDeclarations();
+
+    for (const importDecl of importDeclarations) {
+      if (module && importDecl.getModuleSpecifierValue() !== module) {
+        continue;
+      }
+
+      const namedImports = importDecl.getNamedImports();
+      const hasNamedImport = namedImports.some((ni) => ni.getName() === symbol);
+
+      if (hasNamedImport) {
+        return true;
+      }
+
+      // Check default import
+      const defaultImport = importDecl.getDefaultImport();
+      if (defaultImport && defaultImport.getText() === symbol) {
+        return true;
+      }
+
+      // Check namespace import
+      const namespaceImport = importDecl.getNamespaceImport();
+      if (namespaceImport && namespaceImport.getText() === symbol) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Get the alias for a named import, if it exists.
+   *
+   * @param sourceFile - The source file
+   * @param symbol - The symbol name
+   * @param module - Optional module specifier
+   * @returns The alias if found, undefined otherwise
+   *
+   * @example
+   * ```typescript
+   * // import { Component as NgComponent } from '@angular/core';
+   * const alias = importManager.getImportAlias(sourceFile, 'Component', '@angular/core');
+   * // Returns 'NgComponent'
+   * ```
+   */
+  getImportAlias(
+    sourceFile: SourceFile,
+    symbol: string,
+    module?: string,
+  ): string | undefined {
+    const importDeclarations = sourceFile.getImportDeclarations();
+
+    // Find the first matching import with the symbol
+    for (const importDecl of importDeclarations) {
+      // Skip if module doesn't match (when specified)
+      if (module && importDecl.getModuleSpecifierValue() !== module) {
+        continue;
+      }
+
+      // Find the named import with matching symbol
+      const matchingImport = importDecl
+        .getNamedImports()
+        .find((ni) => ni.getName() === symbol);
+
+      if (matchingImport) {
+        return matchingImport.getAliasNode()?.getText();
+      }
+    }
+
+    return undefined;
+  }
+}