@eventra_dev/eventra-cli 0.3.12 → 0.4.0

package/README.md

@@ -4,10 +4,16 @@
 
 # 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)]()
+<p align="center">
+  <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-52%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="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>
+  <img alt="license" src="https://img.shields.io/npm/l/@eventra_dev/eventra-cli?style=flat-square&color=lightgrey">
+</p>
 
 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.
 
@@ -151,6 +157,13 @@ Incremental scan with the same rules as `sync`.
 
 Uploads `events` from config to the Eventra API. Requires `apiKey` (and optionally `endpoint`) in `eventra.json`. Events are POSTed to `POST /api/v1/cli/events` and marked as non-billable on the backend.
 
+Network resilience:
+
+- Up to 4 attempts with exponential backoff + jitter (capped at 8 s)
+- Retries on 429 and 5xx responses, and on transport errors (timeout / DNS / connection reset)
+- Permanent failure (4xx other than 429) surfaces immediately without retry
+- 10 s timeout per attempt via `AbortController`
+
 ---
 
 ## Configuration
@@ -188,6 +201,54 @@ No runtime execution. No monkey-patching.
 
 ---
 
+## Test Coverage
+
+Two test layers, **52 unit tests + 12 e2e fixtures + 3 `check` exit-code scenarios**.
+
+**Unit tests (vitest)** — 10 suites covering core modules:
+
+| Module | Covers |
+|---|---|
+| `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 |
+| `EventraEngine` | Direct calls, SDK isolation, cross-file wrappers, file updates, file removal, wrapper filtering |
+| `processFile` | Script-kind detection, import/export specifier extraction |
+| `extractTemplateExpressions` | Vue/Svelte/Astro attribute patterns |
+| `normalizeConfig` | Sort events, dedupe wrappers, defaults, preserve `apiKey` / `endpoint` / `sync` |
+| `buildConfigFromScan` | Replace events + wrappers, preserve everything else |
+| `hash` | Stability and uniqueness |
+
+**End-to-end fixtures** — 12 isolated TS projects scanned via `eventra sync`:
+
+| Fixture | Covers |
+|---|---|
+| `sdk/direct` | Plain `tracker.track()` calls |
+| `frontend/react`, `frontend/next`, `frontend/vue` | Framework-specific code shapes |
+| `backend/node`, `backend/express`, `backend/nest` | Backend wrappers and middleware chains |
+| `wrappers/function` | Local wrapper functions, methods, objects, ternaries, templates |
+| `wrappers/barrel` | `export * from "./tracker"` re-exports |
+| `wrappers/default-export` | `export default function trackFeature` propagation |
+| `wrappers/path-aliases` | `tsconfig.json` `paths` mapping (`@app/*`) |
+| `watch-incremental` | Engine state across sequential file updates (matches `sync` output) |
+
+**`eventra check` exit-code scenarios:**
+
+- Drift → exit `1`
+- `--fix` writes scan results into `eventra.json` → exit `0`
+- Parity (no drift) → exit `0`
+
+Run locally:
+
+```bash
+pnpm --filter @eventra_dev/eventra-cli test       # unit + e2e + exit codes
+pnpm --filter @eventra_dev/eventra-cli test:unit  # vitest only
+pnpm --filter @eventra_dev/eventra-cli test:e2e   # fixtures + check exit codes
+```
+
+---
+
 ## License
 
 MIT

package/dist/cli/send.js

@@ -9,6 +9,53 @@ const inquirer_1 = __importDefault(require("inquirer"));
 const config_1 = require("../config/config");
 const package_json_1 = __importDefault(require("../../package.json"));
 const CLI_VERSION = package_json_1.default.version;
+// retry/backoff tuning (mirrors SDK defaults)
+const MAX_ATTEMPTS = 4;
+const BASE_DELAY_MS = 500;
+const MAX_DELAY_MS = 8000;
+const FETCH_TIMEOUT_MS = 10_000;
+// sleep helper for backoff
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+// exponential backoff with jitter (capped)
+function backoffMs(attempt) {
+    const exp = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** attempt);
+    return exp * (0.5 + Math.random() * 0.5);
+}
+// single delivery attempt with abort timeout
+async function attemptDelivery(endpoint, apiKey, payload) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": apiKey,
+            },
+            body: payload,
+            signal: controller.signal,
+        });
+        if (res.ok) {
+            const data = (await res.json());
+            return { ok: true, data };
+        }
+        let body;
+        try {
+            body = await res.text();
+        }
+        catch {
+            /* ignore */
+        }
+        // 429 and 5xx are transient — worth retrying
+        const retryable = res.status === 429 || res.status >= 500;
+        return { ok: false, status: res.status, body, retryable };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
 async function send() {
     const config = await (0, config_1.loadConfig)();
     const endpoint = config?.endpoint || process.env.EVENTRA_ENDPOINT;
@@ -48,63 +95,76 @@ async function send() {
     }
     console.log("");
     console.log(chalk_1.default.blue(`Sending ${config.events.length} events...`));
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), 10000);
-    try {
-        const res = await fetch(endpoint, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "x-api-key": apiKey
-            },
-            body: JSON.stringify({
-                events: config.events,
-                cli: {
-                    name: "@eventra_dev/eventra-cli",
-                    version: CLI_VERSION,
-                    runtime: "node"
-                }
-            }),
-            signal: controller.signal
-        });
-        if (!res.ok) {
-            console.log(chalk_1.default.red(`Request failed (${res.status})`));
-            try {
-                const text = await res.text();
-                console.log(chalk_1.default.gray(text));
+    const payload = JSON.stringify({
+        events: config.events,
+        cli: {
+            name: "@eventra_dev/eventra-cli",
+            version: CLI_VERSION,
+            runtime: "node",
+        },
+    });
+    // attempt delivery with retry on 429/5xx/network errors
+    let data;
+    let lastFailure = null;
+    for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+        try {
+            const outcome = await attemptDelivery(endpoint, apiKey, payload);
+            if (outcome.ok) {
+                data = outcome.data;
+                break;
             }
-            catch {
+            if (!outcome.retryable) {
+                // permanent failure — surface immediately
+                console.log(chalk_1.default.red(`Request failed (${outcome.status})`));
+                if (outcome.body)
+                    console.log(chalk_1.default.gray(outcome.body));
+                return;
+            }
+            lastFailure = { status: outcome.status, body: outcome.body };
+            if (attempt < MAX_ATTEMPTS - 1) {
+                const delay = backoffMs(attempt);
+                console.log(chalk_1.default.yellow(`Attempt ${attempt + 1}/${MAX_ATTEMPTS} failed (${outcome.status}). Retrying in ${Math.round(delay)} ms...`));
+                await sleep(delay);
             }
-            return;
         }
-        const data = await res.json();
-        console.log(chalk_1.default.green("Events registered successfully"));
-        // created
-        if (data.created?.length) {
-            console.log(chalk_1.default.green("\nNew events:"));
-            data.created.forEach((e) => console.log(chalk_1.default.green(`+ ${e}`)));
+        catch (err) {
+            lastFailure = { error: err };
+            if (attempt < MAX_ATTEMPTS - 1) {
+                const delay = backoffMs(attempt);
+                console.log(chalk_1.default.yellow(`Attempt ${attempt + 1}/${MAX_ATTEMPTS} failed (network error). Retrying in ${Math.round(delay)} ms...`));
+                await sleep(delay);
+            }
         }
-        // existing
-        if (data.existing?.length) {
-            console.log(chalk_1.default.gray("\nExisting events:"));
-            data.existing.forEach((e) => console.log(chalk_1.default.gray(`• ${e}`)));
+    }
+    if (!data) {
+        console.log(chalk_1.default.red("All retries exhausted"));
+        if (lastFailure?.status) {
+            console.log(chalk_1.default.gray(`Last status: ${lastFailure.status}`));
+            if (lastFailure.body)
+                console.log(chalk_1.default.gray(lastFailure.body));
         }
-        // processing notice
-        if (data.created?.length) {
-            console.log("");
-            console.log(chalk_1.default.yellow("Events queued for processing (~2 min)"));
-            console.log(chalk_1.default.gray("They will appear in dashboard shortly"));
+        else if (lastFailure?.error instanceof Error) {
+            console.log(chalk_1.default.gray(lastFailure.error.message));
         }
-        console.log("");
-        console.log(chalk_1.default.gray(`Sent ${config.events.length} events`));
+        return;
     }
-    catch (err) {
-        console.log(chalk_1.default.red("Network error"));
-        if (err instanceof Error) {
-            console.log(chalk_1.default.gray(err.message));
-        }
+    console.log(chalk_1.default.green("Events registered successfully"));
+    // created events
+    if (data.created?.length) {
+        console.log(chalk_1.default.green("\nNew events:"));
+        data.created.forEach((e) => console.log(chalk_1.default.green(`+ ${e}`)));
     }
-    finally {
-        clearTimeout(timeout);
+    // existing events
+    if (data.existing?.length) {
+        console.log(chalk_1.default.gray("\nExisting events:"));
+        data.existing.forEach((e) => console.log(chalk_1.default.gray(`• ${e}`)));
+    }
+    // processing notice
+    if (data.created?.length) {
+        console.log("");
+        console.log(chalk_1.default.yellow("Events queued for processing (~2 min)"));
+        console.log(chalk_1.default.gray("They will appear in dashboard shortly"));
     }
+    console.log("");
+    console.log(chalk_1.default.gray(`Sent ${config.events.length} events`));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventra_dev/eventra-cli",
-  "version": "0.3.12",
+  "version": "0.4.0",
   "description": "Static analytics event extraction CLI powered by the TypeScript compiler API",
   "license": "MIT",
   "type": "commonjs",
@@ -17,7 +17,6 @@
     "type": "git",
     "url": "https://github.com/and-1991/eventra-cli"
   },
-
   "homepage": "https://eventra.dev",
   "engines": {
     "node": ">=18"
@@ -25,7 +24,9 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/index.ts",
-    "test": "pnpm run clean && pnpm run build && tsx tests/run.ts",
+    "test": "pnpm run clean && pnpm run build && pnpm run test:unit && tsx tests/run.ts",
+    "test:unit": "vitest run",
+    "test:e2e": "pnpm run clean && pnpm run build && tsx tests/run.ts",
     "clean": "rm -rf dist"
   },
   "dependencies": {
@@ -42,18 +43,39 @@
     "@types/inquirer": "^9.0.9",
     "@types/node": "^20.0.0",
     "cross-spawn": "^7.0.6",
-    "tsx": "^4.7.0"
+    "tsx": "^4.7.0",
+    "vitest": "^4.1.7"
   },
   "keywords": [
     "analytics",
+    "analytics-cli",
     "event-tracking",
+    "feature-usage",
+    "feature-tracking",
+    "product-analytics",
+    "telemetry",
+    "tracking",
+    "events",
+    "event-catalog",
+    "event-discovery",
     "static-analysis",
+    "static-code-analysis",
     "typescript",
+    "typescript-compiler",
     "compiler-api",
     "ast",
+    "code-analysis",
+    "drift-detection",
+    "ci",
+    "ci-cd",
+    "lint",
+    "watch-mode",
     "cli",
-    "telemetry",
-    "eventra"
+    "command-line",
+    "developer-tools",
+    "devtools",
+    "eventra",
+    "eventra-cli"
   ],
   "publishConfig": {
     "access": "public"