@angular-modernizer/api 0.1.3 → 0.2.0

package/src/investigation/codebase-searcher.ts

@@ -12,6 +12,13 @@
  * `search`. For `symbol` mode only top-level named declarations are indexed;
  * local variables and anonymous expressions are not returned.
  *
+ * When `rootDir` is given, `text` and `pattern` modes additionally scan files
+ * under that directory which are NOT part of the ts-morph program: Angular
+ * templates (`.html`) and `.ts` files outside the tsconfig (for example
+ * `src/i18n/*.ts`). `node_modules`, `dist`, `.angular`, `coverage`, `out-tsc`
+ * and hidden directories are skipped. Use `searchWithCoverage` to learn how
+ * many files were actually searched.
+ *
  * @example
  * ```typescript
  * const searcher = new CodebaseSearcher(project);
@@ -27,7 +34,7 @@
  * ```
  */
 
-import type { Project } from 'ts-morph';
+import type { Project, SourceFile } from 'ts-morph';
 
 /** The kind of named declaration returned in symbol-mode results. */
 export type SymbolKind =
@@ -57,6 +64,36 @@ export interface SearchResult {
    * Absent in `text` and `pattern` modes.
    */
   symbolKind?: SymbolKind;
+
+  /**
+   * `program` when the file is part of the ts-morph program, `non-program`
+   * when it was found by the file-system scan (templates, non-program `.ts`).
+   */
+  source?: 'program' | 'non-program';
+}
+
+/** Describes which files a search actually covered. */
+export interface SearchCoverage {
+  /** Number of program source files searched (after the `include` filter). */
+  programFileCount: number;
+
+  /** Number of non-program files searched (templates, non-program `.ts`). */
+  extraFileCount: number;
+
+  /** Whether `.html` templates under `rootDir` were scanned. */
+  templatesScanned: boolean;
+
+  /** Whether `.ts` files outside the program were scanned. */
+  nonProgramFilesScanned: boolean;
+
+  /** Directory names that are never scanned. */
+  excludedDirectories: string[];
+}
+
+/** Result of `CodebaseSearcher.searchWithCoverage()`. */
+export interface SearchWithCoverageResult {
+  results: SearchResult[];
+  coverage: SearchCoverage;
 }
 
 /** Options for `CodebaseSearcher.search()`. */
