@angular-modernizer/api 0.1.0

package/src/analysis/external-template-loader.ts

@@ -0,0 +1,79 @@
+/**
+ * @angular-modernizer/api - External Template Loader
+ *
+ * Loads external Angular templates from templateUrl.
+ *
+ * Philosophy: "Support Both Inline and External"
+ * - Handles templateUrl: './component.html'
+ * - Resolves relative paths correctly
+ * - Graceful fallback on errors
+ */
+
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+
+/**
+ * External Template Loader - Loads templates from templateUrl.
+ *
+ * Supports both relative and absolute template paths.
+ */
+export class ExternalTemplateLoader {
+  /**
+   * Load external template file.
+   *
+   * Handles templateUrl: './user.component.html'
+   *
+   * @param templateUrl - Template URL from `` metadata
+   * @param componentPath - Absolute path to the component file
+   * @returns Template content or empty string on error
+   */
+  async loadExternalTemplate(
+    templateUrl: string,
+    componentPath: string,
+  ): Promise<string> {
+    // Resolve template path relative to component
+    const templatePath = path.resolve(path.dirname(componentPath), templateUrl);
+
+    try {
+      return await fs.readFile(templatePath, 'utf-8');
+    } catch (error: unknown) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      console.warn(`    Failed to load template: ${templatePath}`);
+      console.warn(`    Error: ${errorMessage}`);
+      return ''; // Conservative: no template = include all imports
+    }
+  }
+
+  /**
+   * Check if a template path exists.
+   *
+   * @param templateUrl - Template URL from `` metadata
+   * @param componentPath - Absolute path to the component file
+   * @returns True if template file exists
+   */
+  async templateExists(
+    templateUrl: string,
+    componentPath: string,
+  ): Promise<boolean> {
+    const templatePath = path.resolve(path.dirname(componentPath), templateUrl);
+
+    try {
+      await fs.access(templatePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Resolve template path from component path and templateUrl.
+   *
+   * @param templateUrl - Template URL from `` metadata
+   * @param componentPath - Absolute path to the component file
+   * @returns Absolute path to template file
+   */
+  resolveTemplatePath(templateUrl: string, componentPath: string): string {
+    return path.resolve(path.dirname(componentPath), templateUrl);
+  }
+}

package/src/analysis/selector-mapper.ts

@@ -0,0 +1,186 @@
+/**
+ * @angular-modernizer/api - Selector Mapper
+ *
+ * Reusable selector-to-className mapping utility.
+ * Extracted from Phase 3's selector map caching for reuse across components.
+ *
+ * Philosophy: "Build Once, Use Everywhere"
+ * - O(n) initial build, O(1) lookups
+ * - Lazy initialization (only builds when first needed)
+ * - Universal coverage (standard `` + custom decorators)
+ */
+
+import type {
+  ClassDeclaration,
+  Decorator,
+  Project,
+  ObjectLiteralExpression,
+} from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+
+/**
+ * Selector Mapper - Maps component selectors to class names.
+ *
+ * Provides O(1) selector lookups using a cached map built from project files.
+ * Supports both standard `` decorators and custom decorators (e.g., ``).
+ */
+export class SelectorMapper {
+  private selectorMap: Map<string, string> | undefined;
+
+  /**
+   * Find a component class name by its selector.
+   *
+   * Builds the selector map lazily on first call, then reuses for O(1) lookups.
+   *
+   * @param project - ts-morph Project
+   * @param selector - Component selector (e.g., 'app-user-profile')
+   * @returns Class name (e.g., 'UserProfileComponent') or undefined if not found
+   */
+  findComponentBySelector(
+    project: Project,
+    selector: string,
+  ): string | undefined {
+    // Build selector map lazily on first use
+    this.selectorMap ??= this.buildSelectorMap(project);
+
+    // O(1) lookup in cached map
+    return this.selectorMap.get(selector);
+  }
+
+  /**
+   * Get the complete selector map.
+   *
+   * Builds the map lazily if not yet built.
+   *
+   * @param project - ts-morph Project
+   * @returns Map of selector → className
+   */
+  getSelectorMap(project: Project): Map<string, string> {
+    this.selectorMap ??= this.buildSelectorMap(project);
+    return this.selectorMap;
+  }
+
+  /**
+   * Clear the cached selector map.
+   *
+   * Useful for testing or when project files have changed significantly.
+   */
+  clearCache(): void {
+    this.selectorMap = undefined;
+  }
+
+  /**
+   * Build a comprehensive selector map for the entire project.
+   *
+   * Scans all source files once to build selector → className mapping.
+   * Performance: O(n) initial build, O(1) lookup per selector.
+   *
+   * @param project - ts-morph Project
+   * @returns Map of selector → className
+   * @private
+   */
+  private buildSelectorMap(project: Project): Map<string, string> {
+    const selectorMap = new Map<string, string>();
+    const sourceFiles = project.getSourceFiles();
+
+    for (const sourceFile of sourceFiles) {
+      // Skip node_modules and test files for performance
+      const filePath = sourceFile.getFilePath();
+      if (
+        filePath.includes('node_modules') ||
+        filePath.includes('.spec.ts') ||
+        filePath.includes('.d.ts')
+      ) {
+        continue;
+      }
+
+      const classes = sourceFile.getClasses();
+
+      for (const classDecl of classes) {
+        const className = classDecl.getName();
+        if (!className) {
+          continue;
+        }
+
+        // Check if this class has a @Component decorator
+        // (regardless of other decorators like @ExportComponent)
+        const componentDecorator = this.findDecorator(classDecl, 'Component');
+
+        if (componentDecorator) {
+          // Extract selector from @Component metadata
+          const selector =
+            this.extractSelectorFromDecorator(componentDecorator);
+
+          if (selector) {
+            // Add to map: selector → className
+            selectorMap.set(selector, className);
+          }
+        }
+      }
+    }
+
+    return selectorMap;
+  }
+
+  /**
+   * Extract the selector from a `` decorator.
+   *
+   * @param decorator - The `` decorator
+   * @returns The selector string or undefined
+   * @private
+   */
+  private extractSelectorFromDecorator(
+    decorator: Decorator,
+  ): string | undefined {
+    const args = decorator.getArguments();
+    if (args.length === 0) {
+      return undefined;
+    }
+
+    const metadataObj = args[0];
+    if (
+      !metadataObj ||
+      metadataObj.getKind() !== SyntaxKind.ObjectLiteralExpression
+    ) {
+      return undefined;
+    }
+
+    const objLiteral = metadataObj as ObjectLiteralExpression;
+    const selectorProperty = objLiteral.getProperty('selector');
+
+    if (selectorProperty) {
+      const initializer = selectorProperty.getChildAtIndex(2); // Skip name and colon
+      const text = initializer.getText();
+      // Remove quotes if present
+      return text.replaceAll(/^['"`]|['"`]$/g, '');
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Find a decorator by name on a class declaration.
+   *
+   * Supports both standard decorators (``) and custom decorators (``).
+   *
+   * @param classDecl - Class declaration
+   * @param decoratorName - Decorator name (without @)
+   * @returns Decorator or undefined
+   * @private
+   */
+  private findDecorator(
+    classDecl: ClassDeclaration,
+    decoratorName: string,
+  ): Decorator | undefined {
+    const decorators = classDecl.getDecorators();
+
+    for (const decorator of decorators) {
+      const name = decorator.getName();
+      if (name === decoratorName) {
+        return decorator;
+      }
+    }
+
+    return undefined;
+  }
+}

package/src/analysis/service-detector.ts

@@ -0,0 +1,280 @@
+/**
+ * @angular-modernizer/api - Service Detector
+ *
+ * Centralized service detection API with caching and bulk operations.
+ * Single source of truth for service detection across all analysis rules.
+ *
+ * ARCHITECTURE:
+ * - Wraps ServicePatternRecognizer for consistent detection
+ * - Provides caching to avoid redundant AST traversal
+ * - Supports bulk detection for performance
+ * - Used by all analysis rules that need service detection
+ */
+
+import type { SourceFile, ClassDeclaration } from 'ts-morph';
+import type { ServicePatternRecognizer, ServiceDetectionResult } from './service-pattern-recognizer.js';
+
+/**
+ * Bulk detection result for multiple classes.
+ */
+export interface BulkDetectionResult {
+  /** Map of class name to detection result */
+  results: Map<string, ServiceDetectionResult>;
+
+  /** Total number of services detected */
+  serviceCount: number;
+
+  /** Total number of classes analyzed */
+  totalCount: number;
+
+  /** Detection time in milliseconds */
+  detectionTimeMs: number;
+}
+
+/**
+ * ServiceDetector - Centralized service detection with caching.
+ *
+ * SINGLE SOURCE OF TRUTH:
+ * - All analysis rules should use this detector
+ * - Ensures consistent service detection across rules
+ * - Provides performance optimization through caching
+ *
+ * USAGE:
+ * ```typescript
+ * const detector = new ServiceDetector(recognizer);
+ *
+ * // Single detection
+ * const result = detector.detectService(classDecl);
+ *
+ * // Bulk detection
+ * const bulk = detector.detectServicesInFile(sourceFile);
+ *
+ * // Cache management
+ * detector.clearCache();
+ * ```
+ */
+export class ServiceDetector {
+  private readonly recognizer: ServicePatternRecognizer;
+  private readonly cache: Map<string, ServiceDetectionResult>;
+
+  /**
+   * Create a new ServiceDetector.
+   *
+   * @param recognizer - ServicePatternRecognizer instance
+   */
+  constructor(recognizer: ServicePatternRecognizer) {
+    this.recognizer = recognizer;
+    this.cache = new Map();
+  }
+
+  /**
+   * Detect if a class is a service with caching.
+   *
+   * Results are cached by file path + class name for performance.
+   *
+   * @param classDecl - The class declaration to analyze
+   * @returns Service detection result with confidence
+   *
+   * @example
+   * ```typescript
+   * const result = detector.detectService(classDecl);
+   * if (result.isService && result.confidence >= 0.7) {
+   *   console.info(`High confidence service detected via ${result.detectionMethod}`);
+   * }
+   * ```
+   */
+  detectService(classDecl: ClassDeclaration): ServiceDetectionResult {
+    const cacheKey = this.getCacheKey(classDecl);
+
+    // Check cache first
+    const cached = this.cache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    // Detect and cache result
+    const result = this.recognizer.detectService(classDecl);
+    this.cache.set(cacheKey, result);
+
+    return result;
+  }
+
+  /**
+   * Simple check if a class is a service (cached).
+   *
+   * @param classDecl - The class declaration to check
+   * @returns True if detected as service
+   */
+  isService(classDecl: ClassDeclaration): boolean {
+    return this.detectService(classDecl).isService;
+  }
+
+  /**
+   * Detect all services in a source file (bulk operation).
+   *
+   * More efficient than detecting each class individually.
+   *
+   * @param sourceFile - The source file to analyze
+   * @returns Bulk detection result with statistics
+   *
+   * @example
+   * ```typescript
+   * const bulk = detector.detectServicesInFile(sourceFile);
+   * console.info(`Found ${bulk.serviceCount} services in ${bulk.detectionTimeMs}ms`);
+   *
+   * for (const [className, result] of bulk.results) {
+   *   if (result.isService) {
+   *     console.info(`${className}: ${result.detectionMethod} (${result.confidence})`);
+   *   }
+   * }
+   * ```
+   */
+  detectServicesInFile(sourceFile: SourceFile): BulkDetectionResult {
+    const startTime = Date.now();
+    const results = new Map<string, ServiceDetectionResult>();
+    const classes = sourceFile.getClasses();
+
+    let serviceCount = 0;
+
+    for (const classDecl of classes) {
+      const className = classDecl.getName();
+      if (!className) {
+        continue;
+      }
+
+      const result = this.detectService(classDecl);
+      results.set(className, result);
+
+      if (result.isService) {
+        serviceCount++;
+      }
+    }
+
+    const endTime = Date.now();
+
+    return {
+      results,
+      serviceCount,
+      totalCount: classes.length,
+      detectionTimeMs: endTime - startTime,
+    };
+  }
+
+  /**
+   * Detect services in multiple source files (bulk operation).
+   *
+   * @param sourceFiles - Array of source files to analyze
+   * @returns Bulk detection result with combined statistics
+   *
+   * @example
+   * ```typescript
+   * const files = project.getSourceFiles();
+   * const bulk = detector.detectServicesInFiles(files);
+   * console.info(`Found ${bulk.serviceCount} services across ${files.length} files`);
+   * ```
+   */
+  detectServicesInFiles(sourceFiles: SourceFile[]): BulkDetectionResult {
+    const startTime = Date.now();
+    const results = new Map<string, ServiceDetectionResult>();
+
+    let serviceCount = 0;
+    let totalCount = 0;
+
+    for (const sourceFile of sourceFiles) {
+      const fileResult = this.detectServicesInFile(sourceFile);
+
+      // Merge results with class name prefixed by file path for uniqueness
+      const filePath = sourceFile.getFilePath();
+      for (const [className, result] of fileResult.results) {
+        const key = `${filePath}:${className}`;
+        results.set(key, result);
+      }
+
+      serviceCount += fileResult.serviceCount;
+      totalCount += fileResult.totalCount;
+    }
+
+    const endTime = Date.now();
+
+    return {
+      results,
+      serviceCount,
+      totalCount,
+      detectionTimeMs: endTime - startTime,
+    };
+  }
+
+  /**
+   * Filter classes to only services.
+   *
+   * @param classes - Array of class declarations
+   * @returns Array of service class declarations
+   *
+   * @example
+   * ```typescript
+   * const allClasses = sourceFile.getClasses();
+   * const services = detector.filterServices(allClasses);
+   * console.info(`Found ${services.length} services out of ${allClasses.length} classes`);
+   * ```
+   */
+  filterServices(classes: ClassDeclaration[]): ClassDeclaration[] {
+    return classes.filter((cls) => this.isService(cls));
+  }
+
+  /**
+   * Get detection statistics from cache.
+   *
+   * @returns Statistics about cached detections
+   */
+  getCacheStatistics(): {
+    totalEntries: number;
+    serviceEntries: number;
+    nonServiceEntries: number;
+  } {
+    let serviceEntries = 0;
+    let nonServiceEntries = 0;
+
+    for (const result of this.cache.values()) {
+      if (result.isService) {
+        serviceEntries++;
+      } else {
+        nonServiceEntries++;
+      }
+    }
+
+    return {
+      totalEntries: this.cache.size,
+      serviceEntries,
+      nonServiceEntries,
+    };
+  }
+
+  /**
+   * Clear the detection cache.
+   *
+   * Call this when the AST has been modified and cached results
+   * may be stale.
+   *
+   * @example
+   * ```typescript
+   * // After modifying files
+   * await project.save();
+   * detector.clearCache();
+   * ```
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache key for a class declaration.
+   *
+   * @param classDecl - The class declaration
+   * @returns Cache key string
+   */
+  private getCacheKey(classDecl: ClassDeclaration): string {
+    const filePath = classDecl.getSourceFile().getFilePath();
+    const className = classDecl.getName() ?? 'anonymous';
+    return `${filePath}:${className}`;
+  }
+}