Disheartening API:--watch --hot

[vamsaya]

What version of Bun is running?

1.3.4

What platform is your computer?

Ubuntu 22

What steps can reproduce the bug?

中文	English
由于 Bun 没有实现原生的 FileWatcher，Node 的 fs.watch 又过于简单，因此不得不使用子进程方案。但新的问题层出不穷，让人为之抓狂。	Due to Bun's lack of a native FileWatcher and Node's fs.watch being too simplistic, I had to resort to subprocess-based solutions. However, this has introduced a cascade of new issues that are incredibly frustrating.
fs.watch API 在 --watch 模式下表现正常，但在 --hot 模式下，随着重载次数的增多，会触发大量的回调。	The fs.watch API works correctly in --watch mode, but in --hot mode, it triggers an excessive number of callbacks with each reload.
inotifywait 子进程无论在 --watch 还是 --hot 模式下运行，随着脚本更新，系统进程列表中会残留并堆积大量僵尸进程，持续消耗系统资源。	The inotifywait subprocess leaves behind a growing number of orphaned processes in the system process list as scripts are updated, consuming resources continuously in both --watch and --hot modes.
只有按下 Ctrl+C 结束 Bun 进程后，这些子进程才会被关闭。	These subprocesses only terminate when the Bun process itself is killed with Ctrl+C.
我记得 --hot 最初设计的初衷是保证 Bun.serve 不中断服务，以及通过 global.varName ??= "value" 声明的变量不受重载影响。	I recall that --hot was originally designed to keep Bun.serve running without interruption and to preserve variables declared via global.varName ??= "value" across reloads.
此外，在 --hot 模式下，Bun.build 首次构建正常，但一旦主脚本发生变化导致进程重载，就会报错（error: Unexpected reading file:）。	Additionally, under --hot mode, Bun.build succeeds on the first build but throws errors (error: Unexpected reading file:) after the main script changes and triggers a reload.
现在，为什么变得这么难用？	Why has it become so unreliable and difficult to use?

async function Watcher(dirname, callback) {
    console.log("watch", dirname);
    const proc = Bun.spawn([
        "inotifywait",
        "--format", "%e\t%w%f",
        "-mrq",
        "-e", "create,modify,delete,moved_from,moved_to",
        dirname
    ]);
    const decoder = new TextDecoder();
    for await (let line of proc.stdout) {
        line = decoder.decode(line).trimEnd();
        for (const row of line.split("\n")) {
            const [event, filename] = row.split("\t");
            callback(event, filename);
        }
    }
}
Watcher("./foo", function () {
    console.log(...arguments);
});

What is the expected behavior?

No response

What do you see instead?

No response

Additional information

No response

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and agent prompts for this issue.

• Create Plan

Examples

• Example 1
• Example 2

🔗 Similar & Duplicate Issues

Related Issues

• oven-sh/bun#20983

🔗 Related PRs

#22651 - Fix Windows shell crash with && operator and external commands [merged] | src/shell/IO.zig:
"""

AI-generated summary of changes

• Modifies OutKind.to_subproc_stdio switch handling for the .fd case. Introduces a guarded path: if val.writer.fd.get() yields a valid FD, it now assigns .fd = fd; otherwise it falls back to the inherit path by setting .inherit = {}. This replaces the previous approach which unconditionally used val.writer.fd.get().? and could propagate an error or ignore the moved-to-libuv scenario.
• Adds a specific branch to handle a valid, unmoved FD and updates the Windows-related comment to reflect that if the FD has been moved to libuv, the subprocess should inherit stdio instead of using the FD.
• Overall change alters control flow from unconditionally attempting to unwrap a movable FD to a conditional path that either passes through a real FD or uses inheritance for Windows/libuv-managed cases.

Alterations to the declarations of exported or public entities

• None

Estimated code review effort: High
"""

---

test/regression/issue/22650-shell-crash.test.ts:
"""

AI-generated summary of changes

Adds a new regression test file test/regression/issue/22650-shell-crash.test.ts. The test uses bun:test with harness-provided bunEnv and bunExe. It defines a test named "issue #22650 - shell crash with && operator followed by external command" that spawns a Bun process via Bun.spawn with cmd [bunExe(), "exec", "echo test && node --version"], pipes stdout and stderr, and captures stdout, stderr, and exit code concurrently. It asserts: (1) no output on stderr, (2) stdout contains "test", (3) stdout matches the Node version pattern /v\d+.\d+.\d+/, and (4) exit code equals 0. The test verifies that chaining commands with && and invoking an external command does not crash the shell.

Alterations to the declarations of exported or public entities

• None (no exported/public declarations modified).

Estimated code review effort: Medium
"""

