@angular-modernizer/api 0.1.0

package/src/investigation/stack-trace-parser.ts

@@ -0,0 +1,166 @@
+/**
+ * @angular-modernizer/api - Stack Trace Parser
+ *
+ * Parses Node.js/Angular/Zone.js/browser stack traces and maps frames to project source files.
+ *
+ * @remarks
+ * Frames are classified as project files when their resolved path starts with `projectRoot`
+ * and does not pass through `node_modules`. Browser URL frames (http/https) are always
+ * classified as non-project files regardless of origin.
+ *
+ * @example
+ * ```typescript
+ * const parser = new StackTraceParser('/my/project/src');
+ * const frames = parser.parse(error.stack ?? '');
+ * // frames[0].file → '/my/project/src/app/user.service.ts'
+ * // frames[0].isProjectFile → true
+ *
+ * const projectOnly = parser.parseProjectFrames(error.stack ?? '');
+ * ```
+ */
+
+/** A single resolved stack frame. */
+export interface StackFrame {
+  /** Absolute file path. For browser URL frames, the raw URL string. */
+  file: string;
+
+  /** 1-based line number. */
+  line: number;
+
+  /** 1-based column number. */
+  col: number;
+
+  /** Function or method name. `'<anonymous>'` when not present. */
+  functionName: string;
+
+  /**
+   * `true` when the frame's path starts with `projectRoot`
+   * and does not pass through `node_modules`.
+   */
+  isProjectFile: boolean;
+}
+
+/**
+ * Regex matching a V8-style "at" frame in the following forms:
+ *
+ * ```
+ * at FunctionName (file:line:col)
+ * at async FunctionName (file:line:col)
+ * at new FunctionName (file:line:col)
+ * at file:line:col
+ * ```
+ */
+const AT_FRAME_WITH_LOCATION =
+  /^\s*at\s+(?:async\s+)?(.+?)\s+\((.+):(\d+):(\d+)\)\s*$/;
+
+const AT_FRAME_WITHOUT_FUNCTION =
+  /^\s*at\s+((?!async\s|new\s)[^(]+):(\d+):(\d+)\s*$/;
+
+const HTTP_SCHEME = /^https?:\/\//;
+const NODE_MODULES_SEGMENT = /[/\\]node_modules[/\\]/;
+
+/**
+ * Parses Node.js/Angular/Zone.js/browser stack traces into structured frames.
+ */
+export class StackTraceParser {
+  /**
+   * @param projectRoot - Absolute path to the project root used to classify
+   *   frames as project files vs. external dependencies.
+   */
+  constructor(private readonly projectRoot: string) {}
+
+  /**
+   * Parses a raw stack trace string into an array of structured frames.
+   *
+   * @param stackTrace - Raw `Error.stack` string or console-captured stack trace.
+   * @returns All frames found, including non-project frames.
+   */
+  parse(stackTrace: string): StackFrame[] {
+    if (!stackTrace) {
+      return [];
+    }
+
+    const frames: StackFrame[] = [];
+
+    for (const line of stackTrace.split('\n')) {
+      const frame = this.parseLine(line);
+      if (frame !== null) {
+        frames.push(frame);
+      }
+    }
+
+    return frames;
+  }
+
+  /**
+   * Parses a stack trace and returns only frames that belong to the project.
+   *
+   * @param stackTrace - Raw `Error.stack` string or console-captured stack trace.
+   * @returns Frames where `isProjectFile` is `true`.
+   */
+  parseProjectFrames(stackTrace: string): StackFrame[] {
+    return this.parse(stackTrace).filter((f) => f.isProjectFile);
+  }
+
+  private parseLine(line: string): StackFrame | null {
+    const withFunc = AT_FRAME_WITH_LOCATION.exec(line);
+    if (withFunc !== null) {
+      const [, functionName, file, lineStr, colStr] = withFunc;
+      return this.buildFrame(
+        this.sanitizeFunctionName(functionName ?? ''),
+        file ?? '',
+        Number(lineStr),
+        Number(colStr),
+      );
+    }
+
+    const withoutFunc = AT_FRAME_WITHOUT_FUNCTION.exec(line);
+    if (withoutFunc !== null) {
+      const [, file, lineStr, colStr] = withoutFunc;
+      return this.buildFrame(
+        '<anonymous>',
+        file ?? '',
+        Number(lineStr),
+        Number(colStr),
+      );
+    }
+
+    return null;
+  }
+
+  private buildFrame(
+    functionName: string,
+    file: string,
+    line: number,
+    col: number,
+  ): StackFrame {
+    return {
+      file,
+      line,
+      col,
+      functionName,
+      isProjectFile: this.isProjectFile(file),
+    };
+  }
+
+  private isProjectFile(file: string): boolean {
+    if (HTTP_SCHEME.test(file)) {
+      return false;
+    }
+    if (NODE_MODULES_SEGMENT.test(file)) {
+      return false;
+    }
+    return file.startsWith(this.projectRoot);
+  }
+
+  /**
+   * Strips the `async ` prefix that ts-jest/V8 sometimes leaves in function names
+   * when the regex group captures it as part of the name rather than the keyword.
+   */
+  private sanitizeFunctionName(name: string): string {
+    return name
+      .replace(/^async\s+/, '')
+      .replace(/^new\s+/, 'new ')
+      .trim();
+  }
+}

package/src/investigation/type-resolver.ts

@@ -0,0 +1,144 @@
+/**
+ * @angular-modernizer/api - Type Resolver
+ *
+ * Resolves the TypeScript type at a given position (file, line, column)
+ * using the ts-morph language service and type checker.
+ *
+ * @remarks
+ * Useful in bug investigation to understand what type a variable holds
+ * at a specific location — including whether it is nullable, async,
+ * or wraps a generic parameter.
+ *
+ * @example
+ * ```typescript
+ * const resolver = new TypeResolver(project);
+ * const info = resolver.resolveType('/src/app/user.service.ts', 42, 15);
+ * // info.typeString   → 'UserService'
+ * // info.isNullable   → false
+ * // info.isAsync      → false
+ * // info.declaredIn   → '/src/app/user.service.ts'
+ * ```
+ */
+
+import type { Project } from 'ts-morph';
+
+/** Resolved type information for a source position. */
+export interface ResolvedTypeInfo {
+  /** Human-readable resolved type string. */
+  typeString: string;
+
+  /** Generic type parameters extracted from the type string (e.g. `['string']` for `Array<string>`). */
+  genericParams: string[];
+
+  /** Absolute path of the file where this type is declared. Empty string when not determinable. */
+  declaredIn: string;
+
+  /** `true` when the type includes `null` or `undefined` in a union. */
+  isNullable: boolean;
+
+  /** `true` when the type is `Promise<T>` or `Observable<T>`. */
+  isAsync: boolean;
+}
+
+const ASYNC_TYPE_NAMES = new Set([
+  'Promise',
+  'Observable',
+  'Subject',
+  'BehaviorSubject',
+]);
+const FALLBACK: ResolvedTypeInfo = {
+  typeString: 'unknown',
+  genericParams: [],
+  declaredIn: '',
+  isNullable: false,
+  isAsync: false,
+};
+
+/**
+ * Resolves TypeScript types at source positions via ts-morph.
+ */
+export class TypeResolver {
+  /**
+   * @param project - A ts-morph `Project` instance with source files already added.
+   */
+  constructor(private readonly project: Project) {}
+
+  /**
+   * Resolves the TypeScript type at the given 1-based position.
+   *
+   * @param file - Absolute path of the source file.
+   * @param line - 1-based line number.
+   * @param column - 1-based column number.
+   * @returns Resolved type information, or a fallback with `typeString: 'unknown'`.
+   */
+  resolveType(file: string, line: number, column: number): ResolvedTypeInfo {
+    const sourceFile = this.project.getSourceFile(file);
+    if (!sourceFile) {
+      return FALLBACK;
+    }
+
+    try {
+      const pos = sourceFile.compilerNode.getPositionOfLineAndCharacter(
+        line - 1,
+        column - 1,
+      );
+
+      const node = sourceFile.getDescendantAtPos(pos);
+      if (!node) {
+        return FALLBACK;
+      }
+
+      const type = this.project.getTypeChecker().getTypeAtLocation(node);
+      const typeString = type.getText(node);
+
+      const genericParams = this.extractGenericParams(typeString);
+      const declaredIn = this.resolveDeclaredIn(type);
+      const isNullable = this.checkNullable(typeString);
+      const isAsync = this.checkAsync(typeString);
+
+      return { typeString, genericParams, declaredIn, isNullable, isAsync };
+    } catch {
+      return FALLBACK;
+    }
+  }
+
+  private extractGenericParams(typeString: string): string[] {
+    const match = /<([^>]+)>/.exec(typeString);
+    if (!match?.[1]) {
+      return [];
+    }
+    return match[1]
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+  }
+
+  private resolveDeclaredIn(
+    type: ReturnType<
+      ReturnType<Project['getTypeChecker']>['getTypeAtLocation']
+    >,
+  ): string {
+    try {
+      const symbol = type.getSymbol();
+      if (!symbol) {
+        return '';
+      }
+      const declarations = symbol.getDeclarations();
+      if (declarations.length === 0) {
+        return '';
+      }
+      return declarations[0]?.getSourceFile().getFilePath() ?? '';
+    } catch {
+      return '';
+    }
+  }
+
+  private checkNullable(typeString: string): boolean {
+    return typeString.includes('null') || typeString.includes('undefined');
+  }
+
+  private checkAsync(typeString: string): boolean {
+    const baseName = typeString.split('<')[0]?.trim() ?? '';
+    return ASYNC_TYPE_NAMES.has(baseName);
+  }
+}

package/src/investigation/usage-finder.ts

@@ -0,0 +1,198 @@
+/**
+ * @angular-modernizer/api - Usage Finder
+ *
+ * Finds all references to a symbol (class, method, function, variable, constant)
+ * across a ts-morph Project. Used in bug investigation to determine call paths
+ * and blast radius before proposing a fix.
+ *
+ * @remarks
+ * Uses ts-morph `findReferences()` under the hood. The project must already have
+ * the relevant source files added before calling `findUsages`.
+ *
+ * @example
+ * ```typescript
+ * const finder = new UsageFinder(project);
+ * const usages = finder.findUsages('UserService', { file: '/src/app/user.component.ts' });
+ * // usages[0] → { file, line, col, snippet, usageType: 'read' }
+ * ```
+ */
+
+import type { Project, Node } from 'ts-morph';
+
+/** Classification of how a symbol is used at a given location. */
+export type UsageType = 'read' | 'write' | 'call';
+
+/** A single resolved symbol usage. */
+export interface SymbolUsage {
+  /** Absolute file path containing the usage. */
+  file: string;
+
+  /** 1-based line number. */
+  line: number;
+
+  /** 1-based column number. */
+  col: number;
+
+  /** The source line containing the usage. */
+  snippet: string;
+
+  /** How the symbol is used at this location. */
+  usageType: UsageType;
+}
+
+/** Options for narrowing `findUsages` results. */
+export interface FindUsagesOptions {
+  /**
+   * Restrict results to a single source file (absolute path).
+   * When omitted, all files in the project are searched.
+   */
+  file?: string;
+
+  /**
+   * Restrict results to a specific usage type.
+   * When omitted, all usage types are returned.
+   */
+  usageType?: UsageType;
+}
+
+/**
+ * Finds all references to named symbols across a ts-morph Project.
+ */
+export class UsageFinder {
+  /**
+   * @param project - A ts-morph `Project` instance with source files already added.
+   */
+  constructor(private readonly project: Project) {}
+
+  /**
+   * Finds all usages of the named symbol across the project.
+   *
+   * @param symbol - The symbol name to search for (class, method, function, variable, constant).
+   * @param options - Optional filters for file scope and usage type.
+   * @returns Array of resolved usages, sorted by file path then line number.
+   */
+  findUsages(symbol: string, options: FindUsagesOptions = {}): SymbolUsage[] {
+    const usages: SymbolUsage[] = [];
+
+    const sourceFiles = options.file
+      ? [this.project.getSourceFile(options.file)].filter(Boolean)
+      : this.project.getSourceFiles();
+
+    for (const sourceFile of sourceFiles) {
+      if (!sourceFile) {
+        continue;
+      }
+
+      const nodes = this.findSymbolNodes(sourceFile, symbol);
+
+      for (const node of nodes) {
+        const refs = this.project.getLanguageService().findReferences(node);
+
+        for (const refSymbol of refs) {
+          for (const ref of refSymbol.getReferences()) {
+            const refFile = ref.getSourceFile();
+            const refFilePath = refFile.getFilePath();
+
+            if (options.file && refFilePath !== options.file) {
+              continue;
+            }
+
+            const pos = ref.getNode().getStart();
+            const lineAndCol = refFile.getLineAndColumnAtPos(pos);
+            const lineText =
+              refFile.getFullText().split('\n')[lineAndCol.line - 1] ?? '';
+            const usageType = this.classifyUsage(ref.getNode());
+
+            if (options.usageType && usageType !== options.usageType) {
+              continue;
+            }
+
+            usages.push({
+              file: refFilePath,
+              line: lineAndCol.line,
+              col: lineAndCol.column,
+              snippet: lineText.trim(),
+              usageType,
+            });
+          }
+        }
+      }
+    }
+
+    return this.deduplicate(usages).sort((a, b) =>
+      a.file !== b.file ? a.file.localeCompare(b.file) : a.line - b.line,
+    );
+  }
+
+  private findSymbolNodes(
+    sourceFile: ReturnType<Project['getSourceFile']>,
+    symbol: string,
+  ) {
+    if (!sourceFile) {
+      return [];
+    }
+
+    const nodes: Node[] = [];
+
+    sourceFile.forEachDescendant((node) => {
+      if (
+        'getName' in node &&
+        typeof (node as { getName(): string }).getName === 'function'
+      ) {
+        if ((node as { getName(): string }).getName() === symbol) {
+          nodes.push(node);
+        }
+      }
+    });
+
+    return nodes;
+  }
+
+  private classifyUsage(node: Node): UsageType {
+    const parent = node.getParent();
+    if (!parent) {
+      return 'read';
+    }
+
+    const parentKindName = parent.getKindName();
+
+    // Call expression: svc.method() or method()
+    if (parentKindName === 'CallExpression') {
+      return 'call';
+    }
+    if (parentKindName === 'PropertyAccessExpression') {
+      const grandParent = parent.getParent();
+      if (grandParent?.getKindName() === 'CallExpression') {
+        return 'call';
+      }
+    }
+
+    // Assignment: x = value or x += value
+    if (
+      parentKindName === 'BinaryExpression' ||
+      parentKindName === 'VariableDeclaration' ||
+      parentKindName === 'PropertyAssignment'
+    ) {
+      const parentText = parent.getText();
+      const nodeText = node.getText();
+      const nodePos = parentText.indexOf(nodeText);
+      if (nodePos === 0) {
+        return 'write';
+      }
+    }
+
+    return 'read';
+  }
+
+  private deduplicate(usages: SymbolUsage[]): SymbolUsage[] {
+    const seen = new Set<string>();
+    return usages.filter((u) => {
+      const key = `${u.file}:${u.line}:${u.col}`;
+      if (seen.has(key)) {
+        return false;
+      }
+      seen.add(key);
+      return true;
+    });
+  }
+}