@eventra_dev/eventra-cli 2.0.7 → 2.0.9

package/README.md

@@ -8,7 +8,7 @@
   <a href="https://www.npmjs.com/package/@eventra_dev/eventra-cli"><img alt="npm version" src="https://img.shields.io/npm/v/@eventra_dev/eventra-cli.svg?style=flat-square&color=blue"></a>
   <a href="https://www.npmjs.com/package/@eventra_dev/eventra-cli"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@eventra_dev/eventra-cli.svg?style=flat-square&color=blue"></a>
   <a href="https://github.com/and-1991/eventra-cli/actions/workflows/test.yml"><img alt="tests" src="https://img.shields.io/github/actions/workflow/status/and-1991/eventra-cli/test.yml?branch=main&label=tests&style=flat-square&logo=vitest&logoColor=white"></a>
-  <img alt="unit tests" src="https://img.shields.io/badge/unit-403%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white">
+  <img alt="unit tests" src="https://img.shields.io/badge/unit-445%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white">
   <img alt="e2e fixtures" src="https://img.shields.io/badge/e2e-12%20fixtures-brightgreen?style=flat-square">
   <img alt="coverage" src="https://img.shields.io/badge/coverage-100%25%20(unit)-brightgreen?style=flat-square&logo=vitest&logoColor=white">
   <img alt="node" src="https://img.shields.io/node/v/@eventra_dev/eventra-cli?style=flat-square&color=darkgreen&logo=node.js&logoColor=white">
@@ -24,7 +24,7 @@ Eventra CLI statically discovers analytics events from [**@eventra_dev/eventra-s
 
 The CLI scans TypeScript and JavaScript with the TypeScript compiler API and extracts **only** calls to `Eventra.prototype.track()` on instances of `Eventra` imported from `@eventra_dev/eventra-sdk`.
 
-It does **not** detect generic `track()`, Segment, Google Analytics, or other libraries out of the box. Framework files (e.g. `.vue`, `.svelte`, `.astro`) require an optional [plugin](#plugins).
+It does **not** detect generic `track()`, Segment, Google Analytics, or other libraries out of the box. Framework files (e.g. `.vue`, `.svelte`, `.astro`, Angular's `.html` templates) require an optional [plugin](#plugins).
 
 ---
 
@@ -272,6 +272,31 @@ The plugin:
 
 `sync.include` does **not** need `**/*.astro` manually. See [`@eventra_dev/cli-plugin-astro`](https://www.npmjs.com/package/@eventra_dev/cli-plugin-astro) for details.
 
+### Angular (`.html`, via `templateUrl`)
+
+```bash
+pnpm add -D @eventra_dev/cli-plugin-angular
+```
+
+```json
+{
+  "plugins": ["@eventra_dev/cli-plugin-angular"],
+  "sync": {
+    "include": ["**/*.{ts,tsx,js,jsx}"],
+    "exclude": ["node_modules", "dist", ".angular", ".git"]
+  }
+}
+```
+
+The plugin:
+
+- parses each component template with the real Angular compiler (`@angular/compiler`) into a virtual TypeScript module, paired with its component class (`foo.component.html` ↔ `foo.component.ts`, Angular CLI's default naming)
+- extracts `track()` calls from the component class exactly like a regular `.ts` file (direct calls, wrappers, propagation) - no plugin needed for that part
+- detects `event="feature_name"` attributes on any tag, including `*ngIf`/`*ngFor` and the `@if`/`@for`/`@switch` block syntax - both literal and dynamic; a dynamic binding resolves against the component instance (`this.field`, including getters), or surfaces as a dynamic occurrence if unresolvable
+- use `[attr.event]="expr"`, not `[event]="expr"`, for a dynamic binding on a plain HTML element - `[event]` is a property binding that Angular's real compiler rejects (`NG8002`) unless the element is a component that actually declares `@Input() event`; both forms are detected identically by the plugin, only `[attr.event]` is guaranteed to compile
+
+`sync.include` does **not** need `**/*.html` manually. Only `templateUrl`-based components are covered - an inline `template: "..."` isn't yet. Requires Node `^20.19.0 || ^22.12.0 || >=24.0.0` (higher than the other plugins' `>=18` floor - `@angular/compiler`'s own requirement). See [`@eventra_dev/cli-plugin-angular`](https://www.npmjs.com/package/@eventra_dev/cli-plugin-angular) for details.
+
 ### Before publishing / local development
 
 Plugins are resolved from your project's `node_modules` (same as any dependency):
@@ -357,7 +382,7 @@ No runtime execution. No monkey-patching.
 
 ## Test Coverage
 
-Two test layers, **409 unit tests + 12 e2e fixtures + 3 `check` exit-code scenarios + 1 `watch` scenario**.
+Two test layers, **445 unit tests + 12 e2e fixtures + 3 `check` exit-code scenarios + 1 `watch` scenario**.
 
 **100% statement/branch/function/line coverage** (v8 provider, `pnpm test:coverage`), enforced via a `coverage.thresholds` block in `vitest.config.ts` so a regression fails the build instead of silently slipping under 100%. This measures the vitest unit layer only; the e2e/`check`/`watch` fixtures run against the compiled `dist/` binary via `tsx tests/run.ts` and aren't coverage-instrumented. A handful of genuinely unreachable defensive branches (TS-internal invariants — e.g. an aliased import symbol is always fully resolved before its own declarations are ever inspected — that don't hold a second outcome in practice) are marked with `/* v8 ignore */`, with an inline comment explaining why, rather than tested.
 

package/dist/analysis/extractor/extractor.js

@@ -24,7 +24,7 @@ function extractEvents(index, checker, _config, evaluationCache, exportCache, re
                 }
             }
             if (resolved.dynamic) {
-                (0, dynamicOccurrence_1.recordDynamicOccurrence)(call.node, resolved.values, dynamicOccurrences);
+                (0, dynamicOccurrence_1.recordDynamicOccurrence)(call.node, call.calleeText, resolved.values, dynamicOccurrences);
             }
         }
     }

package/dist/analysis/extractor/propagationExtractor.js

@@ -68,7 +68,10 @@ function extractPropagationEvents(call, checker, wrapperRegistry, resolvedCallCa
     }
 }
 function extractPropagation(propagation, call, checker, evaluationCache, resolvedCallCache, returnPropagationCache, exportCache, events, dynamicOccurrences) {
-    const argument = call.arguments[propagation.sourceParameterIndex];
+    // Call site can omit the argument and rely on the parameter's own default
+    // value (`function f(event = "x") {}` called as `f()`) - that default is a
+    // real static literal, so fall back to it instead of dropping the call site.
+    const argument = call.arguments[propagation.sourceParameterIndex] ?? propagation.sourceParameter.initializer;
     if (!argument) {
         return;
     }
@@ -116,6 +119,6 @@ function extractPropagation(propagation, call, checker, evaluationCache, resolve
         }
     }
     if (resolved.dynamic) {
-        (0, dynamicOccurrence_1.recordDynamicOccurrence)(call, resolved.values, dynamicOccurrences);
+        (0, dynamicOccurrence_1.recordDynamicOccurrence)(call, call.expression.getText(), resolved.values, dynamicOccurrences);
     }
 }

