fix: Drop replayed watch events before they reach the dirty buffer

[Aukevanoost]

Core-side counterpart to angular-adapter#94 / angular-adapter#96.

Context

With the dev server running, edits to sharedMappings libraries and exposes sources never reached the emitted federation bundles. The adapter-side root cause is that syncNfFileWatcher(watcher, bundlerCache) was called with Angular's SourceFileCache, which extends Map but keeps its inputs in typeScriptFileCache/referencedFiles — so keys() was empty and the watch set never filled. That fix belongs in the adapter; it is Angular-private knowledge core cannot have.

But the adapter fix leans on core behaviour that does not hold, and its much wider watch list (~0 → ~1,900 paths) surfaces work that belongs in the watcher core owns.

onChange could not veto the dirty buffer

deliver() records before notifying — deliberately, per fc87599, because the adapter needs both channels:

const deliver = (path: string) => {
  dirtyPaths.add(path);
  if (onChange) onChange(path);
};

So an adapter-side onChange: p => { if (!isRealChange(p)) return; ... } gates its rebuild loop but cannot keep the event out of the buffer. Downstream that meant replayed paths still became modifiedFiles for rebuildForFederation, bypassing the modifiedFiles.length === 0 early-return in rebuildAffectedExternals and clearing shared-bundle cache entries for files that never changed — and any consumer gating on watcher.get().size === 0 silently stopped working after the first replay.

The replay filter is generic (fs.watch behaviour, zero framework content), so it moves here, ahead of dirtyPaths.add.

Changes

Replay dedupe in the watcher

dedupeReplays (default on). Events whose recorded identity — mtime and byte length — is unchanged since the last one seen for that path are dropped before reaching either channel. macOS FSEvents re-delivers 'changed' for recently edited files roughly every 30s; with a watch list of a few thousand sources that replay alone keeps a rebuild loop awake indefinitely.

Length is paired with mtime so that the one genuinely ambiguous case — a second save landing inside a single mtime tick, on a filesystem with coarse granularity — is settled on data rather than on a clock. Only a save that also left byte length untouched reaches the time check at all, which is what keeps a wrong clock reading from swallowing the common case.

replayGraceMs (default 2000) is that time check: an identity-matching event still passes while the mtime is recent. The default is a derived bound, not a tuned constant. A filesystem truncating mtime to granularity g records a value up to g before the write, so two writes can only collide in mtime within 2g; g is 1s on the coarsest filesystems in play (gRPC-FUSE, NFS, WSL2 drvfs, HFS+). On ext4 and APFS g is nanoseconds, so a real save always advances mtime and the window is never reached.

Age is measured from when the event arrived, not from when a debounced flush got round to it, so debounceMs is not silently subtracted from the window. Two limits are documented rather than papered over: an event-loop stall delays the fs.watch callback itself, which no local bookkeeping can correct; and on a network mount the age is a cross-clock subtraction, since mtime carries the server's clock. A server clock running ahead yields a negative age, which reads as recent and delivers — the safe direction, so it is left alone. Running behind shortens the window, and there the only remedy is a larger replayGraceMs or dedupeReplays: false.

addPaths seeds each newly watched file's identity so the first replay after startup is already recognised as one. Directories are skipped — seeding a recursive watch would mean walking the tree — and their entries seed themselves on the event that first reports them. identityOf follows one symlink level, mirroring maxMtime in resolve-shared-dirs.ts; io.stat is lstat-based, so without it every event for a symlinked source reads as a replay.

File watches go through the directory

addPaths no longer opens a handle on a file. A per-file fs.watch holds an inode, and an editor that saves by rename-replace (JetBrains "safe write", vim backupcopy=no) replaces it — the handle then reports nothing, so the second save onward is silently lost. Each tracked file is covered by a non-recursive watch on its containing directory instead, filtered back down through trackedFiles so the event surface is unchanged. This also collapses thousands of sources onto a few hundred handles, and reports files created after they were added. Directories passed explicitly keep their recursive watch.

A failed watch is no longer silent

