@angular-modernizer/api 0.1.3 → 0.2.0

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

@@ -1,13 +1,36 @@
 /**
  * @angular-modernizer/api - Call Graph Builder
  *
- * Builds a call graph for a named method or function within a ts-morph Project.
+ * Builds a call graph for a named callable within a ts-morph Project.
  * Supports traversal upward (callers) and downward (callees) with configurable depth.
  *
+ * Supported targets (and graph nodes):
+ * - class methods and top-level functions
+ * - constructors (`'constructor'` or `'ClassName.constructor'`); a class
+ *   without an explicit constructor is represented by its field initializers
+ * - get/set accessors
+ * - properties and top-level variables initialized with an arrow function or
+ *   function expression
+ *
+ * Callees include:
+ * - call expressions (resolved via the type checker, name-based fallback
+ *   only when the symbol cannot be resolved)
+ * - `new X()` (edge to X's constructor, including X's field initializers)
+ * - `super(...)` (edge to the base class constructor)
+ * - property reads/writes that resolve to a getter/setter
+ * - for constructors: instance field initializers (they run during
+ *   construction)
+ *
+ * Callers are the enclosing callable of each reference: method, function,
+ * constructor, accessor, arrow-function property, or (for references in a
+ * field initializer) the owning class constructor. Callers of a constructor
+ * are the `new X()` sites and the constructors of subclasses.
+ *
  * @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.
+ * entry point to the failing code, e.g. "what runs transitively while an
+ * interceptor is constructed" (ctor -> helper getter -> static config read).
  *
  * @example
  * ```typescript
@@ -18,15 +41,35 @@
  * });
  * // graph.callers → who calls getUser
  * // graph.callees → what getUser calls
+ *
+ * const ctorGraph = builder.buildCallGraph(
+ *   'AuthInterceptor.constructor',
+ *   '/src/app/auth.interceptor.ts',
+ *   { direction: 'down', depth: 3 },
+ * );
  * ```
  */
 