---

src/bun.js/event_loop/MiniEventLoop.zig:
"""

AI-generated summary of changes

• Adds a public API change to MiniEventLoop.initGlobal by introducing an optional cwd parameter and using it to initialize top_level_dir during initialization. The function signature changes from pub fn initGlobal(env: ?*bun.DotEnv.Loader) *MiniEventLoop to pub fn initGlobal(env: ?*bun.DotEnv.Loader, cwd: ?[]const u8) *MiniEventLoop. If cwd is provided, top_level_dir is set from it. If not, and top_level_dir is still empty, it queries the current working directory via bun.sys.getcwd into a PathBuffer, duplicates the path into global.top_level_dir using the default allocator, and falls back to an empty string on failure. This initialization block runs before globalInitialized is set to true, ensuring top_level_dir has a deterministic value during startup. No other public API changes are introduced; only initialization logic and the API signature are modified.

Alterations to the declarations of exported or public entities

• Method signature updated: pub fn initGlobal(env: ?*bun.DotEnv.Loader) *MiniEventLoop in src/bun.js/event_loop/MiniEventLoop.zig → pub fn initGlobal(env: ?*bun.DotEnv.Loader, cwd: ?[]const u8) *MiniEventLoop
  """

---

src/bun.js.zig:
"""

AI-generated summary of changes

In bootBunShell, the call to MiniEventLoop.initGlobal now passes a second argument. Previously: initGlobal(bundle.env). Now: initGlobal(bundle.env, null). The rest of the initialization flow is unchanged (top_level_dir assignment and interpreter startup from the entry file). This indicates a public API change to MiniEventLoop.initGlobal to accept an additional parameter, with the patch providing null for that parameter.

Alterations to the declarations of exported or public entities

• Public API change: jsc.MiniEventLoop.initGlobal signature updated to accept an additional parameter; call-site updated to pass null as the second argument in src/bun.js.zig (from initGlobal(bundle.env) to initGlobal(bundle.env, null)).

Estimated code review effort: Medium
"""

---

src/cli/bunx_command.zig:
"""

AI-generated summary of changes

In the Windows path of BunxCommand, the EventLoopHandle initialization now calls MiniEventLoop.initGlobal with an extra argument (null). This changes the call site from initGlobal(this_transpiler.env) to initGlobal(this_transpiler.env, null) when constructing the event loop for bunx install. No other logic or error handling in the diff is affected.

Alterations to the declarations of exported or public entities

• Method signature updated: bun.jsc.MiniEventLoop.initGlobal now accepts an additional parameter (two-argument form) instead of the previous one-argument form; the code uses initGlobal(this_transpiler.env, null) in src/cli/bunx_command.zig.

Estimated code review effort: Medium
"""

---

src/cli/create_command.zig:
"""

AI-generated summary of changes

• Updated Windows-specific event loop initialization to call MiniEventLoop.initGlobal with an extra argument. Replaced initGlobal(null) with initGlobal(null, null) in two call sites within src/cli/create_command.zig, leaving all other logic intact.

Alterations to the declarations of exported or public entities

• None

Estimated code review effort: Medium
"""

---

src/cli/exec_command.zig:
"""

AI-generated summary of changes

• Introduces retrieval of the current working directory (cwd) via bun.sys.getcwd and uses the resulting path in the script execution flow, including building script_path and the parts array.
• Updates the MiniEventLoop initialization to pass the cwd: from initGlobal(bundle.env) to initGlobal(bundle.env, cwd).
• Ensures the cwd value is computed before using it to initialize the MiniEventLoop and to construct script-related paths.
• Error handling for cwd retrieval remains: on failure, emit an error and exit.
• No changes to the public API of ExecCommand.exec; the change is internal to how the environment and cwd are handled.

Alterations to the declarations of exported or public entities

• Signature updated: bun.jsc.MiniEventLoop.initGlobal(bundle.env) → bun.jsc.MiniEventLoop.initGlobal(bundle.env, cwd)

Estimated code review effort: Medium
"""

---

src/cli/filter_run.zig:
"""

AI-generated summary of changes

• The event loop initialization call changed from bun.jsc.MiniEventLoop.initGlobal(this_transpiler.env) to bun.jsc.MiniEventLoop.initGlobal(this_transpiler.env, null). This adds a second argument (null) to the initialization call; no other logic or control-flow changes are evident.

Alterations to the declarations of exported or public entities

• No exported/public declarations modified.

Estimated code review effort: Medium
"""