package/dist/analysis/resolver/resolver.js

@@ -71,6 +71,54 @@ function resolveBoundObjectNode(rawNode, checker, context) {
     }
     return null;
 }
+// Walks up from a `this` reference to the class it's lexically inside of, so
+// `this.EVENT_NAME` can be resolved against that class's own property
+// declarations - the same idea as resolving a plain identifier against its
+// variable declaration, just rooted at the enclosing class instead of a
+// module-scope symbol (`this` itself has no symbol/declaration of its own to
+// look up via the checker).
+function findEnclosingClass(node) {
+    let current = node;
+    while (current) {
+        if (typescript_1.default.isClassDeclaration(current) || typescript_1.default.isClassExpression(current)) {
+            return current;
+        }
+        current = current.parent;
+    }
+    return null;
+}
+function isFunctionLikeBoundary(node) {
+    return (typescript_1.default.isFunctionDeclaration(node) ||
+        typescript_1.default.isFunctionExpression(node) ||
+        typescript_1.default.isArrowFunction(node) ||
+        typescript_1.default.isMethodDeclaration(node) ||
+        typescript_1.default.isGetAccessorDeclaration(node) ||
+        typescript_1.default.isSetAccessorDeclaration(node));
+}
+// Collects every `return <expr>;` belonging directly to `getter` - i.e. not
+// one that belongs to a function/method/accessor nested inside its body.
+// A getter with conditional returns is legitimately multi-valued (which
+// branch runs depends on runtime state), so the caller unions more than one
+// of these the same way it already does for a reassigned `let`.
+function collectReturnExpressions(getter) {
+    const expressions = [];
+    function visit(node) {
+        if (node !== getter && isFunctionLikeBoundary(node)) {
+            return;
+        }
+        if (typescript_1.default.isReturnStatement(node) && node.expression) {
+            expressions.push(node.expression);
+        }
+        typescript_1.default.forEachChild(node, visit);
+    }
+    if (getter.body) {
+        visit(getter.body);
+    }
+    return expressions;
+}
+function getMemberName(member) {
+    return typescript_1.default.isIdentifier(member.name) ? member.name.text : typescript_1.default.isStringLiteral(member.name) ? member.name.text : null;
+}
 function resolvePropertyAccess(node, checker, context, visited, evaluationCache, resolvedCallCache, returnPropagationCache, exportCache) {
     const propertyName = (0, utils_1.getPropertyName)(node);
     if (!propertyName) {
@@ -96,6 +144,40 @@ function resolvePropertyAccess(node, checker, context, visited, evaluationCache,
             }
         }
     }