-import type { Project, MethodDeclaration, FunctionDeclaration } from 'ts-morph';
-import { SyntaxKind } from 'ts-morph';
+import {
+  Node,
+  SyntaxKind,
+  type ClassDeclaration,
+  type Project,
+} from 'ts-morph';
+
+/** Kind of callable represented by a call graph node. */
+export type CallableKind =
+  | 'method'
+  | 'function'
+  | 'constructor'
+  | 'getter'
+  | 'setter'
+  | 'property'
+  | 'variable';
 
 /** A node in the call graph tree. */
 export interface CallNode {
-  /** Method or function name. */
+  /** Method or function name (`'constructor'` for constructors). */
   name: string;
 
   /** Absolute file path where this method is declared. */
@@ -35,6 +78,12 @@ export interface CallNode {
   /** 1-based line number of the declaration. */
   line: number;
 
+  /** Kind of callable (method, constructor, getter, ...). */
+  kind?: CallableKind;
+
+  /** Owning class name for class members. */
+  className?: string;
+
   /** Nested callers or callees (recursive to configured depth). */
   children: CallNode[];
 }
@@ -69,10 +118,24 @@ export interface CallGraphResult {
   callees: CallNode[];
 }
 
-type NamedCallable = MethodDeclaration | FunctionDeclaration;
+/** Internal representation of anything that can run code. */
+interface Callable {
+  /** Declaration node (class declaration for implicit constructors). */
+  node: Node;
+  name: string;
+  kind: CallableKind;
+  /** Nodes whose code runs when the callable runs. */
+  bodies: Node[];
+  /** Node used for reference lookup (callers). */
+  nameNode?: Node;
+  className?: string;
+}
+
+const CONSTRUCTOR_NAME = 'constructor';
 
 /**
- * Builds caller/callee graphs for methods and functions across a ts-morph Project.
+ * Builds caller/callee graphs for methods, functions, constructors,
+ * accessors and arrow-function properties across a ts-morph Project.
  */
 export class CallGraphBuilder {
   /**
@@ -81,10 +144,13 @@ export class CallGraphBuilder {
   constructor(private readonly project: Project) {}
 
   /**
-   * Builds a call graph rooted at the named method or function.
+   * Builds a call graph rooted at the named callable.
    *
-   * @param method - Name of the method or function to analyse.
-   * @param file - Absolute path of the source file containing the method.
+   * @param method - Name of the callable to analyse. Accepts a method,
+   *   function, accessor or arrow-function property name, `'constructor'`,
+   *   or a class-qualified name such as `'AuthInterceptor.constructor'` or
+   *   `'AuthInterceptor.headers'`.
+   * @param file - Absolute path of the source file containing the callable.
    * @param options - Traversal direction and depth. Defaults to `both` / depth `2`.
    * @returns A `CallGraphResult` with the target and its caller/callee trees.
    */
@@ -104,47 +170,214 @@ export class CallGraphBuilder {
     const targetInfo: Omit<CallNode, 'children'> = {
       name: method,
       file,
-      line: target.getStartLineNumber(),
+      line: target.node.getStartLineNumber(),
+      kind: target.kind,
+      ...(target.className ? { className: target.className } : {}),
     };
 
+    const rootKey = this.keyOf(target);
+
     const callers =
       direction === 'down'
         ? []
-        : this.buildCallers(target, depth, new Set([`${file}:${method}`]));
+        : this.buildCallers(target, depth, new Set([rootKey]));
 
     const callees =
       direction === 'up'
         ? []
-        : this.buildCallees(target, depth, new Set([`${file}:${method}`]));
+        : this.buildCallees(target, depth, new Set([rootKey]));
 
     return { target: targetInfo, callers, callees };
   }
 
-  private resolveTarget(name: string, file: string): NamedCallable | null {
+  // ---------------------------------------------------------------------------
+  // Target resolution
+  // ---------------------------------------------------------------------------
+
+  private resolveTarget(name: string, file: string): Callable | 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;
+    const dotIndex = name.lastIndexOf('.');
+    const className = dotIndex > 0 ? name.slice(0, dotIndex) : undefined;
+    const memberName = dotIndex > 0 ? name.slice(dotIndex + 1) : name;
+
+    const classes = sourceFile
+      .getClasses()
+      .filter((cls) => !className || cls.getName() === className);
+
+    for (const cls of classes) {
+      const member = this.findClassMember(cls, memberName);
+      if (member) {
+        return member;
       }
     }
 
-    // Search top-level functions
-    const fn = sourceFile.getFunction(name);
+    if (className) {
+      return null;
+    }
+
+    const fn = sourceFile.getFunction(memberName);
     if (fn) {
-      return fn;
+      return this.toCallable(fn);
+    }
+
+    const variable = sourceFile.getVariableDeclaration(memberName);
+    if (variable) {
+      return this.toCallable(variable);
+    }
+
+    return null;
+  }
+
+  private findClassMember(
+    cls: ClassDeclaration,
+    memberName: string,
+  ): Callable | null {
+    if (memberName === CONSTRUCTOR_NAME) {
+      return this.constructorOf(cls);
+    }
+
+    const candidates: (Node | undefined)[] = [
+      cls.getMethod(memberName),
+      cls.getGetAccessor(memberName),
+      cls.getSetAccessor(memberName),
+      cls.getProperty(memberName),
+    ];
+    for (const candidate of candidates) {
+      const callable = candidate ? this.toCallable(candidate) : null;
+      if (callable) {
+        return callable;
+      }
+    }
+    return null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Callable construction
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Converts a declaration node into a `Callable`, or `null` when the node
+   * cannot run code (e.g. a plain data property or an interface member).
+   */
+  private toCallable(node: Node): Callable | null {
+    if (Node.isConstructorDeclaration(node)) {
+      const cls = node.getParent();
+      return Node.isClassDeclaration(cls) ? this.constructorOf(cls) : null;
+    }
+
+    if (Node.isMethodDeclaration(node)) {
+      return {
+        node,
+        name: node.getName(),
+        kind: 'method',
+        bodies: this.compact([node.getBody()]),
+        nameNode: node.getNameNode(),
+        className: this.classNameOf(node),
+      };
+    }
+
+    if (Node.isFunctionDeclaration(node)) {
+      const name = node.getName();
+      if (!name) {
+        return null;
+      }
+      return {
+        node,
+        name,
+        kind: 'function',
+        bodies: this.compact([node.getBody()]),
+        nameNode: node.getNameNode(),
+      };
+    }
+
+    if (Node.isGetAccessorDeclaration(node) || Node.isSetAccessorDeclaration(node)) {
+      return {
+        node,
+        name: node.getName(),
+        kind: Node.isGetAccessorDeclaration(node) ? 'getter' : 'setter',
+        bodies: this.compact([node.getBody()]),
+        nameNode: node.getNameNode(),
+        className: this.classNameOf(node),
+      };
     }
 
+    if (Node.isPropertyDeclaration(node) || Node.isVariableDeclaration(node)) {
+      const fnBody = this.functionInitializerBody(node.getInitializer());
+      if (!fnBody) {
+        return null;
+      }
+      return {
+        node,
+        name: node.getName(),
+        kind: Node.isPropertyDeclaration(node) ? 'property' : 'variable',
+        bodies: [fnBody],
+        nameNode: node.getNameNode(),
+        className: Node.isPropertyDeclaration(node)
+          ? this.classNameOf(node)
+          : undefined,
+      };
+    }
+
+    return null;
+  }
+
+  /**
+   * Constructor callable for a class: the explicit constructor body (if any)
+   * plus all non-static, non-function field initializers.
+   */
+  private constructorOf(cls: ClassDeclaration): Callable {
+    const explicit = cls
+      .getConstructors()
+      .find((ctor) => ctor.getBody() !== undefined);
+    const fieldInitializers = cls
+      .getProperties()
+      .filter((prop) => !prop.isStatic())
+      .map((prop) => prop.getInitializer())
+      .filter(
+        (init): init is NonNullable<typeof init> =>
+          init !== undefined && !this.functionInitializerBody(init),
+      );
+
+    return {
+      node: explicit ?? cls,
+      name: CONSTRUCTOR_NAME,
+      kind: 'constructor',
+      bodies: [...this.compact([explicit?.getBody()]), ...fieldInitializers],
+      nameNode: cls.getNameNode(),
+      className: cls.getName(),
+    };
+  }
+
+  private functionInitializerBody(initializer: Node | undefined): Node | null {
+    if (
+      initializer &&
+      (Node.isArrowFunction(initializer) ||
+        Node.isFunctionExpression(initializer))
+    ) {
+      return initializer.getBody();
+    }
     return null;
   }
 
+  private classNameOf(node: Node): string | undefined {
+    const cls = node.getParent();
+    return Node.isClassDeclaration(cls) ? cls.getName() : undefined;
+  }
+
+  private compact(nodes: (Node | undefined)[]): Node[] {
+    return nodes.filter((n): n is Node => n !== undefined);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Callees
+  // ---------------------------------------------------------------------------
+
   private buildCallees(
-    callable: NamedCallable,
+    callable: Callable,
     depth: number,
     visited: Set<string>,
   ): CallNode[] {
@@ -153,125 +386,302 @@ export class CallGraphBuilder {
     }
 
     const callees: CallNode[] = [];
-    const body = callable.getBody();
-    if (!body) {
-      return [];
+    for (const target of this.collectCalleeCallables(callable)) {
+      const key = this.keyOf(target);
+      if (visited.has(key)) {
+        continue;
+      }
+      visited.add(key);
+
+      const children = this.buildCallees(target, depth - 1, new Set(visited));
+      callees.push(this.toCallNode(target, children));
     }
 
-    body.forEachDescendant((node) => {
-      if (node.getKind() !== SyntaxKind.CallExpression) {
-        return;
-      }
+    return this.deduplicateNodes(callees);
+  }
 
-      const callExpr = node.asKindOrThrow(SyntaxKind.CallExpression);
-      const expr = callExpr.getExpression();
-      const calleeName = this.extractCallName(expr.getText());
-      if (!calleeName) {
-        return;
+  private collectCalleeCallables(callable: Callable): Callable[] {
+    const result: Callable[] = [];
+    for (const body of callable.bodies) {
+      for (const node of [body, ...body.getDescendants()]) {
+        result.push(...this.calleesAt(node));
       }
+    }
+    return result;
+  }
 
-      const targetDecl = this.findDeclarationInProject(calleeName);
-      if (!targetDecl) {
-        return;
+  private calleesAt(node: Node): Callable[] {
+    if (Node.isCallExpression(node)) {
+      const expr = node.getExpression();
+      if (expr.getKind() === SyntaxKind.SuperKeyword) {
+        return this.superConstructor(node);
       }
+      return this.resolveCallExpressionTarget(expr);
+    }
 
-      const targetFile = targetDecl.getSourceFile().getFilePath();
-      const key = `${targetFile}:${calleeName}`;
-      if (visited.has(key)) {
-        return;
-      }
-      visited.add(key);
+    if (Node.isNewExpression(node)) {
+      return this.resolveNewExpressionTarget(node.getExpression());
+    }
 
-      const children = this.buildCallees(
-        targetDecl,
-        depth - 1,
-        new Set(visited),
-      );
-      callees.push({
-        name: calleeName,
-        file: targetFile,
-        line: targetDecl.getStartLineNumber(),
-        children,
-      });
-    });
+    if (Node.isPropertyAccessExpression(node)) {
+      return this.resolveAccessorTarget(node);
+    }
 
-    return this.deduplicateNodes(callees);
+    return [];
   }
 
+  private resolveCallExpressionTarget(expr: Node): Callable[] {
+    const resolved = this.resolveSymbolDeclarations(expr);
+    if (resolved) {
+      return this.pickCallables(resolved);
+    }
+
+    // Fallback: name-based lookup when the checker cannot resolve the symbol
+    const calleeName = this.extractCallName(expr.getText());
+    if (!calleeName) {
+      return [];
+    }
+    const fallback = this.findDeclarationInProject(calleeName);
+    return fallback ? [fallback] : [];
+  }
+
+  private resolveNewExpressionTarget(expr: Node): Callable[] {
+    const declarations = this.resolveSymbolDeclarations(expr);
+    const classes = (declarations ?? []).filter((d) =>
+      Node.isClassDeclaration(d),
+    );
+    if (classes.length > 0) {
+      return classes.map((cls) => this.constructorOf(cls));
+    }
+    if (declarations) {
+      return [];
+    }
+
+    const className = this.extractCallName(expr.getText());
+    const cls = className ? this.findClassInProject(className) : null;
+    return cls ? [this.constructorOf(cls)] : [];
+  }
+
+  private resolveAccessorTarget(access: Node): Callable[] {
+    if (!Node.isPropertyAccessExpression(access)) {
+      return [];
+    }
+    const parent = access.getParent();
+    // Calls are handled by the CallExpression branch
+    if (Node.isCallExpression(parent) && parent.getExpression() === access) {
+      return [];
+    }
+
+    const declarations = this.resolveSymbolDeclarations(access);
+    if (!declarations) {
+      return [];
+    }
+
+    const isWrite =
+      Node.isBinaryExpression(parent) &&
+      parent.getLeft() === access &&
+      parent.getOperatorToken().getKind() === SyntaxKind.EqualsToken;
+
+    return declarations
+      .filter((d) =>
+        isWrite
+          ? Node.isSetAccessorDeclaration(d)
+          : Node.isGetAccessorDeclaration(d),
+      )
+      .map((d) => this.toCallable(d))
+      .filter((c): c is Callable => c !== null);
+  }
+
+  private superConstructor(call: Node): Callable[] {
+    const cls = call.getFirstAncestorByKind(SyntaxKind.ClassDeclaration);
+    const base = cls?.getBaseClass();
+    return base ? [this.constructorOf(base)] : [];
+  }
+
+  /**
+   * Resolves the declarations behind an expression via the type checker.
+   * Returns `undefined` when no symbol can be resolved (caller may fall back
+   * to name-based lookup) and an empty array when the symbol resolves to
+   * declarations that cannot be represented.
+   */
+  private resolveSymbolDeclarations(expr: Node): Node[] | undefined {
+    const target = Node.isPropertyAccessExpression(expr)
+      ? expr.getNameNode()
+      : expr;
+    let symbol = target.getSymbol();
+    if (!symbol) {
+      return undefined;
+    }
+    if (symbol.isAlias()) {
+      symbol = symbol.getAliasedSymbol() ?? symbol;
+    }
+    return symbol.getDeclarations();
+  }
+
+  /**
+   * Maps declarations to callables, preferring implementations (with body)
+   * over overload signatures and skipping ambient (.d.ts) declarations.
+   */
+  private pickCallables(declarations: Node[]): Callable[] {
+    const callables = declarations
+      .filter((d) => !d.getSourceFile().isDeclarationFile())
+      .map((d) => this.toCallable(d))
+      .filter((c): c is Callable => c !== null);
+    const withBody = callables.filter((c) => c.bodies.length > 0);
+    return withBody.length > 0 ? withBody : callables;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Callers
+  // ---------------------------------------------------------------------------
+
   private buildCallers(
-    callable: NamedCallable,
+    callable: Callable,
     depth: number,
     visited: Set<string>,
   ): CallNode[] {
-    if (depth <= 0) {
+    if (depth <= 0 || !callable.nameNode) {
       return [];
     }
 
     const callers: CallNode[] = [];
-    const name = callable.getName();
-    if (!name) {
-      return [];
+    for (const refNode of this.referenceNodes(callable)) {
+      const caller = this.callerForReference(callable, refNode);
+      if (!caller) {
+        continue;
+      }
+
+      const key = this.keyOf(caller);
+      if (visited.has(key)) {
+        continue;
+      }
+      visited.add(key);
+
+      const children = this.buildCallers(caller, depth - 1, new Set(visited));
+      callers.push(this.toCallNode(caller, children));
     }
 
-    const refs = this.project.getLanguageService().findReferences(callable);
+    return this.deduplicateNodes(callers);
+  }
 
-    for (const refSymbol of refs) {
-      for (const ref of refSymbol.getReferences()) {
-        if (ref.isDefinition()) {
-          continue;
+  private referenceNodes(callable: Callable): Node[] {
+    if (!callable.nameNode) {
+      return [];
+    }
+    try {
+      const refs = this.project
+        .getLanguageService()
+        .findReferences(callable.nameNode);
+      const nodes: Node[] = [];
+      for (const refSymbol of refs) {
+        for (const ref of refSymbol.getReferences()) {
+          if (!ref.isDefinition()) {
+            nodes.push(ref.getNode());
+          }
         }
+      }
+      return nodes;
+    } catch {
+      return [];
+    }
+  }
 
-        const refNode = ref.getNode();
-        const parentMethod = refNode.getFirstAncestor(
-          (n) =>
-            n.getKind() === SyntaxKind.MethodDeclaration ||
-            n.getKind() === SyntaxKind.FunctionDeclaration,
-        ) as NamedCallable | undefined;
+  /**
+   * Maps a reference to the callable that performs the call. For
+   * constructor targets only `new X()` sites and subclass constructors
+   * (implicit or explicit `super()` calls) count.
+   */
+  private callerForReference(target: Callable, refNode: Node): Callable | null {
+    if (target.kind === 'constructor') {
+      const parent = refNode.getParent();
+      if (Node.isNewExpression(parent) && parent.getExpression() === refNode) {
+        return this.enclosingCallable(refNode);
+      }
+      const heritage = refNode.getFirstAncestorByKind(SyntaxKind.HeritageClause);
+      const subclass = heritage?.getParent();
+      if (
+        heritage?.getToken() === SyntaxKind.ExtendsKeyword &&
+        Node.isClassDeclaration(subclass)
+      ) {
+        return this.constructorOf(subclass);
+      }
+      return null;
+    }
+    return this.enclosingCallable(refNode);
+  }
 
-        if (!parentMethod) {
-          continue;
-        }
+  /**
+   * Finds the callable that contains `node`. Anonymous callbacks are
+   * attributed to their enclosing named callable; references inside a
+   * non-function field initializer are attributed to the class constructor.
+   */
+  private enclosingCallable(node: Node): Callable | null {
+    for (
+      let current = node.getParent();
+      current !== undefined;
+      current = current.getParent()
+    ) {
+      if (
+        Node.isMethodDeclaration(current) ||
+        Node.isFunctionDeclaration(current) ||
+        Node.isConstructorDeclaration(current) ||
+        Node.isGetAccessorDeclaration(current) ||
+        Node.isSetAccessorDeclaration(current)
+      ) {
+        return this.toCallable(current);
+      }
 
-        const callerName = parentMethod.getName();
-        if (!callerName) {
-          continue;
+      if (Node.isArrowFunction(current) || Node.isFunctionExpression(current)) {
+        const owner = current.getParent();
+        const isNamedOwner =
+          (Node.isPropertyDeclaration(owner) ||
+            Node.isVariableDeclaration(owner)) &&
+          owner.getInitializer() === current;
+        if (isNamedOwner) {
+          return this.toCallable(owner);
         }
+        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,
-        });
+      if (Node.isPropertyDeclaration(current)) {
+        const cls = current.getParent();
+        const runsInConstructor =
+          !current.isStatic() && Node.isClassDeclaration(cls);
+        return runsInConstructor ? this.constructorOf(cls) : null;
       }
-    }
 
-    return this.deduplicateNodes(callers);
+      if (Node.isClassDeclaration(current) || Node.isSourceFile(current)) {
+        return null;
+      }
+    }
+    return null;
   }
 
-  private findDeclarationInProject(name: string): NamedCallable | null {
+  // ---------------------------------------------------------------------------
+  // Name-based fallback and helpers
+  // ---------------------------------------------------------------------------
+
+  private findDeclarationInProject(name: string): Callable | null {
     for (const sourceFile of this.project.getSourceFiles()) {
       for (const cls of sourceFile.getClasses()) {
         const method = cls.getMethod(name);
         if (method) {
-          return method;
+          return this.toCallable(method);
         }
       }
       const fn = sourceFile.getFunction(name);
       if (fn) {
-        return fn;
+        return this.toCallable(fn);
+      }
+    }
+    return null;
+  }
+
+  private findClassInProject(name: string): ClassDeclaration | null {
+    for (const sourceFile of this.project.getSourceFiles()) {
+      const cls = sourceFile.getClass(name);
+      if (cls) {
+        return cls;
       }
     }
     return null;
@@ -284,10 +694,25 @@ export class CallGraphBuilder {
     return last && /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(last) ? last : null;
   }
 
+  private keyOf(callable: Callable): string {
+    return `${callable.node.getSourceFile().getFilePath()}:${callable.node.getStartLineNumber()}:${callable.name}`;
+  }
+
+  private toCallNode(callable: Callable, children: CallNode[]): CallNode {
+    return {
+      name: callable.name,
+      file: callable.node.getSourceFile().getFilePath(),
+      line: callable.node.getStartLineNumber(),
+      kind: callable.kind,
+      ...(callable.className ? { className: callable.className } : {}),
+      children,
+    };
+  }
+
   private deduplicateNodes(nodes: CallNode[]): CallNode[] {
     const seen = new Set<string>();
     return nodes.filter((n) => {
-      const key = `${n.file}:${n.name}`;
+      const key = `${n.file}:${n.line}:${n.name}`;
       if (seen.has(key)) {
         return false;
       }