---

src/cli/pm_version_command.zig:
"""

AI-generated summary of changes

• Windows-specific event loop initialization in PmVersionCommand was updated across five call sites to pass an additional null argument to MiniEventLoop.initGlobal. Previously initGlobal(null) is now initGlobal(null, null). The second argument is consistently null. All other logic and error handling remain unchanged, and non-Windows paths are unaffected.

Alterations to the declarations of exported or public entities

• None (no changes to signatures of exported/public entities).

Estimated code review effort: Medium
"""

---

src/cli/run_command.zig:
"""

AI-generated summary of changes

• Non-system-shell script execution now passes the current working directory to MiniEventLoop.initGlobal by switching from initGlobal(env) to initGlobal(env, cwd) in RunPackageScriptForeground.
• Windows spawn paths updated to use initGlobal(env, null) to accommodate the new signature when no cwd is available, affecting both the RunPackageScriptForeground spawn path and the runBinaryWithoutBunxPath path.
• Overall, three call-sites are updated to accommodate a second, optional parameter for the MiniEventLoop initialization; no other logic or error handling changes are introduced.

Alterations to the declarations of exported or public entities

• Method signature updated: pub fn initGlobal in module bun.jsc.MiniEventLoop now accepts an additional parameter cwd: ?[]const u8 (previously it was initGlobal(env)).
  • Old: initGlobal(env: *DotEnv.Loader) ...
  • New: initGlobal(env: *DotEnv.Loader, cwd: ?[]const u8) ...

Estimated code review effort: Medium
"""

---

src/cli/upgrade_command.zig:
"""

AI-generated summary of changes

On Windows, the upgrade command’s Expand-Archive path now initializes the event loop with MiniEventLoop.initGlobal(null, null) instead of MiniEventLoop.initGlobal(null). This changes the EventLoopHandle creation for the spawned process; all other logic, including error handling and the surrounding control flow, remains unchanged.

• No changes to signatures of exported or public entities.

Estimated code review effort: Medium
"""

---

src/create/SourceFileProjectGenerator.zig:
"""

AI-generated summary of changes

• Windows-specific Event Loop initialization now passes an extra argument to MiniEventLoop.initGlobal in two call sites, changing from initGlobal(null) to initGlobal(null, null). The surrounding logic and error handling remain unchanged; only the function call signature at these two places is updated to match a newer API.

Alterations to the declarations of exported or public entities

• Method signature updated: bun.jsc.MiniEventLoop.initGlobal now accepts two parameters (previously one). This change requires updated call sites to provide an additional argument.
  • Updated call-site: src/create/SourceFileProjectGenerator.zig (Windows path) in two locations:
    • .windows = if (Environment.isWindows) .{ .loop = bun.jsc.EventLoopHandle.init(bun.jsc.MiniEventLoop.initGlobal(null, null)), }
    • (Second occurrence mirrors the same signature change)

Estimated code review effort: Medium
"""

---

src/http/HTTPThread.zig:
"""

AI-generated summary of changes

The only observable change is in onStart: the call to bun.jsc.MiniEventLoop.initGlobal now passes two arguments (null, null) instead of a single argument (null). This implies a public API change to MiniEventLoop.initGlobal. All other startup logic and control flow remain unchanged.

Alterations to the declarations of exported or public entities

• Function signature updated: bun.jsc.MiniEventLoop.initGlobal now takes two arguments instead of one.

Estimated code review effort: Medium
"""

---

src/open.zig:
"""

AI-generated summary of changes

In the Windows path of openURL, the initialization of the event loop now calls MiniEventLoop.initGlobal with an extra null argument, changing from initGlobal(null) to initGlobal(null, null). All other logic and control flow around the spawnSync call remains unchanged.

• Method signature updated: bun.jsc.MiniEventLoop.initGlobal(null) in src/open.zig → bun.jsc.MiniEventLoop.initGlobal(null, null) in src/open.zig

• Method signature updated: bun.jsc.MiniEventLoop.initGlobal(null) in src/open.zig → bun.jsc.MiniEventLoop.initGlobal(null, null) in src/open.zig

Estimated code review effort: Medium
"""
#23340 - fix(windows): prevent data loss in pipe reads after libuv 1.51.0 upgrade [merged] | src/io/PipeReader.zig:
"""

AI-generated summary of changes

• WindowsBufferedReader._onReadChunk now defers clearing has_inflight_read until after the onReadChunk callback completes, and ensures the flag is cleared even if the callback is null, adding a local result path when onReadChunk is not provided.
• After invoking the onReadChunk callback, the code clears has_inflight_read to prevent libuv from initiating a new read while data is still being processed.
• WindowsBufferedReader.finish now clears has_inflight_read as part of finishing, aligning with the new cleanup semantics.
• WindowsBufferedReader.onStreamRead handling for 0-byte reads (previously returning a drained result) is changed to ignore 0-byte reads entirely, with comments explaining the avoidance of a race condition in newer libuv versions.
• In the 0-byte-read path, the function no longer immediately returns a drained result; it returns early, effectively skipping the callback for 0-byte reads.

Alterations to the declarations of exported or public entities

• None

Estimated code review effort: High
"""