Now that one watch covers a whole directory of sources, swallowing the throw at debug level hides exactly the #94 symptom: paths that never report a change and a dev server serving the last bundle until restart. The first failure is a logger.warn naming the path and the consequence. Later ones stay at debug — descriptor exhaustion fails every subsequent directory too, and a line per path would flood.

sharedMappingDirs

The source dir of every config.sharedMappings entry point — a framework-agnostic watch set for mappings, derived from config alone rather than from a bundler cache. Coarser than a build's compiled inputs and deliberately so: it covers files added to a lib since the last build, which a compiled-inputs watch set cannot know about yet. It does not follow imports out of the lib, so an adapter that can enumerate its build inputs should watch both.

syncNfFileWatcher accepts paths directly

The second parameter widens to WatchSources = Iterable<string> | { keys(): Iterable<string> }, so an adapter that has to expand its cache passes the resulting array instead of a synthetic { keys: () => files[Symbol.iterator]() }. Backward compatible for cache-keyed-by-input-path consumers.

One trap worth knowing: arrays expose keys() too, and it yields indices — the Array.isArray check has to come first, and there is a test asserting real paths rather than 0, 1.

The JSDoc now names the SourceFileCache case, so the next adapter author meets it as documentation rather than as a dev server serving stale bundles.

Compatibility

dedupeReplays defaults to on, which is a behaviour change for existing consumers.

• esbuild-adapter uses a Map<string, unknown> keyed by input path, watched natively. On inotify a save always advances mtime, so the only events it loses are genuine no-ops. Set dedupeReplays: false to opt out.
• The syncNfFileWatcher signature change is additive — existing call sites keep working.
• StatInfo gains a required size. The io port is internal (not exported from index.ts or internal.ts), so this affects no consumer.
• Website docs (adapters/build-your-own.md, core/api-reference.md) stay accurate; they should gain a note about the dedupe, the widened parameter and sharedMappingDirs in a follow-up.

Out of scope

• Watcher pruning. watchers, fileDirWatchers, trackedFiles and lastSeen are never pruned during a session, only cleared on close(). Linux inotify exhaustion is not a realistic blocker on modern distros (max_user_watches is 247k on the machine this was measured on), and directory collapsing cut handle count by roughly an order of magnitude, but the maps still grow monotonically. Own issue.
• A reconciliation sweep. Nothing here recovers events the platform itself dropped — inotify IN_Q_OVERFLOW under git checkout or npm install churn, where events are lost wholesale and lastSeen still holds the pre-checkout identity. Re-stat'ing the tracked set would catch every one and costs ~3.6 ms for 1,900 files (measured), but it needs a call-cadence decision: addPaths already runs once per build and needs no new API, yet delivering from there fires onChange inside the adapter's own post-build sync call and invites re-entrant rebuilds. Own issue — and note there that the motivation is queue overflow, not the dedupe. It cannot recover a wrongly-dropped ambiguous event, because in that case the recorded identity already equals the current one.

Verification

pnpm test (440 tests / 44 files), pnpm typecheck, pnpm lint (0 errors; 5 warnings, all pre-existing no-console in logger.ts), pnpm build, pnpm knip all pass.

file-watcher.spec.ts goes from 10 to 30 tests. Two existing tests needed a fixed clock plus an mtime advance to model a real save. New coverage: replay dropped from both channels; an identity-matching event inside the grace window passing; an aged same-mtime event whose length changed passing; a future mtime delivering; the grace window measured from event arrival rather than from the debounced flush; mtime advance re-arming; vanished file passing; first event for an unseeded directory entry passing; dedupeReplays: false; symlink target mtime; directory-not-file watch registration, neighbour filtering, post-add file creation, and no double watch under a recursive dir; warn-once on watch failure; and all four WatchSources shapes.

Still to do end-to-end, on a workspace where the issue reproduces: link dist/ into an angular-adapter#96 checkout and confirm a sharedMappings .ts save reaches the emitted bundle in one rebuild, that an 80s idle window after it records zero further cycles, and that two saves inside one second both land.