@eventra_dev/eventra-cli 2.0.10 → 2.2.0

package/dist/cli/init.js

@@ -5,23 +5,78 @@ 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");
-async function init() {
-    console.log(chalk_1.default.blue("Initializing Eventra..."));
-    const { apiKey, endpoint, } = await inquirer_1.default.prompt([
-        {
-            type: "input",
-            name: "apiKey",
-            message: "API Key (optional):",
-        },
+const sinkPresets_1 = require("../plugin/builtins/sinkPresets");
+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(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: "input",
-            name: "endpoint",
-            message: "Custom endpoint (optional):",
-            default: "https://api.eventra.dev/api/v1/cli/events",
+            type: "checkbox",
+            name: "presets",
+            message: "Also read events from these analytics calls (sinks):",
+            choices: detected.map((d) => ({
+                name: `${d.preset} (${d.packages.join(", ")})`,
+                value: d.preset,
+                checked: true,
+            })),
         },
     ]);
+    return presets.map((preset) => ({ preset }));
+}
+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, } = 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")'));
@@ -33,6 +88,7 @@ async function init() {
         endpoint,
         events: [],
         functionWrappers: [],
+        ...(sinks.length > 0 ? { sinks } : {}),
         sync: {
             include: [
                 "**/*.{ts,tsx,js,jsx}",
@@ -47,6 +103,9 @@ async function init() {
     };
     await (0, config_1.saveConfig)(config);
     console.log(chalk_1.default.green("eventra.json created"));
+    if (sinks.length > 0) {
+        console.log(chalk_1.default.green(`sinks: ${sinks.map((s) => s.preset).join(", ")}`));
+    }
     // Never write the key into eventra.json — that file is meant to be
     // committed (CI diffs it via `eventra check`). Keep secrets out of git.
     if (apiKey) {

package/dist/cli/projectDependencies.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectDependencyNames = collectDependencyNames;
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const DEPENDENCY_FIELDS = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+/** Upper bound on workspace members read, so a huge monorepo cannot make `init` crawl. */
+const MAX_WORKSPACE_PACKAGES = 300;
+/**
+ * Parsed package.json, or null when it is missing or not JSON. Whatever else the file holds (an
+ * array, a number) is returned as is: every reader below only looks up named properties on it, which
+ * is harmless on any JSON value, so there is no point in a second validation here.
+ */
+async function readPackage(file) {
+    try {
+        return (await fs_extra_1.default.readJSON(file));
+    }
+    catch {
+        return null;
+    }
+}
+function dependencyNames(pkg) {
+    return DEPENDENCY_FIELDS.flatMap((field) => {
+        const deps = pkg[field];
+        return typeof deps === "object" && deps !== null && !Array.isArray(deps) ? Object.keys(deps) : [];
+    });
+}
+function stringList(value) {
+    // Stryker disable next-line ArrayDeclaration: a stray pattern that matches no directory changes nothing
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+/** `packages:` entries of a pnpm-workspace.yaml (only the plain list form, which is all pnpm writes). */
+function pnpmWorkspacePatterns(yaml) {
+    // Stryker disable next-line ArrayDeclaration: a stray pattern that matches no directory changes nothing
+    const patterns = [];
+    let inPackages = false;
+    for (const line of yaml.split(/\r?\n/)) {
+        if (/^packages:\s*(#.*)?$/.test(line)) {
+            inPackages = true;
+            continue;
+        }
+        if (!inPackages)
+            continue;
+        // YAML lets the dashes sit at the key's own indent (`packages:` / `- 'apps/*'`), so no indent is required.
+        const item = /^\s*-\s*['"]?([^'"#]+?)['"]?\s*(#.*)?$/.exec(line);
+        if (item) {
+            patterns.push(item[1]);
+        }
+        else if (/^\S/.test(line)) {
+            // The next top-level key ends the list.
+            inPackages = false;
+        }
+    }
+    return patterns;
+}
+/** A workspace pattern may only point inside the project: no absolute paths, no `..`. */
+function staysInsideProject(pattern) {
+    // Stryker disable next-line StringLiteral: a negated pattern outside the project excludes nothing, so what replaces the "!" cannot show
+    const target = pattern.replace(/^!/, "");
+    return !path_1.default.isAbsolute(target) && !target.split(/[\\/]/).includes("..");
+}
+/** pnpm-workspace.yaml patterns; an unreadable file (a directory, no permission) counts as having none. */
+async function readPnpmPatterns(file) {
+    try {
+        return pnpmWorkspacePatterns(await fs_extra_1.default.readFile(file, "utf8"));
+    }
+    catch {
+        // Stryker disable next-line ArrayDeclaration: a stray pattern that matches no directory changes nothing
+        return [];
+    }
+}
+async function workspacePatterns(rootDir, rootPackage) {
+    const workspaces = rootPackage.workspaces;
+    const fromPackageJson = Array.isArray(workspaces)
+        ? stringList(workspaces)
+        : stringList(workspaces?.packages);
+    const fromPnpm = await readPnpmPatterns(path_1.default.join(rootDir, "pnpm-workspace.yaml"));
+    return [...fromPackageJson, ...fromPnpm].filter(staysInsideProject);
+}
+/**
+ * `apps/*` -> every member's package.json. A negated pattern (`!apps/skipped`) becomes
+ * `!apps/skipped/package.json`, which fast-glob treats as an exclusion of exactly those files.
+ */
+const memberGlob = (pattern) => `${pattern}/package.json`;
+/** Member package.json paths for the patterns; a pattern fast-glob rejects (a NUL byte, say) yields none. */
+async function findMembers(rootDir, patterns) {
+    try {
+        return await (0, fast_glob_1.default)(patterns.map(memberGlob), { cwd: rootDir, ignore: ["**/node_modules/**"] });
+    }
+    catch {
+        // Stryker disable next-line ArrayDeclaration: a stray path that is not a package.json is read as "no package.json"
+        return [];
+    }
+}
+/**
+ * Every dependency name the project declares: the root package.json plus, in a monorepo
+ * (`workspaces` or pnpm-workspace.yaml), each workspace member's package.json.
+ */
+async function collectDependencyNames(rootDir) {
+    const names = new Set();
+    const rootPackage = await readPackage(path_1.default.join(rootDir, "package.json"));
+    if (rootPackage === null)
+        return names;
+    for (const name of dependencyNames(rootPackage))
+        names.add(name);
+    const patterns = await workspacePatterns(rootDir, rootPackage);
+    const members = (await findMembers(rootDir, patterns)).slice(0, MAX_WORKSPACE_PACKAGES);
+    for (const member of members) {
+        const memberPackage = await readPackage(path_1.default.join(rootDir, member));
+        if (memberPackage !== null)
+            for (const name of dependencyNames(memberPackage))
+                names.add(name);
+    }
+    return names;
+}

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;
 }

package/dist/cli/watch.js

@@ -14,141 +14,242 @@ const eventraSdk_1 = require("../analysis/sdk/eventraSdk");
 const EventraEngine_1 = require("../core/EventraEngine");
 const scanResults_1 = require("../core/scanResults");
 const loadPlugins_1 = require("../plugin/loadPlugins");
-const SDK_TYPES_FILE = "__eventra_sdk_types__.d.ts";
-const processFile_1 = require("../filesystem/processFile");
+const scanFilters_1 = require("../core/scanFilters");
+const skipped_1 = require("../core/skipped");
+const fileLimits_1 = require("../core/fileLimits");
 const getVirtualFile_1 = require("../filesystem/getVirtualFile");
+const SDK_TYPES_FILE = "__eventra_sdk_types__.d.ts";
+// Files outside `include` can still change what a scanned file means when
+// something imports them (a shared constants module, a wrapper in a helper).
+// Only code-like files are worth rebuilding the program for.
+const CODE_FILE = /\.(?:[cm]?[jt]s|[jt]sx|json)$/;
+const isNotFound = (err) => err?.code === "ENOENT";
 async function watch() {
-    const config = await (0, config_1.loadConfig)();
-    if (!config) {
-        console.log(chalk_1.default.red("eventra.json not found"));
-        return;
-    }
+    const config = await (0, config_1.requireConfig)();
+    if (!config)
+        return undefined;
     console.log(chalk_1.default.blue("Watching...\n"));
     const plugins = await (0, loadPlugins_1.createPluginRegistry)(config);
     const include = [...config.sync.include, ...plugins.getIncludePatterns()];
     const engine = new EventraEngine_1.EventraEngine(process.cwd(), plugins);
-    const fileDeps = new Map();
-    const cache = new Map();
     const watchedDeps = new Set();
     const trackedFiles = new Set();
     const sourceFiles = new Set();
+    // files whose last analysis failed; while there are any, saved results keep
+    // the previously known events (see buildConfigFromScan)
+    const skippedNow = new Map();
     const normalize = (file) => {
         return path_1.default.resolve(file).replace(/\\/g, "/");
     };
-    // chokidar's `ignored` receives absolute, normalized paths — reject any path
-    // with an excluded directory name as one of its segments (matches how
-    // `fast-glob`'s own `ignore` option is applied during the initial scan).
-    const excludedDirs = new Set(config.sync.exclude);
-    const isExcludedPath = (file) => {
-        const segments = normalize(file).split("/");
-        return segments.some((segment) => excludedDirs.has(segment));
+    // The same rules as the initial scan (and as `sync`): plain exclude names match
+    // at any depth, and a changed file is only handled when it matches `include`.
+    // The config files are written by this process, so they must never trigger a run.
+    const filter = (0, scanFilters_1.createFileFilter)(include, config.sync.exclude, process.cwd(), [
+        config_1.CONFIG_NAME,
+        config_1.LOCAL_CONFIG_NAME,
+    ]);
+    const isExcludedPath = (file) => filter.isExcluded(normalize(file));
+    const isSource = (abs) => sourceFiles.has(abs) || trackedFiles.has(abs) || filter.isIncluded(abs);
+    // an imported (or newly importable) file outside `include`
+    const isDependencyCandidate = (abs) => CODE_FILE.test(abs) && !isSource(abs);
+    const shouldHandle = (abs) => !filter.isExcluded(abs) && (isSource(abs) || isDependencyCandidate(abs));
+    // what eventra.json holds now: "keep the known events" while a file is broken
+    // must mean the events this process saved last, not the ones at startup
+    let saved = config;
+    const persist = async () => {
+        saved = await (0, scanResults_1.persistScanResults)(saved, engine, { preserveKnown: skippedNow.size > 0 });
     };
+    const signature = () => JSON.stringify([engine.getAllEvents(), engine.getAllFunctionWrappers()]);
     const files = await (0, fast_glob_1.default)(include, {
-        ignore: config.sync.exclude,
+        ignore: (0, scanFilters_1.expandExcludePatterns)(config.sync.exclude),
         absolute: true,
     });
+    const ignoredInitial = [];
     engine.beginPreload();
     await engine.preloadFile(SDK_TYPES_FILE, eventraSdk_1.EVENTRA_SDK_SHIM);
     for (const file of files) {
         try {
             const abs = normalize(file);
-            sourceFiles.add(abs);
             const raw = await promises_1.default.readFile(abs, "utf-8");
+            // the same limit as `sync`: too big to analyse, but not a failure
+            if ((0, fileLimits_1.isOversized)(raw)) {
+                ignoredInitial.push({ file: abs, reason: fileLimits_1.OVERSIZED_REASON });
+                continue;
+            }
+            sourceFiles.add(abs);
             const virtualFiles = await plugins.preprocessFile({ fileName: abs, content: raw });
             for (const virtualFile of virtualFiles) {
                 const scanPath = normalize(virtualFile.fileName);
-                const parsed = await (0, processFile_1.processFile)(scanPath, virtualFile.content);
-                cache.set(scanPath, parsed);
                 trackedFiles.add(scanPath);
                 await engine.preloadFile((0, getVirtualFile_1.getVirtualFile)(scanPath), virtualFile.content);
-                fileDeps.set(scanPath, new Set(parsed.dependencies
-                    .filter((dep) => dep.startsWith(".") || dep.startsWith("/"))
-                    .map((dep) => normalize(path_1.default.resolve(path_1.default.dirname(scanPath), dep)))));
             }
         }
-        catch {
-            // ignore invalid files
+        catch (err) {
+            const skip = (0, skipped_1.skippedFrom)(file, err);
+            skippedNow.set(normalize(file), skip);
         }
     }
     engine.endPreload();
+    (0, skipped_1.reportSkipped)([...skippedNow.values()]);
+    (0, skipped_1.reportIgnored)(ignoredInitial);
     await engine.runFullAnalysis([SDK_TYPES_FILE, ...trackedFiles].map((f) => (0, getVirtualFile_1.getVirtualFile)(f)), config);
-    await (0, scanResults_1.persistScanResults)(config, engine);
+    await persist();
     const initialEvents = engine.getAllEvents();
     const initialWrappers = engine.getAllFunctionWrappers();
-    console.log(chalk_1.default.gray(`Initial: ${initialEvents.length} events, ${initialWrappers.length} wrappers\n`));
+    console.log(chalk_1.default.gray(`Initial: ${(0, skipped_1.plural)(initialEvents.length, "event")}, ${(0, skipped_1.plural)(initialWrappers.length, "wrapper")}\n`));
     // Watch the project root (not just the files found by the initial scan) so
-    // that brand-new files matching `include` are noticed as they're created —
+    // that brand-new files matching `include` are noticed as they're created -
     // a fixed file list only ever detects edits to files chokidar already knows
-    // about. Dependency files outside the root (added below via `watcher.add`)
-    // are unaffected by this and keep working the same way.
+    // about. Project files that live outside the root are added below.
     const watcher = chokidar_1.default.watch(process.cwd(), {
         ignoreInitial: true,
         ignored: isExcludedPath,
     });
+    const root = normalize(process.cwd());
+    const isOutsideRoot = (abs) => abs !== root && !abs.startsWith(`${root}/`);
+    // Imported files outside the project root are not covered by the root
+    // watcher: follow exactly the ones the program really resolved.
+    const syncOutsideDeps = () => {
+        const outside = new Set(engine
+            .getProjectFileNames()
+            .map(normalize)
+            .filter((file) => isOutsideRoot(file) && !filter.isExcluded(file) && CODE_FILE.test(file)));
+        for (const dep of outside) {
+            if (watchedDeps.has(dep))
+                continue;
+            watcher.add(dep);
+            watchedDeps.add(dep);
+        }
+        for (const dep of [...watchedDeps]) {
+            if (outside.has(dep))
+                continue;
+            watcher.unwatch(dep);
+            watchedDeps.delete(dep);
+        }
+    };
+    syncOutsideDeps();
     const queue = new Map();
     let timer = null;
+    // a source file is gone (deleted, or no longer analysable such as one that grew past the size limit)
+    const dropSource = async (abs) => {
+        sourceFiles.delete(abs);
+        skippedNow.delete(abs);
+        for (const virtualPath of plugins.getVirtualPathsForSource(abs)) {
+            trackedFiles.delete(virtualPath);
+            await engine.removeFile((0, getVirtualFile_1.getVirtualFile)(virtualPath), config);
+        }
+    };
     const run = async () => {
         const batch = [...queue.keys()];
         queue.clear();
+        if (batch.length === 0)
+            return;
+        const before = signature();
+        let touchedSource = false;
+        const skippedThisRun = [];
+        const ignoredThisRun = [];
+        // imported files outside `include` that changed, appeared or vanished: one rebuild for all of them
+        const external = batch.filter((file) => !isSource(file));
+        if (external.length > 0) {
+            try {
+                await engine.refreshExternalFiles(external, config);
+            }
+            catch (err) {
+                console.error(chalk_1.default.red(`watch error: ${(0, skipped_1.errorMessage)(err)}`));
+            }
+        }
         for (const file of batch) {
+            if (!isSource(file))
+                continue;
+            touchedSource = true;
             try {
                 const raw = await promises_1.default.readFile(file, "utf-8");
+                if ((0, fileLimits_1.isOversized)(raw)) {
+                    // too big to analyse, like `sync`: not a failure, and its events are not kept
+                    await dropSource(file);
+                    ignoredThisRun.push({ file, reason: fileLimits_1.OVERSIZED_REASON });
+                    continue;
+                }
                 const virtualFiles = await plugins.preprocessFile({ fileName: file, content: raw });
+                sourceFiles.add(file);
+                skippedNow.delete(file);
                 for (const virtualFile of virtualFiles) {
                     const scanPath = normalize(virtualFile.fileName);
-                    const parsed = await (0, processFile_1.processFile)(scanPath, virtualFile.content);
-                    cache.set(scanPath, parsed);
                     trackedFiles.add(scanPath);
                     await engine.updateFile((0, getVirtualFile_1.getVirtualFile)(scanPath), virtualFile.content, config);
-                    const prevDeps = fileDeps.get(scanPath) ?? new Set();
-                    const nextDeps = new Set(parsed.dependencies
-                        .filter((dep) => dep.startsWith(".") || dep.startsWith("/"))
-                        .map((dep) => normalize(path_1.default.resolve(path_1.default.dirname(scanPath), dep))));
-                    for (const dep of nextDeps) {
-                        if (prevDeps.has(dep))
-                            continue;
-                        watcher.add(dep);
-                        watchedDeps.add(dep);
-                    }
-                    for (const dep of prevDeps) {
-                        if (nextDeps.has(dep))
-                            continue;
-                        watcher.unwatch(dep);
-                        watchedDeps.delete(dep);
-                    }
-                    fileDeps.set(scanPath, nextDeps);
                 }
             }
-            catch {
-                console.log(chalk_1.default.gray(`skip: ${file}`));
+            catch (err) {
+                if (isNotFound(err)) {
+                    // gone before it could be read (created and deleted within one debounce, or removed mid-run)
+                    await dropSource(file);
+                    continue;
+                }
+                const skip = (0, skipped_1.skippedFrom)(file, err);
+                skippedNow.set(file, skip);
+                skippedThisRun.push(skip);
             }
         }
-        await (0, scanResults_1.persistScanResults)(config, engine);
-        console.log(chalk_1.default.green(`Updated: ${engine.getAllEvents().length} events, ${engine.getAllFunctionWrappers().length} wrappers`));
+        (0, skipped_1.reportSkipped)(skippedThisRun);
+        (0, skipped_1.reportIgnored)(ignoredThisRun);
+        syncOutsideDeps();
+        // a batch of imported-only files that changed nothing about the result is not worth a write or a log line
+        if (!touchedSource && signature() === before)
+            return;
+        await persist();
+        console.log(chalk_1.default.green(`Updated: ${(0, skipped_1.plural)(engine.getAllEvents().length, "event")}, ${(0, skipped_1.plural)(engine.getAllFunctionWrappers().length, "wrapper")}`));
+    };
+    // One run at a time: a timer firing while the previous run is still awaiting
+    // would otherwise interleave two runs over the same engine.
+    let chain = Promise.resolve();
+    const enqueue = (task) => {
+        chain = chain.then(task).catch((err) => {
+            console.error(chalk_1.default.red(`watch error: ${(0, skipped_1.errorMessage)(err)}`));
+        });
     };
     const schedule = (file) => {
         const abs = normalize(file);
+        if (!shouldHandle(abs))
+            return;
         queue.set(abs, true);
         if (timer)
             clearTimeout(timer);
-        timer = setTimeout(run, 200);
+        timer = setTimeout(() => enqueue(run), 200);
     };
     watcher
         .on("change", schedule)
         .on("add", schedule)
-        .on("unlink", async (file) => {
+        .on("unlink", (file) => {
         const abs = normalize(file);
-        sourceFiles.delete(abs);
-        const virtualPaths = plugins.getVirtualPathsForSource(abs);
-        for (const virtualPath of virtualPaths) {
-            trackedFiles.delete(virtualPath);
-            await engine.removeFile((0, getVirtualFile_1.getVirtualFile)(virtualPath), config);
+        if (filter.isExcluded(abs))
+            return;
+        // a file that failed to analyse is in no set but is still remembered as skipped
+        if (!sourceFiles.has(abs) && !trackedFiles.has(abs) && !skippedNow.has(abs)) {
+            // an imported-only file vanished: dependents resolve differently now
+            if (CODE_FILE.test(abs) && engine.hasProgramFile(abs)) {
+                queue.set(abs, true);
+                if (timer)
+                    clearTimeout(timer);
+                timer = setTimeout(() => enqueue(run), 200);
+            }
+            return;
         }
-        await (0, scanResults_1.persistScanResults)(config, engine);
-        console.log(chalk_1.default.red(`Removed → ${engine.getAllEvents().length} events, ${engine.getAllFunctionWrappers().length} wrappers`));
+        enqueue(async () => {
+            await dropSource(abs);
+            await persist();
+            console.log(chalk_1.default.red(`Removed -> ${(0, skipped_1.plural)(engine.getAllEvents().length, "event")}, ${(0, skipped_1.plural)(engine.getAllFunctionWrappers().length, "wrapper")}`));
+        });
     });
     process.on("SIGINT", async () => {
         await watcher.close();
         process.exit(0);
     });
+    return {
+        close: async () => {
+            if (timer)
+                clearTimeout(timer);
+            await watcher.close();
+            await chain;
+        },
+    };
 }