@@ -80,6 +117,65 @@ export interface SearchOptions {
    * returned.
    */
   maxResults?: number;
+
+  /**
+   * Project root used to discover files that are not part of the ts-morph
+   * program. When omitted only program files are searched.
+   */
+  rootDir?: string;
+
+  /**
+   * Scan `.html` files under `rootDir` (text/pattern modes only).
+   * Defaults to `true` when `rootDir` is set.
+   */
+  includeTemplates?: boolean;
+
+  /**
+   * Scan `.ts` files under `rootDir` that are not part of the program
+   * (text/pattern modes only). Defaults to `true` when `rootDir` is set.
+   */
+  includeNonProgramFiles?: boolean;
+}
+
+/** Directory names never descended into by the non-program file scan. */
+export const EXCLUDED_SEARCH_DIRECTORIES = [
+  'node_modules',
+  'dist',
+  '.angular',
+  'coverage',
+  'out-tsc',
+] as const;
+
+/** A searchable file: path plus lazily loaded text. */
+interface SearchableFile {
+  path: string;
+  text: () => string;
+  source: 'program' | 'non-program';
+}
+
+function normalizePath(path: string): string {
+  return path.replaceAll('\\', '/');
+}
+
+function joinPath(dir: string, name: string): string {
+  const normalizedName = normalizePath(name);
+  if (normalizedName.startsWith('/') || /^[A-Za-z]:\//.test(normalizedName)) {
+    return normalizedName;
+  }
+  const base = normalizePath(dir).replace(/\/+$/, '');
+  return `${base}/${normalizedName}`;
+}
+
+function baseName(path: string): string {
+  const parts = normalizePath(path).split('/');
+  return parts[parts.length - 1] ?? path;
+}
+
+function isExcludedDirectory(name: string): boolean {
+  return (
+    name.startsWith('.') ||
+    (EXCLUDED_SEARCH_DIRECTORIES as readonly string[]).includes(name)
+  );
 }
 
 /**
@@ -116,7 +212,28 @@ export class CodebaseSearcher {
    * ```
    */
   search(query: string, options: SearchOptions): SearchResult[] {
-    const sourceFiles = this.project
+    return this.searchWithCoverage(query, options).results;
+  }
+
+  /**
+   * Like `search`, but also reports which files were covered. Callers should
+   * surface `coverage` whenever a search returns 0 hits: an empty result only
+   * proves absence within the covered files.
+   *
+   * @example
+   * ```typescript
+   * const { results, coverage } = searcher.searchWithCoverage('i18n.key', {
+   *   mode: 'text',
+   *   rootDir: '/project',
+   * });
+   * // coverage.programFileCount, coverage.extraFileCount
+   * ```
+   */
+  searchWithCoverage(
+    query: string,
+    options: SearchOptions,
+  ): SearchWithCoverageResult {
+    const programFiles = this.project
       .getSourceFiles()
       .filter(
         (sf) =>
@@ -124,15 +241,126 @@ export class CodebaseSearcher {
           matchesGlob(sf.getFilePath(), options.include),
       );
 
+    const scanExtras = options.mode !== 'symbol' && options.rootDir !== undefined;
+    const templatesScanned = scanExtras && options.includeTemplates !== false;
+    const nonProgramFilesScanned =
+      scanExtras && options.includeNonProgramFiles !== false;
+
+    const extraFiles =
+      options.rootDir === undefined
+        ? []
+        : this.collectNonProgramFiles(options.rootDir, {
+            html: templatesScanned,
+            ts: nonProgramFilesScanned,
+            include: options.include,
+          });
+
     const results: SearchResult[] =
       options.mode === 'symbol'
-        ? this.searchSymbols(query, sourceFiles)
-        : this.searchText(query, options.mode, sourceFiles);
+        ? this.searchSymbols(query, programFiles)
+        : this.searchText(query, options.mode, [
+            ...programFiles.map((sf) => this.toSearchable(sf)),
+            ...extraFiles,
+          ]);
 
-    if (options.maxResults !== undefined) {
-      return results.slice(0, options.maxResults);
+    const limited =
+      options.maxResults === undefined
+        ? results
+        : results.slice(0, options.maxResults);
+
+    return {
+      results: limited,
+      coverage: {
+        programFileCount: programFiles.length,
+        extraFileCount: extraFiles.length,
+        templatesScanned,
+        nonProgramFilesScanned,
+        excludedDirectories: [...EXCLUDED_SEARCH_DIRECTORIES, '.*'],
+      },
+    };
+  }
+
+  private toSearchable(sf: SourceFile): SearchableFile {
+    return {
+      path: sf.getFilePath(),
+      text: () => sf.getFullText(),
+      source: 'program',
+    };
+  }
+
+  /**
+   * Walks `rootDir` via the project's file system host (works for real and
+   * in-memory file systems) and returns files outside the program.
+   */
+  private collectNonProgramFiles(
+    rootDir: string,
+    filter: { html: boolean; ts: boolean; include: string | undefined },
+  ): SearchableFile[] {
+    if (!filter.html && !filter.ts) {
+      return [];
     }
-    return results;
+
+    const fs = this.project.getFileSystem();
+    const programPaths = new Set(
+      this.project.getSourceFiles().map((sf) => normalizePath(sf.getFilePath())),
+    );
+    const files: SearchableFile[] = [];
+    const pending: string[] = [normalizePath(rootDir)];
+    const visited = new Set<string>();
+
+    const wanted = (path: string): boolean => {
+      if (filter.html && path.endsWith('.html')) {
+        return true;
+      }
+      return filter.ts && path.endsWith('.ts') && !programPaths.has(path);
+    };
+
+    while (pending.length > 0) {
+      const dir = pending.pop();
+      if (dir === undefined || visited.has(dir)) {
+        continue;
+      }
+      visited.add(dir);
+
+      let entries: ReturnType<typeof fs.readDirSync>;
+      try {
+        entries = fs.readDirSync(dir);
+      } catch {
+        continue;
+      }
+
+      for (const entry of entries) {
+        const fullPath = joinPath(dir, entry.name);
+        if (entry.isDirectory) {
+          if (!entry.isSymlink && !isExcludedDirectory(baseName(fullPath))) {
+            pending.push(fullPath);
+          }
+          continue;
+        }
+        if (!entry.isFile || !wanted(fullPath)) {
+          continue;
+        }
+        if (
+          filter.include !== undefined &&
+          !matchesGlob(fullPath, filter.include)
+        ) {
+          continue;
+        }
+        files.push({
+          path: fullPath,
+          text: () => {
+            try {
+              return fs.readFileSync(fullPath);
+            } catch {
+              return '';
+            }
+          },
+          source: 'non-program',
+        });
+      }
+    }
+
+    return files.sort((a, b) => a.path.localeCompare(b.path));
   }
 
   /**
@@ -141,14 +369,14 @@ export class CodebaseSearcher {
   private searchText(
     query: string,
     mode: 'text' | 'pattern',
-    sourceFiles: ReturnType<Project['getSourceFiles']>,
+    files: SearchableFile[],
   ): 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');
+    for (const file of files) {
+      const filePath = file.path;
+      const lines = file.text().split('\n');
 
       lines.forEach((lineText, index) => {
         const matched =
@@ -168,6 +396,7 @@ export class CodebaseSearcher {
           line: index + 1,
           col,
           snippet: lineText.trim(),
+          source: file.source,
         });
       });
     }

package/src/investigation/template-usage-finder.ts

@@ -0,0 +1,389 @@
+/**
+ * @angular-modernizer/api - Template Usage Finder
+ *
+ * Project-level companion to `scanTemplate`: resolves what a symbol means
+ * in Angular templates (component/directive selector, pipe name, class
+ * member, input/output binding) and scans every component template
+ * (external `templateUrl` files and inline `template:` literals).
+ *
+ * @remarks
+ * Member hits are `verified` when they read the member from the component
+ * context (`foo`, `this.foo`) inside the template of the declaring class or
+ * one of its subclasses. Same-name reads elsewhere (other components, or
+ * `x.foo`) are reported as `template-unverified`: they may or may not refer
+ * to the searched member.
+ *
+ * @example
+ * ```typescript
+ * const finder = new TemplateUsageFinder(project);
+ * const usages = finder.findTemplateUsages('UserCardComponent', declarations);
+ * // [{ file: '/src/app/list.component.html', usageType: 'template', templateKind: 'element', ... }]
+ * ```
+ */
+
+import {
+  Node,
+  type ClassDeclaration,
+  type Decorator,
+  type Project,
+  type SourceFile,
+} from 'ts-morph';
+import { dirname, resolve } from 'node:path';
+import {
+  scanTemplate,
+  type TemplateHit,
+  type TemplateQuery,
+  type TemplateUsageKind,
+} from './template-usage-scanner.js';
+
+/** Whether a template hit is known to refer to the searched symbol. */
+export type TemplateMatch = 'verified' | 'template-unverified';
+
+/** A template usage mapped back to a file position. */
+export interface TemplateSymbolUsage {
+  /** Absolute path of the `.html` file, or of the `.ts` file for inline templates. */
+  file: string;
+
+  /** 1-based line. */
+  line: number;
+
+  /** 1-based column. */
+  col: number;
+
+  /** Trimmed source line. */
+  snippet: string;
+
+  /** Kind of template usage. */
+  templateKind: TemplateUsageKind;
+
+  /** Verification level (see class remarks). */
+  templateMatch: TemplateMatch;
+
+  /** Class name of the component that owns the template. */
+  component: string;
+
+  /** Explanation for unverified hits. */
+  note?: string;
+}
+
+const COMPONENT_DECORATORS = new Set(['Component', 'ExportComponent']);
+const DIRECTIVE_DECORATORS = new Set([
+  'Component',
+  'ExportComponent',
+  'Directive',
+]);
+const SIGNAL_BINDING_FACTORIES = new Set(['input', 'output', 'model']);
+
+interface ComponentTemplate {
+  owner: ClassDeclaration;
+  /** File the positions refer to. */
+  file: string;
+  content: string;
+  /** Maps an offset inside `content` to a 1-based line/column in `file`. */
+  locate: (offset: number) => { line: number; col: number; snippet: string };
+}
+
+interface MemberTarget {
+  owner: ClassDeclaration;
+  bindingNames: string[];
+}
+
+function findDecorator(
+  cls: ClassDeclaration,
+  names: Set<string>,
+): Decorator | undefined {
+  return cls.getDecorators().find((d) => names.has(d.getName()));
+}
+
+/** Reads a string-valued property (`selector`, `name`, `templateUrl`) from decorator metadata. */
+function readDecoratorString(
+  decorator: Decorator,
+  property: string,
+): { value: string; node: Node } | undefined {
+  const arg = decorator.getArguments()[0];
+  if (arg === undefined || !Node.isObjectLiteralExpression(arg)) {
+    return undefined;
+  }
+  const prop = arg.getProperty(property);
+  if (prop === undefined || !Node.isPropertyAssignment(prop)) {
+    return undefined;
+  }
+  const init = prop.getInitializer();
+  if (
+    init !== undefined &&
+    (Node.isStringLiteral(init) || Node.isNoSubstitutionTemplateLiteral(init))
+  ) {
+    return { value: init.getLiteralText(), node: init };
+  }
+  return undefined;
+}
+
+function lineInfo(
+  text: string,
+  offset: number,
+): { line: number; col: number; snippet: string } {
+  const before = text.slice(0, offset);
+  const line = before.split('\n').length;
+  const lineStart = before.lastIndexOf('\n') + 1;
+  const lineEnd = text.indexOf('\n', offset);
+  const snippet = text.slice(lineStart, lineEnd === -1 ? undefined : lineEnd);
+  return { line, col: offset - lineStart + 1, snippet: snippet.trim() };
+}
+
+/** Input/output names under which a member can be bound from a parent template. */
+function bindingNamesOf(member: Node): string[] {
+  const names: string[] = [];
+  const name = Node.hasName(member) ? member.getName() : undefined;
+
+  if (Node.isDecoratable(member)) {
+    for (const decorator of member.getDecorators()) {
+      const decoratorName = decorator.getName();
+      if (decoratorName !== 'Input' && decoratorName !== 'Output') {
+        continue;
+      }
+      const alias = decorator.getArguments()[0];
+      const aliasText =
+        alias !== undefined && Node.isStringLiteral(alias)
+          ? alias.getLiteralText()
+          : undefined;
+      names.push(aliasText ?? name ?? '');
+    }
+  }
+
+  if (Node.isPropertyDeclaration(member)) {
+    const init = member.getInitializer();
+    const callee =
+      init !== undefined && Node.isCallExpression(init)
+        ? init.getExpression().getText().split('.')[0]
+        : undefined;
+    if (callee !== undefined && SIGNAL_BINDING_FACTORIES.has(callee)) {
+      names.push(name ?? '');
+      if (callee === 'model' && name !== undefined) {
+        names.push(`${name}Change`);
+      }
+    }
+  }
+
+  return names.filter((n) => n !== '');
+}
+
+function inheritsFrom(cls: ClassDeclaration, owners: Set<ClassDeclaration>): boolean {
+  const seen = new Set<ClassDeclaration>();
+  let current: ClassDeclaration | undefined = cls;
+  while (current !== undefined && !seen.has(current)) {
+    if (owners.has(current)) {
+      return true;
+    }
+    seen.add(current);
+    current = current.getBaseClass();
+  }
+  return false;
+}
+
+/**
+ * Finds usages of a symbol inside Angular component templates.
+ */
+export class TemplateUsageFinder {
+  constructor(private readonly project: Project) {}
+
+  /**
+   * @param symbol - Searched name (class, member, or pipe class name).
+   * @param declarations - Declaration nodes named `symbol` (as found by `UsageFinder`).
+   * @returns Template usages, unsorted.
+   */
+  findTemplateUsages(symbol: string, declarations: Node[]): TemplateSymbolUsage[] {
+    const selectorTargets: string[] = [];
+    const pipeNames: string[] = [];
+    const members: MemberTarget[] = [];
+
+    for (const decl of declarations) {
+      if (Node.isClassDeclaration(decl)) {
+        const directive = findDecorator(decl, DIRECTIVE_DECORATORS);
+        const selector =
+          directive === undefined
+            ? undefined
+            : readDecoratorString(directive, 'selector')?.value;
+        if (selector !== undefined) {
+          selectorTargets.push(selector);
+        }
+        const pipe = findDecorator(decl, new Set(['Pipe']));
+        const pipeName =
+          pipe === undefined ? undefined : readDecoratorString(pipe, 'name')?.value;
+        if (pipeName !== undefined) {
+          pipeNames.push(pipeName);
+        }
+        continue;
+      }
+
+      // Parameter properties live in the constructor; other members directly in the class.
+      const ownerClass = Node.isParameterDeclaration(decl)
+        ? decl.getParent().getParent()
+        : decl.getParent();
+      const isMember =
+        ownerClass !== undefined &&
+        Node.isClassDeclaration(ownerClass) &&
+        (Node.isMethodDeclaration(decl) ||
+          Node.isPropertyDeclaration(decl) ||
+          Node.isGetAccessorDeclaration(decl) ||
+          Node.isSetAccessorDeclaration(decl) ||
+          (Node.isParameterDeclaration(decl) && decl.isParameterProperty()));
+      if (isMember && Node.isClassDeclaration(ownerClass)) {
+        members.push({ owner: ownerClass, bindingNames: bindingNamesOf(decl) });
+      }
+    }
+
+    const hasClassTarget = selectorTargets.length > 0 || pipeNames.length > 0;
+    const scanMembers = members.length > 0 || declarations.length === 0;
+    if (!hasClassTarget && !scanMembers) {
+      return [];
+    }
+
+    const queries = this.buildQueries(symbol, selectorTargets, pipeNames, members, scanMembers);
+    const memberOwners = new Set(members.map((m) => m.owner));
+    const usages: TemplateSymbolUsage[] = [];
+
+    for (const template of this.collectTemplates()) {
+      for (const query of queries) {
+        for (const hit of scanTemplate(template.content, query)) {
+          usages.push(this.toUsage(template, hit, memberOwners));
+        }
+      }
+    }
+
+    return usages;
+  }
+
+  private buildQueries(
+    symbol: string,
+    selectors: string[],
+    pipeNames: string[],
+    members: MemberTarget[],
+    scanMembers: boolean,
+  ): TemplateQuery[] {
+    const queries: TemplateQuery[] = [];
+    for (const selector of selectors) {
+      queries.push({ selector });
+    }
+    for (const pipeName of pipeNames) {
+      queries.push({ pipeName });
+    }
+    if (scanMembers) {
+      queries.push({ memberName: symbol });
+    }
+    for (const member of members) {
+      const directive = findDecorator(member.owner, DIRECTIVE_DECORATORS);
+      const bindingSelector =
+        directive === undefined
+          ? undefined
+          : readDecoratorString(directive, 'selector')?.value;
+      if (bindingSelector === undefined) {
+        continue;
+      }
+      for (const bindingName of member.bindingNames) {
+        queries.push({ bindingName, bindingSelector });
+      }
+    }
+    return queries;
+  }
+
+  private toUsage(
+    template: ComponentTemplate,
+    hit: TemplateHit,
+    memberOwners: Set<ClassDeclaration>,
+  ): TemplateSymbolUsage {
+    const position = template.locate(hit.offset);
+    const isMemberHit = hit.implicitReceiver !== undefined;
+    const verified =
+      !isMemberHit ||
+      (hit.implicitReceiver === true && inheritsFrom(template.owner, memberOwners));
+    const component = template.owner.getName() ?? '<anonymous>';
+
+    return {
+      file: template.file,
+      line: position.line,
+      col: position.col,
+      snippet: position.snippet,
+      templateKind: hit.kind,
+      templateMatch: verified ? 'verified' : 'template-unverified',
+      component,
+      ...(verified
+        ? {}
+        : {
+            note:
+              hit.implicitReceiver === true
+                ? `Same-name member used in the template of ${component}, which does not declare or inherit the searched member.`
+                : `Same-name property accessed on another object ('x.${hit.name}') in the template of ${component}; receiver type not checked.`,
+          }),
+    };
+  }
+
+  /** All component templates in the project (inline and external). */
+  private collectTemplates(): ComponentTemplate[] {
+    const templates: ComponentTemplate[] = [];
+    for (const sf of this.project.getSourceFiles()) {
+      if (sf.isDeclarationFile() || sf.isInNodeModules()) {
+        continue;
+      }
+      for (const cls of sf.getClasses()) {
+        const component = findDecorator(cls, COMPONENT_DECORATORS);
+        if (component === undefined) {
+          continue;
+        }
+        const template = this.loadTemplate(sf, cls, component);
+        if (template !== undefined) {
+          templates.push(template);
+        }
+      }
+    }
+    return templates;
+  }
+
+  private loadTemplate(
+    sf: SourceFile,
+    owner: ClassDeclaration,
+    decorator: Decorator,
+  ): ComponentTemplate | undefined {
+    const inline = readDecoratorString(decorator, 'template');
+    if (inline !== undefined) {
+      // Raw text between the delimiters keeps offsets aligned with the .ts file.
+      const literalStart = inline.node.getStart() + 1;
+      const content = inline.node.getText().slice(1, -1);
+      return {
+        owner,
+        file: sf.getFilePath(),
+        content,
+        locate: (offset) => {
+          const pos = literalStart + offset;
+          const { line, column } = sf.getLineAndColumnAtPos(pos);
+          const snippet = sf.getFullText().split('\n')[line - 1] ?? '';
+          return { line, col: column, snippet: snippet.trim() };
+        },
+      };
+    }
+
+    const templateUrl = readDecoratorString(decorator, 'templateUrl');
+    if (templateUrl === undefined) {
+      return undefined;
+    }
+    const file = resolve(dirname(sf.getFilePath()), templateUrl.value).replaceAll(
+      '\\',
+      '/',
+    );
+    const fs = this.project.getFileSystem();
+    let content: string;
+    try {
+      if (!fs.fileExistsSync(file)) {
+        return undefined;
+      }
+      content = fs.readFileSync(file);
+    } catch {
+      return undefined;
+    }
+    return {
+      owner,
+      file,
+      content,
+      locate: (offset) => lineInfo(content, offset),
+    };
+  }
+}