@eventra_dev/eventra-cli 2.2.0 → 2.3.0

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/resolver/callResolver.js

@@ -9,7 +9,7 @@ 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) {
+function resolveDeclaration(declaration, checker) {
     // function foo() {}
     if (isFunctionLike(declaration)) {
         return declaration;
@@ -26,6 +26,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) {
@@ -69,7 +83,7 @@ function resolveFunctionFromCall(expression, checker, callCache, exportCache) {
     // declaration resolution
     const declarations = symbol.getDeclarations() ?? [];
     for (const declaration of declarations) {
-        const resolved = resolveDeclaration(declaration);
+        const resolved = resolveDeclaration(declaration, checker);
         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/cli/init.js

@@ -3,10 +3,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInstalled = isInstalled;
 exports.init = init;
 const chalk_1 = __importDefault(require("chalk"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const inquirer_1 = __importDefault(require("inquirer"));
+const module_1 = require("module");
 const path_1 = __importDefault(require("path"));
 const config_1 = require("../config/config");
 const sinkPresets_1 = require("../plugin/builtins/sinkPresets");
@@ -15,8 +17,8 @@ const projectDependencies_1 = require("./projectDependencies");
  * Looks for analytics libraries in package.json (and workspace members) and, if there are any,
  * asks which of them Eventra should read events from. Everything detected is pre-selected.
  */
-async function chooseSinks(yes) {
-    const detected = (0, sinkPresets_1.detectSinkPresets)(await (0, projectDependencies_1.collectDependencyNames)(process.cwd()));
+async function chooseSinks(yes, dependencyNames) {
+    const detected = (0, sinkPresets_1.detectSinkPresets)(dependencyNames);
     if (detected.length === 0)
         return [];
     console.log(chalk_1.default.gray(`Found analytics in package.json: ${detected.map((d) => d.packages.join(", ")).join("; ")}`));
@@ -36,12 +38,40 @@ async function chooseSinks(yes) {
     ]);
     return presets.map((preset) => ({ preset }));
 }
+/** Framework dependency -> the plugin that reads its template files (`.vue`, `.svelte`, `.astro`, Angular templates). */
+const FRAMEWORK_PLUGINS = {
+    vue: "@eventra_dev/cli-plugin-vue",
+    svelte: "@eventra_dev/cli-plugin-svelte",
+    astro: "@eventra_dev/cli-plugin-astro",
+    "@angular/core": "@eventra_dev/cli-plugin-angular",
+};
+/** True when the plugin package can be loaded from the project, which is where `sync` will look for it. */
+function isInstalled(plugin) {
+    try {
+        (0, module_1.createRequire)(path_1.default.join(process.cwd(), "package.json")).resolve(plugin);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The plugins for the frameworks found in package.json (and workspace members), split by whether they are
+ * installed. Without a plugin, events fired from component files are never seen. Only an installed one is
+ * written to `plugins`: `sync` stops on a plugin it cannot load, and an `init` followed by `sync` must not.
+ */
+function detectPlugins(dependencyNames, installed) {
+    const found = Object.entries(FRAMEWORK_PLUGINS)
+        .filter(([dependency]) => dependencyNames.has(dependency))
+        .map(([, plugin]) => plugin);
+    return { enabled: found.filter(installed), missing: found.filter((plugin) => !installed(plugin)) };
+}
 const DEFAULT_ENDPOINT = "https://api.eventra.dev/api/v1/cli/events";
 /**
  * `yes` is the non-interactive mode (CI, scripts): defaults for every answer,
  * and an existing eventra.json is never overwritten.
  */
-async function init({ yes = false } = {}) {
+async function init({ yes = false, isPluginInstalled = isInstalled } = {}) {
     if (await fs_extra_1.default.pathExists(path_1.default.join(process.cwd(), config_1.CONFIG_NAME))) {
         if (yes) {
             console.log(chalk_1.default.yellow(`${config_1.CONFIG_NAME} already exists, keeping it`));
@@ -76,7 +106,9 @@ async function init({ yes = false } = {}) {
                 default: DEFAULT_ENDPOINT,
             },
         ]);
-    const sinks = await chooseSinks(yes);
+    const dependencyNames = await (0, projectDependencies_1.collectDependencyNames)(process.cwd());
+    const sinks = await chooseSinks(yes, dependencyNames);
+    const { enabled: plugins, missing: missingPlugins } = detectPlugins(dependencyNames, isPluginInstalled);
     console.log("");
     console.log(chalk_1.default.gray("Eventra detects @eventra_dev/eventra-sdk usage:"));
     console.log(chalk_1.default.gray('• tracker.track("event.name")'));
@@ -88,21 +120,24 @@ async function init({ yes = false } = {}) {
         endpoint,
         events: [],
         functionWrappers: [],
+        ...(plugins.length > 0 ? { plugins } : {}),
         ...(sinks.length > 0 ? { sinks } : {}),
         sync: {
             include: [
                 "**/*.{ts,tsx,js,jsx}",
             ],
-            exclude: [
-                "node_modules",
-                "dist",
-                ".next",
-                ".git",
-            ],
+            exclude: [...config_1.INIT_EXCLUDE],
         },
     };
     await (0, config_1.saveConfig)(config);
     console.log(chalk_1.default.green("eventra.json created"));
+    if (plugins.length > 0) {
+        console.log(chalk_1.default.green(`plugins: ${plugins.join(", ")}`));
+    }
+    if (missingPlugins.length > 0) {
+        console.log(chalk_1.default.yellow(`Component files are not read yet: npm install -D ${missingPlugins.join(" ")}`));
+        console.log(chalk_1.default.yellow(`then add ${missingPlugins.map((p) => `"${p}"`).join(", ")} to "plugins" in ${config_1.CONFIG_NAME}`));
+    }
     if (sinks.length > 0) {
         console.log(chalk_1.default.green(`sinks: ${sinks.map((s) => s.preset).join(", ")}`));
     }

package/dist/cli/projectDependencies.js

@@ -3,13 +3,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.memberGlob = exports.MAX_WORKSPACE_PACKAGES = void 0;
+exports.stringList = stringList;
+exports.pnpmWorkspacePatterns = pnpmWorkspacePatterns;
+exports.staysInsideProject = staysInsideProject;
 exports.collectDependencyNames = collectDependencyNames;
 const fast_glob_1 = __importDefault(require("fast-glob"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const DEPENDENCY_FIELDS = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
 /** Upper bound on workspace members read, so a huge monorepo cannot make `init` crawl. */
-const MAX_WORKSPACE_PACKAGES = 300;
+exports.MAX_WORKSPACE_PACKAGES = 300;
 /**
  * Parsed package.json, or null when it is missing or not JSON. Whatever else the file holds (an
  * array, a number) is returned as is: every reader below only looks up named properties on it, which
@@ -86,10 +90,11 @@ async function workspacePatterns(rootDir, rootPackage) {
  * `!apps/skipped/package.json`, which fast-glob treats as an exclusion of exactly those files.
  */
 const memberGlob = (pattern) => `${pattern}/package.json`;
+exports.memberGlob = memberGlob;
 /** Member package.json paths for the patterns; a pattern fast-glob rejects (a NUL byte, say) yields none. */
 async function findMembers(rootDir, patterns) {
     try {
-        return await (0, fast_glob_1.default)(patterns.map(memberGlob), { cwd: rootDir, ignore: ["**/node_modules/**"] });
+        return await (0, fast_glob_1.default)(patterns.map(exports.memberGlob), { cwd: rootDir, ignore: ["**/node_modules/**"] });
     }
     catch {
         // Stryker disable next-line ArrayDeclaration: a stray path that is not a package.json is read as "no package.json"
@@ -108,7 +113,7 @@ async function collectDependencyNames(rootDir) {
     for (const name of dependencyNames(rootPackage))
         names.add(name);
     const patterns = await workspacePatterns(rootDir, rootPackage);
-    const members = (await findMembers(rootDir, patterns)).slice(0, MAX_WORKSPACE_PACKAGES);
+    const members = (await findMembers(rootDir, patterns)).slice(0, exports.MAX_WORKSPACE_PACKAGES);
     for (const member of members) {
         const memberPackage = await readPackage(path_1.default.join(rootDir, member));
         if (memberPackage !== null)

package/dist/compiler/compilerContext.js

@@ -8,6 +8,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const typescript_1 = __importDefault(require("typescript"));
 const documentRegistry_1 = require("./documentRegistry");
+const workspacePackages_1 = require("./workspacePackages");
 class CompilerContext {
     rootDir;
     registry = new documentRegistry_1.DocumentRegistry();
@@ -22,9 +23,15 @@ class CompilerContext {
     // scan and flushes once, so an eager build in the constructor was thrown away.
     programInstance;
     rootNames = new Set();
-    // Only set while withResolutionCache() runs: it memoises fileExists results,
-    // so it must never outlive one batch of resolutions against one program.
-    activeResolutionCache;
+    // compiler options of the nearest tsconfig.json above a folder (the root one for files outside any other)
+    optionsByDir = new Map();
+    // the options a project starts from before any tsconfig.json is applied
+    defaultOptions;
+    workspacePackages;
+    // one module resolution cache per set of options; only alive while a program is built or a batch runs
+    resolutionCaches = new Map();
+    // how many builds or batches are running that share the caches (a rebuild can start inside a batch)
+    cachingDepth = 0;
     constructor(rootDir) {
         this.rootDir = rootDir;
         const localTsconfig = path_1.default.join(rootDir, "tsconfig.json");
@@ -45,6 +52,7 @@ class CompilerContext {
             allowNonTsExtensions: true,
             incremental: false,
         };
+        this.defaultOptions = compilerOptions;
         if (configPath) {
             const config = typescript_1.default.readConfigFile(configPath, typescript_1.default.sys.readFile);
             if (config.error) {
@@ -55,17 +63,138 @@ class CompilerContext {
                 ...compilerOptions,
                 ...parsed.options,
             };
+            // A solution-style tsconfig (`"files": []` plus `references`, the Vite and Vue template) keeps its
+            // `@/*` aliases in a referenced config, so without this every aliased import stays unresolved.
+            if (!parsed.options.paths) {
+                Object.assign(compilerOptions, this.pathOptionsFromReferences(parsed.projectReferences));
+            }
             for (const file of parsed.fileNames) {
                 this.rootNames.add(this.normalize(file));
             }
         }
         this.compilerOptions = compilerOptions;
+        this.workspacePackages = (0, workspacePackages_1.findWorkspacePackages)(rootDir);
         this.host = typescript_1.default.createCompilerHost(this.compilerOptions, true);
         this.patchCompilerHost();
     }
     normalize(fileName) {
         return this.registry.normalize(fileName);
     }
+    /**
+     * Compiler options for resolving the imports of `fromFile`: those of the nearest tsconfig.json above
+     * it. A monorepo keeps one per app (`@/*` means a different folder in each) and often none at the root;
+     * a single root-level tsconfig.json answers for every file below it, as it always did.
+     */
+    optionsFor(fromFile) {
+        // an installed package may ship a tsconfig.json of its own: its settings are for building it, not for this project
+        if (fromFile.split(/[\\/]/).includes("node_modules"))
+            return this.compilerOptions;
+        const visited = [];
+        let options = this.compilerOptions;
+        for (let dir = path_1.default.dirname(fromFile);; dir = path_1.default.dirname(dir)) {
+            const cached = this.optionsByDir.get(dir);
+            const own = cached ?? this.readDirectoryOptions(dir);
+            if (own) {
+                options = own;
+                visited.push(dir);
+                break;
+            }
+            visited.push(dir);
+            // a file outside the project, or the top of the filesystem, keeps the root options
+            if (path_1.default.relative(this.rootDir, dir).startsWith("..") || path_1.default.dirname(dir) === dir || dir === this.rootDir)
+                break;
+        }
+        for (const dir of visited)
+            this.optionsByDir.set(dir, options);
+        return options;
+    }
+    /** The options a folder's own tsconfig.json sets, `undefined` when it has none (the root's are already loaded). */
+    readDirectoryOptions(dir) {
+        if (dir === this.rootDir)
+            return this.compilerOptions;
+        const configPath = path_1.default.join(dir, "tsconfig.json");
+        if (!fs_1.default.existsSync(configPath))
+            return undefined;
+        const config = typescript_1.default.readConfigFile(configPath, typescript_1.default.sys.readFile);
+        if (config.error)
+            return undefined;
+        const parsed = typescript_1.default.parseJsonConfigFileContent(config.config, typescript_1.default.sys, dir);
+        return {
+            ...this.defaultOptions,
+            ...parsed.options,
+            ...(parsed.options.paths ? {} : this.aliasesWithout(parsed.options, parsed.projectReferences)),
+        };
+    }
+    /**
+     * Aliases for a config that sets no `paths` of its own: those of its project references, or else the root's.
+     * A tsconfig.json that only adjusts a few options (a `tests/` one, say) does not mean the root's `@/*` stopped
+     * being valid there, and the root's aliases applied to every file before configs were read per folder.
+     */
+    aliasesWithout(own, references) {
+        const fromReferences = this.pathOptionsFromReferences(references);
+        if (fromReferences.paths)
+            return fromReferences;
+        const { paths, baseUrl, pathsBasePath } = this.compilerOptions;
+        return { paths, baseUrl: own.baseUrl ?? baseUrl, pathsBasePath };
+    }
+    cacheFor(options) {
+        if (this.cachingDepth === 0)
+            return undefined;
+        let cache = this.resolutionCaches.get(options);
+        if (!cache) {
+            cache = typescript_1.default.createModuleResolutionCache(this.rootDir, (fileName) => this.normalize(fileName), options);
+            this.resolutionCaches.set(options, cache);
+        }
+        return cache;
+    }
+    /** Where a monorepo package's own folder is for an import of it (`@acme/lib`, `@acme/lib/hooks/x`), if it is one. */
+    workspaceTargets(moduleName) {
+        let best;
+        for (const [name, dir] of this.workspacePackages) {
+            if ((moduleName === name || moduleName.startsWith(`${name}/`)) && (!best || name.length > best.name.length)) {
+                best = { name, dir };
+            }
+        }
+        if (!best)
+            return [];
+        const sub = moduleName.slice(best.name.length + 1);
+        // the package's sources may sit in src/ while its package.json points at a build that is not there
+        return [path_1.default.join(best.dir, sub), path_1.default.join(best.dir, "src", sub)];
+    }
+    resolveImport(moduleName, containingFile, redirectedReference, mode) {
+        const options = this.optionsFor(containingFile);
+        const cache = this.cacheFor(options);
+        const resolved = typescript_1.default.resolveModuleName(moduleName, containingFile, options, this.host, cache, redirectedReference, mode);
+        if (resolved.resolvedModule)
+            return resolved;
+        // not installed, so no node_modules link: a package of this very monorepo is found by its folder
+        for (const target of this.workspaceTargets(moduleName)) {
+            const viaWorkspace = typescript_1.default.resolveModuleName(target, containingFile, options, this.host, cache, redirectedReference, mode);
+            if (viaWorkspace.resolvedModule)
+                return viaWorkspace;
+        }
+        return resolved;
+    }
+    /**
+     * Alias options (`paths`, `baseUrl`) of the first referenced tsconfig that defines `paths`. A
+     * reference that is unreadable or has no aliases is skipped; only aliases are taken, never the files.
+     */
+    pathOptionsFromReferences(references) {
+        for (const reference of references ?? []) {
+            const referenced = typescript_1.default.sys.directoryExists(reference.path)
+                ? path_1.default.join(reference.path, "tsconfig.json")
+                : reference.path;
+            const config = typescript_1.default.readConfigFile(referenced, typescript_1.default.sys.readFile);
+            if (config.error)
+                continue;
+            const { options } = typescript_1.default.parseJsonConfigFileContent(config.config, typescript_1.default.sys, path_1.default.dirname(referenced));
+            if (options.paths) {
+                const { paths, baseUrl, pathsBasePath } = options;
+                return { paths, baseUrl, pathsBasePath };
+            }
+        }
+        return {};
+    }
     resolveLanguageVersion(languageVersionOrOptions) {
         if (typeof languageVersionOrOptions === "object") {
             return languageVersionOrOptions.languageVersion;
@@ -127,6 +256,7 @@ class CompilerContext {
             const normalized = this.normalize(fileName);
             return this.registry.has(normalized) || fs_1.default.existsSync(normalized);
         };
+        this.host.resolveModuleNameLiterals = (literals, containingFile, redirectedReference, _options, containingSourceFile) => literals.map((literal) => this.resolveImport(literal.text, containingFile, redirectedReference, typescript_1.default.getModeForUsageLocation(containingSourceFile, literal, this.compilerOptions)));
         this.host.getCanonicalFileName = (f) => this.normalize(f);
         this.host.useCaseSensitiveFileNames = () => true;
         this.host.getCurrentDirectory = () => this.rootDir;
@@ -146,7 +276,29 @@ class CompilerContext {
         return typescript_1.default.ScriptKind.Unknown;
     }
     rebuildProgram() {
-        this.programInstance = typescript_1.default.createProgram([...this.rootNames], this.compilerOptions, this.host);
+        // options are re-read from disk with every build, so an edited nested tsconfig.json is seen
+        this.optionsByDir.clear();
+        this.withSharedCaches(() => {
+            this.programInstance = typescript_1.default.createProgram([...this.rootNames], this.compilerOptions, this.host);
+        });
+    }
+    /**
+     * Imports resolved while `fn` runs share caches, as they do in TypeScript's own host. Files may appear or
+     * go between runs, so nothing is kept after the outermost one; a run started inside another (a lazy
+     * program build inside a batch) joins it instead of dropping its caches.
+     */
+    withSharedCaches(fn) {
+        if (this.cachingDepth === 0)
+            this.resolutionCaches.clear();
+        this.cachingDepth++;
+        try {
+            return fn();
+        }
+        finally {
+            this.cachingDepth--;
+            if (this.cachingDepth === 0)
+                this.resolutionCaches.clear();
+        }
     }
     get program() {
         if (!this.programInstance) {
@@ -160,16 +312,7 @@ class CompilerContext {
      * same directory lookups. The cache is dropped when `fn` returns.
      */
     withResolutionCache(fn) {
-        if (this.activeResolutionCache) {
-            return fn();
-        }
-        this.activeResolutionCache = typescript_1.default.createModuleResolutionCache(this.rootDir, (fileName) => this.normalize(fileName), this.compilerOptions);
-        try {
-            return fn();
-        }
-        finally {
-            this.activeResolutionCache = undefined;
-        }
+        return this.withSharedCaches(fn);
     }
     /** Register file content without rebuilding the TS program (batch via {@link flushUpdates}). */
     stageFile(fileName, content) {
@@ -271,8 +414,7 @@ class CompilerContext {
         ];
     }
     resolveModule(moduleName, fromFile) {
-        const resolved = typescript_1.default.resolveModuleName(moduleName, this.normalize(fromFile), this.compilerOptions, this.host, this.activeResolutionCache);
-        return resolved.resolvedModule?.resolvedFileName;
+        return this.resolveImport(moduleName, this.normalize(fromFile)).resolvedModule?.resolvedFileName;
     }
     getResolvedModules(fileName) {
         const source = this.getSourceFile(fileName);

package/dist/compiler/workspacePackages.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.findWorkspacePackages = findWorkspacePackages;
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const projectDependencies_1 = require("../cli/projectDependencies");
+function readJson(file) {
+    try {
+        return JSON.parse(fs_1.default.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The packages of a monorepo (`workspaces` in package.json, or pnpm-workspace.yaml) by name, mapped to
+ * their folder. `import "@acme/lib/hooks/x"` then resolves to a folder of the repo itself, so a project
+ * whose dependencies are not installed still links its own packages together.
+ */
+function findWorkspacePackages(rootDir) {
+    const packages = new Map();
+    const rootPackage = readJson(path_1.default.join(rootDir, "package.json"));
+    if (!rootPackage)
+        return packages;
+    const workspaces = rootPackage.workspaces;
+    const fromPackageJson = Array.isArray(workspaces)
+        ? (0, projectDependencies_1.stringList)(workspaces)
+        : (0, projectDependencies_1.stringList)(workspaces?.packages);
+    let fromPnpm = [];
+    try {
+        fromPnpm = (0, projectDependencies_1.pnpmWorkspacePatterns)(fs_1.default.readFileSync(path_1.default.join(rootDir, "pnpm-workspace.yaml"), "utf8"));
+    }
+    catch {
+        // no pnpm-workspace.yaml (or an unreadable one): the package.json patterns are all there is
+    }
+    const patterns = [...fromPackageJson, ...fromPnpm].filter(projectDependencies_1.staysInsideProject);
+    if (patterns.length === 0)
+        return packages;
+    let members;
+    try {
+        members = fast_glob_1.default.sync(patterns.map(projectDependencies_1.memberGlob), { cwd: rootDir, ignore: ["**/node_modules/**"] });
+    }
+    catch {
+        // a pattern fast-glob rejects: no members
+        return packages;
+    }
+    for (const member of members.slice(0, projectDependencies_1.MAX_WORKSPACE_PACKAGES)) {
+        const name = readJson(path_1.default.join(rootDir, member))?.name;
+        if (typeof name === "string" && name !== "" && !packages.has(name)) {
+            packages.set(name, path_1.default.dirname(path_1.default.join(rootDir, member)));
+        }
+    }
+    return packages;
+}

package/dist/config/config.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LOCAL_CONFIG_NAME = exports.CONFIG_NAME = void 0;
+exports.INIT_EXCLUDE = exports.LOCAL_CONFIG_NAME = exports.CONFIG_NAME = void 0;
 exports.normalizeConfig = normalizeConfig;
 exports.loadConfig = loadConfig;
 exports.describeConfigProblem = describeConfigProblem;
@@ -22,7 +22,22 @@ exports.CONFIG_NAME = "eventra.json";
  */
 exports.LOCAL_CONFIG_NAME = "eventra.local.json";
 const DEFAULT_INCLUDE = ["**/*.{ts,tsx,js,jsx}"];
+// what a config without `sync.exclude` has always skipped; changing it would change the scan of every
+// existing project that never wrote its own list
 const DEFAULT_EXCLUDE = ["node_modules", "dist", ".next", ".git"];
+/**
+ * What `eventra init` writes into a new eventra.json: the default above plus folders and files whose
+ * code is not the product. Events fired from a test are not features, and on a large repository the tests
+ * alone can double the files scanned. Written out, so it is visible and editable. `build` and `out` are
+ * left out on purpose: they are as likely to be a source folder as output.
+ */
+exports.INIT_EXCLUDE = [
+    ...DEFAULT_EXCLUDE,
+    "coverage",
+    "**/*.{test,spec}.{ts,tsx,js,jsx}",
+    "**/__tests__/**",
+    "**/__mocks__/**",
+];
 function normalizeSinks(sinks) {
     if (!Array.isArray(sinks))
         return [];

package/dist/core/EventraEngine.js

@@ -14,6 +14,7 @@ const resolvedCallCache_1 = require("../analysis/cache/resolvedCallCache");
 const resolvedExportCache_1 = require("../analysis/cache/resolvedExportCache");
 const returnPropagationCache_1 = require("../analysis/cache/returnPropagationCache");
 const analyzeFile_1 = require("../analysis/engine/analyzeFile");
+const wrapperChains_1 = require("../analysis/scanner/wrapperChains");
 const wrapperRegistry_1 = require("../analysis/symbols/wrapperRegistry");
 const loadPlugins_1 = require("../plugin/loadPlugins");
 const EMPTY_RESULT = () => ({
@@ -117,6 +118,17 @@ class EventraEngine {
         for (const sf of sources) {
             this.indexFile(sf.fileName, config);
         }
+        this.resolveWrapperChains();
+    }
+    // Wrappers that reach a sink only through another wrapper (`trackEvent` -> `capture` -> the SDK
+    // call) need every file indexed first, so this runs after the files are indexed, never per file.
+    resolveWrapperChains() {
+        const found = (0, wrapperChains_1.resolveWrapperChains)(this.fileIndices.values(), this.compiler.getChecker(), this.wrapperRegistry, this.resolvedCallCache, this.resolvedExportCache);
+        for (const [file, wrappers] of found) {
+            const index = this.fileIndices.get(file);
+            const kept = index.wrappers.filter((w) => !wrappers.some((n) => n.declaration === w.declaration));
+            this.fileIndices.set(file, { ...index, wrappers: [...kept, ...wrappers] });
+        }
     }
     beginPreload() {
         this.isPreloading = true;
@@ -213,6 +225,7 @@ class EventraEngine {
             this.scannedFiles.add(file);
             this.indexFile(file, config);
         }
+        this.resolveWrapperChains();
         for (const file of normalized) {
             this.extractFile(file, config);
         }
@@ -310,6 +323,7 @@ class EventraEngine {
         this.scannedFiles.add(this.normalize(fileName));
         this.refreshChecker();
         this.indexFile(fileName, config);
+        this.resolveWrapperChains();
         return this.extractFile(fileName, config);
     }
     async removeFile(fileName, config) {

package/dist/index.js

@@ -39,45 +39,53 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const package_json_1 = __importDefault(require("../package.json"));
-const program = new commander_1.Command();
-program
-    .name("eventra")
-    .description("Eventra CLI")
-    .version(package_json_1.default.version);
-program
-    .command("init")
-    .option("-y, --yes", "do not prompt: accept defaults and keep an existing eventra.json")
-    .action(async (opts) => {
-    const { init } = await Promise.resolve().then(() => __importStar(require("./cli/init")));
-    await init({ yes: opts.yes });
+const respawn_1 = require("./respawn");
+// a large repository can need more memory than Node's default: start again with enough
+(0, respawn_1.respawnWithMoreHeap)().then((respawned) => {
+    if (!respawned)
+        run();
 });
-program
-    .command("sync")
-    .option("--strict", "exit with a non-zero code if any file could not be analysed")
-    .action(async (opts) => {
-    const { sync } = await Promise.resolve().then(() => __importStar(require("./cli/sync")));
-    await sync({ strict: opts.strict });
-});
-program
-    .command("check")
-    .option("--fix", "auto fix issues")
-    .option("--strict", "exit with a non-zero code if any file could not be analysed")
-    .action(async (opts) => {
-    const { check } = await Promise.resolve().then(() => __importStar(require("./cli/check")));
-    await check({ fix: opts.fix, strict: opts.strict });
-});
-program
-    .command("watch")
-    .description("Watch files and detect events in real-time")
-    .action(async () => {
-    const { watch } = await Promise.resolve().then(() => __importStar(require("./cli/watch")));
-    await watch();
-});
-program
-    .command("send")
-    .option("--trust-endpoint", "approve the current eventra.json endpoint for local use")
-    .action(async (opts) => {
-    const { send } = await Promise.resolve().then(() => __importStar(require("./cli/send")));
-    await send({ trustEndpoint: opts.trustEndpoint });
-});
-program.parse();
+function run() {
+    const program = new commander_1.Command();
+    program
+        .name("eventra")
+        .description("Eventra CLI")
+        .version(package_json_1.default.version);
+    program
+        .command("init")
+        .option("-y, --yes", "do not prompt: accept defaults and keep an existing eventra.json")
+        .action(async (opts) => {
+        const { init } = await Promise.resolve().then(() => __importStar(require("./cli/init")));
+        await init({ yes: opts.yes });
+    });
+    program
+        .command("sync")
+        .option("--strict", "exit with a non-zero code if any file could not be analysed")
+        .action(async (opts) => {
+        const { sync } = await Promise.resolve().then(() => __importStar(require("./cli/sync")));
+        await sync({ strict: opts.strict });
+    });
+    program
+        .command("check")
+        .option("--fix", "auto fix issues")
+        .option("--strict", "exit with a non-zero code if any file could not be analysed")
+        .action(async (opts) => {
+        const { check } = await Promise.resolve().then(() => __importStar(require("./cli/check")));
+        await check({ fix: opts.fix, strict: opts.strict });
+    });
+    program
+        .command("watch")
+        .description("Watch files and detect events in real-time")
+        .action(async () => {
+        const { watch } = await Promise.resolve().then(() => __importStar(require("./cli/watch")));
+        await watch();
+    });
+    program
+        .command("send")
+        .option("--trust-endpoint", "approve the current eventra.json endpoint for local use")
+        .action(async (opts) => {
+        const { send } = await Promise.resolve().then(() => __importStar(require("./cli/send")));
+        await send({ trustEndpoint: opts.trustEndpoint });
+    });
+    program.parse();
+}

package/dist/plugin/builtins/configuredSinks.js

@@ -82,20 +82,6 @@ function moduleMatches(specifier, modules) {
     return modules.some((m) => specifier === m || specifier.startsWith(`${m}/`));
 }
 const MAX_ALIAS_HOPS = 6;
-/** Identifiers naming the types in a type annotation: `PostHog`, `PostHog | null`, `ph.PostHog`. */
-function typeReferenceRoots(type) {
-    if (typescript_1.default.isParenthesizedTypeNode(type))
-        return typeReferenceRoots(type.type);
-    if (typescript_1.default.isUnionTypeNode(type) || typescript_1.default.isIntersectionTypeNode(type))
-        return type.types.flatMap(typeReferenceRoots);
-    if (typescript_1.default.isTypeReferenceNode(type)) {
-        let name = type.typeName;
-        while (typescript_1.default.isQualifiedName(name))
-            name = name.left;
-        return [name];
-    }
-    return [];
-}
 /**
  * The symbol an identifier refers to, keeping an import as the import binding itself. TS resolves an
  * import all the way to its target in some positions once something makes the module resolvable
@@ -109,6 +95,55 @@ function symbolAt(id, checker) {
         return symbol;
     return checker.getSymbolsInScope(id, typescript_1.default.SymbolFlags.Alias).find((alias) => alias.name === id.text) ?? symbol;
 }
+/** `import("m")`: the specifier of the call decides, no installed package needed. */
+function dynamicImportFrom(expression, modules) {
+    const specifier = typescript_1.default.isCallExpression(expression) && expression.expression.kind === typescript_1.default.SyntaxKind.ImportKeyword
+        ? expression.arguments[0]
+        : undefined;
+    return specifier !== undefined && typescript_1.default.isStringLiteralLike(specifier) && moduleMatches(specifier.text, modules);
+}
+const PROMISE_TYPES = new Set(["Promise", "PromiseLike"]);
+/**
+ * True when a type annotation names something from `modules`: `PostHog`, `PostHog | null`, `ph.PostHog`,
+ * `typeof import("posthog-js")`, `Promise<typeof import("posthog-js")>`, `typeof posthog`.
+ */
+function typeFromModules(type, checker, modules, hops) {
+    if (typescript_1.default.isParenthesizedTypeNode(type))
+        return typeFromModules(type.type, checker, modules, hops);
+    if (typescript_1.default.isUnionTypeNode(type) || typescript_1.default.isIntersectionTypeNode(type)) {
+        return type.types.some((member) => typeFromModules(member, checker, modules, hops));
+    }
+    if (typescript_1.default.isImportTypeNode(type)) {
+        return typescript_1.default.isLiteralTypeNode(type.argument) && typescript_1.default.isStringLiteral(type.argument.literal) && moduleMatches(type.argument.literal.text, modules);
+    }
+    const name = typescript_1.default.isTypeReferenceNode(type) ? type.typeName : typescript_1.default.isTypeQueryNode(type) ? type.exprName : undefined;
+    if (name === undefined)
+        return false;
+    let root = name;
+    while (typescript_1.default.isQualifiedName(root))
+        root = root.left;
+    return (symbolFromModules(symbolAt(root, checker), checker, modules, hops + 1) ||
+        // a promise of the module (`Promise<typeof import("posthog-js")>`), not any generic that mentions it
+        (typescript_1.default.isTypeReferenceNode(type) &&
+            typescript_1.default.isIdentifier(type.typeName) &&
+            PROMISE_TYPES.has(type.typeName.text) &&
+            (type.typeArguments ?? []).some((argument) => typeFromModules(argument, checker, modules, hops))));
+}
+/** `return expr` statements of a function body, not looking into functions nested in it. */
+function returnedExpressions(body) {
+    if (!typescript_1.default.isBlock(body))
+        return [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);
+    };
+    typescript_1.default.forEachChild(body, visit);
+    return found;
+}
 /** The symbol `name` exported by the module a specifier points at, when TS can resolve that module. */
 function resolveExport(specifier, name, checker) {
     const moduleSymbol = checker.getSymbolAtLocation(specifier);
@@ -123,6 +158,8 @@ function expressionFromModules(expression, checker, modules, hops) {
     let expr = (0, utils_1.unwrapExpression)(expression);
     if (typescript_1.default.isAwaitExpression(expr))
         expr = (0, utils_1.unwrapExpression)(expr.expression);
+    if (dynamicImportFrom(expr, modules))
+        return true;
     if (typescript_1.default.isCallExpression(expr) || typescript_1.default.isNewExpression(expr))
         expr = (0, utils_1.unwrapExpression)(expr.expression);
     const fromName = (name) => typescript_1.default.isIdentifier(name) && symbolFromModules(symbolAt(name, checker), checker, modules, hops);
@@ -133,7 +170,10 @@ function expressionFromModules(expression, checker, modules, hops) {
     let root = expr;
     while (typescript_1.default.isPropertyAccessExpression(root))
         root = (0, utils_1.unwrapExpression)(root.expression);
-    return fromName(expr.name) || fromName(root);
+    // `(await import("posthog-js")).default`
+    if (typescript_1.default.isAwaitExpression(root))
+        root = (0, utils_1.unwrapExpression)(root.expression);
+    return fromName(expr.name) || fromName(root) || dynamicImportFrom(root, modules);
 }
 function declarationFromModules(decl, checker, modules, hops) {
     if (typescript_1.default.isImportSpecifier(decl) || typescript_1.default.isImportClause(decl) || typescript_1.default.isNamespaceImport(decl)) {
@@ -162,15 +202,42 @@ function declarationFromModules(decl, checker, modules, hops) {
     if (typescript_1.default.isExportAssignment(decl)) {
         return expressionFromModules(decl.expression, checker, modules, hops + 1);
     }
+    // function useAnalytics() { return usePostHog() } / const load = () => import("posthog-js"): a function
+    // gives back what it returns (or what its return annotation names)
+    const fn = typescript_1.default.isFunctionDeclaration(decl) || typescript_1.default.isMethodDeclaration(decl)
+        ? decl
+        : (typescript_1.default.isVariableDeclaration(decl) || typescript_1.default.isPropertyDeclaration(decl)) &&
+            decl.initializer &&
+            (typescript_1.default.isArrowFunction(decl.initializer) || typescript_1.default.isFunctionExpression(decl.initializer))
+            ? decl.initializer
+            : undefined;
+    if (fn) {
+        if (fn.type && typeFromModules(fn.type, checker, modules, hops))
+            return true;
+        if (fn.body && returnedExpressions(fn.body).some((returned) => expressionFromModules(returned, checker, modules, hops + 1))) {
+            return true;
+        }
+    }
     // const { posthog } = usePostHog(): the binding's own declaration is the enclosing variable.
     const owner = typescript_1.default.isBindingElement(decl) ? decl.parent.parent : decl;
+    // promise.then(({ default: posthog }) => ...) / promise.then((mod) => ...): the parameter holds what the promise resolves to
+    if (typescript_1.default.isParameter(owner)) {
+        const callback = owner.parent;
+        const call = callback.parent;
+        if ((typescript_1.default.isArrowFunction(callback) || typescript_1.default.isFunctionExpression(callback)) &&
+            typescript_1.default.isCallExpression(call) &&
+            call.arguments[0] === callback &&
+            typescript_1.default.isPropertyAccessExpression(call.expression) &&
+            call.expression.name.text === "then") {
+            return expressionFromModules(call.expression.expression, checker, modules, hops + 1);
+        }
+    }
     // Variables, properties, parameters, functions (return type) and type aliases all keep their
     // annotation in `type`; variables, properties and parameters keep a default/initial value in
     // `initializer`. Anything else (classes, interfaces, ...) simply has neither.
     const { type, initializer } = owner;
     // let client: PostHog | null / private client: PostHog / (client: PostHog) => ... / type Client = PostHog
-    if (type &&
-        typeReferenceRoots(type).some((id) => symbolFromModules(symbolAt(id, checker), checker, modules, hops + 1))) {
+    if (type && typeFromModules(type, checker, modules, hops)) {
         return true;
     }
     // const ph = usePostHog() / new PostHog(k) / client = new PostHog(k) / const useTrack = usePostHog

package/dist/plugin/builtins/consoleDynamicEventReporter.js

@@ -28,6 +28,9 @@ const consoleDynamicEventReporter = {
             if (occ.inTemplate) {
                 console.log(chalk_1.default.yellow(`~ template of ${file}: event="${occ.eventExpression ?? ""}"${values}`));
             }
+            else if (occ.inTemplateCode) {
+                console.log(chalk_1.default.yellow(`~ template of ${file}: ${occ.calleeText}(...)${values}`));
+            }
             else {
                 console.log(chalk_1.default.yellow(`~ ${file}:${occ.line} ${occ.calleeText}(...)${values}`));
             }

package/dist/plugin/registry.js

@@ -7,6 +7,20 @@ exports.PluginRegistry = void 0;
 const path_1 = __importDefault(require("path"));
 // the synthetic callee each framework plugin uses for a template `event=...`
 const TEMPLATE_CALLEE = /^__eventra_[a-z]+_template_event__$/;
+// A plugin starts the code it generates from a template with this comment line, so a call found
+// below it is not on a line the user wrote.
+const TEMPLATE_REGION_START = /^\s*\/\/ --- [a-z]+ template \(auto-generated\) ---$/;
+// optional: a module that carries more after the generated code (an Angular component class) ends it
+const TEMPLATE_REGION_END = /^\s*\/\/ --- end template ---$/;
+// 1-based lines of the generated template region in a virtual module, or undefined when it has none
+function templateRegionOf(content) {
+    const lines = content.split("\n");
+    const start = lines.findIndex((line) => TEMPLATE_REGION_START.test(line));
+    if (start === -1)
+        return undefined;
+    const end = lines.findIndex((line, index) => index > start && TEMPLATE_REGION_END.test(line));
+    return { from: start + 1, to: end === -1 ? Infinity : end + 1 };
+}
 // `__eventra_x_template_event__(expr)` (callText may be cut with an ellipsis)
 function templateExpression(occurrence) {
     const open = occurrence.callText.indexOf("(");
@@ -22,6 +36,7 @@ class PluginRegistry {
     dynamicEventReporters = [];
     includePatterns = [];
     sourceToVirtuals = new Map();
+    templateRegions = new Map();
     registerFilePreprocessor(preprocessor) {
         if (this.preprocessors.some((p) => p.name === preprocessor.name)) {
             throw new Error(`File preprocessor already registered: ${preprocessor.name}`);
@@ -85,10 +100,23 @@ class PluginRegistry {
             }
             const files = await preprocessor.process(input);
             if (files.length > 0) {
+                // virtual files this source produced before and no longer does: their regions are not valid for anything else
+                for (const stale of this.sourceToVirtuals.get(sourceKey) ?? [])
+                    this.templateRegions.delete(stale);
+                for (const file of files) {
+                    const key = this.normalizePath(file.fileName);
+                    const region = templateRegionOf(file.content);
+                    if (region === undefined)
+                        this.templateRegions.delete(key);
+                    else
+                        this.templateRegions.set(key, region);
+                }
                 this.sourceToVirtuals.set(sourceKey, files.map((file) => this.normalizePath(file.fileName)));
                 return files;
             }
         }
+        for (const stale of this.sourceToVirtuals.get(sourceKey) ?? [])
+            this.templateRegions.delete(stale);
         this.sourceToVirtuals.delete(sourceKey);
         return [{ fileName: input.fileName, content: input.content }];
     }
@@ -147,6 +175,11 @@ class PluginRegistry {
                     eventExpression: templateExpression(occurrence),
                 };
             }
+            // ordinary code the plugin copied out of the template: its line is in the generated text
+            const region = this.templateRegions.get(this.normalizePath(occurrence.fileName));
+            if (region !== undefined && occurrence.line >= region.from && occurrence.line <= region.to) {
+                return { ...occurrence, fileName: source, inTemplateCode: true };
+            }
             // an Angular template module embeds the component class: lines there
             // are generated, the real call is also reported from the class file
             return source.toLowerCase().endsWith(".html")

package/dist/respawn.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultRespawnDeps = exports.SCANNING_COMMANDS = exports.RESPAWN_ENV = void 0;
+exports.wantedHeapMb = wantedHeapMb;
+exports.usableMemory = usableMemory;
+exports.respawnWithMoreHeap = respawnWithMoreHeap;
+const child_process_1 = require("child_process");
+const os_1 = __importDefault(require("os"));
+const v8_1 = __importDefault(require("v8"));
+/** Set on the child, so a process started with more memory never starts another one. */
+exports.RESPAWN_ENV = "EVENTRA_HEAP_RESPAWNED";
+/** The commands that read the whole project; the rest (`init`, `--version`, `--help`) stay in one process. */
+exports.SCANNING_COMMANDS = new Set(["sync", "check", "watch", "send"]);
+const MIB = 1024 * 1024;
+// a project of tens of thousands of files needs a few GB while its program is built; more than
+// this is never useful, and half the machine's memory is what can be taken without hurting it
+const MAX_HEAP_MB = 8192;
+const SHARE_OF_MEMORY = 0.5;
+/** Signals a parent passes on, so stopping it stops the child too instead of leaving it running. */
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+/**
+ * The old-space limit (MB) worth starting with, or `undefined` to carry on as is: Node's default
+ * limit is a fraction of the memory and can be well below what a large monorepo needs.
+ */
+function wantedHeapMb(availableMemoryBytes, currentLimitBytes) {
+    const wanted = Math.min(MAX_HEAP_MB, Math.floor((availableMemoryBytes * SHARE_OF_MEMORY) / MIB));
+    // not worth a second process for a small difference
+    return wanted > (currentLimitBytes / MIB) * 1.25 ? wanted : undefined;
+}
+/**
+ * Memory this process can use: the smaller of the machine's and the container's limit (cgroups) when it has
+ * one. `constrained` is 0 when nothing limits the process, and undefined on a Node that does not report it.
+ */
+function usableMemory(total, constrained) {
+    return constrained !== undefined && constrained > 0 ? Math.min(total, constrained) : total;
+}
+function runChild(command, args, env) {
+    return new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)(command, [...args], { stdio: "inherit", env });
+        const forwarders = FORWARDED_SIGNALS.map((signal) => {
+            const forward = () => child.kill(signal);
+            process.on(signal, forward);
+            return [signal, forward];
+        });
+        const done = (code) => {
+            for (const [signal, forward] of forwarders)
+                process.off(signal, forward);
+            resolve(code);
+        };
+        // a child that could not start at all (`error`) counts as a failed run, like one killed by a signal
+        child.on("error", () => done(1));
+        child.on("exit", (code) => done(code ?? 1));
+    });
+}
+const defaultRespawnDeps = () => ({
+    env: process.env,
+    execArgv: process.execArgv,
+    argv: process.argv,
+    execPath: process.execPath,
+    availableMemoryBytes: usableMemory(os_1.default.totalmem(), os_1.default.constrainedMemory?.()),
+    heapLimitBytes: v8_1.default.getHeapStatistics().heap_size_limit,
+    run: runChild,
+    exit: (code) => process.exit(code),
+});
+exports.defaultRespawnDeps = defaultRespawnDeps;
+/**
+ * Runs a scanning command again in a child with a larger heap when this process would start with too
+ * little, and exits with the child's status. Resolves `true` when it did, so the caller stops there. An
+ * explicit `--max-old-space-size` (in NODE_OPTIONS or the command line) is the user's choice and is left alone.
+ */
+async function respawnWithMoreHeap(deps = (0, exports.defaultRespawnDeps)()) {
+    if (deps.env[exports.RESPAWN_ENV])
+        return false;
+    // a second process costs startup time, so only a command that scans a project is worth it
+    if (!exports.SCANNING_COMMANDS.has(deps.argv[2] ?? ""))
+        return false;
+    const explicit = [deps.env.NODE_OPTIONS ?? "", ...deps.execArgv].some((part) => part.includes("max-old-space-size"));
+    if (explicit)
+        return false;
+    const heapMb = wantedHeapMb(deps.availableMemoryBytes, deps.heapLimitBytes);
+    if (heapMb === undefined)
+        return false;
+    const code = await deps.run(deps.execPath, [`--max-old-space-size=${heapMb}`, ...deps.execArgv, ...deps.argv.slice(1)], { ...deps.env, [exports.RESPAWN_ENV]: "1" });
+    deps.exit(code);
+    return true;
+}

package/package.json

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