@eventra_dev/eventra-cli 2.1.0 → 2.3.0

package/README.md

@@ -8,7 +8,7 @@
   <a href="https://www.npmjs.com/package/@eventra_dev/eventra-cli"><img alt="npm version" src="https://img.shields.io/npm/v/@eventra_dev/eventra-cli.svg?style=flat-square&color=blue"></a>
   <a href="https://www.npmjs.com/package/@eventra_dev/eventra-cli"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@eventra_dev/eventra-cli.svg?style=flat-square&color=blue"></a>
   <a href="https://github.com/and-1991/eventra-cli/actions/workflows/test.yml"><img alt="tests" src="https://img.shields.io/github/actions/workflow/status/and-1991/eventra-cli/test.yml?branch=main&label=tests&style=flat-square&logo=vitest&logoColor=white"></a>
-  <img alt="unit tests" src="https://img.shields.io/badge/unit-665%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white">
+  <img alt="unit tests" src="https://img.shields.io/badge/unit-783%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white">
   <img alt="e2e fixtures" src="https://img.shields.io/badge/e2e-14%20fixtures-brightgreen?style=flat-square">
   <img alt="coverage" src="https://img.shields.io/badge/coverage-100%25%20(unit)-brightgreen?style=flat-square&logo=vitest&logoColor=white">
   <img alt="node" src="https://img.shields.io/node/v/@eventra_dev/eventra-cli?style=flat-square&color=darkgreen&logo=node.js&logoColor=white">
@@ -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
@@ -212,7 +233,7 @@ Everything found is pre-selected; press Enter to accept or untick what you do no
 | `amplitude` | `@amplitude/analytics-browser`, `@amplitude/analytics-node`, `@amplitude/analytics-react-native`, `@amplitude/unified`, `@amplitude/marketing-analytics-browser`, and the older `amplitude-js` |
 | `ga4` | `react-ga4`, `vue-gtag`, `@next/third-parties`, `nuxt-gtag`, `@types/gtag.js`, and the older `vue-gtag-next` |
 
-Detection reads dependencies only. A tag pasted straight into the HTML (a Segment or `gtag.js` snippet with no package) is not seen: add the preset to `sinks` yourself. In a monorepo only the block-list form of `packages:` in `pnpm-workspace.yaml` is understood (not `packages: [a, b]`), and workspace patterns that are absolute or contain `..` are ignored. Running `init` again rewrites `eventra.json`.
+Detection reads dependencies only. A tag pasted straight into the HTML (a Segment or `gtag.js` snippet with no package) is not seen: add the preset to `sinks` yourself. In a monorepo only the block-list form of `packages:` in `pnpm-workspace.yaml` is understood (not `packages: [a, b]`), and workspace patterns that are absolute or contain `..` are ignored. If `eventra.json` already exists, `init` asks before overwriting it (the default answer is no). `eventra init --yes` never prompts: it uses the default endpoint, accepts every detected preset, and leaves an existing `eventra.json` untouched, so it is safe in scripts and CI.
 
 ### `eventra sync`
 
@@ -221,9 +242,11 @@ Full project scan → updates `eventra.json`:
 - `events` — discovered event names
 - `functionWrappers` — detected wrapper functions
 
+A file that cannot be analysed (a broken `.vue`, `.svelte`, `.astro` or `.html`, an unreadable file, or one over 2 MB) is skipped, and `sync` prints one summary at the end listing each skipped file and why. While anything is skipped, events already in `eventra.json` are kept, because a missing event may simply live in a skipped file. The exit code stays `0`; `eventra sync --strict` exits `1` if any file was skipped.
+
 ### `eventra check`
 
-Compares config with the current scan (events + wrappers). Exit code `1` on drift.
+Compares config with the current scan (events + wrappers). Exit code `1` on drift. When files were skipped, known events that were not found are not reported as removed (they cannot be verified) and the skipped files are listed; `eventra check --strict` also exits `1` if any file was skipped.
 
 ### `eventra check --fix`
 
