@angular-modernizer/api 0.1.3 → 0.2.0

package/src/investigation/usage-finder.ts

@@ -9,6 +9,14 @@
  * Uses ts-morph `findReferences()` under the hood. The project must already have
  * the relevant source files added before calling `findUsages`.
  *
+ * Two additional sources close gaps that would otherwise produce a false
+ * "0 usages" all-clear:
+ * - `unresolved`: same-name identifiers whose symbol does not resolve (e.g. a
+ *   class still used as a type after its import was removed, TS2304).
+ * - `template`: Angular template usages (component/directive selectors, pipe
+ *   names, member reads/calls/bindings) in `templateUrl` files and inline
+ *   templates, see `TemplateUsageFinder`.
+ *
  * @example
  * ```typescript
  * const finder = new UsageFinder(project);
@@ -17,10 +25,21 @@
  * ```
  */
 
-import type { Project, Node } from 'ts-morph';
+import { Node, type Project, type SourceFile } from 'ts-morph';
+import {
+  TemplateUsageFinder,
+  type TemplateMatch,
+} from './template-usage-finder.js';
+import { type TemplateUsageKind } from './template-usage-scanner.js';
 
-/** Classification of how a symbol is used at a given location. */
-export type UsageType = 'read' | 'write' | 'call';
+/**
+ * Classification of how a symbol is used at a given location.
+ *
+ * - `read` / `write` / `call`: resolved TypeScript references
+ * - `template`: usage inside an Angular template (see `templateKind`)
+ * - `unresolved`: same-name identifier whose symbol does not resolve
+ */
+export type UsageType = 'read' | 'write' | 'call' | 'template' | 'unresolved';
 
 /** A single resolved symbol usage. */
 export interface SymbolUsage {
@@ -38,13 +57,30 @@ export interface SymbolUsage {
 
   /** How the symbol is used at this location. */
   usageType: UsageType;
+
+  /** Explanation for `unresolved` and unverified `template` usages. */
+  note?: string;
+
+  /** For `template` usages: what kind of template construct matched. */
+  templateKind?: TemplateUsageKind;
+
+  /**
+   * For `template` usages: `verified` when the hit certainly refers to the
+   * searched symbol, `template-unverified` for same-name matches that could
+   * not be tied to it.
+   */
+  templateMatch?: TemplateMatch;
+
+  /** For `template` usages: the component whose template contains the hit. */
+  component?: string;
 }
 
 /** 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.
+   * Restrict reported usages to a single file (absolute path; a `.ts` source
+   * file or an external `.html` template). Declarations are still looked up
+   * across the whole project.
    */
   file?: string;
 
@@ -53,6 +89,12 @@ export interface FindUsagesOptions {
    * When omitted, all usage types are returned.
    */
   usageType?: UsageType;
+
+  /** Include Angular template usages. Defaults to `true`. */
+  includeTemplates?: boolean;
+
+  /** Include same-name identifiers that do not resolve to a symbol. Defaults to `true`. */
+  includeUnresolved?: boolean;
 }
 
 /**
@@ -72,69 +114,134 @@ export class UsageFinder {
    * @returns Array of resolved usages, sorted by file path then line number.
    */
   findUsages(symbol: string, options: FindUsagesOptions = {}): SymbolUsage[] {
+    const declarations = this.project
+      .getSourceFiles()
+      .flatMap((sf) => this.findSymbolNodes(sf, symbol));
+
+    const usages: SymbolUsage[] = [
+      ...this.findReferenceUsages(declarations),
+      ...(options.includeUnresolved === false
+        ? []
+        : this.findUnresolvedUsages(symbol)),
+      ...(options.includeTemplates === false
+        ? []
+        : this.findTemplateUsages(symbol, declarations)),
+    ];
+
+    const fileFilter =
+      options.file === undefined ? undefined : normalizePath(options.file);
+
+    return this.deduplicate(usages)
+      .filter(
+        (u) => fileFilter === undefined || normalizePath(u.file) === fileFilter,
+      )
+      .filter(
+        (u) => options.usageType === undefined || u.usageType === options.usageType,
+      )
+      .sort((a, b) =>
+        a.file === b.file ? a.line - b.line || a.col - b.col : a.file.localeCompare(b.file),
+      );
+  }
+
+  private findReferenceUsages(declarations: Node[]): SymbolUsage[] {
     const usages: SymbolUsage[] = [];
+    const languageService = this.project.getLanguageService();
+
+    for (const node of declarations) {
+      // Query by the name node: a decorated class starts at its decorator.
+      for (const refSymbol of languageService.findReferences(nameNodeOf(node))) {
+        for (const ref of refSymbol.getReferences()) {
+          const refFile = ref.getSourceFile();
+          const pos = ref.getNode().getStart();
+          const lineAndCol = refFile.getLineAndColumnAtPos(pos);
+
+          usages.push({
+            file: refFile.getFilePath(),
+            line: lineAndCol.line,
+            col: lineAndCol.column,
+            snippet: lineTextAt(refFile, lineAndCol.line),
+            usageType: this.classifyUsage(ref.getNode()),
+          });
+        }
+      }
+    }
 
-    const sourceFiles = options.file
-      ? [this.project.getSourceFile(options.file)].filter(Boolean)
-      : this.project.getSourceFiles();
+    return usages;
+  }
+
+  /**
+   * Same-name identifiers whose symbol does not resolve. The language
+   * service cannot link them to any declaration, so `findReferences` never
+   * returns them; without this pass a removed import looks like "0 usages".
+   */
+  private findUnresolvedUsages(symbol: string): SymbolUsage[] {
+    const usages: SymbolUsage[] = [];
 
-    for (const sourceFile of sourceFiles) {
-      if (!sourceFile) {
+    for (const sf of this.project.getSourceFiles()) {
+      if (sf.isDeclarationFile() || sf.isInNodeModules()) {
+        continue;
+      }
+      if (!sf.getFullText().includes(symbol)) {
         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,
-            });
-          }
+      sf.forEachDescendant((node) => {
+        if (!Node.isIdentifier(node) || node.getText() !== symbol) {
+          return;
         }
-      }
+        const resolved = node.getSymbol();
+        const isResolved =
+          resolved !== undefined && resolved.getDeclarations().length > 0;
+        if (isResolved) {
+          return;
+        }
+
+        const { line, column } = sf.getLineAndColumnAtPos(node.getStart());
+        usages.push({
+          file: sf.getFilePath(),
+          line,
+          col: column,
+          snippet: lineTextAt(sf, line),
+          usageType: 'unresolved',
+          note: unresolvedNote(node, symbol),
+        });
+      });
     }
 
-    return this.deduplicate(usages).sort((a, b) =>
-      a.file !== b.file ? a.file.localeCompare(b.file) : a.line - b.line,
-    );
+    return usages;
   }
 
