watch: fix --watch-path restart on unrelated file with --env-file

[RajeshKumar11]

Summary

• When using --watch-path=<dir> together with --env-file=<path>, touching any file in the directory that contains the env file incorrectly triggers a restart — even if the changed file has nothing to do with the watched path
• Fix: filterFile() now watches the specific file directly in 'all' mode, rather than watching its entire parent directory

Root cause

FilesWatcher has two modes:

Mode	When used	#onChange behaviour
'filter'	No --watch-path	Only fires for files in #filteredFiles
'all'	--watch-path provided	Fires for any change in any watched path

filterFile() in lib/internal/watch_mode/files_watcher.js:131 takes a shortcut on macOS and Windows (platforms with recursive fs.watch support): instead of setting up one watcher per file, it calls watchPath(dirname(file)) to watch the whole parent directory with a single recursive FSWatcher.

In 'filter' mode this is harmless — #onChange checks #filteredFiles before emitting 'changed', so only the tracked file triggers a restart.

In 'all' mode the filter check is skipped. So when watch_mode.js calls filterFile(resolve('.env')) (line 106) to watch the env file, it actually watches . (the CWD) recursively. Any fs.watch event in the CWD — including touch unrelated — then passes straight through and triggers a restart.

Fix

Add && this.#mode === 'filter' to the condition that selects the parent-directory strategy:

// Before
if (supportsRecursiveWatching) {
  this.watchPath(dirname(file));   // watches the whole directory

// After
if (supportsRecursiveWatching && this.#mode === 'filter') {
  this.watchPath(dirname(file));   // only in filter mode
} else {
  this.watchPath(file, false);     // watch the specific file
}

In 'all' mode the env file is now watched directly (watchPath(file, false)), so only changes to that exact file fire the watcher.

Tests

Two new cases added to test/parallel/test-watch-mode-files_watcher.mjs:

1. No false trigger: filterFile() in 'all' mode + modify an unrelated file in the same directory → mustNotCall asserts no 'changed' event fires
2. Correct trigger: filterFile() in 'all' mode + modify the watched file itself → 'changed' fires exactly once

Related

Ref: #61906 (reporter provided a clean minimal repro)

Fixes: #61906

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.77%. Comparing base (da5efc4) to head (869ff22).
⚠️ Report is 16 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #61970      +/-   ##
==========================================
+ Coverage   88.84%   89.77%   +0.93%     
==========================================
  Files         674      674              
  Lines      204957   205608     +651     
  Branches    39309    39415     +106     
==========================================
+ Hits       182087   184588    +2501     
+ Misses      15088    13270    -1818     
+ Partials     7782     7750      -32     

Files with missing lines	Coverage Δ
lib/internal/watch_mode/files_watcher.js	91.20% <100.00%> (+3.41%)	⬆️

... and 180 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.