@angular-modernizer/api 0.1.3 → 0.2.0

package/dist/investigation/template-usage-scanner.js

@@ -0,0 +1,375 @@
+/**
+ * @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, } from '@angular/compiler';
+function isImplicit(receiver) {
+    return receiver instanceof ImplicitReceiver;
+}
+function createMatcher(selector) {
+    if (selector === undefined || selector.trim() === '') {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = CssSelector.parse(selector);
+    }
+    catch {
+        return null;
+    }
+    const matcher = new SelectorMatcher();
+    matcher.addSelectables(parsed, selector);
+    const elementNames = new Set(parsed.map((s) => s.element).filter((e) => e !== null));
+    return {
+        elementNames,
+        matches: (node) => {
+            let matched = false;
+            matcher.match(createCssSelectorFromNode(node), () => {
+                matched = true;
+            });
+            return matched;
+        },
+    };
+}
+/**
+ * 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() {
+    const compilerAvailable = typeof RecursiveAstVisitor === 'function' &&
+        typeof TmplAstRecursiveVisitor === 'function';
+    if (!compilerAvailable) {
+        return null;
+    }
+    /**
+     * Walks template expressions (bindings, interpolations, block expressions).
+     */
+    class ExpressionHitCollector extends RecursiveAstVisitor {
+        query;
+        content;
+        hits;
+        callReceivers = new Set();
+        constructor(query, content, hits) {
+            super();
+            this.query = query;
+            this.content = content;
+            this.hits = hits;
+        }
+        nameOffset(span, name) {
+            const found = this.content.indexOf(name, span.start);
+            return found !== -1 && found < span.end ? found : span.start;
+        }
+        recordMember(kind, name, span, implicitReceiver) {
+            this.hits.push({
+                offset: this.nameOffset(span, name),
+                kind,
+                name,
+                implicitReceiver,
+            });
+        }
+        checkCallee(receiver) {
+            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));
+        }
+        visitCall(ast, context) {
+            this.checkCallee(ast.receiver);
+            super.visitCall(ast, context);
+        }
+        visitSafeCall(ast, context) {
+            this.checkCallee(ast.receiver);
+            super.visitSafeCall(ast, context);
+        }
+        visitPropertyRead(ast, context) {
+            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);
+        }
+        visitSafePropertyRead(ast, context) {
+            if (ast.name === this.query.memberName) {
+                this.recordMember('property-read', ast.name, ast.nameSpan, false);
+            }
+            super.visitSafePropertyRead(ast, context);
+        }
+        visitPropertyWrite(ast, context) {
+            if (ast.name === this.query.memberName) {
+                this.recordMember('property-write', ast.name, ast.nameSpan, isImplicit(ast.receiver));
+            }
+            super.visitPropertyWrite(ast, context);
+        }
+        visitPipe(ast, context) {
+            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) {
+            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 {
+        query;
+        hits;
+        selectorMatcher;
+        bindingMatcher;
+        expressions;
+        constructor(query, content, hits) {
+            super();
+            this.query = query;
+            this.hits = hits;
+            this.selectorMatcher = createMatcher(query.selector);
+            this.bindingMatcher = createMatcher(query.bindingSelector);
+            this.expressions = new ExpressionHitCollector(query, content, hits);
+        }
+        selectorHit(node) {
+            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. */
+        attributeOffset(node) {
+            const attrNames = new Set();
+            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;
+        }
+        bindingAllowed(node) {
+            if (this.query.bindingName === undefined) {
+                return false;
+            }
+            return this.bindingMatcher === null || this.bindingMatcher.matches(node);
+        }
+        bindingHits(node) {
+            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,
+                    });
+                }
+            }
+        }
+        visitElement(element) {
+            this.selectorHit(element);
+            this.bindingHits(element);
+            super.visitElement(element);
+        }
+        visitTemplate(template) {
+            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);
+        }
+        visitBoundAttribute(attribute) {
+            this.expressions.scan(attribute.value);
+        }
+        visitBoundEvent(event) {
+            this.expressions.scan(event.handler);
+        }
+        visitBoundText(text) {
+            this.expressions.scan(text.value);
+        }
+        visitIfBlockBranch(block) {
+            this.expressions.scan(block.expression);
+            super.visitIfBlockBranch(block);
+        }
+        visitForLoopBlock(block) {
+            this.expressions.scan(block.expression);
+            this.expressions.scan(block.trackBy);
+            super.visitForLoopBlock(block);
+        }
+        visitSwitchBlock(block) {
+            this.expressions.scan(block.expression);
+            super.visitSwitchBlock(block);
+        }
+        visitSwitchBlockCase(block) {
+            this.expressions.scan(block.expression);
+            super.visitSwitchBlockCase(block);
+        }
+        visitDeferredTrigger(trigger) {
+            if (trigger instanceof TmplAstBoundDeferredTrigger) {
+                this.expressions.scan(trigger.value);
+            }
+        }
+    }
+    return TemplateHitCollector;
+}
+let hitCollectorClass;
+function getHitCollectorClass() {
+    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, query) {
+    const tokens = [];
+    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, query) {
+    const Collector = getHitCollectorClass();
+    if (Collector === null || !templateMayMatch(content, query)) {
+        return [];
+    }
+    let nodes;
+    try {
+        nodes = parseTemplate(content, 'template.html', {
+            preserveWhitespaces: true,
+        }).nodes;
+    }
+    catch {
+        return [];
+    }
+    const hits = [];
+    tmplAstVisitAll(new Collector(query, content, hits), nodes);
+    const seen = new Set();
+    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);
+}
+//# sourceMappingURL=template-usage-scanner.js.map

