@eventra_dev/eventra-cli 2.2.0 → 2.3.1

package/README.md

@@ -95,6 +95,27 @@ function trackDestructured({ event: name }: { event: string }) {
 trackDestructured({ event: "checkout" });
 ```
 
+A wrapper can call another wrapper, at any depth and across files. `trackEvent("x")` is found even when it only reaches the SDK through `capture`:
+
+```ts
+// capture.ts
+export function capture(name: string, props?: object) { posthog.capture(name, props); }
+
+// track.ts
+export function trackEvent<E extends string>(event: E) { capture(event); }
+
+// page.ts
+trackEvent("checkout_started");
+```
+
+Functions handed back by a hook count too (`const analytics = useAnalytics(); analytics.capture("x")`, where the hook ends with `return { capture }`), and so does a library loaded on demand (`import("posthog-js").then(({ default: ph }) => ph.capture(name))`, `await import(...)`).
+
+### Monorepos
+
+Each import is resolved with the compiler options of the nearest `tsconfig.json` above the file that writes it (a config that sets no `paths` keeps the root's aliases; `node_modules` is never read for options), so an app with its own `@/*` or `~/*` aliases works without a tsconfig at the repository root. When a root `tsconfig.json` only lists `references` (the usual Vite and Vue layout), the aliases of the referenced config are used. Packages of the same repository (`workspaces` or `pnpm-workspace.yaml`) are found by their folder (`@acme/lib`, `@acme/lib/hooks/use-x`, also when the package keeps its sources in `src/`), so the scan does not need `node_modules` to link them. A real install still takes precedence.
+
+`sync`, `check`, `watch` and `send` on a machine with room to spare (a container's memory limit counts) start themselves again with a larger memory limit (half of the machine's memory, at most 8 GB), unless you set `--max-old-space-size` yourself; `init` and `--version` never do. A new `eventra.json` written by `init` leaves out tests and coverage output (see `sync.exclude`); a config that already exists keeps scanning what it scanned.
+
 ### Variables, templates, conditionals
 
 ```ts
@@ -156,7 +177,7 @@ Already have analytics in place? Declare it in `eventra.json` and the CLI treats
 
 Rules are plain data and never run code, so they are safe to commit. A rule with a typo, an invalid `when` or an unknown preset is skipped with a warning. A function with its own name (`trackEvent({ event: "x" })`) is not covered by a preset: add a rule such as `{ "callee": "trackEvent", "nameProperty": "event" }`.
 
-The [name rules](#event-name-rules-aligned-with-sdk) below apply to these events too. Spaces and colons are allowed, so names like `App: User Sign Up` or `Order Completed` are kept as written. Names with other characters, such as PostHog's `$`-prefixed system events (`$pageview`) or a name ending in `!`, are excluded from the scan result.
+The [name rules](#event-name-rules-aligned-with-sdk) below apply to these events too. Spaces and colons are allowed, so names like `App: User Sign Up` or `Order Completed` are kept as written. PostHog's `$`-prefixed names (`$pageview`, `$pageleave`) are kept as well. Names with other characters, such as one ending in `!`, are excluded from the scan result.
 
 ---
 
@@ -165,7 +186,7 @@ The [name rules](#event-name-rules-aligned-with-sdk) below apply to these events
 | Rule | Limit |
 |------|--------|
 | Max length | **64 characters** (same as SDK) |
-| Allowed characters | `a-zA-Z0-9:_./-` and the space (so `App: User Sign Up` works); tabs, newlines and any other character are rejected |
+| Allowed characters | `a-zA-Z0-9$:_./-` and the space (so `App: User Sign Up` and `$pageview` work); tabs, newlines and any other character are rejected |
 | Position | First argument of `.track(name, options?)` |
 
 The second argument (`userId`, `properties`) is **not** used as the event name.
@@ -194,7 +215,7 @@ tracker.track({ event: "click" });
 
 ### `eventra init`
 
-Creates `eventra.json`. It asks for an API key and an endpoint, then looks through `package.json` (and the `package.json` of every workspace member in a monorepo: `workspaces` or `pnpm-workspace.yaml`) for analytics libraries:
+Creates `eventra.json`. It asks for an API key and an endpoint, then looks through `package.json` (and the `package.json` of every workspace member in a monorepo: `workspaces` or `pnpm-workspace.yaml`) for analytics libraries and for the framework (`vue`, `svelte`, `astro`, `@angular/core`), and writes the matching plugin into `plugins` when it is installed. If it is not, `init` prints the install command and the line to add instead: `sync` stops on a plugin it cannot load, so `init` never writes one that would make the next `sync` fail:
 
 ```
 Found analytics in package.json: posthog-js; @segment/analytics-next
@@ -301,6 +322,7 @@ The plugin:
 - parses each `.vue` file with the real Vue compiler (`@vue/compiler-sfc`) into a single virtual TypeScript module combining `<script>`/`<script setup>`
 - extracts `track()` calls from the script exactly like a regular `.ts` file (direct calls, wrappers, propagation)
 - detects `event="feature_name"` attributes in `<template>` — both literal and dynamic (`:event="expr"`); dynamic bindings resolve through the same module scope as the script, or surface as a dynamic occurrence if unresolvable
+- reads calls written anywhere in the template: `@click`/`v-on` handlers (several statements, multi-line arrows), `{{ }}` interpolations and the expressions of `v-bind`, `v-if`, `v-show`, `v-model`, `v-html`, `v-text`
 - Nuxt `.vue` files (pages/layouts/components) are handled the same way; auto-imported composables resolve once the project has run `nuxt prepare`/`nuxt dev`
 
 `sync.include` does **not** need `**/*.vue` manually — the plugin registers `**/*.vue` via `includeGlobs`. See [`@eventra_dev/cli-plugin-vue`](https://www.npmjs.com/package/@eventra_dev/cli-plugin-vue) for details.
@@ -321,6 +343,7 @@ The plugin:
 
 - parses each `.svelte` file with the real Svelte compiler (`svelte/compiler`) into a single virtual TypeScript module combining `context="module"` and instance `<script>` blocks
 - extracts `track()` calls from the script exactly like a regular `.ts` file (direct calls, wrappers, propagation); Svelte 5 runes (`$props`, `$state`, …) pass through untouched
+- reads calls anywhere in the markup: handlers, `{expr}`, `{@html}`, block expressions (`{#if}`, `{#each}`, `{#key}`, `{#await}`), `use:`/`class:`/`transition:` directives and attribute values
 - detects `event="feature_name"` attributes on any tag — plain elements, components, `{#if}`/`{#each}`/`{#await}`/`{#key}` blocks, slots — both literal and dynamic (`event={expr}`); dynamic bindings resolve through the same module scope as the script, or surface as a dynamic occurrence if unresolvable
 
 `sync.include` does **not** need `**/*.svelte` manually. See [`@eventra_dev/cli-plugin-svelte`](https://www.npmjs.com/package/@eventra_dev/cli-plugin-svelte) for details.
@@ -341,6 +364,7 @@ The plugin:
 
 - parses each `.astro` file with the real Astro compiler (`@astrojs/compiler`) into a single virtual TypeScript module from the frontmatter
 - extracts `track()` calls from the frontmatter exactly like a regular `.ts` file (direct calls, wrappers, propagation); `Astro.props` and other globals pass through untouched
+- reads calls in template expressions (`{track("x")}`, `attr={expr}`, `{...spread}`) and in the page's `<script>` tags, each as a module of its own (quoted `onclick="..."` strings are browser text and are not read)
 - detects `event="feature_name"` attributes on any tag, including inside JSX expressions (`{cond && <Button event="..." />}`, `.map()`) — both literal and dynamic (`event={expr}`, including the `{event}` shorthand); dynamic bindings resolve through the same module scope as the frontmatter, or surface as a dynamic occurrence if unresolvable
 
 `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.
@@ -365,6 +389,7 @@ 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
+- reads calls in the template: `(click)` handlers, `[input]` bindings, `{{ }}` interpolations, `*ngIf` and `@if`/`@switch`/`@for`, written against the component class (`track('x')` is `this.track('x')`); an `.html` file no component names as its `templateUrl` is skipped when it does not parse
 - 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
 
@@ -426,7 +451,7 @@ No dependency on `@eventra_dev/eventra-cli` is required — the host CLI loads t
 | `plugins` | `@eventra_dev/cli-plugin-*` specifiers to `import()` at startup. Anything outside that scope is skipped (see [Plugin contract](#plugin-contract-for-authors)) |
 | `sinks` | Third-party analytics calls to treat as event sources, e.g. `[{ "preset": "posthog" }]` (see [Third-party analytics](#third-party-analytics-sinks)) |
 | `sync.include` | Base glob patterns; plugin `includeGlobs` are merged automatically |
-| `sync.exclude` | Paths skipped during scan. A plain name such as `node_modules` or `dist` matches at any depth (nested `packages/*/node_modules` too); entries containing `/` or glob characters are used as written |
+| `sync.exclude` | Paths skipped during scan. Default for a config that has none: `node_modules`, `dist`, `.next`, `.git`. `eventra init` writes a longer list into a new `eventra.json`: that plus `coverage`, test files (`**/*.{test,spec}.{ts,tsx,js,jsx}`) and `__tests__`/`__mocks__` folders. A plain name such as `node_modules` or `dist` matches at any depth (nested `packages/*/node_modules` too); entries containing `/` or glob characters are used as written |
 
 `eventra init`/`eventra send` never write a real key into this file — they write to `eventra.local.json` instead, which is automatically added to `.gitignore`.
 
@@ -439,7 +464,7 @@ No dependency on `@eventra_dev/eventra-cli` is required — the host CLI loads t
 3. Run file preprocessors (e.g. `.vue` → virtual `.ts` modules).
 4. Load sources into an incremental TypeScript program (with SDK type shim).
 5. **Phase 1** — find `Eventra` instances from `@eventra_dev/eventra-sdk` and register function wrappers that call `.track()`.
-6. **Phase 2** — resolve static event names and wrapper propagation chains (sink detector chain includes plugin sinks).
+6. **Phase 2** - resolve static event names and wrapper propagation chains, a wrapper that calls another wrapper included (sink detector chain includes plugin sinks).
 7. Write results to `eventra.json`.
 
 `watch` tracks **disk source files** (including `.vue`), re-runs preprocessors on change, and incrementally updates the engine.
@@ -457,7 +482,7 @@ No runtime execution. No monkey-patching.
 
 ## Test Coverage
 
-Two test layers, **783 unit tests + 14 e2e fixtures + 3 `check` exit-code scenarios + 1 `watch` scenario**.
+Two test layers, **925 unit tests + 14 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.
 
@@ -468,7 +493,10 @@ Two test layers, **783 unit tests + 14 e2e fixtures + 3 `check` exit-code scenar
 | `ImportGraph` | Forward/reverse edges, cycles, stale-edge cleanup, file removal |
 | `Scheduler` | Batch coalescing, last-write-wins per file, sequential bursts, error propagation |
 | `DocumentRegistry` | Path normalization, version bumping, no-op on identical content, `ensure()` from disk |
-| `CompilerContext` | Stage/update/remove files, `resolveModule` with `tsconfig.json` `paths`, source-file enumeration |
+| `CompilerContext` | Stage/update/remove files, `resolveModule` with `tsconfig.json` `paths`, source-file enumeration, nearest `tsconfig.json` per file, `references`, workspace packages without an install |
+| `wrapper chains` | A wrapper calling a wrapper (depth 2 and 3), either file order, generics, destructuring, cycles, watch updates |
+| `hook wrappers` | `return { capture }`, dynamic `import()` receivers, `.then` callbacks, promise-typed getters |
+| `respawn` | Heap sizing (a container's lower memory limit counts), only scanning commands respawn, signals reach the child, no second respawn, explicit `--max-old-space-size` respected |
 | `EventraEngine` | Direct calls, SDK isolation, cross-file wrappers, file updates, file removal, wrapper filtering |
 | `PluginRegistry` | Built-in SDK sink, preprocessors, virtual-path mapping, include-pattern dedup |
 | `external plugin adapter` | Transform output mapping, static sink registration, invalid result rejection |

package/dist/analysis/extractor/extractor.js

@@ -8,6 +8,7 @@ const typescript_1 = __importDefault(require("typescript"));
 const resolver_1 = require("../resolver/resolver");
 const evaluationContext_1 = require("../shared/evaluationContext");
 const propagationExtractor_1 = require("./propagationExtractor");
+const symbolUtils_1 = require("../symbols/symbolUtils");
 const eventValidation_1 = require("../shared/eventValidation");
 const dynamicOccurrence_1 = require("../shared/dynamicOccurrence");
 function extractEvents(index, checker, _config, evaluationCache, exportCache, resolvedCallCache, returnPropagationCache, wrapperRegistry) {
@@ -38,7 +39,7 @@ function extractEvents(index, checker, _config, evaluationCache, exportCache, re
     visit(index.sourceFile);
     return {
         events,
-        detectedFunctionWrappers: new Set(index.wrappers.map(wrapper => wrapper.symbol.getName())),
+        detectedFunctionWrappers: new Set(index.wrappers.map(wrapper => (0, symbolUtils_1.wrapperName)(wrapper.declaration, wrapper.symbol))),
         dynamicOccurrences,
     };
 }

package/dist/analysis/resolver/callResolver.js

@@ -9,7 +9,60 @@ const exportResolver_1 = require("./exportResolver");
 function isFunctionLike(node) {
     return (typescript_1.default.isFunctionDeclaration(node) || typescript_1.default.isMethodDeclaration(node) || typescript_1.default.isArrowFunction(node) || typescript_1.default.isFunctionExpression(node));
 }
-function resolveDeclaration(declaration) {
+/** `return expr` statements of a function body, not looking into functions nested in it. */
+function returnedExpressions(fn) {
+    if (!fn.body) {
+        return [];
+    }
+    if (!typescript_1.default.isBlock(fn.body)) {
+        return [fn.body];
+    }
+    const found = [];
+    const visit = (node) => {
+        if (typescript_1.default.isFunctionLike(node)) {
+            return;
+        }
+        if (typescript_1.default.isReturnStatement(node) && node.expression) {
+            found.push(node.expression);
+        }
+        typescript_1.default.forEachChild(node, visit);
+    };
+    visit(fn.body);
+    return found;
+}
+const MAX_RETURN_HOPS = 4;
+/**
+ * The function a call hands back: `useTracker()` for `function useTracker() { return (n) => t.track(n) }`,
+ * where the returned value is a function expression or a name bound to one.
+ */
+function resolveReturnedFunction(call, checker, callCache, exportCache, hops) {
+    if (hops > MAX_RETURN_HOPS) {
+        return null;
+    }
+    const factory = resolveFunctionFromCall(call.expression, checker, callCache, exportCache, hops + 1);
+    if (!factory) {
+        return null;
+    }
+    for (const returned of returnedExpressions(factory)) {
+        let value = returned;
+        while (typescript_1.default.isParenthesizedExpression(value) || typescript_1.default.isAsExpression(value) || typescript_1.default.isNonNullExpression(value)) {
+            value = value.expression;
+        }
+        if (isFunctionLike(value)) {
+            return value;
+        }
+        if (typescript_1.default.isIdentifier(value)) {
+            for (const next of checker.getSymbolAtLocation(value)?.getDeclarations() ?? []) {
+                const resolved = resolveDeclaration(next, checker);
+                if (resolved) {
+                    return resolved;
+                }
+            }
+        }
+    }
+    return null;
+}
+function resolveDeclaration(declaration, checker) {
     // function foo() {}
     if (isFunctionLike(declaration)) {
         return declaration;
@@ -26,6 +79,20 @@ function resolveDeclaration(declaration) {
     if (typescript_1.default.isPropertyAssignment(declaration) && declaration.initializer && isFunctionLike(declaration.initializer)) {
         return declaration.initializer;
     }
+    // `return { capture }` / `return { capture: capture }`: a hook or factory that hands back functions
+    // it defined, so `analytics.capture(...)` is a call of the `capture` declared next to the return
+    const target = typescript_1.default.isShorthandPropertyAssignment(declaration)
+        ? checker.getShorthandAssignmentValueSymbol(declaration)
+        : typescript_1.default.isPropertyAssignment(declaration) && typescript_1.default.isIdentifier(declaration.initializer)
+            ? checker.getSymbolAtLocation(declaration.initializer)
+            : undefined;
+    // the target is a variable, never another property, so this does not recurse into a cycle
+    for (const next of target?.getDeclarations() ?? []) {
+        const resolved = resolveDeclaration(next, checker);
+        if (resolved) {
+            return resolved;
+        }
+    }
     return null;
 }
 function getExpressionSymbol(expression, checker) {
@@ -50,7 +117,15 @@ function getExpressionSymbol(expression, checker) {
     // track()
     return checker.getSymbolAtLocation(expression);
 }
-function resolveFunctionFromCall(expression, checker, callCache, exportCache) {
+function resolveFunctionFromCall(expression, checker, callCache, exportCache, hops = 0) {
+    // useTracker()("x")
+    let callee = expression;
+    while (typescript_1.default.isParenthesizedExpression(callee)) {
+        callee = callee.expression;
+    }
+    if (typescript_1.default.isCallExpression(callee)) {
+        return resolveReturnedFunction(callee, checker, callCache, exportCache, hops);
+    }
     let symbol = getExpressionSymbol(expression, checker);
     if (!symbol) {
         return null;
@@ -69,7 +144,10 @@ function resolveFunctionFromCall(expression, checker, callCache, exportCache) {
     // declaration resolution
     const declarations = symbol.getDeclarations() ?? [];
     for (const declaration of declarations) {
-        const resolved = resolveDeclaration(declaration);
+        // const track = useTracker(); track("x")
+        const resolved = resolveDeclaration(declaration, checker) ?? (typescript_1.default.isVariableDeclaration(declaration) && declaration.initializer && typescript_1.default.isCallExpression(declaration.initializer)
+            ? resolveReturnedFunction(declaration.initializer, checker, callCache, exportCache, hops)
+            : null);
         if (!resolved) {
             continue;
         }

package/dist/analysis/scanner/scanner.js

@@ -101,5 +101,6 @@ function scanSource(source, checker, wrapperRegistry, plugins) {
         sinks,
         trackCalls,
         wrappers,
+        functions,
     };
 }

package/dist/analysis/scanner/wrapperChains.js

@@ -0,0 +1,115 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWrapperChains = resolveWrapperChains;
+const typescript_1 = __importDefault(require("typescript"));
+const callResolver_1 = require("../resolver/callResolver");
+const propagationAnalyzer_1 = require("./analyzer/propagationAnalyzer");
+/**
+ * Each round can only discover wrappers one call deeper than the previous one, so this is also the
+ * longest wrapper chain that is followed (`track` -> `capture` -> `posthog.capture` is two rounds).
+ * Real chains are two or three deep; the bound mostly stops a cycle from spinning.
+ */
+const MAX_ROUNDS = 8;
+/** Every call inside `fn`, nested functions included (the same reach the direct sinks have). */
+function callsWithin(fn) {
+    const calls = [];
+    const visit = (node) => {
+        if (typescript_1.default.isCallExpression(node))
+            calls.push(node);
+        typescript_1.default.forEachChild(node, visit);
+    };
+    /* v8 ignore else -- only functions with a body are collected */
+    if (fn.body)
+        visit(fn.body);
+    return calls;
+}
+/**
+ * A call of an already known wrapper is, for the function containing it, the same thing a call of a
+ * real sink is: the arguments the wrapper forwards to its sink are the ones to follow.
+ *
+ * Only a plain parameter (`event`) or an object literal read by one property (`{ event }`) can be
+ * followed: a wrapper that reads `options.event` from a whole object has no argument in the caller
+ * to point at, so it is not chained rather than guessed.
+ */
+function wrapperCallAsSink(call, self, checker, registry, callCache, exportCache) {
+    const callee = (0, callResolver_1.resolveFunctionFromCall)(call.expression, checker, callCache, exportCache);
+    if (!callee || callee === self)
+        return null;
+    const wrapper = registry.get(callee);
+    if (!wrapper)
+        return null;
+    const trackedArguments = wrapper.propagations
+        .filter((p) => {
+        const argument = call.arguments[p.sourceParameterIndex];
+        if (!argument)
+            return false;
+        return p.propertyPath.length === 0 || typescript_1.default.isObjectLiteralExpression(argument);
+    })
+        .map((p) => ({ index: p.sourceParameterIndex, propertyPath: p.propertyPath }));
+    return trackedArguments.length > 0 ? { call, trackedArguments } : null;
+}
+const sameNode = (a, b) => a.targetNode === b.targetNode &&
+    a.sourceParameterIndex === b.sourceParameterIndex &&
+    a.propertyPath.join("\0") === b.propertyPath.join("\0");
+/**
+ * Finds the wrappers that only reach a sink through another wrapper (`trackEvent(event)` calls
+ * `capture(event)`, which calls `posthog.capture(event)`), which scanning one file at a time cannot:
+ * the inner wrapper may live in a file that has not been indexed yet. Repeats over every file until
+ * a round finds nothing new, registers what it finds, and returns the files whose wrapper list grew.
+ */
+function resolveWrapperChains(indices, checker, registry, callCache, exportCache) {
+    const found = new Map();
+    const files = [...indices].filter((index) => (index.functions?.length ?? 0) > 0);
+    // the calls of a function never change between rounds, so they are collected once; a function with
+    // none (most of them) costs nothing in the rounds that follow
+    const callsOf = new Map();
+    for (const index of files) {
+        for (const fn of index.functions) {
+            if (fn.body) {
+                const calls = callsWithin(fn);
+                if (calls.length > 0)
+                    callsOf.set(fn, calls);
+            }
+        }
+    }
+    for (let round = 0; round < MAX_ROUNDS; round++) {
+        let changed = false;
+        for (const index of files) {
+            for (const fn of index.functions) {
+                const calls = callsOf.get(fn);
+                if (!calls)
+                    continue;
+                const sinks = [];
+                for (const call of calls) {
+                    const sink = wrapperCallAsSink(call, fn, checker, registry, callCache, exportCache);
+                    if (sink)
+                        sinks.push(sink);
+                }
+                if (sinks.length === 0)
+                    continue;
+                const chained = (0, propagationAnalyzer_1.analyzeWrapperPropagation)(fn, checker, sinks);
+                if (!chained)
+                    continue;
+                const known = registry.get(fn);
+                const added = chained.propagations.filter((p) => !known?.propagations.some((k) => sameNode(k, p)));
+                if (added.length === 0)
+                    continue;
+                const merged = {
+                    symbol: chained.symbol,
+                    declaration: fn,
+                    propagations: [...(known?.propagations ?? []), ...added],
+                };
+                registry.set(merged);
+                const list = found.get(index.fileName) ?? [];
+                found.set(index.fileName, [...list.filter((w) => w.declaration !== fn), merged]);
+                changed = true;
+            }
+        }
+        if (!changed)
+            break;
+    }
+    return found;
+}

package/dist/analysis/sdk/eventraSdk.js

@@ -4,7 +4,7 @@ exports.EVENTRA_SDK_SHIM = exports.MAX_EVENT_NAME_LENGTH = exports.EVENTRA_SDK_P
 exports.isEventraSdkModuleSpecifier = isEventraSdkModuleSpecifier;
 exports.normalizeEventName = normalizeEventName;
 exports.isValidEventName = isValidEventName;
-/** Mirrors @eventra_dev/eventra-sdk runtime limits (see packages/sdk/src/client.ts). */
+/** Mirrors the length limit of @eventra_dev/eventra-sdk (see packages/sdk/src/client.ts). */
 exports.EVENTRA_SDK_PACKAGE = "@eventra_dev/eventra-sdk";
 exports.MAX_EVENT_NAME_LENGTH = 64;
 function isEventraSdkModuleSpecifier(specifier) {
@@ -13,10 +13,12 @@ function isEventraSdkModuleSpecifier(specifier) {
         normalized.startsWith(`${exports.EVENTRA_SDK_PACKAGE}/`));
 }
 /**
- * Letters, digits and `: _ . / -`, plus the plain space - so third-party names such as
- * `App: User Sign Up` survive. Tabs, newlines and every other character stay rejected.
+ * Letters, digits and `$ : _ . / -`, plus the plain space - so third-party names such as
+ * `App: User Sign Up` and PostHog's own `$pageview` survive. The SDK and the API accept any text up
+ * to the length limit; the CLI stays stricter so that a name read out of code is a clean identifier:
+ * tabs, newlines and every other character are rejected.
  */
-const EVENT_NAME_PATTERN = /^[a-zA-Z0-9:_./ -]+$/;
+const EVENT_NAME_PATTERN = /^[a-zA-Z0-9$:_./ -]+$/;
 function normalizeEventName(value) {
     const trimmed = value.trim();
     if (!trimmed || trimmed.length > exports.MAX_EVENT_NAME_LENGTH) {

package/dist/analysis/sdk/isEventraTrackCall.js

@@ -91,7 +91,12 @@ function isEventraNewExpression(node, checker) {
         return false;
     }
     const symbol = checker.getSymbolAtLocation(expr);
-    return symbol ? isEventraSymbol(symbol, checker) : false;
+    if (symbol && isEventraSymbol(symbol, checker)) {
+        return true;
+    }
+    // `const { Eventra } = await import("@eventra_dev/eventra-sdk")`: the binding is not an import, but
+    // the instance it builds is still typed as the SDK's class
+    return typeLooksLikeEventra(checker.getTypeAtLocation(node), checker);
 }
 function typeLooksLikeEventra(type, checker, depth = 0) {
     // cycle guard - TypeScript flattens union/intersection types (a literal
@@ -115,7 +120,63 @@ function typeLooksLikeEventra(type, checker, depth = 0) {
     }
     return false;
 }
-function isEventraReceiverExpression(receiver, checker) {
+const MAX_RECEIVER_HOPS = 6;
+/** `return expr` statements of a function body, not looking into functions nested in it. */
+function returnedExpressions(fn) {
+    if (!fn.body) {
+        return [];
+    }
+    if (!typescript_1.default.isBlock(fn.body)) {
+        return [fn.body];
+    }
+    const found = [];
+    const visit = (node) => {
+        if (typescript_1.default.isFunctionLike(node)) {
+            return;
+        }
+        if (typescript_1.default.isReturnStatement(node) && node.expression) {
+            found.push(node.expression);
+        }
+        typescript_1.default.forEachChild(node, visit);
+    };
+    visit(fn.body);
+    return found;
+}
+function functionOf(decl) {
+    if (typescript_1.default.isFunctionDeclaration(decl) || typescript_1.default.isMethodDeclaration(decl)) {
+        return decl;
+    }
+    if (typescript_1.default.isVariableDeclaration(decl) && decl.initializer && (typescript_1.default.isArrowFunction(decl.initializer) || typescript_1.default.isFunctionExpression(decl.initializer))) {
+        return decl.initializer;
+    }
+    return undefined;
+}
+/** `t = new Eventra(...)` anywhere in the file of a variable's declaration: a lazily filled `let t: any`. */
+function assignedValues(symbol, checker) {
+    const values = [];
+    const files = new Set((symbol.getDeclarations() ?? []).map((decl) => decl.getSourceFile()));
+    for (const file of files) {
+        const visit = (node) => {
+            if (typescript_1.default.isBinaryExpression(node) &&
+                node.operatorToken.kind === typescript_1.default.SyntaxKind.EqualsToken &&
+                typescript_1.default.isIdentifier(node.left) &&
+                checker.getSymbolAtLocation(node.left) === symbol) {
+                values.push(node.right);
+            }
+            typescript_1.default.forEachChild(node, visit);
+        };
+        visit(file);
+    }
+    return values;
+}
+function isEventraReceiverExpression(receiver, checker, hops = 0) {
+    if (hops > MAX_RECEIVER_HOPS) {
+        return false;
+    }
+    // `(await getTracker()).track(...)`, `(tracker as Eventra).track(...)`, `tracker!.track(...)`
+    if (typescript_1.default.isParenthesizedExpression(receiver) || typescript_1.default.isAwaitExpression(receiver) || typescript_1.default.isNonNullExpression(receiver) || typescript_1.default.isAsExpression(receiver)) {
+        return isEventraReceiverExpression(receiver.expression, checker, hops + 1);
+    }
     if (typescript_1.default.isNewExpression(receiver)) {
         return isEventraNewExpression(receiver, checker);
     }
@@ -126,6 +187,18 @@ function isEventraReceiverExpression(receiver, checker) {
     if (typeLooksLikeEventra(type, checker)) {
         return true;
     }
+    // `getTracker().track(...)` where the getter's type is lost (`any`) but what it returns is a tracker
+    if (typescript_1.default.isCallExpression(receiver)) {
+        const callee = typescript_1.default.isIdentifier(receiver.expression) || typescript_1.default.isPropertyAccessExpression(receiver.expression)
+            ? checker.getSymbolAtLocation(typescript_1.default.isIdentifier(receiver.expression) ? receiver.expression : receiver.expression.name)
+            : undefined;
+        for (const decl of callee?.getDeclarations() ?? []) {
+            const fn = functionOf(decl);
+            if (fn && returnedExpressions(fn).some((returned) => isEventraReceiverExpression(returned, checker, hops + 1))) {
+                return true;
+            }
+        }
+    }
     if (typescript_1.default.isIdentifier(receiver)) {
         const symbol = checker.getSymbolAtLocation(receiver);
         if (!symbol) {
@@ -134,6 +207,9 @@ function isEventraReceiverExpression(receiver, checker) {
         // See the identical `?? []` above isEventraSymbol's declaration loop: a
         // real ts.Symbol here always has a declarations array.
         /* v8 ignore next */
+        if (assignedValues(symbol, checker).some((value) => isEventraReceiverExpression(value, checker, hops + 1))) {
+            return true;
+        }
         for (const decl of symbol.getDeclarations() ?? []) {
             if (typescript_1.default.isVariableDeclaration(decl) && decl.initializer) {
                 if (typescript_1.default.isNewExpression(decl.initializer) && isEventraNewExpression(decl.initializer, checker)) {
@@ -167,7 +243,7 @@ function isEventraReceiverExpression(receiver, checker) {
         }
     }
     if (typescript_1.default.isPropertyAccessExpression(receiver) || typescript_1.default.isPropertyAccessChain(receiver)) {
-        return isEventraReceiverExpression(receiver.expression, checker);
+        return isEventraReceiverExpression(receiver.expression, checker, hops + 1);
     }
     return false;
 }

package/dist/analysis/symbols/symbolUtils.js

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getValueSymbol = getValueSymbol;
 exports.getFunctionSymbol = getFunctionSymbol;
+exports.isReturnedFunction = isReturnedFunction;
+exports.wrapperName = wrapperName;
 const typescript_1 = __importDefault(require("typescript"));
 /**
  * Symbol an identifier *refers to*. For the name in a shorthand property (`{ event }`) a plain
@@ -53,5 +55,44 @@ function getFunctionSymbol(node, checker) {
     if (typescript_1.default.isExportAssignment(parent)) {
         return checker.getSymbolAtLocation(node);
     }
+    // `return (name) => ...` / `() => (name) => ...`: a function a hook or factory hands back has no
+    // name of its own, but the binder still gives it a symbol, and that is what a call of the result
+    // (`const track = useTracker(); track("x")`) is matched against.
+    if (isReturnedFunction(node)) {
+        return node.symbol;
+    }
     return undefined;
 }
+/** An arrow/function expression that is the value of a `return`, or the concise body of an arrow. */
+function isReturnedFunction(node) {
+    if (!typescript_1.default.isArrowFunction(node) && !typescript_1.default.isFunctionExpression(node)) {
+        return false;
+    }
+    let outer = node.parent;
+    while (typescript_1.default.isParenthesizedExpression(outer)) {
+        outer = outer.parent;
+    }
+    return typescript_1.default.isReturnStatement(outer) || (typescript_1.default.isArrowFunction(outer) && unparen(outer.body) === node);
+}
+function unparen(node) {
+    while (typescript_1.default.isParenthesizedExpression(node)) {
+        node = node.expression;
+    }
+    return node;
+}
+/**
+ * The name a wrapper is reported under: its own, or for an anonymous returned function the hook that
+ * returns it (`useTracker` for `function useTracker() { return (n) => t.track(n); }`).
+ */
+function wrapperName(declaration, symbol) {
+    if (!isReturnedFunction(declaration)) {
+        return symbol.getName();
+    }
+    const owner = typescript_1.default.findAncestor(declaration.parent, (n) => typescript_1.default.isFunctionLike(n));
+    const ownerName = owner && owner.name;
+    if (ownerName && typescript_1.default.isIdentifier(ownerName)) {
+        return ownerName.text;
+    }
+    const holder = owner?.parent;
+    return holder && typescript_1.default.isVariableDeclaration(holder) && typescript_1.default.isIdentifier(holder.name) ? holder.name.text : symbol.getName();
+}