+    // this.EVENT_NAME
+    // class Foo { EVENT_NAME = "checkout"; bar() { track(this.EVENT_NAME); } }
+    //
+    // this.computedEventName (getter)
+    // class Foo { get computedEventName() { return "checkout"; } }
+    if (targetExpression.kind === typescript_1.default.SyntaxKind.ThisKeyword) {
+        const enclosingClass = findEnclosingClass(node);
+        if (enclosingClass) {
+            for (const member of enclosingClass.members) {
+                if (typescript_1.default.isPropertyDeclaration(member) && member.initializer && getMemberName(member) === propertyName) {
+                    return resolveNodeValue(member.initializer, checker, context, visited, evaluationCache, resolvedCallCache, returnPropagationCache, exportCache);
+                }
+                if (typescript_1.default.isGetAccessorDeclaration(member) && getMemberName(member) === propertyName) {
+                    const returnExpressions = collectReturnExpressions(member);
+                    if (returnExpressions.length === 0) {
+                        return empty();
+                    }
+                    if (returnExpressions.length === 1) {
+                        return resolveNodeValue(returnExpressions[0], checker, context, visited, evaluationCache, resolvedCallCache, returnPropagationCache, exportCache);
+                    }
+                    const values = [];
+                    for (const expression of returnExpressions) {
+                        const resolved = resolveNodeValue(expression, checker, context, visited, evaluationCache, resolvedCallCache, returnPropagationCache, exportCache);
+                        values.push(...resolved.values);
+                    }
+                    return {
+                        values: unique(values),
+                        dynamic: true,
+                    };
+                }
+            }
+        }
+        return empty();
+    }
     if (typescript_1.default.isIdentifier(targetExpression)) {
         let symbol = checker.getSymbolAtLocation(targetExpression);
         if (symbol) {
@@ -157,6 +239,63 @@ function resolvePropertyAccess(node, checker, context, visited, evaluationCache,
     }
     return empty();
 }
+function isConstDeclaration(declaration) {
+    return (typescript_1.default.getCombinedNodeFlags(declaration) & typescript_1.default.NodeFlags.Const) !== 0;
+}
+// `ts.isAssignmentOperator` exists on the compiled module at runtime but
+// isn't part of the public .d.ts (an internal-only export), so the operator
+// set is spelled out here instead of depending on an undocumented API.
+const ASSIGNMENT_OPERATOR_KINDS = new Set([
+    typescript_1.default.SyntaxKind.EqualsToken,
+    typescript_1.default.SyntaxKind.PlusEqualsToken,
+    typescript_1.default.SyntaxKind.MinusEqualsToken,
+    typescript_1.default.SyntaxKind.AsteriskEqualsToken,
+    typescript_1.default.SyntaxKind.AsteriskAsteriskEqualsToken,
+    typescript_1.default.SyntaxKind.SlashEqualsToken,
+    typescript_1.default.SyntaxKind.PercentEqualsToken,
+    typescript_1.default.SyntaxKind.LessThanLessThanEqualsToken,
+    typescript_1.default.SyntaxKind.GreaterThanGreaterThanEqualsToken,
+    typescript_1.default.SyntaxKind.GreaterThanGreaterThanGreaterThanEqualsToken,
+    typescript_1.default.SyntaxKind.AmpersandEqualsToken,
+    typescript_1.default.SyntaxKind.BarEqualsToken,
+    typescript_1.default.SyntaxKind.CaretEqualsToken,
+    typescript_1.default.SyntaxKind.AmpersandAmpersandEqualsToken,
+    typescript_1.default.SyntaxKind.BarBarEqualsToken,
+    typescript_1.default.SyntaxKind.QuestionQuestionEqualsToken,
+]);
+// A `let`/`var` binding can be reassigned after its declaration - resolving
+// only the initializer would confidently report a value that a later
+// assignment (still just as static - a literal, another variable, a
+// template, etc.) overwrites before any sink ever sees it. This walks the
+// declaring file(s) for every assignment to `symbol` so the caller can treat
+// the binding as multi-valued (or at least uncertain) instead of silently
+// trusting the first value it was ever given.
+function collectReassignments(symbol, checker) {
+    const values = [];
+    let hasUnresolvedReassignment = false;
+    // See the identical `?? []` elsewhere in this file: a real ts.Symbol here
+    // always has a declarations array.
+    /* v8 ignore next */
+    const sourceFiles = new Set((symbol.getDeclarations() ?? []).map(declaration => declaration.getSourceFile()));
+    for (const sourceFile of sourceFiles) {
+        const visit = (node) => {
+            if (typescript_1.default.isBinaryExpression(node) &&
+                ASSIGNMENT_OPERATOR_KINDS.has(node.operatorToken.kind) &&
+                typescript_1.default.isIdentifier(node.left) &&
+                checker.getSymbolAtLocation(node.left) === symbol) {
+                if (node.operatorToken.kind === typescript_1.default.SyntaxKind.EqualsToken) {
+                    values.push(node.right);
+                }
+                else {
+                    hasUnresolvedReassignment = true;
+                }
+            }
+            typescript_1.default.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+    }
+    return { values, hasUnresolvedReassignment };
+}
 function resolveIdentifier(node, checker, context, visited, evaluationCache, resolvedCallCache, returnPropagationCache, exportCache) {
     const boundSymbol = checker.getSymbolAtLocation(node);
     if (boundSymbol && context.parameterBindings.has(boundSymbol)) {
@@ -186,7 +325,21 @@ function resolveIdentifier(node, checker, context, visited, evaluationCache, res
     const declarations = symbol.getDeclarations() ?? [];
     for (const declaration of declarations) {
         if (typescript_1.default.isVariableDeclaration(declaration) && declaration.initializer) {
-            const resolved = resolveNodeValue(declaration.initializer, checker, context, visited, evaluationCache, resolvedCallCache, returnPropagationCache, exportCache);
+            const reassignment = isConstDeclaration(declaration) ? null : collectReassignments(symbol, checker);
+            if (!reassignment || (reassignment.values.length === 0 && !reassignment.hasUnresolvedReassignment)) {
+                const resolved = resolveNodeValue(declaration.initializer, checker, context, visited, evaluationCache, resolvedCallCache, returnPropagationCache, exportCache);
+                evaluationCache.set(symbol, resolved);
+                return resolved;
+            }
+            const values = [];
+            for (const expression of [declaration.initializer, ...reassignment.values]) {
+                const resolvedValue = resolveNodeValue(expression, checker, context, visited, evaluationCache, resolvedCallCache, returnPropagationCache, exportCache);
+                values.push(...resolvedValue.values);
+            }
+            const resolved = {
+                values: unique(values),
+                dynamic: true,
+            };
             evaluationCache.set(symbol, resolved);
             return resolved;
         }
@@ -213,7 +366,11 @@ function resolveCallExpression(node, checker, context, visited, evaluationCache,
     }
     const values = [];
     for (const propagation of semantic.propagations) {
-        const argument = node.arguments[propagation.parameterIndex];
+        // Call site can omit the argument and rely on the parameter's own default
+        // value (`function build(name = "x") {}` called as `build()`) - that
+        // default is a real static literal, so fall back to it instead of
+        // dropping the call site.
+        const argument = node.arguments[propagation.parameterIndex] ?? propagation.parameter.initializer;
         if (!argument) {
             continue;
         }

package/dist/analysis/scanner/jsxEventAttribute.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectJsxEventAttribute = detectJsxEventAttribute;
+const typescript_1 = __importDefault(require("typescript"));
+const EVENT_ATTRIBUTE_NAME = "event";
+/**
+ * Detects a JSX `event="literal"` / `event={expr}` attribute - the same
+ * declarative-tracking convention the Vue/Svelte/Astro/Angular CLI plugins
+ * already use for their own templates, recognized on any tag (plain
+ * elements and components alike). No plugin or preprocessing is needed for
+ * React: JSX is already part of the TypeScript AST the core walks natively,
+ * so this is a plain node-kind check alongside the existing CallExpression
+ * sink detection, not a separate virtual-module bridge.
+ *
+ * Reported through the exact same `TrackCall` shape as a real track() call:
+ * a literal value resolves directly, and a dynamic expression is resolved
+ * through the same checker-based pipeline as any other TS expression,
+ * falling back to a dynamic occurrence (not silently dropped) when it
+ * doesn't resolve to a literal.
+ */
+function detectJsxEventAttribute(node) {
+    if (!typescript_1.default.isJsxAttribute(node)) {
+        return null;
+    }
+    if (!typescript_1.default.isIdentifier(node.name) || node.name.text !== EVENT_ATTRIBUTE_NAME) {
+        return null;
+    }
+    const initializer = node.initializer;
+    if (!initializer) {
+        // Boolean shorthand `<Button event />` - no name to extract, same as
+        // the other plugins' own boolean-shorthand `event` handling.
+        return null;
+    }
+    let value;
+    if (typescript_1.default.isStringLiteral(initializer)) {
+        // event="literal"
+        value = initializer;
+    }
+    else if (typescript_1.default.isJsxExpression(initializer)) {
+        // event={expr} - an empty event={} has no expression to extract.
+        if (!initializer.expression) {
+            return null;
+        }
+        value = initializer.expression;
+    }
+    else {
+        return null;
+    }
+    return {
+        node,
+        sourceFile: node.getSourceFile(),
+        trackedArguments: [value],
+        calleeText: node.parent.parent.tagName.getText(),
+    };
+}

package/dist/analysis/scanner/scanner.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.scanSource = scanSource;
 const typescript_1 = __importDefault(require("typescript"));
 const sinkDetector_1 = require("./sinkDetector");
+const jsxEventAttribute_1 = require("./jsxEventAttribute");
 const propagationAnalyzer_1 = require("./analyzer/propagationAnalyzer");
 function scanSource(source, checker, wrapperRegistry, plugins) {
     const sinks = [];
@@ -51,9 +52,16 @@ function scanSource(source, checker, wrapperRegistry, plugins) {
                     node,
                     sourceFile: source,
                     trackedArguments,
+                    calleeText: node.expression.getText(source),
                 });
             }
         }
+        // JSX `event="..."`/`event={expr}` attribute detection (React/JSX files
+        // only - a plain .ts/.js file never contains a JsxAttribute node).
+        const jsxEventAttribute = (0, jsxEventAttribute_1.detectJsxEventAttribute)(node);
+        if (jsxEventAttribute) {
+            trackCalls.push(jsxEventAttribute);
+        }
         typescript_1.default.forEachChild(node, visit);
     }
     visit(source);

package/dist/analysis/shared/dynamicOccurrence.js

@@ -7,15 +7,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.recordDynamicOccurrence = recordDynamicOccurrence;
 const typescript_1 = __importDefault(require("typescript"));
 const CALL_TEXT_MAX_LENGTH = 120;
-function recordDynamicOccurrence(call, resolvedValues, out) {
-    const sourceFile = call.getSourceFile();
-    const { line, character } = typescript_1.default.getLineAndCharacterOfPosition(sourceFile, call.getStart(sourceFile));
-    const callText = call.getText(sourceFile);
+// `node` is a CallExpression for a real track() call, or a JsxAttribute for
+// a JSX `event="..."`/`event={expr}` binding (see jsxEventAttribute.ts) -
+// `calleeText` is supplied by the caller since it's derived differently per
+// node kind (a call's callee text vs. a JSX element's tag name).
+function recordDynamicOccurrence(node, calleeText, resolvedValues, out) {
+    const sourceFile = node.getSourceFile();
+    const { line, character } = typescript_1.default.getLineAndCharacterOfPosition(sourceFile, node.getStart(sourceFile));
+    const callText = node.getText(sourceFile);
     out.push({
         fileName: sourceFile.fileName,
         line: line + 1,
         character,
-        calleeText: call.expression.getText(sourceFile),
+        calleeText,
         callText: callText.length > CALL_TEXT_MAX_LENGTH ? `${callText.slice(0, CALL_TEXT_MAX_LENGTH)}…` : callText,
         resolvedValues,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventra_dev/eventra-cli",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "description": "Static analytics event extraction CLI powered by the TypeScript compiler API",
   "license": "MIT",
   "type": "commonjs",