@angular-modernizer/api 0.1.0

package/src/analysis/template-analyzer.ts

@@ -0,0 +1,208 @@
+/**
+ * @angular-modernizer/api - Template Analyzer
+ *
+ * Dumb Collector - extracts ALL elements from Angular templates.
+ * Zero filtering, zero intelligence. Based on the "Trust the Map" principle.
+ *
+ * Philosophy: "Collect Everything, Filter Later"
+ * - No business logic in collectors
+ * - Plugins decide what matters
+ * - Raw data is more valuable than pre-filtered data
+ */
+
+/**
+ * Represents a single template usage (element, directive, pipe, etc.).
+ */
+export interface TemplateUsage {
+  /**
+   * Type of usage.
+   */
+  type:
+    | 'element'
+    | 'directive'
+    | 'pipe'
+    | 'component'
+    | 'structural-directive'
+    | 'control-flow';
+
+  /**
+   * Name/selector of the element.
+   */
+  name: string;
+
+  /**
+   * Position in template (line number).
+   */
+  line?: number;
+
+  /**
+   * Position in template (column number).
+   */
+  column?: number;
+
+  /**
+   * Raw HTML/template string of this usage.
+   */
+  raw?: string;
+
+  /**
+   * Attributes/inputs on this element.
+   */
+  attributes?: Record<string, string>;
+
+  /**
+   * Additional metadata.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Template Analyzer - extracts all usages from Angular templates.
+ *
+ * This is a "Dumb Collector" that doesn't filter or interpret.
+ * It just collects everything and lets plugins decide what's important.
+ */
+export class TemplateAnalyzer {
+  /**
+   * Analyze a template string and extract all usages.
+   *
+   * @param template - The template string to analyze
+   * @returns Array of template usages
+   *
+   * Philosophy: "Collect Everything, Filter Later"
+   * - Extracts ALL elements, attributes, pipes, directives
+   * - No filtering, no business logic
+   * - Plugins decide what's important using the SymbolMapper
+   */
+  analyze(template: string): TemplateUsage[] {
+    const usages: TemplateUsage[] = [];
+    const lines = template.split('\n');
+
+    // Extract element tags (e.g., <fixture-child>, <div>, <custom-component>)
+    const elementRegex = /<([a-zA-Z][\w-]*)/g;
+
+    // Extract pipes (e.g., {{ value | pipeName }}, {{ value | pipeName: arg }})
+    const pipeRegex = /\|\s*([a-zA-Z]\w*)/g;
+
+    lines.forEach((line, lineIndex) => {
+      // Extract elements
+      let match: RegExpExecArray | null;
+      while ((match = elementRegex.exec(line)) !== null) {
+        const tagName = match[1];
+        if (tagName) {
+          usages.push({
+            type: 'element',
+            name: tagName,
+            line: lineIndex + 1,
+            column: match.index,
+            raw: match[0],
+          });
+        }
+      }
+
+      // Extract attributes - use multiple patterns for better coverage
+
+      // Pattern 1: Structural directives (*ngIf, *ngFor)
+      const structuralDirectiveRegex = /\*([a-zA-Z][\w-]*)/g;
+      while ((match = structuralDirectiveRegex.exec(line)) !== null) {
+        usages.push({
+          type: 'structural-directive',
+          name: `*${match[1]}`,
+          line: lineIndex + 1,
+          column: match.index,
+          raw: match[0],
+        });
+      }
+
+      // Pattern 2: Angular 17+ control flow (@if, @for, @switch, @empty, @let)
+      const controlFlowRegex =
+        /@(if|else if|for|switch|case|default|empty|let)\b/g;
+      while ((match = controlFlowRegex.exec(line)) !== null) {
+        usages.push({
+          type: 'control-flow',
+          name: match[1]!,
+          line: lineIndex + 1,
+          column: match.index,
+          raw: match[0],
+        });
+      }
+
+      // Pattern 3: Property bindings ([propName]="value")
+      const propertyBindingRegex = /\[([a-zA-Z][\w-]*)\]/g;
+      while ((match = propertyBindingRegex.exec(line)) !== null) {
+        usages.push({
+          type: 'directive',
+          name: `[${match[1]}]`,
+          line: lineIndex + 1,
+          column: match.index,
+          raw: match[0],
+        });
+      }
+
+      // Pattern 3: Bare attribute selectors (fixtureAttribute, ngModel)
+      // Look for attribute names that are NOT standard HTML attributes
+      const bareAttributeRegex =
+        /\s+([a-z][\w-]*(?:[A-Z][\w-]*)+)\s*(?:=|>|\s|$)/g;
+      while ((match = bareAttributeRegex.exec(line)) !== null) {
+        const attrName = match[1];
+        // Only add if it looks like a directive (has camelCase or kebab-case)
+        if (attrName && (attrName.includes('-') || /[A-Z]/.test(attrName))) {
+          usages.push({
+            type: 'directive',
+            name: attrName,
+            line: lineIndex + 1,
+            column: match.index,
+            raw: match[0].trim(),
+          });
+        }
+      }
+
+      // Extract pipes
+      const pipeMatches = line.matchAll(pipeRegex);
+      for (const pipeMatch of pipeMatches) {
+        const pipeName = pipeMatch[1];
+        if (pipeName) {
+          usages.push({
+            type: 'pipe',
+            name: pipeName,
+            line: lineIndex + 1,
+            column: pipeMatch.index,
+            raw: pipeMatch[0],
+          });
+        }
+      }
+    });
+
+    return usages;
+  }
+
+  /**
+   * Extract inline template from component decorator.
+   *
+   * @param decoratorText - The `` decorator text
+   * @returns The template string or undefined
+   */
+  extractInlineTemplate(decoratorText: string): string | undefined {
+    // Match template: `...` or template: '...' (including multiline)
+    const templateRegex = /template\s*:\s*(['`])([\s\S]*?)\1/;
+    const match = templateRegex.exec(decoratorText);
+
+    if (match) {
+      return match[2];
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Check if a template uses a specific selector.
+   *
+   * @param template - The template string
+   * @param selector - The selector to search for
+   * @returns True if selector is used
+   */
+  usesSelector(template: string, selector: string): boolean {
+    const usages = this.analyze(template);
+    return usages.some((usage) => usage.name === selector);
+  }
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Main entry point for @angular-modernizer/api
+ */
+
+export * from './public-api.js';
+export * from './transformation/ng-morph-adapter.js';
+export * from './transformation/ngmodule-manager.js';
+export * from './transformation/import-manager.js';
+export * from './analysis/service-pattern-recognizer.js';
+export * from './analysis/service-detector.js';
+export type { ServiceDetectionResult } from './analysis/service-pattern-recognizer.js';
+export * from './analysis/dependency-analyzer.js';
+export * from './analysis/template-analyzer.js';
+export * from './analysis/template-analyzer-usage.js';
+export * from './analysis/selector-mapper.js';
+export * from './analysis/external-template-loader.js';
+export {
+  SymbolLocator,
+  type SymbolInfo as ProjectSymbolInfo,
+} from './analysis/symbol-locator.js';
+export {
+  StackTraceParser,
+  type StackFrame,
+} from './investigation/stack-trace-parser.js';
+export {
+  UsageFinder,
+  type SymbolUsage,
+  type UsageType,
+  type FindUsagesOptions,
+} from './investigation/usage-finder.js';
+export {
+  CallGraphBuilder,
+  type CallNode,
+  type CallGraphOptions,
+  type CallGraphResult,
+} from './investigation/call-graph-builder.js';
+export {
+  TypeResolver,
+  type ResolvedTypeInfo,
+} from './investigation/type-resolver.js';
+export {
+  AngularSymbolFinder,
+  type AngularSymbolResult,
+  type AngularSymbolType,
+} from './investigation/angular-symbol-finder.js';
+export {
+  CodebaseSearcher,
+  type SearchResult,
+  type SearchOptions,
+  type SymbolKind,
+} from './investigation/codebase-searcher.js';

package/src/investigation/angular-symbol-finder.ts

@@ -0,0 +1,263 @@
+/**
+ * @angular-modernizer/api - Angular Symbol Finder
+ *
+ * Finds Angular symbols (components, directives, pipes, services, guards,
+ * interceptors, resolvers, modules, tokens) by selector, template name, class
+ * name, or token name. Supports standard Angular decorators as well as
+ * ngUWI-specific external decorators (@ExportComponent, @ExportFunction).
+ *
+ * @remarks
+ * The project must already have the relevant source files added before calling
+ * `findSymbol`. Queries are matched case-sensitively for class names, and
+ * substring-matched for selectors/pipe names (e.g. searching "app-list" also
+ * returns "app-list-item" selectors).
+ *
+ * @example
+ * ```typescript
+ * const finder = new AngularSymbolFinder(project);
+ * const results = finder.findSymbol('app-user');
+ * // results[0] → { file, className, angularType: 'component', selector: 'app-user', metadata: {...} }
+ *
+ * const pipes = finder.findSymbol('dateFormat', 'pipe');
+ * // pipes[0] → { file, className: 'DateFormatPipe', angularType: 'pipe', pipeName: 'dateFormat', metadata: {...} }
+ * ```
+ */
+
+import type { Project, ClassDeclaration, Decorator } from 'ts-morph';
+
+/** The Angular symbol type classification. */
+export type AngularSymbolType =
+  | 'component'
+  | 'directive'
+  | 'pipe'
+  | 'service'
+  | 'guard'
+  | 'interceptor'
+  | 'resolver'
+  | 'module'
+  | 'token';
+
+/** A resolved Angular symbol. */
+export interface AngularSymbolResult {
+  /** Absolute file path containing the class. */
+  file: string;
+
+  /** Class name (e.g. `UserComponent`). */
+  className: string;
+
+  /** Angular symbol type. */
+  angularType: AngularSymbolType;
+
+  /** CSS selector for components and directives (stripped of brackets). */
+  selector?: string;
+
+  /** Template name for pipes (value of `@Pipe({ name: '...' })`). */
+  pipeName?: string;
+
+  /** Raw decorator metadata (key-value pairs extracted from the decorator). */
+  metadata: Record<string, string>;
+}
+
+/** Decorator names that map to Angular symbol types. */
+const DECORATOR_TYPE_MAP: Record<string, AngularSymbolType> = {
+  Component: 'component',
+  ExportComponent: 'component',
+  Directive: 'directive',
+  Pipe: 'pipe',
+  Injectable: 'service',
+  ExportFunction: 'service',
+  NgModule: 'module',
+  Guard: 'guard',
+  Interceptor: 'interceptor',
+  Resolver: 'resolver',
+};
+
+/**
+ * Extracts the string value of a named property from a decorator's argument
+ * object literal (e.g. `selector: 'app-foo'` → `'app-foo'`).
+ */
+function extractDecoratorProperty(
+  decorator: Decorator,
+  property: string,
+): string | undefined {
+  try {
+    const args = decorator.getArguments();
+    if (args.length === 0) {
+      return undefined;
+    }
+    const arg = args[0];
+    if (arg === undefined) {
+      return undefined;
+    }
+    const text = arg.getText();
+    const match = new RegExp(`${property}\\s*:\\s*['"\`]([^'"\`]+)['"\`]`).exec(
+      text,
+    );
+    return match?.[1];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Extracts all string-valued properties from a decorator's first argument
+ * as a flat `Record<string, string>`.
+ */
+function extractDecoratorMetadata(
+  decorator: Decorator,
+): Record<string, string> {
+  const metadata: Record<string, string> = {};
+  try {
+    const args = decorator.getArguments();
+    const firstArg = args[0];
+    if (args.length === 0 || firstArg === undefined) {
+      return metadata;
+    }
+    const text = firstArg.getText();
+    const pattern = /(\w+)\s*:\s*['"`]([^'"`]+)['"`]/g;
+    let match: RegExpExecArray | null;
+    while ((match = pattern.exec(text)) !== null) {
+      const key = match[1];
+      const value = match[2];
+      if (key !== undefined && value !== undefined) {
+        metadata[key] = value;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return metadata;
+}
+
+/**
+ * Strips attribute-selector brackets from a selector string.
+ * `[appHighlight]` → `appHighlight`; `app-user` → `app-user`.
+ */
+function normalizeSelector(raw: string): string {
+  return raw.replace(/^\[(.+)\]$/, '$1');
+}
+
+/**
+ * Returns `true` when the query matches the given selector (substring) or
+ * class name (exact).
+ */
+function matchesQuery(
+  query: string,
+  className: string,
+  selector: string | undefined,
+  pipeName: string | undefined,
+): boolean {
+  if (className === query) {
+    return true;
+  }
+  if (selector?.includes(query)) {
+    return true;
+  }
+  if (pipeName !== undefined && pipeName === query) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Finds Angular symbols across all source files in a ts-morph `Project`.
+ */
+export class AngularSymbolFinder {
+  constructor(private readonly project: Project) {}
+
+  /**
+   * Find Angular symbols matching `query`.
+   *
+   * @param query - Selector (e.g. `app-user`, `appHighlight`), pipe name
+   *   (e.g. `dateFormat`), class name (e.g. `UserComponent`), or partial
+   *   selector substring.
+   * @param type - Optional filter; when provided only results of the given type
+   *   are returned.
+   * @returns Array of matching `AngularSymbolResult` objects, empty when none
+   *   are found.
+   *
+   * @example
+   * ```typescript
+   * // By selector
+   * finder.findSymbol('app-user');
+   *
+   * // By class name with type filter
+   * finder.findSymbol('UserService', 'service');
+   * ```
+   */
+  findSymbol(query: string, type?: AngularSymbolType): AngularSymbolResult[] {
+    const results: AngularSymbolResult[] = [];
+
+    for (const sourceFile of this.project.getSourceFiles()) {
+      for (const cls of sourceFile.getClasses()) {
+        const result = this.classifyClass(cls);
+        if (result === null) {
+          continue;
+        }
+        if (type !== undefined && result.angularType !== type) {
+          continue;
+        }
+        if (
+          matchesQuery(
+            query,
+            result.className,
+            result.selector,
+            result.pipeName,
+          )
+        ) {
+          results.push(result);
+        }
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Attempts to classify a class declaration as an Angular symbol.
+   * Returns `null` when the class carries no recognised Angular decorator.
+   */
+  private classifyClass(cls: ClassDeclaration): AngularSymbolResult | null {
+    for (const decorator of cls.getDecorators()) {
+      const decoratorName = decorator.getName();
+      const angularType = DECORATOR_TYPE_MAP[decoratorName];
+      if (angularType === undefined) {
+        continue;
+      }
+
+      const className = cls.getName() ?? '(anonymous)';
+      const file = cls.getSourceFile().getFilePath();
+      const metadata = extractDecoratorMetadata(decorator);
+
+      let selector: string | undefined;
+      let pipeName: string | undefined;
+
+      if (angularType === 'component' || angularType === 'directive') {
+        const rawSelector = extractDecoratorProperty(decorator, 'selector');
+        if (rawSelector !== undefined) {
+          selector = normalizeSelector(rawSelector);
+        }
+      }
+
+      if (angularType === 'pipe') {
+        pipeName = extractDecoratorProperty(decorator, 'name');
+      }
+
+      const result: AngularSymbolResult = {
+        file,
+        className,
+        angularType,
+        metadata,
+      };
+      if (selector !== undefined) {
+        result.selector = selector;
+      }
+      if (pipeName !== undefined) {
+        result.pipeName = pipeName;
+      }
+      return result;
+    }
+
+    return null;
+  }
+}