-  private findSymbolNodes(
-    sourceFile: ReturnType<Project['getSourceFile']>,
-    symbol: string,
-  ) {
-    if (!sourceFile) {
-      return [];
-    }
+  private findTemplateUsages(symbol: string, declarations: Node[]): SymbolUsage[] {
+    return new TemplateUsageFinder(this.project)
+      .findTemplateUsages(symbol, declarations)
+      .map((t) => ({
+        file: t.file,
+        line: t.line,
+        col: t.col,
+        snippet: t.snippet,
+        usageType: 'template' as const,
+        templateKind: t.templateKind,
+        templateMatch: t.templateMatch,
+        component: t.component,
+        ...(t.note === undefined ? {} : { note: t.note }),
+      }));
+  }
 
+  /**
+   * Declaration-like nodes named `symbol`. Expressions that merely carry a
+   * name (`svc.getUser` property accesses) are not declarations and would
+   * make `findReferences` resolve their receiver instead.
+   */
+  private findSymbolNodes(sourceFile: SourceFile, symbol: string): Node[] {
     const nodes: Node[] = [];
 
     sourceFile.forEachDescendant((node) => {
+      if (
+        Node.isPropertyAccessExpression(node) ||
+        Node.isElementAccessExpression(node)
+      ) {
+        return;
+      }
       if (
         'getName' in node &&
         typeof (node as { getName(): string }).getName === 'function'
@@ -187,7 +294,7 @@ export class UsageFinder {
   private deduplicate(usages: SymbolUsage[]): SymbolUsage[] {
     const seen = new Set<string>();
     return usages.filter((u) => {
-      const key = `${u.file}:${u.line}:${u.col}`;
+      const key = `${u.file}:${u.line}:${u.col}:${u.templateKind ?? ''}`;
       if (seen.has(key)) {
         return false;
       }
@@ -196,3 +303,36 @@ export class UsageFinder {
     });
   }
 }
+
+function normalizePath(path: string): string {
+  return path.replaceAll('\\', '/');
+}
+
+function lineTextAt(sourceFile: SourceFile, line: number): string {
+  return (sourceFile.getFullText().split('\n')[line - 1] ?? '').trim();
+}
+
+function unresolvedNote(node: Node, symbol: string): string {
+  const parent = node.getParent();
+  const isMemberName =
+    parent !== undefined &&
+    Node.isPropertyAccessExpression(parent) &&
+    parent.getNameNode() === node;
+  if (isMemberName) {
+    return (
+      `'${symbol}' is accessed on a receiver whose type is 'any' or unresolved; ` +
+      'it may or may not refer to the searched member.'
+    );
+  }
+  return (
+    `'${symbol}' does not resolve to any declaration (missing import or ` +
+    'removed symbol, typically TS2304/TS2552). The file still depends on it.'
+  );
+}
+
+function nameNodeOf(node: Node): Node {
+  const named = node as { getNameNode?: () => Node | undefined };
+  return typeof named.getNameNode === 'function'
+    ? (named.getNameNode() ?? node)
+    : node;
+}