## Summary
Adds `BUN_WATCHER_TRACE` environment variable that logs all file watcher
events to a JSON file for debugging. When set, the watcher appends
detailed event information to the specified file path.
## Motivation
Debugging watch-related issues (especially with `bun --watch` and `bun
--hot`) can be difficult without visibility into what the watcher is
actually seeing. This feature provides detailed trace logs showing
exactly which files are being watched and what events are triggered.
## Implementation
- **Isolated module** (`src/watcher/WatcherTrace.zig`) - All trace logic
in separate file
- **No locking needed** - Watcher runs on its own thread, no mutex
required
- **Append-only mode** - Traces persist across multiple runs for easier
debugging
- **Silent errors** - Won't break functionality if trace file can't be
created
- **JSON format** - Easy to parse and analyze
## Usage
```bash
BUN_WATCHER_TRACE=/tmp/watch.log bun --watch script.js
BUN_WATCHER_TRACE=/tmp/hot.log bun --hot server.ts
```
## JSON Output Format
Each line is a JSON object with:
```json
{
"timestamp": 1760280923269,
"index": 0,
"path": "/path/to/watched/file.js",
"delete": false,
"write": true,
"rename": false,
"metadata": false,
"move_to": false,
"changed_files": ["script.js"]
}
```
## Testing
All tests use stdout streaming to wait for actual reloads (no
sleeps/timeouts):
- Tests with `--watch` flag
- Tests with `fs.watch` API
- Tests that trace file appends across multiple runs
- Tests validation of JSON format and event details
```
✅ 4 pass
❌ 0 fail
📊 52 expect() calls
```
## Files Changed
- `src/Watcher.zig` - Minimal integration with WatcherTrace module
- `src/watcher/WatcherTrace.zig` - New isolated trace implementation
- `src/watcher/KEventWatcher.zig` - Calls writeTraceEvents before
onFileUpdate
- `src/watcher/INotifyWatcher.zig` - Calls writeTraceEvents before
onFileUpdate
- `src/watcher/WindowsWatcher.zig` - Calls writeTraceEvents before
onFileUpdate
- `test/cli/watch/watcher-trace.test.ts` - Comprehensive tests
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
### What does this PR do?
Fixes `bun -p "process.stderr.write('Hello' +
String.fromCharCode(0xd800))"`.
Also fixes potential index out of bounds if there are many invalid
sequences.
This also affects `TextEncoder`.
### How did you verify your code works?
Added tests for edgecases
---------
Co-authored-by: Jarred Sumner <jarred@jarredsumner.com>
## Summary
Fixes a crash in the Windows file watcher that occurred when the number
of file system events exceeded the fixed `watch_events` buffer size
(128).
## Problem
The crash manifested as:
```
index out of bounds: index 128, len 128
```
This happened when:
1. More than 128 file system events were generated in a single watch
cycle
2. The code tried to access `this.watch_events[128]` on an array of
length 128 (valid indices: 0-127)
3. Later, `std.sort.pdq()` would operate on an invalid array slice
## Solution
Implemented a hybrid approach that preserves the original behavior while
handling overflow gracefully:
- **Fixed array for common case**: Uses the existing 128-element array
when possible for optimal performance
- **Dynamic allocation for overflow**: Switches to `ArrayList` only when
needed
- **Single-batch processing**: All events are still processed together
in one batch, preserving event coalescing
- **Graceful fallback**: Handles allocation failures with appropriate
fallbacks
## Benefits
- ✅ **Fixes the crash** while maintaining existing performance
characteristics
- ✅ **Preserves event coalescing** - events for the same file still get
properly merged
- ✅ **Single consolidated callback** instead of multiple partial updates
- ✅ **Memory efficient** - no overhead for normal cases (≤128 events)
- ✅ **Backward compatible** - no API changes
## Test Plan
- [x] Compiles successfully with `bun run zig:check-windows`
- [x] Preserves existing behavior for common case (≤128 events)
- [x] Handles overflow case gracefully with dynamic allocation
🤖 Generated with [Claude Code](https://claude.ai/code)
---------
Co-authored-by: Claude Bot <claude-bot@bun.sh>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Jarred Sumner <jarred@bun.sh>
Co-authored-by: Jarred Sumner <jarred@jarredsumner.com>
