robobun 755b41e85b Add BUN_WATCHER_TRACE environment variable for debugging file watcher events (#23533) ...

## 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>

2025-10-12 11:29:48 -07:00

..

watch.test.ts

safety: a lot more exception checker progress (#20956)

2025-07-16 00:11:19 -07:00

watcher-trace.test.ts

Add BUN_WATCHER_TRACE environment variable for debugging file watcher events (#23533)

2025-10-12 11:29:48 -07:00