@harperfast/harper 5.2.0 → 5.2.1

package/dist/components/EntryHandler.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EntryHandler = void 0;
 const harper_logger_ts_1 = require("../utility/logging/harper_logger.js");
+const node_crypto_1 = require("node:crypto");
 const node_events_1 = require("node:events");
 const Component_ts_1 = require("./Component.js");
 const chokidar_1 = __importDefault(require("chokidar"));
@@ -18,29 +19,63 @@ class EntryHandler extends node_events_1.EventEmitter {
     #watcher;
     #logger;
     #pendingFileReads;
+    #pendingFileReadsByGeneration;
     #isInitialScanComplete;
-    // When true, #watch() short-circuits without creating a chokidar watcher.
-    // pause() sets it, resume() clears it. Lets a deploy quiesce the watcher
-    // without losing the EntryHandler instance (and therefore listener
-    // attachments registered by plugins via scope.handleEntry(handler)).
+    #readyPending = false;
+    #readyGeneration = 0;
+    #watchGeneration = 0;
+    #eventSequence = 0;
+    #latestPathSequence = new Map();
+    #entries = new Map();
+    #redeployScan;
     #paused = false;
-    // Tracks the in-flight close() promise from pause() so resume() can await
-    // the old watcher's inotify handles releasing before installing a fresh
-    // chokidar instance — otherwise a rapid pause→resume can overlap teardown
-    // and setup, which under inotify pressure can produce spurious EMFILE.
     #pausedClose;
+    // Serializes replacements so concurrent update/recovery calls cannot orphan an intervening watcher.
+    #watchInstall;
     #usingPolling = false;
     #closed = false;
     #openCount = 0;
+    #liveWatchers = new Set();
     ready;
     constructor(name, directory, config, logger) {
         super();
         this.#component = new Component_ts_1.Component(name, directory, castConfig(config));
         this.#logger = logger || (0, harper_logger_ts_1.loggerWithTag)(name);
         this.#pendingFileReads = new Set();
+        this.#pendingFileReadsByGeneration = new Map();
         this.#isInitialScanComplete = false;
-        this.ready = (0, node_events_1.once)(this, 'ready');
-        this.#watch();
+        this.ready = this.#createReadyLatch();
+        this.#watch().catch(() => { });
+    }
+    #createReadyLatch() {
+        if (this.#readyPending)
+            return this.ready;
+        this.#readyPending = true;
+        const ready = new Promise((resolve, reject) => {
+            const cleanup = () => {
+                this.#readyPending = false;
+                this.off('ready', handleReady);
+                this.off('error', handleError);
+                this.off('close', handleClose);
+            };
+            const handleReady = () => {
+                cleanup();
+                resolve([]);
+            };
+            const handleError = (error) => {
+                cleanup();
+                reject(error);
+            };
+            const handleClose = () => {
+                cleanup();
+                reject(new Error(`Entry handler for ${this.name} closed before becoming ready`));
+            };
+            this.once('ready', handleReady);
+            this.once('error', handleError);
+            this.once('close', handleClose);
+        });
+        void ready.catch(() => { });
+        return ready;
     }
     get name() {
         return this.#component.name;
@@ -48,7 +83,9 @@ class EntryHandler extends node_events_1.EventEmitter {
     get directory() {
         return this.#component.directory;
     }
-    #handleAll(...[event, path, stats]) {
+    #handleAll(generation, ...[event, path, stats]) {
+        if (generation !== this.#watchGeneration)
+            return;
         if (path === '')
             path = '/';
         if (!(0, micromatch_1.isMatch)(path, this.#component.globOptions.source, { ignore: this.#component.globOptions.ignore }))
@@ -57,25 +94,7 @@ class EntryHandler extends node_events_1.EventEmitter {
         switch (event) {
             case 'add':
             case 'change': {
-                const urlPath = (0, deriveURLPath_ts_1.deriveURLPath)(this.#component, path, 'file');
-                const fileReadPromise = (0, promises_1.readFile)(absolutePath)
-                    .then((contents) => {
-                    const entry = {
-                        eventType: event,
-                        entryType: 'file',
-                        contents,
-                        stats,
-                        absolutePath,
-                        urlPath,
-                    };
-                    this.emit('all', entry);
-                    this.emit(event, entry);
-                })
-                    .finally(() => {
-                    this.#pendingFileReads.delete(fileReadPromise);
-                    this.#checkIfAllComplete();
-                });
-                this.#pendingFileReads.add(fileReadPromise);
+                this.#queueFileRead(generation, event, path, absolutePath, stats, (0, promises_1.readFile)(absolutePath));
                 break;
             }
             case 'unlink': {
@@ -87,27 +106,200 @@ class EntryHandler extends node_events_1.EventEmitter {
                     absolutePath,
                     urlPath,
                 };
-                this.emit('all', entry);
-                this.emit(event, entry);
+                this.#handleRemovedEntry(generation, entry);
                 break;
             }
             case 'addDir':
             case 'unlinkDir': {
                 const urlPath = (0, deriveURLPath_ts_1.deriveURLPath)(this.#component, path, 'directory');
-                const entry = {
-                    eventType: event,
-                    entryType: 'directory',
-                    stats,
-                    absolutePath,
-                    urlPath,
-                };
-                this.emit('all', entry);
-                this.emit(event, entry);
+                if (event === 'addDir') {
+                    const entry = {
+                        eventType: event,
+                        entryType: 'directory',
+                        stats,
+                        absolutePath,
+                        urlPath,
+                    };
+                    this.#handleAddedEntry(generation, entry, this.#snapshot(entry));
+                }
+                else {
+                    const entry = {
+                        eventType: event,
+                        entryType: 'directory',
+                        stats,
+                        absolutePath,
+                        urlPath,
+                    };
+                    this.#handleRemovedEntry(generation, entry);
+                }
                 break;
             }
         }
     }
-    #handleError(error) {
+    #queueFileRead(generation, event, path, absolutePath, stats, contentsPromise) {
+        const sequence = ++this.#eventSequence;
+        this.#latestPathSequence.set(absolutePath, sequence);
+        const fileReadPromise = contentsPromise
+            .then((contents) => {
+            if (generation !== this.#watchGeneration || this.#latestPathSequence.get(absolutePath) !== sequence)
+                return;
+            if (this.#redeployScan?.generation === generation)
+                this.#redeployScan.readFailures.delete(absolutePath);
+            const entry = {
+                eventType: event,
+                entryType: 'file',
+                contents,
+                stats,
+                absolutePath,
+                urlPath: (0, deriveURLPath_ts_1.deriveURLPath)(this.#component, path, 'file'),
+            };
+            try {
+                this.#handleAddedEntry(generation, entry, this.#snapshot(entry));
+            }
+            catch (error) {
+                this.#reportConsumerError(error);
+            }
+        }, (error) => {
+            if (generation !== this.#watchGeneration ||
+                this.#latestPathSequence.get(absolutePath) !== sequence ||
+                error?.code === 'ENOENT')
+                return;
+            if (this.#redeployScan?.generation === generation) {
+                this.#redeployScan.readFailures.set(absolutePath, error);
+            }
+            else {
+                this.#handleWatcherError(error);
+            }
+        })
+            .finally(() => {
+            if (this.#latestPathSequence.get(absolutePath) === sequence)
+                this.#latestPathSequence.delete(absolutePath);
+            this.#pendingFileReads.delete(fileReadPromise);
+            const generationReads = this.#pendingFileReadsByGeneration.get(generation);
+            generationReads?.delete(fileReadPromise);
+            if (generationReads?.size === 0)
+                this.#pendingFileReadsByGeneration.delete(generation);
+            this.#checkIfAllComplete(generation);
+        });
+        this.#pendingFileReads.add(fileReadPromise);
+        let generationReads = this.#pendingFileReadsByGeneration.get(generation);
+        if (!generationReads)
+            this.#pendingFileReadsByGeneration.set(generation, (generationReads = new Set()));
+        generationReads.add(fileReadPromise);
+        return fileReadPromise;
+    }
+    #snapshot(entry) {
+        if (entry.entryType === 'file')
+            return {
+                entryType: entry.entryType,
+                urlPath: entry.urlPath,
+                digest: (0, node_crypto_1.createHash)('sha256').update(entry.contents).digest(),
+            };
+        return { entryType: entry.entryType, urlPath: entry.urlPath };
+    }
+    #handleAddedEntry(generation, entry, snapshot) {
+        if (generation !== this.#watchGeneration)
+            return;
+        const scan = this.#redeployScan?.generation === generation ? this.#redeployScan : undefined;
+        if (!scan) {
+            const wasKnown = this.#entries.has(entry.absolutePath);
+            this.#entries.set(entry.absolutePath, snapshot);
+            // A newer change read can supersede an initial add read for the same path. The consumer still
+            // needs its first event to be an add so it can load the entry before handling later changes.
+            if (entry.entryType === 'file' && entry.eventType === 'change' && !wasKnown)
+                this.#emitEntrySafely({ ...entry, eventType: 'add' });
+            else
+                this.#emitEntrySafely(entry);
+            return;
+        }
+        const wasRemovedDuringScan = scan.removalsEmitted.delete(entry.absolutePath);
+        const currentEntry = scan.currentEntries.get(entry.absolutePath);
+        const previousEntry = wasRemovedDuringScan
+            ? undefined
+            : (currentEntry ?? scan.previousEntries.get(entry.absolutePath));
+        scan.currentEntries.set(entry.absolutePath, snapshot);
+        if (!previousEntry) {
+            this.#emitAddition(entry);
+            return;
+        }
+        if (previousEntry.entryType !== snapshot.entryType || previousEntry.urlPath !== snapshot.urlPath) {
+            try {
+                this.#emitRemoval(previousEntry, entry.absolutePath);
+            }
+            catch (error) {
+                this.#reportConsumerError(error);
+            }
+            this.#emitAddition(entry);
+            return;
+        }
+        if (snapshot.entryType === 'file' &&
+            previousEntry.entryType === 'file' &&
+            !previousEntry.digest.equals(snapshot.digest)) {
+            this.#emitEntrySafely({ ...entry, eventType: 'change' });
+        }
+    }
+    #emitAddition(entry) {
+        if (entry.entryType === 'file')
+            this.#emitEntrySafely({ ...entry, eventType: 'add' });
+        else
+            this.#emitEntrySafely({ ...entry, eventType: 'addDir' });
+    }
+    #handleRemovedEntry(generation, entry) {
+        if (generation !== this.#watchGeneration)
+            return;
+        this.#latestPathSequence.delete(entry.absolutePath);
+        const scan = this.#redeployScan?.generation === generation ? this.#redeployScan : undefined;
+        if (!scan) {
+            this.#entries.delete(entry.absolutePath);
+            this.#emitEntrySafely(entry);
+            return;
+        }
+        const knownEntry = scan.currentEntries.get(entry.absolutePath) ?? scan.previousEntries.get(entry.absolutePath);
+        scan.currentEntries.delete(entry.absolutePath);
+        if (!knownEntry || scan.removalsEmitted.has(entry.absolutePath))
+            return;
+        try {
+            this.#emitRemoval(knownEntry, entry.absolutePath);
+        }
+        catch (error) {
+            this.#reportConsumerError(error);
+        }
+        scan.removalsEmitted.add(entry.absolutePath);
+    }
+    #emitRemoval(snapshot, absolutePath) {
+        if (snapshot.entryType === 'file')
+            this.#emitEntry({ eventType: 'unlink', entryType: 'file', absolutePath, urlPath: snapshot.urlPath });
+        else
+            this.#emitEntry({ eventType: 'unlinkDir', entryType: 'directory', absolutePath, urlPath: snapshot.urlPath });
+    }
+    #emitEntry(entry) {
+        this.emit('all', entry);
+        switch (entry.eventType) {
+            case 'add':
+                this.emit('add', entry);
+                break;
+            case 'change':
+                this.emit('change', entry);
+                break;
+            case 'unlink':
+                this.emit('unlink', entry);
+                break;
+            case 'addDir':
+                this.emit('addDir', entry);
+                break;
+            case 'unlinkDir':
+                this.emit('unlinkDir', entry);
+        }
+    }
+    #emitEntrySafely(entry) {
+        try {
+            this.#emitEntry(entry);
+        }
+        catch (error) {
+            this.#reportConsumerError(error);
+        }
+    }
+    #handleWatcherError(error) {
         if ((0, watcherFallback_ts_1.isWatcherExhaustionError)(error)) {
             // Swallow every exhaustion error — chokidar can emit several before the
             // failed native watcher closes, and we don't want a flurry of ENOSPC to
@@ -127,46 +319,133 @@ class EntryHandler extends node_events_1.EventEmitter {
             }
             return;
         }
-        this.emit('error', error);
+        this.#reportConsumerError(error);
+    }
+    #reportConsumerError(error) {
+        if (this.listenerCount('error') > 0)
+            this.emit('error', error);
+        else
+            this.#logger.error?.('Error in entry listener:', error);
     }
-    #handleReady() {
+    #handleReady(generation) {
+        if (generation !== this.#watchGeneration)
+            return;
         this.#isInitialScanComplete = true;
-        if (this.#pendingFileReads.size > 0) {
-            this.#logger.debug?.(`Initial scan complete, still waiting for ${this.#pendingFileReads.size} pending file reads`);
+        const pendingReads = this.#pendingFileReadsByGeneration.get(generation)?.size ?? 0;
+        if (pendingReads > 0) {
+            this.#logger.debug?.(`Initial scan complete, still waiting for ${pendingReads} pending file reads`);
         }
-        this.#checkIfAllComplete();
+        this.#checkIfAllComplete(generation);
     }
-    #checkIfAllComplete() {
-        // Only emit 'ready' once the initial scan is complete AND all file reads are done
-        if (this.#isInitialScanComplete && this.#pendingFileReads.size === 0) {
+    #checkIfAllComplete(generation) {
+        if (generation === this.#watchGeneration &&
+            this.#readyGeneration !== generation &&
+            this.#isInitialScanComplete &&
+            !this.#pendingFileReadsByGeneration.has(generation)) {
+            this.#readyGeneration = generation;
+            const { listenerErrors, readErrors } = this.#finishRedeployScan(generation);
             this.emit('ready');
+            // The readiness latch rejects if `error` is emitted first. Surface consumer failures only
+            // after resolving the generation's ready latch so one bad removal listener cannot strand startup.
+            for (const error of listenerErrors)
+                this.#reportConsumerError(error);
+            for (const error of readErrors)
+                this.#handleWatcherError(error);
         }
     }
+    #finishRedeployScan(generation) {
+        const scan = this.#redeployScan;
+        if (!scan || scan.generation !== generation)
+            return { listenerErrors: [], readErrors: [] };
+        const listenerErrors = [];
+        for (const absolutePath of scan.readFailures.keys()) {
+            const previousEntry = scan.previousEntries.get(absolutePath);
+            if (previousEntry && !scan.currentEntries.has(absolutePath))
+                scan.currentEntries.set(absolutePath, previousEntry);
+        }
+        const missingEntries = [...scan.previousEntries].filter(([absolutePath]) => !scan.currentEntries.has(absolutePath) && !scan.removalsEmitted.has(absolutePath));
+        // Match watcher deletion semantics: descendants disappear before the directory that contained them.
+        missingEntries.sort(([a], [b]) => b.length - a.length);
+        // Commit the generation before invoking consumer code. A synchronously throwing removal listener must
+        // not leave the old snapshot installed or keep the readiness latch permanently unresolved.
+        this.#entries = scan.currentEntries;
+        this.#redeployScan = undefined;
+        for (const [absolutePath, snapshot] of missingEntries) {
+            try {
+                this.#emitRemoval(snapshot, absolutePath);
+            }
+            catch (error) {
+                listenerErrors.push(error);
+            }
+        }
+        return { listenerErrors, readErrors: [...scan.readFailures.values()] };
+    }
+    #observedEntries() {
+        const scan = this.#redeployScan;
+        if (!scan)
+            return this.#entries;
+        // A generation can be replaced before `ready`, after some events have already reached consumers.
+        // Carry exactly that observed state forward: retain previously known paths that this partial scan
+        // has not reached, apply additions/changes it emitted, and remove paths whose unlink was emitted.
+        const observedEntries = new Map(scan.previousEntries);
+        for (const absolutePath of scan.removalsEmitted)
+            observedEntries.delete(absolutePath);
+        for (const [absolutePath, snapshot] of scan.currentEntries)
+            observedEntries.set(absolutePath, snapshot);
+        return observedEntries;
+    }
     async #watch() {
-        // If pause() retained an in-flight close, wait for it to release inotify
-        // handles before we install a new watcher. Otherwise a fast pause→resume
-        // can overlap teardown and setup under inotify pressure.
+        const install = this.#watchInstall ? this.#watchInstall.then(() => this.#installWatcher()) : this.#installWatcher();
+        const settled = install.then(() => {
+            if (this.#watchInstall === settled)
+                this.#watchInstall = undefined;
+        }, () => {
+            if (this.#watchInstall === settled)
+                this.#watchInstall = undefined;
+        });
+        this.#watchInstall = settled;
+        await install;
+        return this.ready;
+    }
+    async #installWatcher() {
         if (this.#pausedClose) {
             await this.#pausedClose;
             this.#pausedClose = undefined;
         }
-        await this.#watcher?.close();
-        this.#watcher = undefined;
-        // If close() landed while a previous close()/recreate was awaiting, don't
-        // install a fresh watcher — it would outlive the EntryHandler.
+        const outgoing = this.#watcher;
+        if (outgoing) {
+            // Stays installed across the await so a close() landing in the gap still includes this
+            // teardown in its own settle set; only clear it if close() didn't already replace it.
+            try {
+                await outgoing.close();
+            }
+            catch (error) {
+                this.#logger.warn?.(`Failed to close the previous watcher for ${this.name}; replacing it anyway:`, error);
+            }
+            finally {
+                this.#liveWatchers.delete(outgoing);
+            }
+            if (this.#watcher === outgoing)
+                this.#watcher = undefined;
+        }
         if (this.#closed)
-            return this.ready;
-        // pause() may have landed in the gap before our async close resolved.
-        // If so, do not install a replacement watcher — resume() will.
+            return;
         if (this.#paused)
-            return this.ready;
-        // When a fresh watcher is installed (after pause+resume, or update), the
-        // initial scan emits add events anew, so reset the readiness latch so
-        // `ready` resolves after the new scan completes.
+            return;
+        const generation = ++this.#watchGeneration;
         this.#isInitialScanComplete = false;
+        const previousEntries = this.#observedEntries();
+        this.#entries = previousEntries;
+        this.#redeployScan = {
+            generation,
+            previousEntries,
+            currentEntries: new Map(),
+            removalsEmitted: new Set(),
+            readFailures: new Map(),
+        };
         const allowedBases = this.#component.patternBases.map((base) => (0, node_path_1.join)(this.#component.directory, base));
         this.#openCount++;
-        this.#watcher = chokidar_1.default
+        const watcher = (this.#watcher = chokidar_1.default
             .watch(this.#component.commonPatternBase, {
             cwd: this.#component.directory,
             persistent: false,
@@ -200,34 +479,43 @@ class EntryHandler extends node_events_1.EventEmitter {
                 return (normalizedPath !== normalizedDirectory && normalizedBases.every((base) => !normalizedPath.startsWith(base)));
             },
         })
-            .on('all', this.#handleAll.bind(this))
-            .on('error', this.#handleError.bind(this))
-            .on('ready', this.#handleReady.bind(this));
-        return this.ready;
+            .on('all', (...args) => this.#handleAll(generation, ...args))
+            .on('error', (error) => {
+            if (generation === this.#watchGeneration)
+                this.#handleWatcherError(error);
+        })
+            .on('ready', () => this.#handleReady(generation)));
+        this.#liveWatchers.add(watcher);
     }
-    // Test-only: simulate the underlying chokidar watcher emitting an error.
-    // Exposed so the polling-fallback path can be exercised without triggering a
-    // real ENOSPC/EMFILE on the host.
     _simulateWatcherErrorForTests(error) {
-        this.#handleError(error);
+        this.#handleWatcherError(error);
+    }
+    _simulateFileReadForTests(event, path, contents) {
+        const absolutePath = (0, node_path_1.join)(this.directory, path);
+        return this.#queueFileRead(this.#watchGeneration, event, path, absolutePath, undefined, contents);
     }
-    // Test-only: whether the watcher has fallen back to polling.
     get _usingPollingForTests() {
         return this.#usingPolling;
     }
-    // Test-only: number of times the underlying watcher has been (re)opened.
-    // Used to assert that a close()-during-fallback race didn't install a
-    // replacement watcher.
     get _openCountForTests() {
         return this.#openCount;
     }
+    get _liveWatcherCountForTests() {
+        return this.#liveWatchers.size;
+    }
     close() {
+        this.#watchGeneration++;
         this.#closed = true;
         const pendingReads = [...this.#pendingFileReads];
-        const watcherClose = this.#watcher ? Promise.resolve(this.#watcher.close()).catch(() => { }) : Promise.resolve();
+        const outgoing = this.#watcher;
+        const watcherClose = outgoing
+            ? Promise.resolve(outgoing.close())
+                .catch(() => { })
+                .then(() => {
+                this.#liveWatchers.delete(outgoing);
+            })
+            : Promise.resolve();
         this.#watcher = undefined;
-        // If paused, there may be an in-flight close from pause() that hasn't settled yet.
-        // Include it so close() doesn't resolve while inotify handles are still releasing.
         const pausedClose = this.#pausedClose ?? Promise.resolve();
         this.#pausedClose = undefined;
         this.emit('close');
@@ -244,27 +532,25 @@ class EntryHandler extends node_events_1.EventEmitter {
      * Idempotent. Awaiting `ready` while paused will not resolve until resume().
      */
     pause() {
+        if (this.#paused || this.#closed)
+            return;
+        this.#watchGeneration++;
         this.#paused = true;
-        // Reset `ready` to a fresh pending promise so the documented "awaiting
-        // ready while paused will not resolve until resume()" contract holds even
-        // when the watcher had already become ready before pause(). The next
-        // 'ready' emit will come from the chokidar instance installed by resume().
-        this.ready = (0, node_events_1.once)(this, 'ready');
+        this.ready = this.#createReadyLatch();
         if (this.#watcher) {
-            // Retain the close promise so resume()→#watch() can await full
-            // teardown before opening a new watcher.
-            this.#pausedClose = Promise.resolve(this.#watcher.close()).catch(() => {
-                // Teardown errors aren't actionable; swallow so resume can proceed.
+            const outgoing = this.#watcher;
+            this.#pausedClose = Promise.resolve(outgoing.close())
+                .catch(() => { })
+                .then(() => {
+                this.#liveWatchers.delete(outgoing);
             });
             this.#watcher = undefined;
         }
     }
     /**
      * Reinstate the watcher previously stopped by pause(). The fresh chokidar
-     * instance does an initial scan and emits add events for every file
-     * currently matching the configured globs — by design, since the typical
-     * caller (Scope, on deploy:end) wants plugins to see the post-deploy tree
-     * as if loading cold.
+     * instance scans the post-pause tree, compares it with the retained snapshot,
+     * and emits only the logical add, change, unlink, addDir, and unlinkDir events.
      *
      * No-op if not currently paused.
      */
@@ -272,12 +558,17 @@ class EntryHandler extends node_events_1.EventEmitter {
         if (!this.#paused)
             return this.ready;
         this.#paused = false;
-        // `this.ready` was already reset to a pending promise in pause(); just
-        // trigger the watcher recreation and let its 'ready' emit resolve it.
         return this.#watch();
     }
     update(config) {
+        if (this.#closed)
+            return this.ready;
+        this.#watchGeneration++;
         this.#component = new Component_ts_1.Component(this.name, this.directory, castConfig(config));
+        // Re-arm the readiness latch for parity with pause(). Without this, awaiting update() on an
+        // already-ready handler resolves against the outgoing generation's 'ready' — before the
+        // replacement generation has scanned, digested, and emitted its logical events.
+        this.ready = this.#createReadyLatch();
         return this.#watch();
     }
 }