@eventra_dev/eventra-cli 0.3.6 → 0.3.10

package/README.md

@@ -9,17 +9,15 @@
 [![TypeScript](https://img.shields.io/badge/typescript-ready-blue.svg)](https://www.typescriptlang.org/)
 [![License](https://img.shields.io/npm/l/@eventra_dev/eventra-cli)]()
 
-Eventra CLI automatically discovers and tracks event usage across your codebase — even through abstractions like wrappers, propagation chains, variables, and cross-file calls.
+Eventra CLI statically discovers analytics events from [**@eventra_dev/eventra-sdk**](https://www.npmjs.com/package/@eventra_dev/eventra-sdk) usage in your codebase — including function wrappers and cross-file propagation chains.
 
 ---
 
 ## Overview
 
-Eventra scans your JavaScript and TypeScript codebase using a TypeScript-powered semantic engine and extracts analytics event usage statically.
+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 supports semantic parameter propagation, return propagation, cross-file resolution, and incremental dependency-aware analysis.
-
-No runtime instrumentation required.
+It does **not** detect generic `track()`, Segment, Google Analytics, or other libraries.
 
 ---
 
@@ -31,6 +29,12 @@ npm install -D @eventra_dev/eventra-cli
 pnpm add -D @eventra_dev/eventra-cli
 ```
 
+Your project should use the runtime SDK:
+
+```bash
+pnpm add @eventra_dev/eventra-sdk
+```
+
 ---
 
 ## Quick Start
@@ -44,180 +48,108 @@ eventra send
 
 ---
 
-## How it works
-
-1. Parses your project using the TypeScript compiler API
-2. Builds semantic indexes from AST nodes
-3. Resolves wrappers, imports, exports, and propagation chains
-4. Extracts concrete analytics events statically
-5. Incrementally re-analyzes only affected files
-
-No runtime SDK hooks.
-No Babel transforms.
-No instrumentation.
-
----
-
-## Why Eventra
-
-* Prevent missing or inconsistent event tracking
-* Keep analytics schemas synchronized with source code
-* Detect dead or unused events
-* Analyze wrapper-heavy codebases statically
-* Integrate validation into CI/CD pipelines
-* Avoid runtime analytics overhead
-
----
-
-## Commands
-
-### `eventra init`
-
-Creates `eventra.json` configuration file.
-
----
-
-### `eventra sync`
-
-Scans your project and updates the list of detected events.
+## What gets detected
 
-#### Supports
-
-##### Direct calls
+### Direct SDK calls
 
 ```ts
-track("event")
-analytics.track("event")
-```
+import { Eventra } from "@eventra_dev/eventra-sdk";
 
-##### Variables
+const tracker = new Eventra({ apiKey: "YOUR_PROJECT_API_KEY" });
 
-```ts
-const EVENT = "click"
-track(EVENT)
+tracker.track("checkout.completed");
+tracker.track("app.loaded", { userId: "user_123" });
+tracker?.track("optional.chain");
 ```
 
-##### Enums
-
-```ts
-track(EVENTS.CLICK)
-```
+### Function wrappers (propagation)
 
-##### Template strings
+Wrappers that call `Eventra.track()` inside are registered automatically:
 
 ```ts
-track(`click_${type}`)
-```
-
-##### Conditional expressions
+function trackFeature(name: string) {
+  sdk.track(name);
+}
 
-```ts
-track(condition ? "a" : "b")
+trackFeature("purchase");
 ```
 
-##### Arrays
+### Variables, templates, conditionals
 
 ```ts
-track(["a", "b"])
-```
+const EVENT = "signup";
+tracker.track(EVENT);
 
-##### Object payloads
+tracker.track(`feature_${type}`);
 
-```ts
-track({
-  event: "click"
-})
+tracker.track(flag ? "path.a" : "path.b");
 ```
 
-##### Function wrappers
+### Cross-file
 
 ```ts
-function trackFeature(name: string) {
-  track(name)
+// tracker.ts
+export function trackFeature(name: string) {
+  client.track(name);
 }
 
-trackFeature("click")
+// app.ts
+import { trackFeature } from "./tracker";
+trackFeature("purchase");
 ```
 
-##### Semantic parameter propagation
+---
 
-```ts
-function trackEvent(props: {
-  event: string
-}) {
-  track(props.event)
-}
+## Event name rules (aligned with SDK)
 
-trackEvent({
-  event: "purchase"
-})
-```
+| Rule | Limit |
+|------|--------|
+| Max length | **64 characters** (same as SDK) |
+| Allowed characters | `a-zA-Z0-9:_./-` |
+| Position | First argument of `.track(name, options?)` |
 
-##### Return propagation
+The second argument (`userId`, `properties`) is **not** used as the event name.
 
-```ts
-function buildEvent(name: string) {
-  return name
-}
-
-track(buildEvent("signup"))
-```
+---
 
-##### Cross-file resolution
+## What is ignored
 
 ```ts
-import { trackFeature } from "./tracker"
+// Not from @eventra_dev/eventra-sdk
+track("legacy");
+analytics.track("ga");
+segment.track("x");
 
-trackFeature("purchase")
+// Wrong API shape for SDK (object as first argument)
+tracker.track({ event: "click" });
 ```
 
 ---
 
-### `eventra check`
+## Commands
 
-Validates detected events against config.
+### `eventra sync`
 
-```bash
-eventra check
-```
+Full project scan → updates `eventra.json`:
 
-Detects:
+- `events` — discovered event names
+- `functionWrappers` — detected wrapper functions
 
-* New events
-* Removed events
-* Invalid or inconsistent tracking usage
+### `eventra check`
 
----
+Compares config with the current scan (events + wrappers). Exit code `1` on drift.
 
 ### `eventra check --fix`
 
-Automatically updates config to match detected events.
-
-```bash
-eventra check --fix
-```
-
----
+Writes scan results into `eventra.json`.
 
 ### `eventra watch`
 
-Runs in watch mode with incremental semantic analysis.
-
-```bash
-eventra watch
-```
-
-Only affected files are re-analyzed after changes.
-
----
+Incremental scan with the same rules as `sync`.
 
 ### `eventra send`
 
-Sends events to Eventra backend.
-
-```bash
-eventra send
-```
+Uploads `events` from config to the Eventra API.
 
 ---
 
@@ -228,79 +160,31 @@ eventra send
   "apiKey": "",
   "endpoint": "",
   "events": [],
-  "wrappers": [],
   "functionWrappers": [],
   "sync": {
     "include": ["**/*.{ts,tsx,js,jsx}"],
-    "exclude": [
-      "node_modules",
-      "dist",
-      ".next",
-      ".git"
-    ]
+    "exclude": ["node_modules", "dist", ".next", ".git"]
   }
 }
 ```
 
 ---
 
-## Architecture Highlights
-
-### Semantic propagation analysis
-
-Eventra resolves event propagation through wrappers and returned values.
-
-```ts
-function createEvent(name: string) {
-  return name
-}
-
-function trackEvent(name: string) {
-  track(createEvent(name))
-}
-```
-
----
-
-### Incremental analysis engine
-
-Eventra does NOT rescan the whole project after every update.
-
-Instead it:
-
-1. Updates changed files
-2. Invalidates affected caches
-3. Rebuilds TypeScript incrementally
-4. Traverses dependency graph
-5. Re-analyzes affected files only
-
----
-
-### Static extraction
-
-Eventra works entirely statically.
-
-No runtime execution.
-No monkey patching.
-No SDK instrumentation.
-
----
-
-## Supported Environments
+## How it works
 
-Eventra works with:
+1. Load project files into an incremental TypeScript program (with SDK type shim).
+2. **Phase 1** — find `Eventra` instances from `@eventra_dev/eventra-sdk` and register function wrappers that call `.track()`.
+3. **Phase 2** — resolve static event names and wrapper propagation chains.
+4. Write results to `eventra.json`.
 
-* JavaScript
-* TypeScript
-* Node.js projects
-* Browser applications
-* Monorepos
+No runtime execution. No monkey-patching.
 
 ---
 
 ## Requirements
 
-* Node.js 18+
+- Node.js 18+
+- TypeScript/JavaScript source using `@eventra_dev/eventra-sdk`
 
 ---
 

package/dist/analysis/engine/analyzeFile.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.indexSourceFile = indexSourceFile;
+exports.extractFromIndex = extractFromIndex;
+const scanner_1 = require("../scanner/scanner");
+const extractor_1 = require("../extractor/extractor");
+function indexSourceFile(source, checker, wrapperRegistry) {
+    return (0, scanner_1.scanSource)(source, checker, wrapperRegistry);
+}
+function extractFromIndex(index, config, checker, wrapperRegistry, evaluationCache, resolvedCallCache, returnPropagationCache, resolvedExportCache) {
+    return (0, extractor_1.extractEvents)(index, checker, config, evaluationCache, resolvedExportCache, resolvedCallCache, returnPropagationCache, wrapperRegistry);
+}

package/dist/analysis/extractor/extractor.js

@@ -8,9 +8,7 @@ const typescript_1 = __importDefault(require("typescript"));
 const resolver_1 = require("../resolver/resolver");
 const evaluationContext_1 = require("../shared/evaluationContext");
 const propagationExtractor_1 = require("./propagationExtractor");
-function isValidEvent(value) {
-    return (value.length > 0 && value.length < 160 && /^[a-zA-Z0-9:_./-]+$/.test(value));
-}
+const eventValidation_1 = require("../shared/eventValidation");
 function extractEvents(index, checker, _config, evaluationCache, exportCache, resolvedCallCache, returnPropagationCache, wrapperRegistry) {
     const events = new Set();
     // direct track sinks
@@ -18,8 +16,9 @@ function extractEvents(index, checker, _config, evaluationCache, exportCache, re
         for (const argument of call.trackedArguments) {
             const resolved = (0, resolver_1.resolveNodeValue)(argument, checker, (0, evaluationContext_1.createEvaluationContext)(), new Set(), evaluationCache, resolvedCallCache, returnPropagationCache, exportCache);
             for (const value of resolved.values) {
-                if (isValidEvent(value)) {
-                    events.add(value);
+                const normalized = (0, eventValidation_1.normalizeEventName)(value);
+                if (normalized) {
+                    events.add(normalized);
                 }
             }
         }

package/dist/analysis/extractor/propagationExtractor.js

@@ -8,9 +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");
-function isValidEvent(value) {
-    return (value.length > 0 && value.length < 160 && /^[a-zA-Z0-9:_./-]+$/.test(value));
-}
+const eventValidation_1 = require("../shared/eventValidation");
 function resolveObjectPath(expression, path) {
     let current = expression;
     for (const segment of path) {
@@ -86,8 +84,9 @@ function extractPropagation(propagation, call, checker, evaluationCache, resolve
     }
     const resolved = (0, resolver_1.resolveNodeValue)(propagation.targetNode, checker, context, new Set(), evaluationCache, resolvedCallCache, returnPropagationCache, exportCache);
     for (const value of resolved.values) {
-        if (isValidEvent(value)) {
-            events.add(value);
+        const normalized = (0, eventValidation_1.normalizeEventName)(value);
+        if (normalized) {
+            events.add(normalized);
         }
     }
 }

package/dist/analysis/resolver/callResolver.js

@@ -22,6 +22,10 @@ function resolveDeclaration(declaration) {
     if (typescript_1.default.isPropertyDeclaration(declaration) && declaration.initializer && isFunctionLike(declaration.initializer)) {
         return declaration.initializer;
     }
+    // { trackFeature() {} }
+    if (typescript_1.default.isPropertyAssignment(declaration) && declaration.initializer && isFunctionLike(declaration.initializer)) {
+        return declaration.initializer;
+    }
     return null;
 }
 function getExpressionSymbol(expression, checker) {

package/dist/analysis/resolver/exportResolver.js

@@ -16,6 +16,9 @@ function isConcreteDeclaration(node) {
         || typescript_1.default.isPropertyDeclaration(node));
 }
 function resolveExportedSymbol(symbol, checker, cache, visited) {
+    if (typeof symbol.getDeclarations !== "function") {
+        return null;
+    }
     const seen = visited ?? new Set();
     const cached = cache.get(symbol);
     if (cached !== undefined) {

package/dist/analysis/scanner/scanner.js

@@ -23,7 +23,7 @@ function scanSource(source, checker, wrapperRegistry) {
         }
         // sink detection
         if (typescript_1.default.isCallExpression(node)) {
-            const sink = (0, sinkDetector_1.detectTrackSink)(node);
+            const sink = (0, sinkDetector_1.detectTrackSink)(node, checker);
             if (sink) {
                 sinks.push(sink);
                 const trackedArguments = sink.trackedArguments.map(tracked => {

package/dist/analysis/scanner/sinkDetector.js

@@ -5,53 +5,33 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectTrackSink = detectTrackSink;
 const typescript_1 = __importDefault(require("typescript"));
-function isElementTrackProperty(expr) {
-    return (typescript_1.default.isElementAccessExpression(expr) && expr.argumentExpression && typescript_1.default.isStringLiteral(expr.argumentExpression) && expr.argumentExpression.text === "track");
-}
-function isTrackIdentifier(expr) {
-    return (typescript_1.default.isIdentifier(expr) && expr.text === "track");
-}
-function isTrackProperty(expr) {
-    return (typescript_1.default.isPropertyAccessExpression(expr) && expr.name.text === "track");
-}
-function isOptionalTrackProperty(expr) {
-    return (typescript_1.default.isPropertyAccessChain(expr) && expr.name.text === "track");
-}
+const isEventraTrackCall_1 = require("../sdk/isEventraTrackCall");
+/** SDK: track(name: string, options?) — event name is always the first argument. */
 function extractTrackedArguments(call) {
-    const result = [];
     if (call.arguments.length === 0) {
-        return result;
+        return [];
     }
     const first = call.arguments[0];
     if (typescript_1.default.isObjectLiteralExpression(first)) {
-        for (const property of first.properties) {
-            if (!typescript_1.default.isPropertyAssignment(property) && !typescript_1.default.isShorthandPropertyAssignment(property)) {
-                continue;
-            }
-            const name = property.name.getText();
-            if (name !== "event" && name !== "name" && name !== "type") {
-                continue;
-            }
-            result.push({
-                index: 0,
-                propertyPath: [name],
-            });
-        }
-        return result;
+        return [];
     }
-    result.push({
-        index: 0,
-        propertyPath: [],
-    });
-    return result;
+    return [
+        {
+            index: 0,
+            propertyPath: [],
+        },
+    ];
 }
-function detectTrackSink(call) {
-    const expression = call.expression;
-    if (!isTrackIdentifier(expression) && !isTrackProperty(expression) && !isOptionalTrackProperty(expression) && !isElementTrackProperty(expression)) {
+function detectTrackSink(call, checker) {
+    if (!(0, isEventraTrackCall_1.isEventraSdkTrackCall)(call, checker)) {
+        return null;
+    }
+    const trackedArguments = extractTrackedArguments(call);
+    if (trackedArguments.length === 0) {
         return null;
     }
     return {
         call,
-        trackedArguments: extractTrackedArguments(call),
+        trackedArguments,
     };
 }

package/dist/analysis/sdk/eventraSdk.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENTRA_SDK_SHIM = exports.MAX_EVENT_NAME_LENGTH = exports.EVENTRA_SDK_PACKAGE = void 0;
+exports.isEventraSdkModuleSpecifier = isEventraSdkModuleSpecifier;
+exports.normalizeEventName = normalizeEventName;
+exports.isValidEventName = isValidEventName;
+/** Mirrors @eventra_dev/eventra-sdk runtime limits (see packages/sdk/src/client.ts). */
+exports.EVENTRA_SDK_PACKAGE = "@eventra_dev/eventra-sdk";
+exports.MAX_EVENT_NAME_LENGTH = 64;
+function isEventraSdkModuleSpecifier(specifier) {
+    const normalized = specifier.replace(/\\/g, "/");
+    return (normalized === exports.EVENTRA_SDK_PACKAGE ||
+        normalized.startsWith(`${exports.EVENTRA_SDK_PACKAGE}/`));
+}
+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)) {
+        return null;
+    }
+    return trimmed;
+}
+function isValidEventName(value) {
+    return normalizeEventName(value) !== null;
+}
+exports.EVENTRA_SDK_SHIM = `declare module "@eventra_dev/eventra-sdk" {
+  export interface TrackOptions {
+    userId?: string;
+    properties?: Record<string, unknown>;
+  }
+  export interface TrackerOptions {
+    apiKey: string;
+    endpoint?: string;
+  }
+  export class Eventra {
+    constructor(options: TrackerOptions);
+    track(name: string, options?: TrackOptions): void;
+  }
+}
+`;