package/dist/investigation/template-usage-scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-usage-scanner.js","sourceRoot":"","sources":["../../src/investigation/template-usage-scanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,qBAAqB,EACrB,2BAA2B,EAC3B,cAAc,EACd,uBAAuB,EACvB,yBAAyB,EACzB,aAAa,EACb,eAAe,GAehB,MAAM,mBAAmB,CAAC;AAyD3B,SAAS,UAAU,CAAC,QAAa;IAC/B,OAAO,QAAQ,YAAY,gBAAgB,CAAC;AAC9C,CAAC;AAED,SAAS,aAAa,CAAC,QAA4B;IAIjD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,MAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,eAAe,EAAU,CAAC;IAC9C,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACzC,MAAM,YAAY,GAAG,IAAI,GAAG,CAC1B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,CACpE,CAAC;IAEF,OAAO;QACL,YAAY;QACZ,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YAChB,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,yBAAyB,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE;gBAClD,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC,CAAC,CAAC;YACH,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC;AASD;;;;;;;GAOG;AACH,SAAS,uBAAuB;IAC9B,MAAM,iBAAiB,GACrB,OAAQ,mBAA+B,KAAK,UAAU;QACtD,OAAQ,uBAAmC,KAAK,UAAU,CAAC;IAC7D,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,MAAM,sBAAuB,SAAQ,mBAAmB;QAInC;QACA;QACA;QALF,aAAa,GAAG,IAAI,GAAG,EAAO,CAAC;QAEhD,YACmB,KAAoB,EACpB,OAAe,EACf,IAAmB;YAEpC,KAAK,EAAE,CAAC;YAJS,UAAK,GAAL,KAAK,CAAe;YACpB,YAAO,GAAP,OAAO,CAAQ;YACf,SAAI,GAAJ,IAAI,CAAe;QAGtC,CAAC;QAEO,UAAU,CAAC,IAAc,EAAE,IAAY;YAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YACrD,OAAO,KAAK,KAAK,CAAC,CAAC,IAAI,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;QAC/D,CAAC;QAEO,YAAY,CAClB,IAAuB,EACvB,IAAY,EACZ,IAAc,EACd,gBAAyB;YAEzB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;gBACb,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC;gBACnC,IAAI;gBACJ,IAAI;gBACJ,gBAAgB;aACjB,CAAC,CAAC;QACL,CAAC;QAEO,WAAW,CAAC,QAAa;YAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC;YACrC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,OAAO;YACT,CAAC;YACD,MAAM,MAAM,GAAG,QAAQ,YAAY,YAAY,CAAC;YAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;YACpD,IAAI,CAAC,MAAM,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;gBACnC,OAAO;YACT,CAAC;YACD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACjC,IAAI,CAAC,YAAY,CACf,aAAa,EACb,MAAM,EACN,QAAQ,CAAC,QAAQ,EACjB,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAC9B,CAAC;QACJ,CAAC;QAEQ,SAAS,CAAC,GAAS,EAAE,OAAgB;YAC5C,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC/B,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAChC,CAAC;QAEQ,aAAa,CAAC,GAAa,EAAE,OAAgB;YACpD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC/B,KAAK,CAAC,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACpC,CAAC;QAEQ,iBAAiB,CAAC,GAAiB,EAAE,OAAgB;YAC5D,MAAM,QAAQ,GACZ,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACrE,IAAI,QAAQ,EAAE,CAAC;gBACb,IAAI,CAAC,YAAY,CACf,eAAe,EACf,GAAG,CAAC,IAAI,EACR,GAAG,CAAC,QAAQ,EACZ,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CACzB,CAAC;YACJ,CAAC;YACD,KAAK,CAAC,iBAAiB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACxC,CAAC;QAEQ,qBAAqB,CAAC,GAAqB,EAAE,OAAgB;YACpE,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;gBACvC,IAAI,CAAC,YAAY,CAAC,eAAe,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YACpE,CAAC;YACD,KAAK,CAAC,qBAAqB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC5C,CAAC;QAEQ,kBAAkB,CAAC,GAAkB,EAAE,OAAgB;YAC9D,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;gBACvC,IAAI,CAAC,YAAY,CACf,gBAAgB,EAChB,GAAG,CAAC,IAAI,EACR,GAAG,CAAC,QAAQ,EACZ,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CACzB,CAAC;YACJ,CAAC;YACD,KAAK,CAAC,kBAAkB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC;QAEQ,SAAS,CAAC,GAAgB,EAAE,OAAgB;YACnD,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;gBACrC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;oBACb,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC;oBAC/C,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,GAAG,CAAC,IAAI;iBACf,CAAC,CAAC;YACL,CAAC;YACD,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAChC,CAAC;QAED,IAAI,CAAC,GAA2B;YAC9B,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;gBACtC,OAAO;YACT,CAAC;YACD,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;KACF;IAED;;;OAGG;IACH,MAAM,oBAAqB,SAAQ,uBAAuB;QAMrC;QAEA;QAPF,eAAe,CAAmC;QAClD,cAAc,CAAmC;QACjD,WAAW,CAAyB;QAErD,YACmB,KAAoB,EACrC,OAAe,EACE,IAAmB;YAEpC,KAAK,EAAE,CAAC;YAJS,UAAK,GAAL,KAAK,CAAe;YAEpB,SAAI,GAAJ,IAAI,CAAe;YAGpC,IAAI,CAAC,eAAe,GAAG,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YACrD,IAAI,CAAC,cAAc,GAAG,aAAa,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;YAC3D,IAAI,CAAC,WAAW,GAAG,IAAI,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;QACtE,CAAC;QAEO,WAAW,CAAC,IAAsC;YACxD,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,CAAC;YACrC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC5B,OAAO;YACT,CAAC;YACD,MAAM,SAAS,GACb,IAAI,YAAY,cAAc,IAAI,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;YAC3C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;gBACb,MAAM,EAAE,SAAS;oBACf,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;oBACvC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;gBAC9B,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW;gBACzC,IAAI,EAAE,QAAQ;aACf,CAAC,CAAC;QACL,CAAC;QAED,iFAAiF;QACzE,eAAe,CAAC,IAAsC;YAC5D,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;YACpC,IAAI,CAAC;gBACH,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAAC;oBAC7D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;wBAC3C,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;wBACxB,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;4BACvB,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;wBACtB,CAAC;oBACH,CAAC;gBACH,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,iCAAiC;YACnC,CAAC;YAED,MAAM,UAAU,GAAG;gBACjB,GAAG,IAAI,CAAC,UAAU;gBAClB,GAAG,IAAI,CAAC,MAAM;gBACd,GAAG,IAAI,CAAC,OAAO;gBACf,GAAG,CAAC,eAAe,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;aACvD,CAAC;YACF,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAC1D,OAAO,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,MAAM,CAAC;QACzE,CAAC;QAEO,cAAc,CAAC,IAAsC;YAC3D,IAAI,IAAI,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;gBACzC,OAAO,KAAK,CAAC;YACf,CAAC;YACD,OAAO,IAAI,CAAC,cAAc,KAAK,IAAI,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC3E,CAAC;QAEO,WAAW,CAAC,IAAsC;YACxD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC;YACpC,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC;gBACrD,OAAO;YACT,CAAC;YACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChC,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;oBACxB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;wBACb,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM;wBAClC,IAAI,EAAE,eAAe;wBACrB,IAAI;qBACL,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;gBACnC,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;oBACvB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;wBACb,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM;wBAClE,IAAI,EAAE,eAAe;wBACrB,IAAI;qBACL,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YACD,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBAClC,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;oBACzB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;wBACb,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM;wBACnC,IAAI,EAAE,gBAAgB;wBACtB,IAAI;qBACL,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAEQ,YAAY,CAAC,OAAuB;YAC3C,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAC1B,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;YAC1B,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;QAEQ,aAAa,CAAC,QAAyB;YAC9C,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YAC3B,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YAC3B,yDAAyD;YACzD,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,aAAa,EAAE,CAAC;gBAC1C,IAAI,IAAI,YAAY,qBAAqB,EAAE,CAAC;oBAC1C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;YACD,KAAK,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAChC,CAAC;QAEQ,mBAAmB,CAAC,SAAgC;YAC3D,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACzC,CAAC;QAEQ,eAAe,CAAC,KAAwB;YAC/C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACvC,CAAC;QAEQ,cAAc,CAAC,IAAsB;YAC5C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QAEQ,kBAAkB,CAAC,KAA2B;YACrD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YACxC,KAAK,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAClC,CAAC;QAEQ,iBAAiB,CAAC,KAA0B;YACnD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YACxC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACrC,KAAK,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;QAEQ,gBAAgB,CAAC,KAAyB;YACjD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YACxC,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;QAEQ,oBAAoB,CAAC,KAA6B;YACzD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YACxC,KAAK,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QAEQ,oBAAoB,CAAC,OAA+B;YAC3D,IAAI,OAAO,YAAY,2BAA2B,EAAE,CAAC;gBACnD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;KACF;IAED,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED,IAAI,iBAAuD,CAAC;AAE5D,SAAS,oBAAoB;IAC3B,IAAI,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACpC,iBAAiB,GAAG,uBAAuB,EAAE,CAAC;IAChD,CAAC;IACD,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,KAAoB;IACpE,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC9B,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAChC,CAAC;IACD,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACjC,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAClD,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,OAAO,KAAK,GAAG,EAAE,CAAC;oBAC5C,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;gBACzB,CAAC;gBACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC3C,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;oBACxB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;wBACtC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACpB,CAAC;gBACH,CAAC;gBACD,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,KAAoB;IAChE,MAAM,SAAS,GAAG,oBAAoB,EAAE,CAAC;IACzC,IAAI,SAAS,KAAK,IAAI,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;QAC5D,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,KAAgD,CAAC;IACrD,IAAI,CAAC;QACH,KAAK,GAAG,aAAa,CAAC,OAAO,EAAE,eAAe,EAAE;YAC9C,mBAAmB,EAAE,IAAI;SAC1B,CAAC,CAAC,KAAK,CAAC;IACX,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,IAAI,GAAkB,EAAE,CAAC;IAC/B,eAAe,CAAC,IAAI,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;IAE5D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,IAAI;SACR,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QACZ,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;AACzC,CAAC"}