---

src/bun.js/webcore/FileSink.zig:
"""

AI-generated summary of changes

• Removes the unconditional force_sync assignment prior to the Windows/Unix split.
• On non-Windows (Unix-like), reintroduces force_sync assignment inside the comptime !Environment.isWindows branch.
• On Windows, adds logic to conditionally set blocking mode for underlying uv streams when a writer.source exists (pipe or tty) and, if blocking setup succeeds, returns early; otherwise falls back to enabling force_sync as a final step.
• Adds a Windows-specific fallback path that ensures force_sync is set when the blocking configuration is not applied successfully.
• Overall control flow now defers force_sync enabling to branch-specific code paths rather than a single pre-branch assignment, and introduces additional platform-specific handling for process object stdio scenarios.

Alterations to the declarations of exported or public entities

Estimated code review effort: High
"""

---

test/js/bun/spawn/spawn-stdin-readable-stream.test.ts:
"""

AI-generated summary of changes

• In the "ReadableStream with very large chunked data" test case:

  • Introduces a pre-created chunk buffer (chunk) and enqueues this buffer instead of repeatedly enqueuing a string of repeated "x" characters.
  • Updates the spawned Bun process command to run a multi-line script that counts the number of data bytes received on stdin and logs the total length on beforeExit, instead of a simple process.stdin.pipe(process.stdout) invocation.
  • Updates the final content assertion to compare against the chunk buffer converted to string, repeated numChunks times, instead of the previous "x".repeat(chunkSize * numChunks).

• No changes to exported/public entity declarations.

Estimated code review effort: Medium
"""

---

test/regression/issue/11297/11297.fixture.ts:
"""

AI-generated summary of changes

The Bun.spawn cmd now uses a multi-line inline script for -e that:

• Replaces the previous single-line "process.stdin.pipe(process.stdout)" with a script that counts input data length from stdin.
• On each data event, accumulates length.
• Registers a beforeExit handler to log the accumulated length to stderr.
• Still ends with piping stdin to stdout.

No changes to stdio or exit behavior aside from the additional logging of input length prior to exit.

Alterations to the declarations of exported or public entities

• None

Estimated code review effort: Medium
"""
#23344 - fix(windows): handle UV_ENOTCONN gracefully when spawning with long cwd [merged] | src/bun.js/api/bun/subprocess.zig:
"""

AI-generated summary of changes

• Replaced assert-based error handling for starting stdio streams with explicit asErr() checks. If start(subprocess, loop) or start(subprocess.killSignal) returns an error, the code now kills the subprocess, converts the error to a JS error, and returns JSError, instead of asserting. This affects stdin.buffer.start, stdout.pipe.start, and stderr.pipe.start paths.
• Maintains existing subsequent logic for reading from pipes (readAll) only when appropriate (unchanged conditional flow), but branches into explicit error handling rather than assertion failure.

Alterations to the declarations of exported or public entities

• No changes to signatures of exported/public entities detected.

Estimated code review effort: Medium
"""

---

test/regression/issue/23316-long-path-spawn.test.ts:
"""

AI-generated summary of changes

Adds a new Windows-focused regression test file test/regression/issue/23316-long-path-spawn.test.ts containing two tests that verify Bun spawn behavior with long or 8.3-disabled Windows paths. Both tests are guarded by a Windows check and construct deeply nested directories to exceed or approach MAX_PATH, then attempt to spawn or copy with a working directory set to the deep path. The tests assert that operations either succeed without panicking or fail with a non-panic, Error instance. The first test builds a path exceeding 260 characters, spawns a process with that cwd, and ensures the outcome is either a successful spawn or a non-panicking error path. The second test creates a deep path, writes a test.js file there, and spawns a process using that path, asserting that errors are non-panic and are Error instances as appropriate. Both tests use Bun.write to create auxiliary files and Bun.spawn to run commands, with stdout/stderr handling specified.

Alterations to the declarations of exported or public entities

• No exported/public declarations changed
  """

