@angular-modernizer/api 0.1.0

package/src/investigation/call-graph-builder.ts

@@ -0,0 +1,298 @@
+/**
+ * @angular-modernizer/api - Call Graph Builder
+ *
+ * Builds a call graph for a named method or function within a ts-morph Project.
+ * Supports traversal upward (callers) and downward (callees) with configurable depth.
+ *
+ * @remarks
+ * Used in bug investigation to understand how an error propagates through the
+ * codebase. Combine with `find-usages` to trace the full call path from the
+ * entry point to the failing code.
+ *
+ * @example
+ * ```typescript
+ * const builder = new CallGraphBuilder(project);
+ * const graph = builder.buildCallGraph('getUser', '/src/app/user.service.ts', {
+ *   direction: 'both',
+ *   depth: 2,
+ * });
+ * // graph.callers → who calls getUser
+ * // graph.callees → what getUser calls
+ * ```
+ */
+
+import type { Project, MethodDeclaration, FunctionDeclaration } from 'ts-morph';
+import { SyntaxKind } from 'ts-morph';
+
+/** A node in the call graph tree. */
+export interface CallNode {
+  /** Method or function name. */
+  name: string;
+
+  /** Absolute file path where this method is declared. */
+  file: string;
+
+  /** 1-based line number of the declaration. */
+  line: number;
+
+  /** Nested callers or callees (recursive to configured depth). */
+  children: CallNode[];
+}
+
+/** Options for `buildCallGraph`. */
+export interface CallGraphOptions {
+  /**
+   * Traversal direction.
+   * - `'up'`   — callers only (who calls the target)
+   * - `'down'` — callees only (what the target calls)
+   * - `'both'` — both directions
+   * @default 'both'
+   */
+  direction?: 'up' | 'down' | 'both';
+
+  /**
+   * How many levels deep to traverse.
+   * @default 2
+   */
+  depth?: number;
+}
+
+/** Result of `buildCallGraph`. */
+export interface CallGraphResult {
+  /** The resolved target node, or `null` when not found. */
+  target: Omit<CallNode, 'children'> | null;
+
+  /** Nodes that call the target (populated for `'up'` and `'both'`). */
+  callers: CallNode[];
+
+  /** Nodes called by the target (populated for `'down'` and `'both'`). */
+  callees: CallNode[];
+}
+
+type NamedCallable = MethodDeclaration | FunctionDeclaration;
+
+/**
+ * Builds caller/callee graphs for methods and functions across a ts-morph Project.
+ */
+export class CallGraphBuilder {
+  /**
+   * @param project - A ts-morph `Project` instance with source files already added.
+   */
+  constructor(private readonly project: Project) {}
+
+  /**
+   * Builds a call graph rooted at the named method or function.
+   *
+   * @param method - Name of the method or function to analyse.
+   * @param file - Absolute path of the source file containing the method.
+   * @param options - Traversal direction and depth. Defaults to `both` / depth `2`.
+   * @returns A `CallGraphResult` with the target and its caller/callee trees.
+   */
+  buildCallGraph(
+    method: string,
+    file: string,
+    options: CallGraphOptions = {},
+  ): CallGraphResult {
+    const direction = options.direction ?? 'both';
+    const depth = options.depth ?? 2;
+
+    const target = this.resolveTarget(method, file);
+    if (!target) {
+      return { target: null, callers: [], callees: [] };
+    }
+
+    const targetInfo: Omit<CallNode, 'children'> = {
+      name: method,
+      file,
+      line: target.getStartLineNumber(),
+    };
+
+    const callers =
+      direction === 'down'
+        ? []
+        : this.buildCallers(target, depth, new Set([`${file}:${method}`]));
+
+    const callees =
+      direction === 'up'
+        ? []
+        : this.buildCallees(target, depth, new Set([`${file}:${method}`]));
+
+    return { target: targetInfo, callers, callees };
+  }
+
+  private resolveTarget(name: string, file: string): NamedCallable | null {
+    const sourceFile = this.project.getSourceFile(file);
+    if (!sourceFile) {
+      return null;
+    }
+
+    // Search class methods
+    for (const cls of sourceFile.getClasses()) {
+      const method = cls.getMethod(name);
+      if (method) {
+        return method;
+      }
+    }
+
+    // Search top-level functions
+    const fn = sourceFile.getFunction(name);
+    if (fn) {
+      return fn;
+    }
+
+    return null;
+  }
+
+  private buildCallees(
+    callable: NamedCallable,
+    depth: number,
+    visited: Set<string>,
+  ): CallNode[] {
+    if (depth <= 0) {
+      return [];
+    }
+
+    const callees: CallNode[] = [];
+    const body = callable.getBody();
+    if (!body) {
+      return [];
+    }
+
+    body.forEachDescendant((node) => {
+      if (node.getKind() !== SyntaxKind.CallExpression) {
+        return;
+      }
+
+      const callExpr = node.asKindOrThrow(SyntaxKind.CallExpression);
+      const expr = callExpr.getExpression();
+      const calleeName = this.extractCallName(expr.getText());
+      if (!calleeName) {
+        return;
+      }
+
+      const targetDecl = this.findDeclarationInProject(calleeName);
+      if (!targetDecl) {
+        return;
+      }
+
+      const targetFile = targetDecl.getSourceFile().getFilePath();
+      const key = `${targetFile}:${calleeName}`;
+      if (visited.has(key)) {
+        return;
+      }
+      visited.add(key);
+
+      const children = this.buildCallees(
+        targetDecl,
+        depth - 1,
+        new Set(visited),
+      );
+      callees.push({
+        name: calleeName,
+        file: targetFile,
+        line: targetDecl.getStartLineNumber(),
+        children,
+      });
+    });
+
+    return this.deduplicateNodes(callees);
+  }
+
+  private buildCallers(
+    callable: NamedCallable,
+    depth: number,
+    visited: Set<string>,
+  ): CallNode[] {
+    if (depth <= 0) {
+      return [];
+    }
+
+    const callers: CallNode[] = [];
+    const name = callable.getName();
+    if (!name) {
+      return [];
+    }
+
+    const refs = this.project.getLanguageService().findReferences(callable);
+
+    for (const refSymbol of refs) {
+      for (const ref of refSymbol.getReferences()) {
+        if (ref.isDefinition()) {
+          continue;
+        }
+
+        const refNode = ref.getNode();
+        const parentMethod = refNode.getFirstAncestor(
+          (n) =>
+            n.getKind() === SyntaxKind.MethodDeclaration ||
+            n.getKind() === SyntaxKind.FunctionDeclaration,
+        ) as NamedCallable | undefined;
+
+        if (!parentMethod) {
+          continue;
+        }
+
+        const callerName = parentMethod.getName();
+        if (!callerName) {
+          continue;
+        }
+
+        const callerFile = parentMethod.getSourceFile().getFilePath();
+        const key = `${callerFile}:${callerName}`;
+        if (visited.has(key)) {
+          continue;
+        }
+        visited.add(key);
+
+        const children = this.buildCallers(
+          parentMethod,
+          depth - 1,
+          new Set(visited),
+        );
+        callers.push({
+          name: callerName,
+          file: callerFile,
+          line: parentMethod.getStartLineNumber(),
+          children,
+        });
+      }
+    }
+
+    return this.deduplicateNodes(callers);
+  }
+
+  private findDeclarationInProject(name: string): NamedCallable | null {
+    for (const sourceFile of this.project.getSourceFiles()) {
+      for (const cls of sourceFile.getClasses()) {
+        const method = cls.getMethod(name);
+        if (method) {
+          return method;
+        }
+      }
+      const fn = sourceFile.getFunction(name);
+      if (fn) {
+        return fn;
+      }
+    }
+    return null;
+  }
+
+  private extractCallName(exprText: string): string | null {
+    // svc.method() → method, method() → method
+    const parts = exprText.split('.');
+    const last = parts.at(-1);
+    return last && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(last) ? last : null;
+  }
+
+  private deduplicateNodes(nodes: CallNode[]): CallNode[] {
+    const seen = new Set<string>();
+    return nodes.filter((n) => {
+      const key = `${n.file}:${n.name}`;
+      if (seen.has(key)) {
+        return false;
+      }
+      seen.add(key);
+      return true;
+    });
+  }
+}

