@eventra_dev/eventra-cli 0.2.3 → 0.3.1

package/README.md

@@ -9,15 +9,28 @@
 [![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, variables, and cross-file calls.
+<p align="center">
+<img src="./assets/eventra-icon-animated.svg" width="120">
+</p>
+
+# Eventra CLI
+
+[![npm version](https://img.shields.io/npm/v/@eventra_dev/eventra-cli.svg)](https://www.npmjs.com/package/@eventra_dev/eventra-cli)
+[![npm downloads](https://img.shields.io/npm/dm/@eventra_dev/eventra-cli.svg)](https://www.npmjs.com/package/@eventra_dev/eventra-cli)
+[![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.
 
 ---
 
 ## Overview
 
-Eventra scans your codebase using a TypeScript-powered engine and extracts event usage — even through abstractions like wrappers, variables, and cross-file calls.
+Eventra scans your JavaScript and TypeScript codebase using a TypeScript-powered semantic engine and extracts analytics event usage statically.
+
+It supports wrapper propagation, return propagation, cross-file resolution, and incremental dependency-aware analysis.
 
-It requires no runtime instrumentation and fits naturally into CI/CD workflows.
+No runtime instrumentation required.
 
 ---
 
@@ -44,83 +57,135 @@ eventra send
 
 ## How it works
 
-1. Parses your project using the TypeScript AST
-2. Resolves function calls, imports, and dependencies
-3. Tracks event propagation through variables and wrappers
-4. Extracts event names and aggregates them
+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 required. No SDK needed.
+No runtime SDK hooks.
+No Babel transforms.
+No instrumentation.
 
 ---
 
 ## Why Eventra
 
-- Prevent missing or inconsistent event tracking
-- Keep your analytics schema in sync with code
-- Detect dead or unused events
-- Integrate validation into CI pipelines
+* 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.
 
 #### Supports
 
-- Direct calls
+##### Direct calls
+
 ```ts
 track("event")
 analytics.track("event")
 ```
 
-- Variables
+##### Variables
+
 ```ts
 const EVENT = "click"
 track(EVENT)
 ```
 
-- Enums
+##### Enums
+
 ```ts
 track(EVENTS.CLICK)
 ```
 
-- Template strings
+##### Template strings
+
 ```ts
 track(`click_${type}`)
 ```
 
-- Conditionals
+##### Conditional expressions
+
 ```ts
 track(condition ? "a" : "b")
 ```
 
-- Object payloads
+##### Arrays
+
 ```ts
-track({ event: "click" })
+track(["a", "b"])
 ```
 
-- Function wrappers
+##### Object payloads
+
 ```ts
-const trackFeature = (name: string) => {
+track({
+  event: "click"
+})
+```
+
+##### Function wrappers
+
+```ts
+function trackFeature(name: string) {
   track(name)
 }
 
 trackFeature("click")
 ```
 
-- Cross-file event resolution
-- Framework templates (Vue, Svelte, Astro)
+##### Wrapper propagation
+
+```ts
+function trackEvent(props: {
+  event: string
+}) {
+  track(props.event)
+}
+
+trackEvent({
+  event: "purchase"
+})
+```
+
+##### Return propagation
+
+```ts
+function buildEvent(name: string) {
+  return name
+}
+
+track(buildEvent("signup"))
+```
+
+##### Cross-file resolution
+
+```ts
+import { trackFeature } from "./tracker"
+
+trackFeature("purchase")
+```
 
 ---
 
 ### `eventra check`
+
 Validates detected events against config.
 
 ```bash
@@ -128,13 +193,15 @@ eventra check
 ```
 
 Detects:
-- New events
-- Removed events
-- Inconsistent tracking usage
+
+* New events
+* Removed events
+* Invalid or inconsistent tracking usage
 
 ---
 
 ### `eventra check --fix`
+
 Automatically updates config to match detected events.
 
 ```bash
@@ -144,15 +211,19 @@ eventra check --fix
 ---
 
 ### `eventra watch`
-Runs in watch mode and updates events in real time.
+
+Runs in watch mode with incremental semantic analysis.
 
 ```bash
 eventra watch
 ```
 
+Only affected files are re-analyzed after changes.
+
 ---
 
 ### `eventra send`
+
 Sends events to Eventra backend.
 
 ```bash
@@ -171,25 +242,76 @@ eventra send
   "wrappers": [],
   "functionWrappers": [],
   "sync": {
-    "include": ["**/*.{ts,tsx,js,jsx,vue,svelte,astro}"],
-    "exclude": ["node_modules", "dist", ".next", ".git"]
+    "include": ["**/*.{ts,tsx,js,jsx}"],
+    "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
 
-Eventra works with **any JavaScript or TypeScript codebase**.
+Eventra works with:
 
-No framework limitations.
+* JavaScript
+* TypeScript
+* Node.js projects
+* Browser applications
+* Monorepos
 
 ---
 
 ## Requirements
 
-- Node.js 18+
+* Node.js 18+
 
 ---
 

package/dist/analysis/cache/evaluationCache.js

@@ -0,0 +1,21 @@
+"use strict";
+// src/analysis/cache/evaluationCache.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EvaluationCache = void 0;
+class EvaluationCache {
+    cache = new WeakMap();
+    get(symbol) {
+        return this.cache.get(symbol);
+    }
+    set(symbol, result) {
+        this.cache.set(symbol, result);
+    }
+    delete(symbol) {
+        this.cache.delete(symbol);
+    }
+    clear() {
+        this.cache =
+            new WeakMap();
+    }
+}
+exports.EvaluationCache = EvaluationCache;

package/dist/analysis/cache/resolvedCallCache.js

@@ -0,0 +1,21 @@
+"use strict";
+// src/analysis/cache/resolvedCallCache.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResolvedCallCache = void 0;
+class ResolvedCallCache {
+    cache = new WeakMap();
+    get(symbol) {
+        return this.cache.get(symbol);
+    }
+    set(symbol, value) {
+        this.cache.set(symbol, value);
+    }
+    delete(symbol) {
+        this.cache.delete(symbol);
+    }
+    clear() {
+        this.cache =
+            new WeakMap();
+    }
+}
+exports.ResolvedCallCache = ResolvedCallCache;

package/dist/analysis/cache/resolvedExportCache.js

@@ -0,0 +1,21 @@
+"use strict";
+// src/analysis/cache/resolvedExportCache.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResolvedExportCache = void 0;
+class ResolvedExportCache {
+    cache = new WeakMap();
+    get(symbol) {
+        return this.cache.get(symbol);
+    }
+    set(symbol, resolved) {
+        this.cache.set(symbol, resolved);
+    }
+    delete(symbol) {
+        this.cache.delete(symbol);
+    }
+    clear() {
+        this.cache =
+            new WeakMap();
+    }
+}
+exports.ResolvedExportCache = ResolvedExportCache;

package/dist/analysis/cache/semanticDependencyGraph.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SemanticDependencyGraph = void 0;
+class SemanticDependencyGraph {
+    dependencies = new Map();
+    addDependency(from, to) {
+        let deps = this.dependencies.get(from);
+        if (!deps) {
+            deps =
+                new Set();
+            this.dependencies.set(from, deps);
+        }
+        deps.add(to);
+    }
+    getDependents(file) {
+        const result = new Set();
+        for (const [from, deps,] of this.dependencies) {
+            if (deps.has(file)) {
+                result.add(from);
+            }
+        }
+        return result;
+    }
+}
+exports.SemanticDependencyGraph = SemanticDependencyGraph;

package/dist/analysis/cache/symbolInvalidation.js

@@ -0,0 +1,20 @@
+"use strict";
+// src/analysis/cache/symbolInvalidation.ts
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.invalidateSourceFileSymbols = invalidateSourceFileSymbols;
+const typescript_1 = __importDefault(require("typescript"));
+function invalidateSourceFileSymbols(sourceFile, checker, evaluationCache, resolvedCallCache, resolvedExportCache) {
+    function visit(node) {
+        const symbol = checker.getSymbolAtLocation(node);
+        if (symbol) {
+            evaluationCache.delete(symbol);
+            resolvedCallCache.delete(symbol);
+            resolvedExportCache.delete(symbol);
+        }
+        typescript_1.default.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+}

package/dist/analysis/extractor/extractor.js

@@ -0,0 +1,47 @@
+"use strict";
+// src/analysis/extractor/extractor.ts
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractEvents = extractEvents;
+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));
+}
+function extractEvents(index, checker, _config, evaluationCache, exportCache, resolvedCallCache, wrapperRegistry) {
+    const events = new Set();
+    //
+    // direct track sinks
+    //
+    for (const call of index.trackCalls) {
+        for (const argument of call.trackedArguments) {
+            const resolved = (0, resolver_1.resolveNodeValue)(argument, checker, (0, evaluationContext_1.createEvaluationContext)(), new Set(), evaluationCache, resolvedCallCache, exportCache);
+            for (const value of resolved.values) {
+                if (isValidEvent(value)) {
+                    events.add(value);
+                }
+            }
+        }
+    }
+    //
+    // wrapper propagation
+    //
+    function visit(node) {
+        if (typescript_1.default.isCallExpression(node)) {
+            (0, propagationExtractor_1.extractPropagationEvents)(node, checker, wrapperRegistry, resolvedCallCache, evaluationCache, exportCache, events, new Set());
+        }
+        typescript_1.default.forEachChild(node, visit);
+    }
+    visit(index.sourceFile);
+    return {
+        events,
+        detectedFunctionWrappers: new Set(index.wrappers.map(wrapper => wrapper.symbol.getName())),
+        detectedComponentWrappers: new Map(),
+    };
+}

package/dist/analysis/extractor/propagationExtractor.js

@@ -0,0 +1,52 @@
+"use strict";
+// src/analysis/extractor/propagationExtractor.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractPropagationEvents = extractPropagationEvents;
+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));
+}
+function extractPropagationEvents(call, checker, wrapperRegistry, resolvedCallCache, evaluationCache, exportCache, events, visited) {
+    const resolved = (0, callResolver_1.resolveFunctionFromCall)(call.expression, checker, resolvedCallCache, exportCache);
+    if (!resolved) {
+        return;
+    }
+    const semantic = wrapperRegistry.get(resolved, checker, exportCache);
+    if (!semantic) {
+        return;
+    }
+    const signature = checker.getSignatureFromDeclaration(resolved);
+    if (!signature) {
+        return;
+    }
+    if (visited.has(signature)) {
+        return;
+    }
+    visited.add(signature);
+    for (const propagation of semantic.propagations) {
+        extractPropagation(propagation, call, checker, evaluationCache, resolvedCallCache, exportCache, events);
+    }
+}
+function extractPropagation(propagation, call, checker, evaluationCache, resolvedCallCache, exportCache, events) {
+    const argument = call.arguments[propagation.sourceParameterIndex];
+    if (!argument) {
+        return;
+    }
+    const context = (0, evaluationContext_1.createEvaluationContext)();
+    const parameterSymbol = checker.getSymbolAtLocation(propagation
+        .sourceParameter
+        .name);
+    if (parameterSymbol) {
+        context.parameterBindings.set(parameterSymbol, argument);
+    }
+    const resolved = (0, resolver_1.resolveNodeValue)(propagation.targetNode, checker, context, new Set(), evaluationCache, resolvedCallCache, exportCache);
+    for (const value of resolved.values) {
+        if (isValidEvent(value)) {
+            events.add(value);
+        }
+    }
+}

package/dist/analysis/pipeline/semanticPass.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/analysis/resolver/callResolver.js

@@ -0,0 +1,125 @@
+"use strict";
+// src/analysis/resolver/callResolver.ts
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFunctionFromCall = resolveFunctionFromCall;
+const typescript_1 = __importDefault(require("typescript"));
+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 foo() {}
+    //
+    if (isFunctionLike(declaration)) {
+        return declaration;
+    }
+    //
+    // const foo = () => {}
+    //
+    if (typescript_1.default.isVariableDeclaration(declaration)
+        && declaration.initializer
+        && isFunctionLike(declaration.initializer)) {
+        return declaration.initializer;
+    }
+    //
+    // class field = () => {}
+    //
+    if (typescript_1.default.isPropertyDeclaration(declaration)
+        && declaration.initializer
+        && isFunctionLike(declaration.initializer)) {
+        return declaration.initializer;
+    }
+    return null;
+}
+function getExpressionSymbol(expression, checker) {
+    //
+    // analytics.track()
+    //
+    if (typescript_1.default.isPropertyAccessExpression(expression)) {
+        return checker.getSymbolAtLocation(expression.name);
+    }
+    //
+    // analytics?.track()
+    //
+    if (typescript_1.default.isPropertyAccessChain(expression)) {
+        return checker.getSymbolAtLocation(expression.name);
+    }
+    //
+    // analytics["track"]()
+    //
+    if (typescript_1.default.isElementAccessExpression(expression)
+        && expression.argumentExpression) {
+        return checker.getSymbolAtLocation(expression.argumentExpression);
+    }
+    //
+    // track()
+    //
+    return checker.getSymbolAtLocation(expression);
+}
+function resolveFunctionFromCall(expression, checker, callCache, exportCache) {
+    let symbol = getExpressionSymbol(expression, checker);
+    if (!symbol) {
+        return null;
+    }
+    //
+    // export unwrap
+    //
+    symbol =
+        (0, exportResolver_1.resolveExportedSymbol)(symbol, checker, exportCache)
+            ?? symbol;
+    //
+    // alias unwrap
+    //
+    if (symbol.flags
+        & typescript_1.default.SymbolFlags.Alias) {
+        symbol =
+            checker.getAliasedSymbol(symbol);
+    }
+    //
+    // cache
+    //
+    const cached = callCache.get(symbol);
+    if (cached !== undefined) {
+        return cached;
+    }
+    //
+    // declaration resolution
+    //
+    const declarations = symbol.getDeclarations()
+        ?? [];
+    for (const declaration of declarations) {
+        const resolved = resolveDeclaration(declaration);
+        if (!resolved) {
+            continue;
+        }
+        callCache.set(symbol, resolved);
+        return resolved;
+    }
+    //
+    // fallback:
+    // type signatures
+    //
+    const type = checker.getTypeOfSymbolAtLocation(symbol, declarations[0]
+        ?? expression);
+    const signatures = checker.getSignaturesOfType(type, typescript_1.default.SignatureKind.Call);
+    for (const signature of signatures) {
+        const declaration = signature.declaration;
+        if (declaration
+            && isFunctionLike(declaration)) {
+            callCache.set(symbol, declaration);
+            return declaration;
+        }
+    }
+    //
+    // unresolved
+    //
+    callCache.set(symbol, null);
+    return null;
+}