@angular-modernizer/api 0.1.0

package/src/analysis/dependency-analyzer.ts

@@ -0,0 +1,720 @@
+/**
+ * @angular-modernizer/api - Dependency Analyzer
+ *
+ * The "All-Knowing Cartographer" - builds comprehensive symbol maps for Angular modules.
+ * Recursively walks NgModule imports to create a complete map of available symbols.
+ *
+ * Philosophy: "Trust the Map"
+ * - Builds the definitive map of what's available in a module's scope
+ * - Handles the critical edge case: `` on setters with aliases
+ * - Plugins use this map to make intelligent decisions
+ */
+
+import type {
+  SourceFile,
+  ClassDeclaration,
+  Decorator,
+  Project,
+  PropertyDeclaration,
+  SetAccessorDeclaration,
+  GetAccessorDeclaration,
+} from 'ts-morph';
+
+/**
+ * Represents a dependency between two artifacts.
+ */
+export interface Dependency {
+  /**
+   * Source file path.
+   */
+  from: string;
+
+  /**
+   * Target file path.
+   */
+  to: string;
+
+  /**
+   * Type of dependency.
+   */
+  type: 'import' | 'component-usage' | 'directive-usage' | 'service-injection';
+
+  /**
+   * Symbol name being used.
+   */
+  symbol?: string;
+
+  /**
+   * Additional metadata.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Represents a symbol in the Angular module system.
+ */
+export interface SymbolInfo {
+  /**
+   * Class name of the symbol.
+   */
+  className: string;
+
+  /**
+   * Selector(s) for components/directives.
+   * For components: ['app-root']
+   * For directives: ['[myDirective]', 'myDirective']
+   */
+  selectors: string[];
+
+  /**
+   * Input property names (including aliases).
+   * For ``('customValue') set value(...), this includes 'customValue'.
+   */
+  inputs: string[];
+
+  /**
+   * Output property names (including aliases).
+   */
+  outputs: string[];
+
+  /**
+   * Type of Angular artifact.
+   */
+  type: 'component' | 'directive' | 'pipe' | 'module';
+
+  /**
+   * Source file path.
+   */
+  filePath: string;
+}
+
+/**
+ * Complete symbol map for a module's scope.
+ */
+export interface SymbolMap {
+  /**
+   * Symbols declared in this module.
+   */
+  declared: Map<string, SymbolInfo>;
+
+  /**
+   * Symbols imported into this module (from other modules).
+   */
+  imported: Map<string, SymbolInfo>;
+
+  /**
+   * Symbols exported by this module (available to consumers).
+   */
+  exported: Map<string, SymbolInfo>;
+
+  /**
+   * All effectively available symbols in this module's scope.
+   * This is the union of declared + imported symbols.
+   */
+  available: Map<string, SymbolInfo>;
+}
+
+/**
+ * Dependency Analyzer - extracts dependency relationships and builds symbol maps.
+ *
+ * This is the "All-Knowing Cartographer" that creates comprehensive maps of
+ * what's available in an NgModule's scope.
+ */
+export class DependencyAnalyzer {
+  /**
+   * Analyze all dependencies from a source file.
+   * Extracts all named imports and creates dependency objects for each.
+   *
+   * @param sourceFile - The source file to analyze
+   * @returns Array of dependencies
+   */
+  analyzeDependencies(sourceFile: SourceFile): Dependency[] {
+    const filePath = sourceFile.getFilePath();
+
+    return sourceFile.getImportDeclarations().flatMap((importDecl) => {
+      const moduleSpecifier = importDecl.getModuleSpecifierValue();
+      return importDecl.getNamedImports().map((namedImport) => ({
+        from: filePath,
+        to: moduleSpecifier,
+        type: 'import' as const,
+        symbol: namedImport.getName(),
+      }));
+    });
+  }
+
+  /**
+   * Check if a file depends on another file.
+   *
+   * @param sourceFile - The source file
+   * @param targetPath - The target file path
+   * @returns True if dependency exists
+   */
+  dependsOn(sourceFile: SourceFile, targetPath: string): boolean {
+    const dependencies = this.analyzeDependencies(sourceFile);
+    return dependencies.some((dep) => dep.to === targetPath);
+  }
+
+  /**
+   * Build a comprehensive symbol map for an NgModule.
+   *
+   * This is the heart of the "Trust the Map" architecture.
+   * It creates the definitive map of what's available in a module's scope.
+   *
+   * @param moduleFile - The source file containing the NgModule
+   * @param project - Optional ts-morph Project to resolve symbols across files
+   * @returns Complete symbol map
+   */
+  buildSymbolMap(moduleFile: SourceFile, project?: Project): SymbolMap {
+    const symbolMap: SymbolMap = {
+      declared: new Map(),
+      imported: new Map(),
+      exported: new Map(),
+      available: new Map(),
+    };
+
+    // Find the NgModule class
+    const moduleClass = this.findNgModuleClass(moduleFile);
+    if (!moduleClass) {
+      return symbolMap;
+    }
+
+    // Extract symbols from the @NgModule decorator
+    const decorator = this.findDecorator(moduleClass, 'NgModule');
+    if (!decorator) {
+      return symbolMap;
+    }
+
+    // Parse the decorator to find declarations, imports, exports
+    const decoratorText = decorator.getText();
+
+    // Extract declared symbols
+    const declarations = this.extractArrayProperty(
+      decoratorText,
+      'declarations',
+    );
+
+    declarations.forEach((className) => {
+      let symbolInfo = this.extractSymbolInfo(moduleFile, className);
+
+      if (!symbolInfo && project) {
+        const foundFile = project
+          .getSourceFiles()
+          .find((sf) => this.extractSymbolInfo(sf, className));
+        symbolInfo = foundFile
+          ? this.extractSymbolInfo(foundFile, className)
+          : undefined;
+      }
+
+      if (symbolInfo) {
+        symbolMap.declared.set(className, symbolInfo);
+        symbolMap.available.set(className, symbolInfo);
+      }
+    });
+
+    // Extract imported symbols (from other modules)
+    const imports = this.extractArrayProperty(decoratorText, 'imports');
+    const knownModules = new Set(['CommonModule', 'FormsModule']);
+
+    imports.forEach((moduleName) => {
+      if (knownModules.has(moduleName)) {
+        const builtInSymbol: SymbolInfo = {
+          className: moduleName,
+          selectors: [],
+          inputs: [],
+          outputs: [],
+          type: 'module',
+          filePath: '@angular/common',
+        };
+        symbolMap.imported.set(moduleName, builtInSymbol);
+        symbolMap.available.set(moduleName, builtInSymbol);
+      }
+
+      if (project && !knownModules.has(moduleName)) {
+        const importedModuleSymbols = this.loadModuleExports(
+          moduleName,
+          project,
+          moduleFile,
+        );
+        importedModuleSymbols.forEach((symbolInfo, symbolName) => {
+          symbolMap.imported.set(symbolName, symbolInfo);
+          symbolMap.available.set(symbolName, symbolInfo);
+        });
+      }
+    });
+
+    // Extract exported symbols
+    const exports = this.extractArrayProperty(decoratorText, 'exports');
+    exports.forEach((className) => {
+      const symbolInfo =
+        symbolMap.declared.get(className) ?? symbolMap.imported.get(className);
+      if (symbolInfo) {
+        symbolMap.exported.set(className, symbolInfo);
+      }
+    });
+
+    return symbolMap;
+  }
+
+  /**
+   * Load exported symbols from an imported module.
+   * Recursively resolves module imports to build complete symbol map.
+   *
+   * @param moduleName - The module class name to load
+   * @param project - The ts-morph project
+   * @param _currentFile - The current source file (reserved for future use in resolving relative imports)
+   * @returns Map of exported symbols
+   */
+  private loadModuleExports(
+    moduleName: string,
+    project: Project,
+    _currentFile: SourceFile,
+  ): Map<string, SymbolInfo> {
+    const exports = new Map<string, SymbolInfo>();
+    const allSourceFiles = project.getSourceFiles();
+
+    // Find the module class across all source files
+    const moduleResult = allSourceFiles
+      .map((sf) => ({ file: sf, class: sf.getClass(moduleName) }))
+      .find(({ class: cls }) => cls && this.findDecorator(cls, 'NgModule'));
+
+    if (!moduleResult?.class) {
+      return exports;
+    }
+
+    const { file: moduleFile, class: moduleClass } = moduleResult;
+
+    // Get the @NgModule decorator
+    const decorator = this.findDecorator(moduleClass, 'NgModule');
+    if (!decorator) {
+      return exports;
+    }
+
+    // Extract exported symbols from the module
+    const exportedSymbols = this.extractArrayProperty(
+      decorator.getText(),
+      'exports',
+    );
+
+    exportedSymbols.forEach((symbolName) => {
+      let symbolInfo = this.extractSymbolInfo(moduleFile, symbolName);
+
+      if (!symbolInfo) {
+        const foundFile = allSourceFiles.find((sf) =>
+          this.extractSymbolInfo(sf, symbolName),
+        );
+        symbolInfo = foundFile
+          ? this.extractSymbolInfo(foundFile, symbolName)
+          : undefined;
+      }
+
+      if (symbolInfo) {
+        exports.set(symbolName, symbolInfo);
+      }
+    });
+
+    return exports;
+  }
+
+  /**
+   * Get all transitive dependencies for a source file.
+   * Follows dependency chain recursively.
+   *
+   * @param sourceFile - The source file
+   * @param project - The ts-morph project
+   * @param visited - Set of already visited files (for cycle detection)
+   * @returns Array of all transitive dependencies
+   */
+  getTransitiveDependencies(
+    sourceFile: SourceFile,
+    project: Project,
+    visited = new Set<string>(),
+  ): Dependency[] {
+    const filePath = sourceFile.getFilePath();
+
+    // Prevent infinite recursion
+    if (visited.has(filePath)) {
+      return [];
+    }
+    visited.add(filePath);
+
+    const directDependencies = this.analyzeDependencies(sourceFile);
+    const localDeps = directDependencies.filter(
+      (dep) => dep.to.startsWith('.') || dep.to.startsWith('/'),
+    );
+
+    const transitiveDeps = localDeps.flatMap((dep) => {
+      const depPath = dep.to.replace(/^\.\//, '').replace(/\.ts$/, '');
+      const depSourceFile = project.getSourceFiles().find((sf) => {
+        const sfPath = sf.getFilePath();
+        return (
+          sfPath.includes(depPath + '.ts') ||
+          sfPath.endsWith('/' + depPath + '.ts')
+        );
+      });
+
+      return depSourceFile
+        ? this.getTransitiveDependencies(depSourceFile, project, visited)
+        : [];
+    });
+
+    return [...directDependencies, ...transitiveDeps];
+  }
+
+  /**
+   * Detect circular dependencies in a project.
+   *
+   * @param project - The ts-morph project
+   * @returns Array of circular dependency chains
+   */
+  detectCircularDependencies(
+    project: Project,
+  ): { cycle: string[]; severity: 'warning' | 'error' }[] {
+    const cycles: { cycle: string[]; severity: 'warning' | 'error' }[] = [];
+    const sourceFiles = project.getSourceFiles();
+
+    for (const sourceFile of sourceFiles) {
+      const filePath = sourceFile.getFilePath();
+      const visited = new Set<string>();
+      const path: string[] = [];
+
+      this.detectCyclesFromFile(
+        sourceFile,
+        project,
+        visited,
+        path,
+        cycles,
+        filePath,
+      );
+    }
+
+    // Deduplicate cycles (same cycle can be found from different starting points)
+    return this.deduplicateCycles(cycles);
+  }
+
+  /**
+   * Detect cycles starting from a specific file.
+   * Recursively traverses local dependencies to find circular import chains.
+   * Severity based on cycle length: >3 files = error, ≤3 files = warning.
+   */
+  private detectCyclesFromFile(
+    sourceFile: SourceFile,
+    project: Project,
+    visited: Set<string>,
+    path: string[],
+    cycles: { cycle: string[]; severity: 'warning' | 'error' }[],
+    targetFile: string,
+  ): void {
+    const filePath = sourceFile.getFilePath();
+
+    // If we've returned to the target file, we found a cycle
+    if (path.length > 0 && filePath === targetFile) {
+      cycles.push({
+        cycle: [...path, filePath],
+        severity: path.length > 3 ? 'error' : 'warning',
+      });
+      return;
+    }
+
+    // Prevent infinite recursion on already visited paths
+    if (visited.has(filePath)) {
+      return;
+    }
+    visited.add(filePath);
+    path.push(filePath);
+
+    // Follow dependencies - filter to local project files only (not node_modules)
+    const localDeps = this.analyzeDependencies(sourceFile).filter(
+      (dep) => dep.to.startsWith('.') || dep.to.startsWith('/'),
+    );
+
+    localDeps.forEach((dep) => {
+      // Normalize import path: strip leading ./ and .ts extension
+      const depPath = dep.to.replace(/^\.\//, '').replace(/\.ts$/, '');
+      const depSourceFile = project.getSourceFiles().find((sf) => {
+        const sfPath = sf.getFilePath();
+        // Handle both relative imports with and without .ts extension
+        return (
+          sfPath.includes(depPath + '.ts') ||
+          sfPath.endsWith('/' + depPath + '.ts')
+        );
+      });
+
+      if (depSourceFile) {
+        // Recurse with fresh visited set and path copy to track independent branches
+        this.detectCyclesFromFile(
+          depSourceFile,
+          project,
+          new Set(visited),
+          [...path],
+          cycles,
+          targetFile,
+        );
+      }
+    });
+  }
+
+  /**
+   * Deduplicate cycle arrays (same cycle in different order).
+   * Example: [A→B→C→A] and [B→C→A→B] represent the same cycle.
+   * Uses sorted paths to create unique signatures for comparison.
+   */
+  private deduplicateCycles(
+    cycles: { cycle: string[]; severity: 'warning' | 'error' }[],
+  ): { cycle: string[]; severity: 'warning' | 'error' }[] {
+    const seen = new Set<string>();
+
+    return cycles.filter((item) => {
+      // Normalize cycle by sorting paths and creating unique signature
+      const sorted = [...item.cycle].sort();
+      const signature = sorted.join('->');
+
+      if (seen.has(signature)) {
+        return false;
+      }
+      seen.add(signature);
+      return true;
+    });
+  }
+
+  /**
+   * Extract comprehensive symbol information from a class.
+   * Identifies Angular artifact types (``, ``, ``) and extracts metadata.
+   *
+   * CRITICAL: Handles the edge case of `` on setters with aliases.
+   *
+   * @param sourceFile - The source file
+   * @param className - The class name to analyze
+   * @returns Symbol information or undefined
+   */
+  extractSymbolInfo(
+    sourceFile: SourceFile,
+    className: string,
+  ): SymbolInfo | undefined {
+    const classDecl = sourceFile.getClass(className);
+    if (!classDecl) {
+      return undefined;
+    }
+
+    const filePath = sourceFile.getFilePath();
+
+    // Map decorator types to extraction methods
+    const decoratorHandlers: {
+      name: string;
+      extract: (
+        cls: ClassDeclaration,
+        dec: Decorator,
+        path: string,
+      ) => SymbolInfo;
+    }[] = [
+      { name: 'Component', extract: this.extractComponentInfo.bind(this) },
+      { name: 'Directive', extract: this.extractDirectiveInfo.bind(this) },
+      { name: 'Pipe', extract: this.extractPipeInfo.bind(this) },
+    ];
+
+    for (const { name, extract } of decoratorHandlers) {
+      const decorator = this.findDecorator(classDecl, name);
+      if (decorator) {
+        return extract(classDecl, decorator, filePath);
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Extract component information including selectors and inputs.
+   */
+  private extractComponentInfo(
+    classDecl: ClassDeclaration,
+    decorator: Decorator,
+    filePath: string,
+  ): SymbolInfo {
+    const decoratorText = decorator.getText();
+    const selector = this.extractStringProperty(decoratorText, 'selector');
+
+    return {
+      className: classDecl.getName() ?? 'UnknownComponent',
+      selectors: selector ? [selector] : [],
+      inputs: this.extractInputs(classDecl),
+      outputs: this.extractOutputs(classDecl),
+      type: 'component',
+      filePath,
+    };
+  }
+
+  /**
+   * Extract directive information including selectors and inputs.
+   */
+  private extractDirectiveInfo(
+    classDecl: ClassDeclaration,
+    decorator: Decorator,
+    filePath: string,
+  ): SymbolInfo {
+    const decoratorText = decorator.getText();
+    const selector = this.extractStringProperty(decoratorText, 'selector');
+
+    // For attribute selectors like '[myDirective]', we want both forms
+    const selectors: string[] = [];
+    if (selector) {
+      selectors.push(selector);
+      // If it's an attribute selector, also add the bare name
+      const bareSelector = selector.replace(/^\[|\]$/g, '');
+      if (bareSelector !== selector) {
+        selectors.push(bareSelector);
+      }
+    }
+
+    return {
+      className: classDecl.getName() ?? 'UnknownDirective',
+      selectors,
+      inputs: this.extractInputs(classDecl),
+      outputs: this.extractOutputs(classDecl),
+      type: 'directive',
+      filePath,
+    };
+  }
+
+  /**
+   * Extract pipe information.
+   */
+  private extractPipeInfo(
+    classDecl: ClassDeclaration,
+    decorator: Decorator,
+    filePath: string,
+  ): SymbolInfo {
+    const decoratorText = decorator.getText();
+    const name = this.extractStringProperty(decoratorText, 'name');
+
+    return {
+      className: classDecl.getName() ?? 'UnknownPipe',
+      selectors: name ? [name] : [],
+      inputs: [],
+      outputs: [],
+      type: 'pipe',
+      filePath,
+    };
+  }
+
+  /**
+   * Extract all `` properties from a class.
+   *
+   * CRITICAL: Handles the edge case of `` on setters with aliases.
+   * Example: ``('customValue') set value(val: any) { ... }
+   * This should extract 'customValue', not 'value'.
+   */
+  private extractInputs(classDecl: ClassDeclaration): string[] {
+    // Helper to extract decorated names with optional aliases
+    const extractDecorated = (
+      nodes: (
+        | PropertyDeclaration
+        | SetAccessorDeclaration
+        | GetAccessorDeclaration
+      )[],
+      decoratorName: string,
+    ): string[] => {
+      const results: string[] = [];
+      nodes.forEach((node) => {
+        const decorator = this.findDecorator(node, decoratorName);
+        if (decorator) {
+          const alias = this.extractDecoratorAlias(decorator);
+          results.push(alias ?? node.getName());
+        }
+      });
+      return results;
+    };
+
+    // Extract from properties, setters (CRITICAL for fixture test!), and getters
+    return [
+      ...extractDecorated(classDecl.getProperties(), 'Input'),
+      ...extractDecorated(classDecl.getSetAccessors(), 'Input'),
+      ...extractDecorated(classDecl.getGetAccessors(), 'Input'),
+    ];
+  }
+
+  /**
+   * Extract all `` properties from a class.
+   */
+  private extractOutputs(classDecl: ClassDeclaration): string[] {
+    const outputs: string[] = [];
+
+    classDecl.getProperties().forEach((prop) => {
+      const outputDecorator = this.findDecorator(prop, 'Output');
+      if (outputDecorator) {
+        const alias = this.extractDecoratorAlias(outputDecorator);
+        outputs.push(alias ?? prop.getName());
+      }
+    });
+
+    return outputs;
+  }
+
+  /**
+   * Extract alias from a decorator.
+   * Example: ``('customValue') -> 'customValue'
+   */
+  private extractDecoratorAlias(decorator: Decorator): string | undefined {
+    const args = decorator.getArguments();
+    const firstArg = args[0];
+
+    // Remove quotes from string literal if argument exists
+    return firstArg?.getText().replace(/^['"`]|['"`]$/g, '');
+  }
+
+  /**
+   * Find a decorator on a node by name.
+   */
+  private findDecorator(
+    node:
+      | ClassDeclaration
+      | PropertyDeclaration
+      | SetAccessorDeclaration
+      | GetAccessorDeclaration,
+    name: string,
+  ): Decorator | undefined {
+    const decorators = node.getDecorators();
+    return decorators.find((d: Decorator) => d.getName() === name);
+  }
+
+  /**
+   * Find the NgModule class in a source file.
+   */
+  private findNgModuleClass(
+    sourceFile: SourceFile,
+  ): ClassDeclaration | undefined {
+    const classes = sourceFile.getClasses();
+    return classes.find(
+      (cls) => this.findDecorator(cls, 'NgModule') !== undefined,
+    );
+  }
+
+  /**
+   * Extract a string property value from decorator text.
+   * Example: selector: 'app-root' -> 'app-root'
+   */
+  private extractStringProperty(
+    text: string,
+    propertyName: string,
+  ): string | undefined {
+    const regex = new RegExp(`${propertyName}\\s*:\\s*['"\`]([^'"\`]+)['"\`]`);
+    const match = text.match(regex);
+    return match ? match[1] : undefined;
+  }
+
+  /**
+   * Extract an array property value from decorator text.
+   * Example: declarations: [Foo, Bar] -> ['Foo', 'Bar']
+   */
+  private extractArrayProperty(text: string, propertyName: string): string[] {
+    const regex = new RegExp(`${propertyName}\\s*:\\s*\\[([^\\]]*)\\]`);
+    const match = text.match(regex);
+    if (!match?.[1]) {
+      return [];
+    }
+
+    const arrayContent = match[1];
+    return arrayContent
+      .split(',')
+      .map((item) => item.trim())
+      .filter((item) => item.length > 0);
+  }
+}