package/src/investigation/codebase-searcher.ts

@@ -0,0 +1,286 @@
+/**
+ * @angular-modernizer/api - Codebase Searcher
+ *
+ * Searches across all source files in a ts-morph Project using three modes:
+ * - `text`    — literal string search (case-sensitive substring)
+ * - `pattern` — regular-expression search
+ * - `symbol`  — TypeScript declaration search (class, function, interface,
+ *               enum, type alias, variable)
+ *
+ * @remarks
+ * The project must already have the relevant source files added before calling
+ * `search`. For `symbol` mode only top-level named declarations are indexed;
+ * local variables and anonymous expressions are not returned.
+ *
+ * @example
+ * ```typescript
+ * const searcher = new CodebaseSearcher(project);
+ *
+ * // Text search
+ * const hits = searcher.search('TODO:', { mode: 'text' });
+ *
+ * // Regex search
+ * const selectors = searcher.search('selector:\\s*["\']([^"\']+)["\']', { mode: 'pattern' });
+ *
+ * // Symbol search
+ * const classes = searcher.search('UserService', { mode: 'symbol' });
+ * ```
+ */
+
+import type { Project } from 'ts-morph';
+
+/** The kind of named declaration returned in symbol-mode results. */
+export type SymbolKind =
+  | 'class'
+  | 'function'
+  | 'interface'
+  | 'enum'
+  | 'typeAlias'
+  | 'variable';
+
+/** A single search result. */
+export interface SearchResult {
+  /** Absolute file path. */
+  file: string;
+
+  /** 1-based line number of the match. */
+  line: number;
+
+  /** 1-based column of the match start. */
+  col: number;
+
+  /** The source line (trimmed) containing the match. */
+  snippet: string;
+
+  /**
+   * Set in `symbol` mode to classify the declaration type.
+   * Absent in `text` and `pattern` modes.
+   */
+  symbolKind?: SymbolKind;
+}
+
+/** Options for `CodebaseSearcher.search()`. */
+export interface SearchOptions {
+  /**
+   * - `text`    — literal substring match
+   * - `pattern` — regular expression match
+   * - `symbol`  — TypeScript named declaration lookup
+   */
+  mode: 'text' | 'pattern' | 'symbol';
+
+  /**
+   * Optional glob pattern (minimatch) to restrict which files are searched.
+   * E.g. `'**\/*.service.ts'`. When omitted all project source files are
+   * searched.
+   */
+  include?: string;
+
+  /**
+   * Maximum number of results to return. When omitted all matches are
+   * returned.
+   */
+  maxResults?: number;
+}
+
+/**
+ * Converts a glob pattern (`**\/*.service.ts`) to a RegExp and tests `filePath`.
+ * Supports `**` (any path segments) and `*` (single segment wildcard).
+ */
+function matchesGlob(filePath: string, pattern: string): boolean {
+  const escaped = pattern
+    .replaceAll(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replaceAll('**', '\u0000')
+    .replaceAll('*', '[^/]*')
+    .replaceAll('\u0000', '.*');
+  return new RegExp(`(^|/)${escaped}$`).test(filePath);
+}
+
+/**
+ * Searches source files in a ts-morph `Project` by text, regex, or symbol
+ * name.
+ */
+export class CodebaseSearcher {
+  constructor(private readonly project: Project) { }
+
+  /**
+   * Search for `query` across all (filtered) source files.
+   *
+   * @param query - The text, regex pattern, or symbol name to find.
+   * @param options - Search mode and optional file filter / result limit.
+   * @returns Array of `SearchResult` objects ordered by file then line.
+   *
+   * @example
+   * ```typescript
+   * searcher.search('UserService', { mode: 'symbol' });
+   * searcher.search('TODO', { mode: 'text', include: 'src/**\/*.ts' });
+   * ```
+   */
+  search(query: string, options: SearchOptions): SearchResult[] {
+    const sourceFiles = this.project
+      .getSourceFiles()
+      .filter(
+        (sf) =>
+          options.include === undefined ||
+          matchesGlob(sf.getFilePath(), options.include),
+      );
+
+    const results: SearchResult[] =
+      options.mode === 'symbol'
+        ? this.searchSymbols(query, sourceFiles)
+        : this.searchText(query, options.mode, sourceFiles);
+
+    if (options.maxResults !== undefined) {
+      return results.slice(0, options.maxResults);
+    }
+    return results;
+  }
+
+  /**
+   * Text or pattern search: splits each file into lines and tests each line.
+   */
+  private searchText(
+    query: string,
+    mode: 'text' | 'pattern',
+    sourceFiles: ReturnType<Project['getSourceFiles']>,
+  ): SearchResult[] {
+    const results: SearchResult[] = [];
+    const regex = mode === 'pattern' ? new RegExp(query) : null;
+
+    for (const sf of sourceFiles) {
+      const filePath = sf.getFilePath();
+      const lines = sf.getFullText().split('\n');
+
+      lines.forEach((lineText, index) => {
+        const matched =
+          regex === null ? lineText.includes(query) : regex.test(lineText);
+
+        if (!matched) {
+          return;
+        }
+
+        const col =
+          regex === null
+            ? lineText.indexOf(query) + 1
+            : lineText.search(regex) + 1;
+
+        results.push({
+          file: filePath,
+          line: index + 1,
+          col,
+          snippet: lineText.trim(),
+        });
+      });
+    }
+
+    return results;
+  }
+
+  /**
+   * Symbol search: finds top-level named declarations whose name equals
+   * `query`.
+   */
+  private searchSymbols(
+    query: string,
+    sourceFiles: ReturnType<Project['getSourceFiles']>,
+  ): SearchResult[] {
+    const results: SearchResult[] = [];
+
+    for (const sf of sourceFiles) {
+      const filePath = sf.getFilePath();
+
+      // Classes
+      for (const decl of sf.getClasses()) {
+        if (decl.getName() === query) {
+          const pos = decl.getNameNode()?.getStart() ?? decl.getStart();
+          const { line, column } = sf.getLineAndColumnAtPos(pos);
+          results.push({
+            file: filePath,
+            line,
+            col: column,
+            snippet: (decl.getText().split('\n')[0] ?? '').trim(),
+            symbolKind: 'class',
+          });
+        }
+      }
+
+      // Functions
+      for (const decl of sf.getFunctions()) {
+        if (decl.getName() === query) {
+          const pos = decl.getNameNode()?.getStart() ?? decl.getStart();
+          const { line, column } = sf.getLineAndColumnAtPos(pos);
+          results.push({
+            file: filePath,
+            line,
+            col: column,
+            snippet: (decl.getText().split('\n')[0] ?? '').trim(),
+            symbolKind: 'function',
+          });
+        }
+      }
+
+      // Interfaces
+      for (const decl of sf.getInterfaces()) {
+        if (decl.getName() === query) {
+          const pos = decl.getNameNode().getStart();
+          const { line, column } = sf.getLineAndColumnAtPos(pos);
+          results.push({
+            file: filePath,
+            line,
+            col: column,
+            snippet: (decl.getText().split('\n')[0] ?? '').trim(),
+            symbolKind: 'interface',
+          });
+        }
+      }
+
+      // Enums
+      for (const decl of sf.getEnums()) {
+        if (decl.getName() === query) {
+          const pos = decl.getNameNode().getStart();
+          const { line, column } = sf.getLineAndColumnAtPos(pos);
+          results.push({
+            file: filePath,
+            line,
+            col: column,
+            snippet: (decl.getText().split('\n')[0] ?? '').trim(),
+            symbolKind: 'enum',
+          });
+        }
+      }
+
+      // Type aliases
+      for (const decl of sf.getTypeAliases()) {
+        if (decl.getName() === query) {
+          const pos = decl.getNameNode().getStart();
+          const { line, column } = sf.getLineAndColumnAtPos(pos);
+          results.push({
+            file: filePath,
+            line,
+            col: column,
+            snippet: (decl.getText().split('\n')[0] ?? '').trim(),
+            symbolKind: 'typeAlias',
+          });
+        }
+      }
+
+      // Variables (top-level const/let/var declarations)
+      for (const varStmt of sf.getVariableStatements()) {
+        for (const decl of varStmt.getDeclarations()) {
+          if (decl.getName() === query) {
+            const pos = decl.getNameNode().getStart();
+            const { line, column } = sf.getLineAndColumnAtPos(pos);
+            results.push({
+              file: filePath,
+              line,
+              col: column,
+              snippet: (varStmt.getText().split('\n')[0] ?? '').trim(),
+              symbolKind: 'variable',
+            });
+          }
+        }
+      }
+    }
+
+    return results;
+  }
+}