---

src/bun.js/webcore/Blob.zig:
"""

AI-generated summary of changes

• In writeFileWithSourceDestination Windows path, wrap the WriteFileWindows.create call with a catch block to swallow WriteFileWindowsDeinitialized error, preventing propagation.

Alterations to the declarations of exported or public entities

Estimated code review effort: Medium
"""

---

src/bun.js/webcore/blob/write_file.zig:
"""

AI-generated summary of changes

• Introduces a new public error type WriteFileWindowsError = error{WriteFileWindowsDeinitialized}.
• Change of public API surface: createWithCtx in WriteFileWindows now returns WriteFileWindowsError!*WriteFileWindows instead of *WriteFileWindows.
• Change of public API surface: open method on WriteFileWindows now returns WriteFileWindowsError!void instead of void.
• Change of public API surface: doWriteLoop now returns WriteFileWindowsError!void instead of void.
• Change of public API surface: onFinish now returns WriteFileWindowsError instead of void.
• Change of public API surface: runFromJSThread now returns WriteFileWindowsError instead of void.
• Change of public API surface: throw now returns WriteFileWindowsError instead of void.
• Several call sites updated to propagate the new error type (e.g., using try, return this.throw(...), and catch blocks for error.WriteFileWindowsDeinitialized).
• Control flow updated to swallow error.WriteFileWindowsDeinitialized in multiple branches via catch blocks, and to return the new error type from several functions.
• Initialization path adjusted in createWithCtx/open/loop flows to use try/catch with the new WriteFileWindowsError handling, including in mkdirp and open-related paths.
• toSystemError and other utility logic updated to align with the new error propagation, including path/fd handling via a switch over pathlike.
• Minor adjustments to ensure deinitialization paths are guarded by the new error type and that finishing paths return the appropriate error-aware results.

Alterations to the declarations of exported or public entities

• Added public error set: WriteFileWindowsError = error{WriteFileWindowsDeinitialized} inside the WriteFileWindows scope.
• Signature changed: pub fn createWithCtx(...) !*WriteFileWindows in the WriteFileWindows struct (formerly *WriteFileWindows).
• Signature changed: pub fn open(this: *WriteFileWindows) WriteFileWindowsError!void (formerly void).
• Signature changed: pub fn doWriteLoop(this: *WriteFileWindows, uv_loop: *uv.Loop) WriteFileWindowsError!void (formerly void).
• Signature changed: pub fn onFinish(container: *WriteFileWindows) WriteFileWindowsError (formerly void).
• Signature changed: pub fn runFromJSThread(this: *WriteFileWindows) WriteFileWindowsError (formerly void).
• Signature changed: pub fn throw(this: *WriteFileWindows, err: bun.sys.Error) WriteFileWindowsError (formerly void).
• Signature changed: pub fn create(...) WriteFileWindowsError!*WriteFileWindows (previously )!*WriteFileWindows).
• Signature changed: pub fn createWithCtx(...) in the top of WriteFileWindows now returns WriteFileWindowsError!*WriteFileWindows (as above).
• Signature changes propagate: various internal calls now return or throw WriteFileWindowsError and callers handle with try/catch blocks.
• Added error-handling propagation in multiple internal helpers (e.g., onOpen, onWriteComplete) to convert and propagate errors using the new WriteFileWindowsError.

Estimated code review effort: High
"""
#23533 - Add BUN_WATCHER_TRACE environment variable for debugging file watcher events [merged] | src/Watcher.zig:
"""

AI-generated summary of changes

• Adds watcher tracing lifecycle: initializes WatcherTrace during init, and deinitializes on watcher thread exit.
• Introduces public API writeTraceEvents(this, events, changed_files) to forward events to WatcherTrace.
• Ensures trace file is closed on thread termination by deinitializing WatcherTrace in threadMain and on watcher exit.
• Adds internal import of WatcherTrace and references to create, use, and clean up the trace file lifecycle in multiple points (init, threadMain, and end-of-thread).

Alterations to the declarations of exported or public entities

• Method added: pub fn writeTraceEvents(this: *Watcher, events: []WatchEvent, changed_files: []?[:0]u8) void in src/Watcher.zig

Estimated code review effort: Medium

"""

---

