fs: watch directories, not files, in recursive fs.watch fallback

[codebytere]

Makes the JavaScript recursive watcher (used where fs.watch() has no native recursive mode) arm one watcher per directory instead of one per file on Linux, and answer each event with one stat() instead of re-reading the directory.

Linux, this repository's test/ tree (13 500 entries, 896 directories):

	before	after
fs.watch(test, { recursive: true }) setup	~150 ms, 13 501 handles, +52 MB RSS	~45 ms, 896 handles, +20 MB RSS
benchmark/fs/bench-watch-recursive.js (new), test/fixtures, 30 runs		+287 % ±4 %
CPU for 300 appends to one file in test/parallel	2 860 ms	11 ms
CPU for 100 create+unlink in test/parallel	2 890 ms	110 ms

The fallback armed an fs.watch() handle and ran a statSync() for every file in the tree, and handled every event by stat()ing and re-reading the whole directory it happened in. A file replaced by rename() (the usual editor save) also stopped being reported, because its watch stayed on the old inode, and watcher.ref()/unref() were no-ops on this path.

inotify reports changes to a watched directory's entries with the entry name, so on Linux the watcher now keeps one handle per directory (symbolic links keep their own, as before) plus the set of known paths, and resolves an event with a single stat() of the named entry: new names are reported as 'rename' and descended into if they are directories, vanished ones are dropped with their subtree and reported as 'rename', changes to known files are 'change'. kqueue and event ports only report that the directory itself changed, so on the other platforms this fallback serves (illumos, the BSDs, AIX) files keep a watcher each and a directory event rescans that directory, as today. Two event differences remain, both matching the native watchers: creating a file with content yields 'rename' then 'change', and a file keeps being reported after it is replaced by rename(). ref()/unref() now reach the handles.

Tests: all test-fs-watch-recursive-*, test-fs-watch-ignore-*, test-fs-promises-watch* and watch-mode tests pass in both modes (the per-file mode exercised on Linux by flipping the platform check; recursive ones 3/3 repeated runs); a new Linux-only test covers the per-directory handle count, rename-over reporting, events behind a symbolic link, removal of a watched root directory and root file, and ref()/unref().

---

Disclosure: the code, test, benchmark, measurements and this description were written by Claude Code, directed and reviewed by @codebytere.

[nodejs-github-bot]

Review requested:

• @nodejs/performance

[codecov]

Codecov Report

❌ Patch coverage is 85.24590% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.11%. Comparing base (21f0f27) to head (bd967d5).
⚠️ Report is 64 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/fs/recursive_watch.js	85.24%	17 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #65486      +/-   ##
==========================================
- Coverage   90.12%   90.11%   -0.01%     
==========================================
  Files         752      751       -1     
  Lines      252315   252488     +173     
  Branches    47444    47497      +53     
==========================================
+ Hits       227395   227538     +143     
- Misses      16217    16266      +49     
+ Partials     8703     8684      -19     

Files with missing lines	Coverage Δ
lib/internal/fs/recursive_watch.js	87.17% <85.24%> (-0.03%)	⬇️

... and 54 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/76280/

[codebytere]

the smartos failure was legit: event ports (and kqueue) only report that a watched directory changed, not which entry or writes to files inside it, so per-directory watches are an inotify-only option. 7774d81 keeps the per-directory design on Linux and, on the other platforms this fallback serves, keeps a watcher per file and rescans the directory on a directory event as main does; watch() on an entry that vanished between the listing and the call is now tolerated everywhere. all recursive watch tests pass in both modes here (per-file mode exercised by flipping the platform check). needs a CI run to confirm on smartos.