@@ -255,6 +278,14 @@ This records the endpoint in `eventra.local.json` (gitignored). If `eventra.json
 
 Once `eventra.json` already commits an `endpoint`, that committed value is what events actually get sent to - `EVENTRA_ENDPOINT` only controls whether the approval prompt is skipped; its own value is not read or compared against anything in that case. `EVENTRA_ENDPOINT` becomes the real destination only when `eventra.json` has no `endpoint` set at all. In other words, setting the variable to point somewhere else does not redirect traffic away from an already-committed endpoint - it only means you won't be asked to approve it.
 
+**Catalog snapshot.** Besides the event list, `send` scans the project once more and tells the server how trustworthy that list is, so the dashboard can compare what is in your code with what actually arrived. It adds four optional fields to the request: `complete`, `dynamicCount`, `branch` and `cliVersion`.
+
+- `complete` is `true` only when the scan skipped no file, hit no error, and `eventra.json` matches what the scan just found. The server marks names that are missing from a complete snapshot as removed from code, so anything doubtful is `false` (a file that could not be parsed, a failed scan, or an `eventra.json` that is out of date: run `eventra sync` first). A request that is not complete never removes anything.
+- `dynamicCount` is the number of event-name call sites that could not be resolved to any string (for example `track(name)` with an unknown `name`). The dashboard uses it to warn that such names may show up as unexpected events.
+- `branch` is the current branch, read from the usual CI variables (`GITHUB_REF_NAME`, `CI_COMMIT_REF_NAME`, `BRANCH_NAME`, `BITBUCKET_BRANCH`, `CIRCLE_BRANCH`, `BUILDKITE_BRANCH`, `VERCEL_GIT_COMMIT_REF`) and otherwise from `git`; it is left out when unknown (for example a detached checkout with no CI variable). `cliVersion` is the CLI version.
+
+Run `send` from the main branch in CI: a snapshot from a feature branch describes that branch. A server that predates these fields rejects them, so `send` repeats the request once with the plain event list. The extra scan adds the same time as one `eventra sync`.
+
 Network resilience:
 
 - Up to 4 attempts with exponential backoff + jitter (capped at 8 s)
@@ -291,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.
@@ -311,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.
@@ -331,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.
@@ -355,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
 
@@ -416,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 |
+| `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`.
 
@@ -429,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.
@@ -440,14 +475,14 @@ No runtime execution. No monkey-patching.
 
 ## Requirements
 
-- Node.js 18+
+- Node.js 18+ (`eventra watch` needs Node.js 20.19+, which its file-watching dependency requires; `init`, `sync`, `check` and `send` run on 18)
 - TypeScript/JavaScript source using `@eventra_dev/eventra-sdk`
 
 ---
 
 ## Test Coverage
 
-Two test layers, **665 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.
 
@@ -458,7 +493,10 @@ Two test layers, **665 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/analysis/symbols/wrapperRegistry.js

@@ -7,18 +7,27 @@ function isSymbol(value) {
     return typeof value.getDeclarations === "function";
 }
 class WrapperRegistry {
-    checker;
+    pendingChecker;
     exportCache;
     wrappers = new WeakMap();
-    constructor(checker, exportCache) {
-        this.checker = checker;
+    resolvedChecker;
+    /** `checker` may be a provider, called once on first use (setChecker replaces it). */
+    constructor(pendingChecker, exportCache) {
+        this.pendingChecker = pendingChecker;
         this.exportCache = exportCache;
     }
     setChecker(checker) {
-        this.checker = checker;
+        this.resolvedChecker = checker;
     }
     getChecker() {
-        return this.checker;
+        if (!this.resolvedChecker) {
+            this.resolvedChecker =
+                typeof this.pendingChecker === "function" ? this.pendingChecker() : this.pendingChecker;
+        }
+        return this.resolvedChecker;
+    }
+    get checker() {
+        return this.getChecker();
     }
     normalize(symbol) {
         return ((0, exportResolver_1.resolveExportedSymbol)(symbol, this.checker, this.exportCache) ?? symbol);

package/dist/cli/check.js

@@ -8,30 +8,41 @@ const chalk_1 = __importDefault(require("chalk"));
 const config_1 = require("../config/config");
 const projectScanner_1 = require("../core/projectScanner");
 const scanResults_1 = require("../core/scanResults");
+const skipped_1 = require("../core/skipped");
 function diffSets(found, known) {
     return {
         added: [...found].filter((e) => !known.has(e)),
         removed: [...known].filter((e) => !found.has(e)),
     };
 }
-async function check({ fix = false }) {
-    const config = await (0, config_1.loadConfig)();
-    if (!config) {
-        console.log(chalk_1.default.red("eventra.json not found"));
-        process.exit(1);
-    }
+async function check({ fix = false, strict = false } = {}) {
+    const config = await (0, config_1.requireConfig)();
+    if (!config)
+        return;
     console.log(chalk_1.default.blue("Checking events and function wrappers..."));
-    const { engine, plugins } = await (0, projectScanner_1.scanProject)(config);
+    const { engine, plugins, skipped, ignored } = await (0, projectScanner_1.scanProject)(config);
     await plugins.runDynamicEventReporters(engine.getAllDynamicOccurrences());
+    const partial = skipped.length > 0;
     const foundEvents = new Set(engine.getAllEvents());
     const knownEvents = new Set(config.events ?? []);
     const eventDiff = diffSets(foundEvents, knownEvents);
     const foundWrappers = new Set(engine.getAllFunctionWrappers());
     const knownWrappers = new Set(config.functionWrappers?.map((w) => w.name) ?? []);
     const wrapperDiff = diffSets(foundWrappers, knownWrappers);
+    // With skipped files the scan is incomplete: a known event that was not found
+    // may simply live in a skipped file, so it is not reported as removed.
+    const unverified = partial ? eventDiff.removed.length + wrapperDiff.removed.length : 0;
+    if (partial) {
+        eventDiff.removed = [];
+        wrapperDiff.removed = [];
+    }
     if (fix) {
-        await (0, config_1.saveConfig)((0, scanResults_1.buildConfigFromScan)(config, engine));
+        await (0, config_1.saveConfig)((0, scanResults_1.buildConfigFromScan)(config, engine, { preserveKnown: partial }));
         console.log(chalk_1.default.green("Synced"));
+        (0, skipped_1.reportSkipped)(skipped);
+        (0, skipped_1.reportIgnored)(ignored);
+        if (strict && partial)
+            process.exitCode = 1;
         return;
     }
     let hasDiff = false;
@@ -47,7 +58,12 @@ async function check({ fix = false }) {
         wrapperDiff.added.forEach((w) => console.log(chalk_1.default.red(`+ ${w}`)));
         wrapperDiff.removed.forEach((w) => console.log(chalk_1.default.yellow(`- ${w}`)));
     }
-    if (hasDiff) {
+    (0, skipped_1.reportSkipped)(skipped);
+    (0, skipped_1.reportIgnored)(ignored);
+    if (unverified > 0) {
+        console.error(chalk_1.default.gray(`${(0, skipped_1.plural)(unverified, "known entry", "known entries")} could not be verified because files were skipped.`));
+    }
+    if (hasDiff || (strict && partial)) {
         process.exit(1);
     }
     console.log(chalk_1.default.green("All good"));

package/dist/cli/init.js

@@ -3,9 +3,13 @@ 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");
 const projectDependencies_1 = require("./projectDependencies");
@@ -13,11 +17,13 @@ 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() {
-    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("; ")}`));
+    if (yes)
+        return detected.map((d) => ({ preset: d.preset }));
     const { presets } = await inquirer_1.default.prompt([
         {
             type: "checkbox",
@@ -32,22 +38,77 @@ async function chooseSinks() {
     ]);
     return presets.map((preset) => ({ preset }));
 }
-async function init() {
+/** 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, 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`));
+            return;
+        }
+        const { overwrite } = await inquirer_1.default.prompt([
+            {
+                type: "confirm",
+                name: "overwrite",
+                message: `${config_1.CONFIG_NAME} already exists. Overwrite it? Its events, wrappers, plugins and sinks will be lost.`,
+                default: false,
+            },
+        ]);
+        if (!overwrite) {
+            console.log(chalk_1.default.gray(`Kept the existing ${config_1.CONFIG_NAME}`));
+            return;
+        }
+    }
     console.log(chalk_1.default.blue("Initializing Eventra..."));
-    const { apiKey, endpoint, } = await inquirer_1.default.prompt([
-        {
-            type: "input",
-            name: "apiKey",
-            message: "API Key (optional):",
-        },
-        {
-            type: "input",
-            name: "endpoint",
-            message: "Custom endpoint (optional):",
-            default: "https://api.eventra.dev/api/v1/cli/events",
-        },
-    ]);
-    const sinks = await chooseSinks();
+    const { apiKey, endpoint, } = yes
+        ? { apiKey: "", endpoint: DEFAULT_ENDPOINT }
+        : await inquirer_1.default.prompt([
+            {
+                type: "input",
+                name: "apiKey",
+                message: "API Key (optional):",
+            },
+            {
+                type: "input",
+                name: "endpoint",
+                message: "Custom endpoint (optional):",
+                default: DEFAULT_ENDPOINT,
+            },
+        ]);
+    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")'));
@@ -59,21 +120,24 @@ async function init() {
         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(", ")}`));
     }