src/watcher/INotifyWatcher.zig:
"""

AI-generated summary of changes

• Adds a new call to writeTraceEvents inside processINotifyEventBatch, executed when the watcher is running. The call uses the same event slice as onFileUpdate (all_events[0 .. last_event_index + 1]) and the corresponding changed_filepaths slice (0..name_off). This occurs before the existing onFileUpdate call, increasing tracing coverage for batched events without altering control flow otherwise.

Alterations to the declarations of exported or public entities

• none

Estimated code review effort: Medium
"""

---

src/watcher/KEventWatcher.zig:
"""

AI-generated summary of changes

Adds a call to this.writeTraceEvents(watchevents, this.changed_filepaths[0..watchevents.len]) inside the synchronized block of watchLoopCycle when this.running is true, preceding the existing onFileUpdate call. No other logic, error handling, or control flow changes are introduced.

Alterations to the declarations of exported or public entities

none

Estimated code review effort: Medium
"""

---

src/watcher/WatcherTrace.zig:
"""

AI-generated summary of changes

• Adds a WatcherTrace.zig module that provides a trace file for watcher events, controlled by the BUN_WATCHER_TRACE environment variable. On first init, if a non-empty path is provided, opens the file for write/append and stores the file handle; ignores open errors. writeEvents writes a JSON structure with a timestamp and a per-file mapping of observed events, mapping events to watcher file paths via the watchlist and event indices, including an optional changed array when available. Deinit closes and clears the trace file handle. Public APIs: init, writeEvents, deinit. Declares external dependencies on Watcher, bun, and std.

• Control flow:

  • init: idempotent; checks BUN_WATCHER_TRACE; if path provided and non-empty, attempts to open with WRONLY|CREAT|APPEND and mode 0644; stores handle on success; otherwise ignores errors.
  • writeEvents: no-op if trace not enabled; otherwise buffers and writes a JSON object with timestamp and files mapping, iterating events to map to file paths using the watchlist; records per-file events array with possible changed filenames; handles IO errors by returning early.
  • deinit: closes and clears trace_file if open.

• Public API surface:

  • pub fn init() void
  • pub fn writeEvents(watcher: *Watcher, events: []Watcher.WatchEvent, changed_files: []?[:0]u8) void
  • pub fn deinit() void

• Adds module imports: Watcher, bun, std.

Alterations to the declarations of exported or public entities

• Public function added: pub fn init() void in src/watcher/WatcherTrace.zig
• Public function added: pub fn writeEvents(watcher: *Watcher, events: []Watcher.WatchEvent, changed_files: []?[:0]u8) void in src/watcher/WatcherTrace.zig
• Public function added: pub fn deinit() void in src/watcher/WatcherTrace.zig
  """

---

src/watcher/WindowsWatcher.zig:
"""

AI-generated summary of changes

In WindowsWatcher.zig, processWatchEventBatch now invokes this.writeTraceEvents(all_events, this.changed_filepaths[0 .. last_event_index + 1]); immediately before calling onFileUpdate, adding a new side-effect trace event emission for the batched events. No changes to the surrounding control flow other than the added call.

Alterations to the declarations of exported or public entities

No changes to exported/public entity declarations detected.

Estimated code review effort: Medium
"""

---

test/cli/watch/watcher-trace.test.ts:
"""

AI-generated summary of changes

Adds a new test file test/cli/watch/watcher-trace.test.ts that validates the BUN_WATCHER_TRACE feature by launching Bun in watch mode and mutating source files to produce and verify trace data. The tests cover:

• Creation of trace files on initial and subsequent reloads with --watch.
• Trace generation when BUN_WATCHER_TRACE is set to a path.
• No trace creation when BUN_WATCHER_TRACE is an empty string.
• Appending trace data across multiple reloads and validating JSON-structured events with required fields (timestamp, files) and per-file event data (events array, optional changed).
• Verification of trace content: file existence, proper JSON parsing, and structure validation for each event line.
• Use of environment variable BUN_WATCHER_TRACE, Bun.spawn for process orchestration, and source mutations via file writes to trigger reloads.

Alterations to the declarations of exported or public entities

No exported/public declarations modified.
"""
#23566 - fix(watcher): handle vim atomic save race on macOS [merged] | src/CLAUDE.md:
"""

AI-generated summary of changes

Two convention lines were replaced with explanatory variants:

• The bottom-placement guidance remains, but now notes that the auto formatter will move @import lines, so manual worry is unnecessary.
• The recommended import changes from @import("bun") to specifically prefer @import("bun"), and explicitly disallows using @import("root").bun or relative paths like @import("../bun.zig").

No functional or control-flow changes; only documentation wording was updated.

Alterations to the declarations of exported or public entities

• None

Estimated code review effort: Medium
"""

