@angular-modernizer/api 0.1.3 → 0.2.0

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

@@ -0,0 +1,529 @@
+/**
+ * @angular-modernizer/api - Template Usage Scanner
+ *
+ * Parses a single Angular template with `@angular/compiler` and reports
+ * where a selector, pipe, class member, or input/output binding is used.
+ * Positions are returned as offsets into the template text so callers can
+ * map them to external `.html` files or to inline `template:` literals.
+ *
+ * @remarks
+ * Pure function over template text; it knows nothing about ts-morph. The
+ * project-level lookup (which templates belong to which class, selector and
+ * pipe resolution) lives in `TemplateUsageFinder`.
+ *
+ * @example
+ * ```typescript
+ * const hits = scanTemplate('<app-user (saved)="onSave()"></app-user>', {
+ *   selector: 'app-user',
+ *   memberName: 'onSave',
+ * });
+ * // [{ kind: 'element', ... }, { kind: 'method-call', implicitReceiver: true, ... }]
+ * ```
+ */
+
+import {
+  CssSelector,
+  ImplicitReceiver,
+  PropertyRead,
+  RecursiveAstVisitor,
+  SelectorMatcher,
+  TmplAstBoundAttribute,
+  TmplAstBoundDeferredTrigger,
+  TmplAstElement,
+  TmplAstRecursiveVisitor,
+  createCssSelectorFromNode,
+  parseTemplate,
+  tmplAstVisitAll,
+  type AST,
+  type BindingPipe,
+  type Call,
+  type PropertyWrite,
+  type SafeCall,
+  type SafePropertyRead,
+  type TmplAstBoundEvent,
+  type TmplAstBoundText,
+  type TmplAstDeferredTrigger,
+  type TmplAstForLoopBlock,
+  type TmplAstIfBlockBranch,
+  type TmplAstSwitchBlock,
+  type TmplAstSwitchBlockCase,
+  type TmplAstTemplate,
+} from '@angular/compiler';
+
+/** How a template refers to the searched symbol. */
+export type TemplateUsageKind =
+  | 'element'
+  | 'attribute'
+  | 'pipe'
+  | 'property-read'
+  | 'property-write'
+  | 'method-call'
+  | 'input-binding'
+  | 'output-binding';
+
+/** What to look for in a template. All fields are optional and combinable. */
+export interface TemplateQuery {
+  /** Component/directive CSS selector (may be a selector list). */
+  selector?: string;
+
+  /** Pipe name as used in templates (`{{ x | name }}`). */
+  pipeName?: string;
+
+  /** Class member name read, written, or called in expressions. */
+  memberName?: string;
+
+  /** Input/output name bound as `[name]`, `name="..."` or `(name)`. */
+  bindingName?: string;
+
+  /**
+   * Restricts `bindingName` matches to elements matching this selector.
+   * When omitted, bindings on any element match.
+   */
+  bindingSelector?: string;
+}
+
+/** A single match inside a template. */
+export interface TemplateHit {
+  /** 0-based offset into the template text. */
+  offset: number;
+
+  /** Kind of usage. */
+  kind: TemplateUsageKind;
+
+  /** Matched name (selector, pipe, member, or binding name). */
+  name: string;
+
+  /**
+   * For member hits: `true` when the expression reads the member from the
+   * component context (`foo`, `this.foo`), `false` for `x.foo`.
+   */
+  implicitReceiver?: boolean;
+}
+
+interface SpanLike {
+  start: number;
+  end: number;
+}
+
+function isImplicit(receiver: AST): boolean {
+  return receiver instanceof ImplicitReceiver;
+}
+
+function createMatcher(selector: string | undefined): {
+  matches: (node: TmplAstElement | TmplAstTemplate) => boolean;
+  elementNames: Set<string>;
+} | null {
+  if (selector === undefined || selector.trim() === '') {
+    return null;
+  }
+
+  let parsed: CssSelector[];
+  try {
+    parsed = CssSelector.parse(selector);
+  } catch {
+    return null;
+  }
+
+  const matcher = new SelectorMatcher<string>();
+  matcher.addSelectables(parsed, selector);
+  const elementNames = new Set(
+    parsed.map((s) => s.element).filter((e): e is string => e !== null),
+  );
+
+  return {
+    elementNames,
+    matches: (node) => {
+      let matched = false;
+      matcher.match(createCssSelectorFromNode(node), () => {
+        matched = true;
+      });
+      return matched;
+    },
+  };
+}
+
+/** Constructor of the template walker (created lazily, see below). */
+type HitCollectorClass = new (
+  query: TemplateQuery,
+  content: string,
+  hits: TemplateHit[],
+) => TmplAstRecursiveVisitor;
+
+/**
+ * Builds the visitor classes on first use instead of at module load.
+ *
+ * Several packages replace `@angular/compiler` with a minimal Jest mock that
+ * lacks the visitor base classes; extending them at module scope would make
+ * every import of `@angular-modernizer/api` throw. When the base classes are
+ * missing, template scanning is disabled (returns no hits).
+ */
+function createHitCollectorClass(): HitCollectorClass | null {
+  const compilerAvailable =
+    typeof (RecursiveAstVisitor as unknown) === 'function' &&
+    typeof (TmplAstRecursiveVisitor as unknown) === 'function';
+  if (!compilerAvailable) {
+    return null;
+  }
+
+  /**
+   * Walks template expressions (bindings, interpolations, block expressions).
+   */
+  class ExpressionHitCollector extends RecursiveAstVisitor {
+    private readonly callReceivers = new Set<AST>();
+
+    constructor(
+      private readonly query: TemplateQuery,
+      private readonly content: string,
+      private readonly hits: TemplateHit[],
+    ) {
+      super();
+    }
+
+    private nameOffset(span: SpanLike, name: string): number {
+      const found = this.content.indexOf(name, span.start);
+      return found !== -1 && found < span.end ? found : span.start;
+    }
+
+    private recordMember(
+      kind: TemplateUsageKind,
+      name: string,
+      span: SpanLike,
+      implicitReceiver: boolean,
+    ): void {
+      this.hits.push({
+        offset: this.nameOffset(span, name),
+        kind,
+        name,
+        implicitReceiver,
+      });
+    }
+
+    private checkCallee(receiver: AST): void {
+      const member = this.query.memberName;
+      if (member === undefined) {
+        return;
+      }
+      const isRead = receiver instanceof PropertyRead;
+      const readName = isRead ? receiver.name : undefined;
+      if (!isRead || readName !== member) {
+        return;
+      }
+      this.callReceivers.add(receiver);
+      this.recordMember(
+        'method-call',
+        member,
+        receiver.nameSpan,
+        isImplicit(receiver.receiver),
+      );
+    }
+
+    override visitCall(ast: Call, context: unknown): void {
+      this.checkCallee(ast.receiver);
+      super.visitCall(ast, context);
+    }
+
+    override visitSafeCall(ast: SafeCall, context: unknown): void {
+      this.checkCallee(ast.receiver);
+      super.visitSafeCall(ast, context);
+    }
+
+    override visitPropertyRead(ast: PropertyRead, context: unknown): void {
+      const isMember =
+        ast.name === this.query.memberName && !this.callReceivers.has(ast);
+      if (isMember) {
+        this.recordMember(
+          'property-read',
+          ast.name,
+          ast.nameSpan,
+          isImplicit(ast.receiver),
+        );
+      }
+      super.visitPropertyRead(ast, context);
+    }
+
+    override visitSafePropertyRead(ast: SafePropertyRead, context: unknown): void {
+      if (ast.name === this.query.memberName) {
+        this.recordMember('property-read', ast.name, ast.nameSpan, false);
+      }
+      super.visitSafePropertyRead(ast, context);
+    }
+
+    override visitPropertyWrite(ast: PropertyWrite, context: unknown): void {
+      if (ast.name === this.query.memberName) {
+        this.recordMember(
+          'property-write',
+          ast.name,
+          ast.nameSpan,
+          isImplicit(ast.receiver),
+        );
+      }
+      super.visitPropertyWrite(ast, context);
+    }
+
+    override visitPipe(ast: BindingPipe, context: unknown): void {
+      if (ast.name === this.query.pipeName) {
+        this.hits.push({
+          offset: this.nameOffset(ast.nameSpan, ast.name),
+          kind: 'pipe',
+          name: ast.name,
+        });
+      }
+      super.visitPipe(ast, context);
+    }
+
+    scan(ast: AST | null | undefined): void {
+      if (ast === null || ast === undefined) {
+        return;
+      }
+      ast.visit(this);
+    }
+  }
+
+  /**
+   * Walks the template node tree: selector matches, bindings, and every
+   * embedded expression (delegated to {@link ExpressionHitCollector}).
+   */
+  class TemplateHitCollector extends TmplAstRecursiveVisitor {
+    private readonly selectorMatcher: ReturnType<typeof createMatcher>;
+    private readonly bindingMatcher: ReturnType<typeof createMatcher>;
+    private readonly expressions: ExpressionHitCollector;
+
+    constructor(
+      private readonly query: TemplateQuery,
+      content: string,
+      private readonly hits: TemplateHit[],
+    ) {
+      super();
+      this.selectorMatcher = createMatcher(query.selector);
+      this.bindingMatcher = createMatcher(query.bindingSelector);
+      this.expressions = new ExpressionHitCollector(query, content, hits);
+    }
+
+    private selectorHit(node: TmplAstElement | TmplAstTemplate): void {
+      const matcher = this.selectorMatcher;
+      if (!matcher?.matches(node)) {
+        return;
+      }
+      const isElement =
+        node instanceof TmplAstElement && matcher.elementNames.has(node.name);
+      const selector = this.query.selector ?? '';
+      this.hits.push({
+        offset: isElement
+          ? node.startSourceSpan.start.offset + 1
+          : this.attributeOffset(node),
+        kind: isElement ? 'element' : 'attribute',
+        name: selector,
+      });
+    }
+
+    /** Offset of the first attribute/binding named in the selector, else the tag. */
+    private attributeOffset(node: TmplAstElement | TmplAstTemplate): number {
+      const attrNames = new Set<string>();
+      try {
+        for (const s of CssSelector.parse(this.query.selector ?? '')) {
+          for (let i = 0; i < s.attrs.length; i += 2) {
+            const attr = s.attrs[i];
+            if (attr !== undefined) {
+              attrNames.add(attr);
+            }
+          }
+        }
+      } catch {
+        // fall through to the tag offset
+      }
+
+      const candidates = [
+        ...node.attributes,
+        ...node.inputs,
+        ...node.outputs,
+        ...('templateAttrs' in node ? node.templateAttrs : []),
+      ];
+      const hit = candidates.find((a) => attrNames.has(a.name));
+      return hit?.keySpan?.start.offset ?? node.startSourceSpan.start.offset;
+    }
+
+    private bindingAllowed(node: TmplAstElement | TmplAstTemplate): boolean {
+      if (this.query.bindingName === undefined) {
+        return false;
+      }
+      return this.bindingMatcher === null || this.bindingMatcher.matches(node);
+    }
+
+    private bindingHits(node: TmplAstElement | TmplAstTemplate): void {
+      const name = this.query.bindingName;
+      if (name === undefined || !this.bindingAllowed(node)) {
+        return;
+      }
+      for (const input of node.inputs) {
+        if (input.name === name) {
+          this.hits.push({
+            offset: input.keySpan.start.offset,
+            kind: 'input-binding',
+            name,
+          });
+        }
+      }
+      for (const attr of node.attributes) {
+        if (attr.name === name) {
+          this.hits.push({
+            offset: attr.keySpan?.start.offset ?? attr.sourceSpan.start.offset,
+            kind: 'input-binding',
+            name,
+          });
+        }
+      }
+      for (const output of node.outputs) {
+        if (output.name === name) {
+          this.hits.push({
+            offset: output.keySpan.start.offset,
+            kind: 'output-binding',
+            name,
+          });
+        }
+      }
+    }
+
+    override visitElement(element: TmplAstElement): void {
+      this.selectorHit(element);
+      this.bindingHits(element);
+      super.visitElement(element);
+    }
+
+    override visitTemplate(template: TmplAstTemplate): void {
+      this.selectorHit(template);
+      this.bindingHits(template);
+      // The base visitor skips `*directive="expr"` attributes.
+      for (const attr of template.templateAttrs) {
+        if (attr instanceof TmplAstBoundAttribute) {
+          this.expressions.scan(attr.value);
+        }
+      }
+      super.visitTemplate(template);
+    }
+
+    override visitBoundAttribute(attribute: TmplAstBoundAttribute): void {
+      this.expressions.scan(attribute.value);
+    }
+
+    override visitBoundEvent(event: TmplAstBoundEvent): void {
+      this.expressions.scan(event.handler);
+    }
+
+    override visitBoundText(text: TmplAstBoundText): void {
+      this.expressions.scan(text.value);
+    }
+
+    override visitIfBlockBranch(block: TmplAstIfBlockBranch): void {
+      this.expressions.scan(block.expression);
+      super.visitIfBlockBranch(block);
+    }
+
+    override visitForLoopBlock(block: TmplAstForLoopBlock): void {
+      this.expressions.scan(block.expression);
+      this.expressions.scan(block.trackBy);
+      super.visitForLoopBlock(block);
+    }
+
+    override visitSwitchBlock(block: TmplAstSwitchBlock): void {
+      this.expressions.scan(block.expression);
+      super.visitSwitchBlock(block);
+    }
+
+    override visitSwitchBlockCase(block: TmplAstSwitchBlockCase): void {
+      this.expressions.scan(block.expression);
+      super.visitSwitchBlockCase(block);
+    }
+
+    override visitDeferredTrigger(trigger: TmplAstDeferredTrigger): void {
+      if (trigger instanceof TmplAstBoundDeferredTrigger) {
+        this.expressions.scan(trigger.value);
+      }
+    }
+  }
+
+  return TemplateHitCollector;
+}
+
+let hitCollectorClass: HitCollectorClass | null | undefined;
+
+function getHitCollectorClass(): HitCollectorClass | null {
+  if (hitCollectorClass === undefined) {
+    hitCollectorClass = createHitCollectorClass();
+  }
+  return hitCollectorClass;
+}
+
+/**
+ * Cheap pre-check: can the template possibly contain a hit for `query`?
+ * Avoids parsing templates that do not mention any searched token.
+ */
+export function templateMayMatch(content: string, query: TemplateQuery): boolean {
+  const tokens: string[] = [];
+  if (query.pipeName !== undefined) {
+    tokens.push(query.pipeName);
+  }
+  if (query.memberName !== undefined) {
+    tokens.push(query.memberName);
+  }
+  if (query.bindingName !== undefined) {
+    tokens.push(query.bindingName);
+  }
+  if (query.selector !== undefined) {
+    try {
+      for (const s of CssSelector.parse(query.selector)) {
+        if (s.element !== null && s.element !== '*') {
+          tokens.push(s.element);
+        }
+        for (let i = 0; i < s.attrs.length; i += 2) {
+          const attr = s.attrs[i];
+          if (attr !== undefined && attr !== '') {
+            tokens.push(attr);
+          }
+        }
+        tokens.push(...s.classNames);
+      }
+    } catch {
+      return true;
+    }
+  }
+  return tokens.some((t) => content.includes(t));
+}
+
+/**
+ * Scans one template for usages described by `query`.
+ *
+ * @param content - Raw template text.
+ * @param query - What to look for.
+ * @returns Hits ordered by offset. Returns `[]` when the template cannot be
+ *   parsed at all.
+ */
+export function scanTemplate(content: string, query: TemplateQuery): TemplateHit[] {
+  const Collector = getHitCollectorClass();
+  if (Collector === null || !templateMayMatch(content, query)) {
+    return [];
+  }
+
+  let nodes: ReturnType<typeof parseTemplate>['nodes'];
+  try {
+    nodes = parseTemplate(content, 'template.html', {
+      preserveWhitespaces: true,
+    }).nodes;
+  } catch {
+    return [];
+  }
+
+  const hits: TemplateHit[] = [];
+  tmplAstVisitAll(new Collector(query, content, hits), nodes);
+
+  const seen = new Set<string>();
+  return hits
+    .filter((h) => {
+      const key = `${h.offset}:${h.kind}`;
+      if (seen.has(key)) {
+        return false;
+      }
+      seen.add(key);
+      return true;
+    })
+    .sort((a, b) => a.offset - b.offset);
+}