package/dist/investigation/usage-finder.d.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);
@@ -16,9 +24,17 @@
  * // usages[0] → { file, line, col, snippet, usageType: 'read' }
  * ```
  */
-import type { Project } from 'ts-morph';
-/** Classification of how a symbol is used at a given location. */
-export type UsageType = 'read' | 'write' | 'call';
+import { type Project } from 'ts-morph';
+import { 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.
+ *
+ * - `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 {
     /** Absolute file path containing the usage. */
@@ -31,12 +47,25 @@ export interface SymbolUsage {
     snippet: string;
     /** 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;
     /**
@@ -44,6 +73,10 @@ 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;
 }
 /**
  * Finds all references to named symbols across a ts-morph Project.
@@ -62,6 +95,19 @@ export declare class UsageFinder {
      * @returns Array of resolved usages, sorted by file path then line number.
      */
     findUsages(symbol: string, options?: FindUsagesOptions): SymbolUsage[];
+    private findReferenceUsages;
+    /**
+     * 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;
+    private findTemplateUsages;
+    /**
+     * 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;
     private classifyUsage;
     private deduplicate;

package/dist/investigation/usage-finder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage-finder.d.ts","sourceRoot":"","sources":["../../src/investigation/usage-finder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAQ,MAAM,UAAU,CAAC;AAE9C,kEAAkE;AAClE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAElD,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IAEb,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IAEb,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IAEZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAEhB,+CAA+C;IAC/C,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED;;GAEG;AACH,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC;;OAEG;gBAC0B,OAAO,EAAE,OAAO;IAE7C;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,WAAW,EAAE;IAqD1E,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,aAAa;IAoCrB,OAAO,CAAC,WAAW;CAWpB"}
+{"version":3,"file":"usage-finder.d.ts","sourceRoot":"","sources":["../../src/investigation/usage-finder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAQ,KAAK,OAAO,EAAmB,MAAM,UAAU,CAAC;AAC/D,OAAO,EAEL,KAAK,aAAa,EACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,YAAY,CAAC;AAE9E,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IAEb,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IAEb,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IAEZ,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAEhB,+CAA+C;IAC/C,SAAS,EAAE,SAAS,CAAC;IAErB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,sEAAsE;IACtE,YAAY,CAAC,EAAE,iBAAiB,CAAC;IAEjC;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,2DAA2D;IAC3D,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,yFAAyF;IACzF,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,WAAW;IAIV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC;;OAEG;gBAC0B,OAAO,EAAE,OAAO;IAE7C;;;;;;OAMG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,WAAW,EAAE;IA8B1E,OAAO,CAAC,mBAAmB;IA0B3B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAqC5B,OAAO,CAAC,kBAAkB;IAgB1B;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAuBvB,OAAO,CAAC,aAAa;IAoCrB,OAAO,CAAC,WAAW;CAWpB"}