---

src/Watcher.zig:
"""

AI-generated summary of changes

• Adds public function addFileDescriptorToKQueueWithoutChecks(this: *Watcher, fd: bun.FileDescriptor, watchlist_id: usize) void to register a macOS kqueue vnode event with EVADD/CLEAR/ENABLE, VNODE filter, and fflags for WRITE/RENAME/DELETE; stores watchlist_id in udata and issues kevent without propagating errors.
• Replaces inline macOS kevent registration previously in appendFileAssumeCapacity with a call to addFileDescriptorToKQueueWithoutChecks(fd, watchlist_id) to consolidate platform-specific kqueue registration.
• Adds public function addFileByPathSlow(
  this: *Watcher,
  file_path: string,
  loader: options.Loader,
  +) bool to lazily watch a path by resolving a file descriptor on macOS or path-based watching on Linux, delegating to addFile; includes hash computation, initial autowatch logic, and error handling for open/append flow.
• Exposes the new public methods in the Watcher API surface by declaring their signatures and ensuring observable behavior paths (macOS kqueue registration and slow-path path watching).

Alterations to the declarations of exported or public entities

• Added: pub fn addFileDescriptorToKQueueWithoutChecks(this: *Watcher, fd: bun.FileDescriptor, watchlist_id: usize) void in src/Watcher.zig
• Added: pub fn addFileByPathSlow(
  this: *Watcher,
  file_path: string,
  loader: options.Loader,
  +) bool in src/Watcher.zig
  """

---

src/bun.js.zig:
"""

AI-generated summary of changes

• Replaces hot module reloading calls to pass the entry path: HotReloader.enableHotModuleReloading(vm) → HotReloader.enableHotModuleReloading(vm, entry_path), and WatchReloader.enableHotModuleReloading(vm) → WatchReloader.enableHotModuleReloading(vm, entry_path).

• When a hot-reload promise is handled and assigned, the code now invokes addMainToWatcherIfNeeded() on the VM before advancing the event loop.

• Replaces direct handling of pending internal promise rejections with reportExceptionInHotReloadedModuleIfNeeded() in three places during watcher-related post-promise handling and exit paths.

• Method signature updates:

  • jsc.hot_reloader.HotReloader.enableHotModuleReloading(vm, entry_path)
  • jsc.hot_reloader.WatchReloader.enableHotModuleReloading(vm, entry_path)

Estimated code review effort: Medium
"""

---

src/bun.js/VirtualMachine.zig:
"""

AI-generated summary of changes

• Renamed public function handlePendingInternalPromiseRejection(this: *jsc.VirtualMachine) void to reportExceptionInHotReloadedModuleIfNeeded(this: *jsc.VirtualMachine) void. The new function preserves prior behavior for pending internal promise rejection handling but adds an early watcher interaction when no promise is present and invokes an additional watcher-related call after processing.
• Added public function addMainToWatcherIfNeeded(this: *jsc.VirtualMachine) void. This helper watches the main file when the watcher is enabled by calling bun_watcher.addFileByPathSlow with the main path and loader extension.
• Updated reportExceptionInHotReloadedModuleIfNeeded to call addMainToWatcherIfNeeded() both when there is no pending promise and after processing a resolved/rejected promise, ensuring the main file is watched in hot-reload scenarios.

Alterations to the declarations of exported or public entities

• Method updated: pub fn handlePendingInternalPromiseRejection(this: *jsc.VirtualMachine) void in file src/bun.js/VirtualMachine.zig → renamed to
  pub fn reportExceptionInHotReloadedModuleIfNeeded(this: *jsc.VirtualMachine) void
• Method added: pub fn addMainToWatcherIfNeeded(this: *jsc.VirtualMachine) void in file src/bun.js/VirtualMachine.zig

Estimated code review effort: Medium
"""

---

