@eventra_dev/eventra-cli 2.1.0 → 2.2.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">
@@ -212,7 +212,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 +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`
 
@@ -255,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)
@@ -416,7 +426,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. 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`.
 
@@ -440,14 +450,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, **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.
 

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

@@ -5,7 +5,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.init = init;
 const chalk_1 = __importDefault(require("chalk"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
 const inquirer_1 = __importDefault(require("inquirer"));
+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 +15,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() {
+async function chooseSinks(yes) {
     const detected = (0, sinkPresets_1.detectSinkPresets)(await (0, projectDependencies_1.collectDependencyNames)(process.cwd()));
     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 +36,47 @@ async function chooseSinks() {
     ]);
     return presets.map((preset) => ({ preset }));
 }
-async function init() {
+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 } = {}) {
+    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 sinks = await chooseSinks(yes);
     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")'));

package/dist/cli/send.js

@@ -7,6 +7,7 @@ exports.send = send;
 const chalk_1 = __importDefault(require("chalk"));
 const inquirer_1 = __importDefault(require("inquirer"));
 const config_1 = require("../config/config");
+const catalogMeta_1 = require("../core/catalogMeta");
 const package_json_1 = __importDefault(require("../../package.json"));
 const CLI_VERSION = package_json_1.default.version;
 // Always trusted, no local approval needed — matches `eventra init`'s prompt default.
@@ -64,6 +65,10 @@ async function attemptDelivery(endpoint, apiKey, payload) {
         clearTimeout(timeout);
     }
 }
+// the API answers a rejected unknown property with {"error":{"code":"VALIDATION_ERROR",...}}
+function isValidationError(body) {
+    return typeof body === "string" && body.includes("VALIDATION_ERROR");
+}
 async function send(opts = {}) {
     const config = await (0, config_1.loadConfig)();
     if (!config) {
@@ -134,24 +139,48 @@ async function send(opts = {}) {
     }
     console.log("");
     console.log(chalk_1.default.blue(`Sending ${config.events.length} events...`));
-    const payload = JSON.stringify({
+    // Tells the server whether this list is a full snapshot of the code (so names
+    // missing from it can be marked as removed) and how many event names could
+    // not be resolved. Older servers ignore the extra fields.
+    const meta = await (0, catalogMeta_1.collectCatalogMeta)(config);
+    if (!meta.complete) {
+        console.log(chalk_1.default.gray("Catalog snapshot marked incomplete (files were skipped, the scan failed, or eventra.json is out of date: run 'eventra sync')"));
+    }
+    const legacyBody = {
         events: config.events,
         cli: {
             name: "@eventra_dev/eventra-cli",
             version: CLI_VERSION,
             runtime: "node",
         },
+    };
+    const payload = JSON.stringify({
+        ...legacyBody,
+        complete: meta.complete,
+        cliVersion: CLI_VERSION,
+        ...(meta.dynamicCount !== undefined ? { dynamicCount: meta.dynamicCount } : {}),
+        ...(meta.branch ? { branch: meta.branch } : {}),
     });
+    // A server that predates the catalog fields rejects unknown properties with a
+    // generic validation 400; the request is then repeated once without them.
+    const legacyPayload = JSON.stringify(legacyBody);
+    let body = payload;
     // 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);
+            const outcome = await attemptDelivery(endpoint, apiKey, body);
             if (outcome.ok) {
                 data = outcome.data;
                 break;
             }
+            if (outcome.status === 400 && body !== legacyPayload && isValidationError(outcome.body)) {
+                body = legacyPayload;
+                console.log(chalk_1.default.gray("Server does not know the catalog fields yet, sending the plain event list"));
+                attempt--;
+                continue;
+            }
             if (!outcome.retryable) {
                 // permanent failure — surface immediately
                 console.log(chalk_1.default.red(`Request failed (${outcome.status})`));

package/dist/cli/sync.js

@@ -8,17 +8,20 @@ const chalk_1 = __importDefault(require("chalk"));
 const config_1 = require("../config/config");
 const projectScanner_1 = require("../core/projectScanner");
 const scanResults_1 = require("../core/scanResults");
-async function sync() {
-    const config = await (0, config_1.loadConfig)();
-    if (!config) {
-        console.log(chalk_1.default.red("eventra.json not found"));
+const skipped_1 = require("../core/skipped");
+async function sync({ strict = false } = {}) {
+    const config = await (0, config_1.requireConfig)();
+    if (!config)
         return;
-    }
     console.log(chalk_1.default.blue("Scanning..."));
-    const { engine, plugins } = await (0, projectScanner_1.scanProject)(config);
-    await (0, scanResults_1.persistScanResults)(config, engine);
-    const events = engine.getAllEvents();
-    const wrappers = engine.getAllFunctionWrappers();
-    console.log(chalk_1.default.green(`Found ${events.length} events, ${wrappers.length} function wrappers`));
+    const { engine, plugins, skipped, ignored } = await (0, projectScanner_1.scanProject)(config);
+    // report what was saved: with skipped files that is the union of the known and
+    // the found events, not just what this scan found
+    const saved = await (0, scanResults_1.persistScanResults)(config, engine, { preserveKnown: skipped.length > 0 });
+    console.log(chalk_1.default.green(`Found ${(0, skipped_1.plural)(saved.events?.length ?? 0, "event")}, ${(0, skipped_1.plural)(saved.functionWrappers?.length ?? 0, "function wrapper")}`));
     await plugins.runDynamicEventReporters(engine.getAllDynamicOccurrences());
+    (0, skipped_1.reportSkipped)(skipped);
+    (0, skipped_1.reportIgnored)(ignored);
+    if (strict && skipped.length > 0)
+        process.exitCode = 1;
 }