@eventra_dev/eventra-cli 2.0.10 → 2.2.0

package/LICENSE

@@ -1,9 +1,21 @@
 MIT License
 
-Copyright (c) 2026 Eventra
+Copyright (c) 2026 and-1991
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software.
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,8 +8,8 @@
   <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-445%20passing-brightgreen?style=flat-square&logo=vitest&logoColor=white">
-  <img alt="e2e fixtures" src="https://img.shields.io/badge/e2e-12%20fixtures-brightgreen?style=flat-square">
+  <img alt="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">
   <a href="https://www.typescriptlang.org/"><img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-ready-blue?style=flat-square&logo=typescript&logoColor=white"></a>
@@ -24,7 +24,7 @@ Eventra CLI statically discovers analytics events from [**@eventra_dev/eventra-s
 
 The CLI scans TypeScript and JavaScript with the TypeScript compiler API and extracts **only** calls to `Eventra.prototype.track()` on instances of `Eventra` imported from `@eventra_dev/eventra-sdk`.
 
-It does **not** detect generic `track()`, Segment, Google Analytics, or other libraries out of the box. Framework files (e.g. `.vue`, `.svelte`, `.astro`, Angular's `.html` templates) require an optional [plugin](#plugins).
+It does **not** detect generic `track()`, Segment, Google Analytics, or other libraries out of the box - but you can opt in to a third-party library with [`sinks`](#third-party-analytics-sinks) (PostHog, Segment, Amplitude and Google Analytics 4 have built-in presets). Framework files (e.g. `.vue`, `.svelte`, `.astro`, Angular's `.html` templates) require an optional [plugin](#plugins).
 
 ---
 
@@ -121,12 +121,51 @@ trackFeature("purchase");
 
 ---
 
+## Third-party analytics (`sinks`)
+
+Already have analytics in place? Declare it in `eventra.json` and the CLI treats its calls as event sources too, with no SDK swap. Wrappers, constants, cross-file imports and JSX component props resolve exactly as they do for the Eventra SDK.
+
+```json
+{
+  "sinks": [
+    { "preset": "posthog" },
+    { "preset": "segment" },
+    { "preset": "amplitude" },
+    { "preset": "ga4" },
+    { "callee": "analytics.track" },
+    { "callee": "gtag", "nameArg": 1, "when": { "arg": 0, "equals": "event" } }
+  ]
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `preset` | A built-in rule set: `posthog`, `segment`, `amplitude` or `ga4` (see below) |
+| `callee` | Dotted call path, matched as a suffix: `analytics.track` also matches `this.analytics.track`, but not `myanalytics.track` |
+| `nameArg` | Zero-based index of the event-name argument (default `0`) |
+| `nameProperty` | If that argument is an object literal, read the name from this property (e.g. `event`) |
+| `modules` | Only match when the receiver comes from one of these npm packages (imported, re-exported, typed, or built from them) |
+| `when` | Only match when the argument at `arg` is the string literal `equals`, e.g. `{ "arg": 0, "equals": "event" }` for `gtag("event", name)` |
+
+| Preset | Detects |
+|--------|---------|
+| `posthog` | `posthog.capture("x")`, the `usePostHog()` hook (from `posthog-js/react` or `@posthog/react`) under any variable name (also through re-exports like `export { usePostHog as useAnalytics }`), and posthog-node's `client.capture({ distinctId, event: "x" })`, including typed class fields |
+| `segment` | `analytics.track("x", props)` (analytics.js, `window.analytics`), analytics-node's `client.track({ userId, event: "x" })`, and clients from `@segment/analytics-next`, `@segment/analytics-node`, `@segment/analytics-react-native` or `analytics-node` under any variable name, including `const [analytics] = await AnalyticsBrowser.load(...)` |
+| `amplitude` | `amplitude.track("x")`, `amplitude.track({ event_type: "x" })`, `amplitude.logEvent("x")`, `amplitude.getInstance().logEvent("x")`, and clients from the `@amplitude/*` browser, node, react-native and unified packages or `amplitude-js` |
+| `ga4` | `gtag("event", "x", params)` (also `window.gtag` and nuxt-gtag's `const { gtag } = useGtag()`), `sendGAEvent("event", "x", params)` from `@next/third-parties`, nuxt-gtag's `useTrackEvent("x")`, vue-gtag's `this.$gtag.event("x")` and `event("x")` / `const { event } = useGtag()`, and react-ga4's `ReactGA.event("x")` / `ReactGA.event({ category, action: "x" })`. Other gtag commands (`gtag("config", id)`, `gtag("set", ...)`) are not events and are ignored |
+
+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.
+
+---
+
 ## Event name rules (aligned with SDK)
 
 | Rule | Limit |
 |------|--------|
 | Max length | **64 characters** (same as SDK) |
-| Allowed characters | `a-zA-Z0-9:_./-` |
+| Allowed characters | `a-zA-Z0-9:_./-` and the space (so `App: User Sign Up` works); 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.
@@ -137,8 +176,10 @@ A literal name that violates either rule (too long, or a character outside the a
 
 ## What is ignored
 
+By default only the Eventra SDK is read. Calls to other analytics are ignored unless you enable them with [`sinks`](#third-party-analytics-sinks).
+
 ```ts
-// Not from @eventra_dev/eventra-sdk
+// Not from @eventra_dev/eventra-sdk (and no matching `sinks` rule)
 track("legacy");
 analytics.track("ga");
 segment.track("x");
@@ -151,6 +192,28 @@ tracker.track({ event: "click" });
 
 ## Commands
 
+### `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:
+
+```
+Found analytics in package.json: posthog-js; @segment/analytics-next
+? Also read events from these analytics calls (sinks):
+❯◉ posthog (posthog-js)
+ ◉ segment (@segment/analytics-next)
+```
+
+Everything found is pre-selected; press Enter to accept or untick what you do not want. The chosen presets are written to `sinks` in `eventra.json`. Recognised packages:
+
+| Preset | Packages |
+|--------|----------|
+| `posthog` | `posthog-js`, `@posthog/react`, `posthog-js-lite`, `posthog-node`, `posthog-react-native` |
+| `segment` | `@segment/analytics-next`, `@segment/analytics-node`, `@segment/analytics-react-native`, `@segment/snippet`, and the older `analytics-node`, `@segment/analytics.js-core` |
+| `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. 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`
 
 Full project scan → updates `eventra.json`:
@@ -158,9 +221,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`
 
@@ -192,6 +257,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)
@@ -338,6 +411,7 @@ No dependency on `@eventra_dev/eventra-cli` is required — the host CLI loads t
   "events": [],
   "functionWrappers": [],
   "plugins": [],
+  "sinks": [],
   "sync": {
     "include": ["**/*.{ts,tsx,js,jsx}"],
     "exclude": ["node_modules", "dist", ".next", ".git"]
@@ -350,8 +424,9 @@ No dependency on `@eventra_dev/eventra-cli` is required — the host CLI loads t
 | `apiKey` | Legacy inline API key — leave empty. Use `EVENTRA_API_KEY` or `eventra.local.json` instead (see [`eventra send`](#eventra-send)) so a real key never ends up in this committed file |
 | `endpoint` | Custom `eventra send` target (e.g. self-hosted). Non-default values from this file need one-time local approval — see [`eventra send`](#eventra-send) |
 | `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. 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`.
 
@@ -375,18 +450,18 @@ 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, **445 unit tests + 12 e2e fixtures + 3 `check` exit-code scenarios + 1 `watch` scenario**.
+Two test layers, **783 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.
 
-**Unit tests (vitest)** — 39 suites covering core modules:
+**Unit tests (vitest)** - 47 suites covering core modules:
 
 | Module | Covers |
 |---|---|
@@ -411,8 +486,14 @@ Two test layers, **445 unit tests + 12 e2e fixtures + 3 `check` exit-code scenar
 | `property propagation` | Direct/optional/nested property access, destructured/aliased/nested-destructured params, element access, enum member access (same-file and cross-file), wrapper detection surviving a cast/non-null assertion, and direct object-literal payloads to `track()` staying ignored (including when cast) |
 | `send()` | Endpoint trust-on-first-use (TOFU): default-trusted, blocked-until-approved, approve-then-persists, re-block-on-change, env-var-bypasses-approval |
 | `wrapper detector plugin` | A custom `WrapperDetector` (e.g. a template-literal wrapper shape the built-in analyzer can't cover) alongside the built-in fallback |
+| `configured sinks` | `sinks` rules and the PostHog, Segment, Amplitude and GA4 presets: every call shape, receivers traced through imports, re-exports, hooks, typed fields and aliases, the `when` guard, spaced names, wrong-typed config, circular chains |
+| `sink presets` | The package table behind the presets: detection per package, order, legacy and detect-only flags, rules vetted only against their own preset's packages |
+| `project dependencies` | package.json and workspace reading for `eventra init` (`workspaces`, pnpm-workspace.yaml, negations, caps, patterns that leave the project, unreadable files) |
+| `init` | `eventra init` prompts, pre-selected presets, written config, exact console output, API key kept out of `eventra.json` |
+| `preset package check` | The registry verdicts behind `pnpm check:presets` (missing, deprecated, stale, legacy) |
+| `license` | `LICENSE` is the complete MIT text, its holder is the package author, and both match `package.json` |
 
-**End-to-end fixtures** — 12 isolated TS projects scanned via `eventra sync`:
+**End-to-end fixtures** - 14 isolated TS projects scanned via `eventra sync`:
 
 | Fixture | Covers |
 |---|---|
@@ -423,6 +504,8 @@ Two test layers, **445 unit tests + 12 e2e fixtures + 3 `check` exit-code scenar
 | `wrappers/barrel` | `export * from "./tracker"` re-exports |
 | `wrappers/default-export` | `export default function trackFeature` propagation |
 | `wrappers/path-aliases` | `tsconfig.json` `paths` mapping (`@app/*`) |
+| `sinks/presets` | PostHog, Segment, Amplitude and GA4 side by side, including `gtag("config")` that must not count |
+| `sinks/spaced-names` | Names with spaces and colons through the SDK, PostHog (client and server shapes), a custom rule, wrappers and JSX, plus calls that must be ignored |
 | `watch-incremental` | Engine state across sequential file updates (matches `sync` output) |
 
 **`eventra check` exit-code scenarios:**
@@ -447,4 +530,4 @@ pnpm --filter @eventra_dev/eventra-cli test:e2e   # fixtures + check exit codes
 
 ## License
 
-MIT
+MIT, copyright (c) 2026 [and-1991](https://github.com/and-1991). See [LICENSE](LICENSE).

package/dist/analysis/extractor/extractor.js

@@ -30,7 +30,7 @@ function extractEvents(index, checker, _config, evaluationCache, exportCache, re
     }
     const propagationVisited = new Set();
     function visit(node) {
-        if (typescript_1.default.isCallExpression(node)) {
+        if (typescript_1.default.isCallExpression(node) || typescript_1.default.isJsxOpeningElement(node) || typescript_1.default.isJsxSelfClosingElement(node)) {
             (0, propagationExtractor_1.extractPropagationEvents)(node, checker, wrapperRegistry, resolvedCallCache, returnPropagationCache, evaluationCache, exportCache, events, propagationVisited, dynamicOccurrences);
         }
         typescript_1.default.forEachChild(node, visit);

package/dist/analysis/extractor/propagationExtractor.js

@@ -8,6 +8,7 @@ const typescript_1 = __importDefault(require("typescript"));
 const callResolver_1 = require("../resolver/callResolver");
 const resolver_1 = require("../resolver/resolver");
 const evaluationContext_1 = require("../shared/evaluationContext");
+const symbolUtils_1 = require("../symbols/symbolUtils");
 const eventValidation_1 = require("../shared/eventValidation");
 const dynamicOccurrence_1 = require("../shared/dynamicOccurrence");
 function resolveObjectPath(expression, path) {
@@ -35,8 +36,39 @@ function resolveObjectPath(expression, path) {
     }
     return current;
 }
+/**
+ * A JSX element is a call of its component with one argument: the props object. Rebuilt here as an
+ * object literal from the attributes so the existing call-site machinery (`resolveObjectPath`,
+ * parameter bindings) works unchanged. Spread attributes and children are ignored, and each
+ * attribute value is the original AST node, so symbol resolution still sees real code.
+ */
+function jsxPropsAsObjectLiteral(element) {
+    const properties = [];
+    for (const attribute of element.attributes.properties) {
+        if (!typescript_1.default.isJsxAttribute(attribute) || !typescript_1.default.isIdentifier(attribute.name) || !attribute.initializer) {
+            continue;
+        }
+        const value = typescript_1.default.isJsxExpression(attribute.initializer) ? attribute.initializer.expression : attribute.initializer;
+        if (value && !typescript_1.default.isJsxElement(value) && !typescript_1.default.isJsxSelfClosingElement(value) && !typescript_1.default.isJsxFragment(value)) {
+            properties.push(typescript_1.default.factory.createPropertyAssignment(attribute.name, value));
+        }
+    }
+    return typescript_1.default.factory.createObjectLiteralExpression(properties);
+}
+/** The expression naming the called function/component; null for `<ns:tag>`, which is never a component. */
+function callSiteExpression(site) {
+    if (typescript_1.default.isCallExpression(site)) {
+        return site.expression;
+    }
+    return typescript_1.default.isJsxNamespacedName(site.tagName) ? null : site.tagName;
+}
+function callSiteArgument(site, index) {
+    // A JSX site only reaches here for index 0 (the props object): see the guard in extractPropagationEvents.
+    return typescript_1.default.isCallExpression(site) ? site.arguments[index] : jsxPropsAsObjectLiteral(site);
+}
 function extractPropagationEvents(call, checker, wrapperRegistry, resolvedCallCache, returnPropagationCache, evaluationCache, exportCache, events, visited, dynamicOccurrences) {
-    const resolved = (0, callResolver_1.resolveFunctionFromCall)(call.expression, checker, resolvedCallCache, exportCache);
+    const callee = callSiteExpression(call);
+    const resolved = callee && (0, callResolver_1.resolveFunctionFromCall)(callee, checker, resolvedCallCache, exportCache);
     if (!resolved) {
         return;
     }
@@ -60,6 +92,11 @@ function extractPropagationEvents(call, checker, wrapperRegistry, resolvedCallCa
     visited.add(signature);
     try {
         for (const propagation of semantic.propagations) {
+            // A component only ever receives props (an object), so a propagation that reads the
+            // parameter as a whole (`name` rather than `props.name`) can't be satisfied by a JSX site.
+            if (!typescript_1.default.isCallExpression(call) && (propagation.sourceParameterIndex !== 0 || propagation.propertyPath.length === 0)) {
+                continue;
+            }
             extractPropagation(propagation, call, checker, evaluationCache, resolvedCallCache, returnPropagationCache, exportCache, events, dynamicOccurrences);
         }
     }
@@ -71,11 +108,12 @@ function extractPropagation(propagation, call, checker, evaluationCache, resolve
     // Call site can omit the argument and rely on the parameter's own default
     // value (`function f(event = "x") {}` called as `f()`) - that default is a
     // real static literal, so fall back to it instead of dropping the call site.
-    const argument = call.arguments[propagation.sourceParameterIndex] ?? propagation.sourceParameter.initializer;
+    const argument = callSiteArgument(call, propagation.sourceParameterIndex) ?? propagation.sourceParameter.initializer;
     if (!argument) {
         return;
     }
     const context = (0, evaluationContext_1.createEvaluationContext)();
+    let directTarget;
     if (typescript_1.default.isIdentifier(propagation.sourceParameter.name)) {
         // sourceParameter is a plain identifier (`function f(payload)`), so
         // propagation.targetNode — `payload`, `payload.event`, or any expression
@@ -98,20 +136,30 @@ function extractPropagation(propagation, call, checker, evaluationCache, resolve
         // returns nothing. Narrow to the leaf value ourselves via propertyPath,
         // then bind it to the destructured binding's own symbol (targetNode is
         // that binding's reference, e.g. `event` in `sdk.track(event)`).
-        if (propagation.propertyPath.length === 0 || !typescript_1.default.isIdentifier(propagation.targetNode)) {
+        if (propagation.propertyPath.length === 0) {
             return;
         }
         const resolvedPath = resolveObjectPath(argument, propagation.propertyPath);
         if (!resolvedPath) {
             return;
         }
-        const bindingSymbol = checker.getSymbolAtLocation(propagation.targetNode);
-        if (!bindingSymbol) {
+        if (typescript_1.default.isIdentifier(propagation.targetNode)) {
+            const bindingSymbol = (0, symbolUtils_1.getValueSymbol)(propagation.targetNode, checker);
+            if (!bindingSymbol) {
+                return;
+            }
+            context.parameterBindings.set(bindingSymbol, resolvedPath);
+        }
+        else if (typescript_1.default.isPropertyAccessExpression(propagation.targetNode) || typescript_1.default.isElementAccessExpression(propagation.targetNode)) {
+            // `function f({ analytics }) { track(analytics.name) }`: propertyPath already walks the binding
+            // AND the trailing property access (["analytics", "name"]), so resolvedPath is the leaf value.
+            directTarget = resolvedPath;
+        }
+        else {
             return;
         }
-        context.parameterBindings.set(bindingSymbol, resolvedPath);
     }
-    const resolved = (0, resolver_1.resolveNodeValue)(propagation.targetNode, checker, context, new Set(), evaluationCache, resolvedCallCache, returnPropagationCache, exportCache);
+    const resolved = (0, resolver_1.resolveNodeValue)(directTarget ?? propagation.targetNode, checker, context, new Set(), evaluationCache, resolvedCallCache, returnPropagationCache, exportCache);
     for (const value of resolved.values) {
         const normalized = (0, eventValidation_1.normalizeEventName)(value);
         if (normalized) {
@@ -119,6 +167,6 @@ function extractPropagation(propagation, call, checker, evaluationCache, resolve
         }
     }
     if (resolved.dynamic) {
-        (0, dynamicOccurrence_1.recordDynamicOccurrence)(call, call.expression.getText(), resolved.values, dynamicOccurrences);
+        (0, dynamicOccurrence_1.recordDynamicOccurrence)(call, callSiteExpression(call).getText(), resolved.values, dynamicOccurrences);
     }
 }

package/dist/analysis/resolver/resolver.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveNodeValue = resolveNodeValue;
 const typescript_1 = __importDefault(require("typescript"));
+const symbolUtils_1 = require("../symbols/symbolUtils");
 const exportResolver_1 = require("./exportResolver");
 const returnPropagationAnalyzer_1 = require("../scanner/analyzer/returnPropagationAnalyzer");
 const callResolver_1 = require("./callResolver");
@@ -37,7 +38,7 @@ function concat(left, right) {
 function resolveBoundObjectNode(rawNode, checker, context) {
     const node = (0, utils_1.unwrapExpression)(rawNode);
     if (typescript_1.default.isIdentifier(node)) {
-        const symbol = checker.getSymbolAtLocation(node);
+        const symbol = (0, symbolUtils_1.getValueSymbol)(node, checker);
         if (!symbol || !context.parameterBindings.has(symbol)) {
             return null;
         }
@@ -220,10 +221,12 @@ function resolvePropertyAccess(node, checker, context, visited, evaluationCache,
             /* v8 ignore next */
             const declarations = symbol.getDeclarations() ?? [];
             for (const declaration of declarations) {
-                if (!typescript_1.default.isVariableDeclaration(declaration) || !declaration.initializer || !typescript_1.default.isObjectLiteralExpression(declaration.initializer)) {
+                // `{ ... } as const` / `satisfies Record<...>` is still the same object literal.
+                const objectLiteral = typescript_1.default.isVariableDeclaration(declaration) && declaration.initializer ? (0, utils_1.unwrapExpression)(declaration.initializer) : null;
+                if (!objectLiteral || !typescript_1.default.isObjectLiteralExpression(objectLiteral)) {
                     continue;
                 }
-                for (const property of declaration.initializer.properties) {
+                for (const property of objectLiteral.properties) {
                     if (!typescript_1.default.isPropertyAssignment(property) && !typescript_1.default.isShorthandPropertyAssignment(property)) {
                         continue;
                     }
@@ -297,7 +300,7 @@ function collectReassignments(symbol, checker) {
     return { values, hasUnresolvedReassignment };
 }
 function resolveIdentifier(node, checker, context, visited, evaluationCache, resolvedCallCache, returnPropagationCache, exportCache) {
-    const boundSymbol = checker.getSymbolAtLocation(node);
+    const boundSymbol = (0, symbolUtils_1.getValueSymbol)(node, checker);
     if (boundSymbol && context.parameterBindings.has(boundSymbol)) {
         const bound = context.parameterBindings.get(boundSymbol);
         // `has(boundSymbol)` above already guarantees a Map entry, and every

package/dist/analysis/scanner/analyzer/propagationAnalyzer.js

@@ -138,6 +138,11 @@ function collectPropagations(fn, sinks) {
                     if (!typescript_1.default.isPropertyAssignment(property) && !typescript_1.default.isShorthandPropertyAssignment(property)) {
                         continue;
                     }
+                    // The sink only reads one property (e.g. `event`) as the name; `{ distinctId, event }`
+                    // must not propagate `distinctId` as an event name too.
+                    if (tracked.propertyPath.length > 0 && property.name.getText() !== tracked.propertyPath[0]) {
+                        continue;
+                    }
                     const initializer = typescript_1.default.isShorthandPropertyAssignment(property) ? property.name : property.initializer;
                     if (!typescript_1.default.isIdentifier(initializer)) {
                         continue;

package/dist/analysis/scanner/scanner.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scanSource = scanSource;
 const typescript_1 = __importDefault(require("typescript"));
+const utils_1 = require("../shared/utils");
 const sinkDetector_1 = require("./sinkDetector");
 const jsxEventAttribute_1 = require("./jsxEventAttribute");
 const propagationAnalyzer_1 = require("./analyzer/propagationAnalyzer");
@@ -35,13 +36,19 @@ function scanSource(source, checker, wrapperRegistry, plugins) {
                     // track({
                     //   event: name
                     // })
-                    if (tracked.propertyPath.length > 0 && typescript_1.default.isObjectLiteralExpression(argument)) {
-                        const property = argument.properties.find(prop => {
-                            return (typescript_1.default.isPropertyAssignment(prop) && prop.name.getText() === tracked.propertyPath[0]);
+                    const argumentLiteral = (0, utils_1.unwrapExpression)(argument);
+                    if (tracked.propertyPath.length > 0 && typescript_1.default.isObjectLiteralExpression(argumentLiteral)) {
+                        const property = argumentLiteral.properties.find(prop => {
+                            return ((typescript_1.default.isPropertyAssignment(prop) || typescript_1.default.isShorthandPropertyAssignment(prop)) &&
+                                prop.name.getText() === tracked.propertyPath[0]);
                         });
                         if (property && typescript_1.default.isPropertyAssignment(property)) {
                             return property.initializer;
                         }
+                        // track({ event })
+                        if (property && typescript_1.default.isShorthandPropertyAssignment(property)) {
+                            return property.name;
+                        }
                     }
                     // track(name)
                     return argument;

package/dist/analysis/sdk/eventraSdk.js

@@ -12,12 +12,17 @@ function isEventraSdkModuleSpecifier(specifier) {
     return (normalized === exports.EVENTRA_SDK_PACKAGE ||
         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.
+ */
+const EVENT_NAME_PATTERN = /^[a-zA-Z0-9:_./ -]+$/;
 function normalizeEventName(value) {
     const trimmed = value.trim();
     if (!trimmed || trimmed.length > exports.MAX_EVENT_NAME_LENGTH) {
         return null;
     }
-    if (!/^[a-zA-Z0-9:_./-]+$/.test(trimmed)) {
+    if (!EVENT_NAME_PATTERN.test(trimmed)) {
         return null;
     }
     return trimmed;

package/dist/analysis/symbols/symbolUtils.js

@@ -3,8 +3,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getValueSymbol = getValueSymbol;
 exports.getFunctionSymbol = getFunctionSymbol;
 const typescript_1 = __importDefault(require("typescript"));
+/**
+ * Symbol an identifier *refers to*. For the name in a shorthand property (`{ event }`) a plain
+ * `getSymbolAtLocation` yields the property's own symbol, not the variable/parameter it reads.
+ */
+function getValueSymbol(node, checker) {
+    const parent = node.parent;
+    if (parent && typescript_1.default.isShorthandPropertyAssignment(parent) && parent.name === node) {
+        return checker.getShorthandAssignmentValueSymbol(parent);
+    }
+    return checker.getSymbolAtLocation(node);
+}
 function getFunctionSymbol(node, checker) {
     // function foo() {}
     if (typescript_1.default.isFunctionDeclaration(node) && node.name) {

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"));