src/bun.js/hot_reloader.zig:
"""

AI-generated summary of changes

• Added ImportWatcher.addFileByPathSlow(file_path, loader) to delegate to the underlying watcher (hot/watch) or return true for others.
• Introduced a new public field main in the reloader struct and defined a new MainFile struct to track an entrypoint file, its directory, and a dir-change awaiting flag.
• Added MainFile.init(file) initializer to compute and store file, directory, hashes, and initial waiting state.
• Extended NewHotReloader to initialize and carry a MainFile instance via .main, and initialize main with MainFile.init(entry_path orelse "") when enabling hot reloading.
• Changed enableHotModuleReloading to accept an optional entry_path parameter (entry_path: ?[]const u8) and updated its initialization to set .main accordingly.
• Adjusted hot-reload event handling on macOS to defer reloads when an atomic save race could occur, using is_waiting_for_dir_change and dir_change handling to trigger reloads only after the directory write confirms the new file exists.
• Added macOS-specific checks in event handling to delay and then resume reloads based on the entrypoint’s state and current file hash.
• Updated loader lookup for changed files from Fs.PathName.init(changed_name).ext to Fs.PathName.findExtname(changed_name) and preserved existing fallback behavior.
• Enhanced debug logs to include event information (e.g., "File changed: … ({})") and to log removals of replaced files when applicable.
• Augmented directory-change handling to trigger reloads when the entrypoint reappears after an atomic save (presence check via bun.sys.faccessat) and to enqueue the corresponding hash for reload.
• Extended directory-change messaging to include affected counts and event context in logs (Dir change: … (affecting N, …)).

Alterations to the declarations of exported or public entities

• Added public method: pub inline fn addFileByPathSlow(this: ImportWatcher, file_path: string, loader: options.Loader) bool in src/bun.js/hot_reloader.zig → signature unchanged for call sites but new public API on ImportWatcher.
• Added public field: main: MainFile = .{} in the reloader struct within NewHotReloader (both in old and new spots visible in the diff).
• Introduced public struct: MainFile with fields and an initializer:
  • dir: []const u8 = ""
  • dir_hash: Watcher.HashType = 0
  • file: []const u8 = ""
  • hash: Watcher.HashType = 0
  • is_waiting_for_dir_change: bool = false
  • pub fn init(file: []const u8) MainFile
• Public initializer for MainFile: MainFile.init(file) logic to derive directory, directory hash, and initial hash.
• Updated function signature: pub fn enableHotModuleReloading(this: *Ctx, entry_path: ?[]const u8) void (instead of previous no-arg variant).
• Updated usage to initialize main: .main = MainFile.init(entry_path orelse "") when constructing the reloader.
• Replaced extname-based loader lookup: Fs.PathName.init(changed_name).ext → Fs.PathName.findExtname(changed_name) in the public code path that resolves loaders for changed files.

Estimated code review effort: High
"""

---

src/bundler/bundle_v2.zig:
"""

AI-generated summary of changes

• Replaces a call to enableHotModuleReloading with an additional argument: Watcher.enableHotModuleReloading(this) is changed to Watcher.enableHotModuleReloading(this, null). The surrounding control flow remains the same; the only observable change is the extra parameter passed to the function.

Alterations to the declarations of exported or public entities

• none

Estimated code review effort: Medium
"""

---

src/cli/test_command.zig:
"""

AI-generated summary of changes

In src/cli/test_command.zig, both hot and watch cases now call enableHotModuleReloading with an additional null argument (vm, null) instead of the previous single-argument form (vm). The switch structure and overall control flow remain the same; only the arity of the enableHotModuleReloading calls changes.

Estimated code review effort: Medium
"""

---

src/fs.zig:
"""

AI-generated summary of changes

• Added a new public function to PathName:
  • PathName.findExtname(_path: string) string
  • Logic: determine the base portion after the last path separator; locate the last '.' in that base; if found and not the first character, return substring from the dot to end; otherwise return "".
• No changes to existing methods or control flow; ext handling for other code paths remains unchanged.

• Public function added: pub fn findExtname(_path: string) string in struct PathName in file src/fs.zig

Estimated code review effort: Medium
"""

---

src/sys.zig:
"""

AI-generated summary of changes

In faccessat, the non-sentinel path branch now uses std.posix.toPosixPath(subpath) to obtain the path and passes the address of that path (&path) to the recursive faccessat call, instead of passing the path by value with std.os.toPosixPath(subpath). The error path remains NAMETOOLONG(.access). The surrounding control flow for the Linux/Windows/macOS branches remains unchanged.

NONE

Estimated code review effort: Medium
"""

👤 Suggested Assignees

• robobun
• Jarred-Sumner
• vamsaya

---

🧪 Issue enrichment is currently in early access.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

[github-actions]

Found 3 possible duplicate issues:

1. Spawned processes become zombies when using --watch #9871
2. Unexpected reading file error when working with Bun.build + --hot #11123
3. --hot/--watch causes fs.watch to drop filechange events #4854

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code