vendor tsgo

tools/tsgo/internal/fswatch/README.md

@@ -0,0 +1,98 @@
+# fswatch
+
+A filesystem watcher for Go. Pure Go, no cgo.
+
+A Go port of the C++
+[`@parcel/watcher`](https://github.com/parcel-bundler/watcher), with substantial
+modifications. See [`CHANGES.md`](CHANGES.md) for the list of differences and
+bugfixes.
+
+| GOOS                                        | Watcher                                    |
+| ------------------------------------------- | ------------------------------------------ |
+| `linux`                                     | fanotify (default, kernel ≥ 5.13), inotify |
+| `darwin`                                    | FSEvents (default), kqueue                 |
+| `windows`                                   | `ReadDirectoryChangesW`                    |
+| `freebsd`, `openbsd`, `netbsd`, `dragonfly` | kqueue                                     |
+
+## Usage
+
+```go
+package main
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"os/signal"
+
+	"github.com/microsoft/typescript-go/internal/fswatch"
+)
+
+func main() {
+	dir, _ := os.Getwd()
+
+	sub, err := fswatch.Default().WatchDirectory(dir, func(events []fswatch.Event, err error) {
+		if err != nil {
+			log.Println("watch error:", err)
+			return
+		}
+		for _, e := range events {
+			fmt.Printf("%s %s\n", e.Kind, e.Path)
+		}
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer sub.Close()
+
+	c := make(chan os.Signal, 1)
+	signal.Notify(c, os.Interrupt)
+	<-c
+}
+```
+
+### Picking a watcher
+
+`Default()` picks the best watcher for the current OS. To use a specific one:
+
+```go
+sub, err := fswatch.Inotify().WatchDirectory(dir, callback, fswatch.WithRecursive())
+```
+
+All watchers exist on every platform. Use `Available()` to check support at
+runtime, or just call `WatchDirectory`; it returns `ErrUnavailable` if the
+watcher isn't supported.
+
+### Error handling
+
+Errors are delivered through the callback. Use `errors.Is` to distinguish them:
+
+- **`ErrOverflow`**: some events were lost (kernel queue overflow). The watch is
+  still active; rescan the directory to catch up.
+- **`ErrWatchTerminated`**: the watch is dead (e.g. directory deleted). No
+  further events will arrive. Call `Close` to clean up.
+
+```go
+if errors.Is(err, fswatch.ErrOverflow) {
+    rescanDir(dir)
+    return
+}
+if errors.Is(err, fswatch.ErrWatchTerminated) {
+    log.Println("watch terminated:", err)
+    sub.Close()
+    return
+}
+```
+
+### Behavior notes
+
+- Events arriving in quick succession are **batched** before delivery.
+- Event order within a batch is **not guaranteed**.
+- The callback runs on a library goroutine, not the caller's. Each watch's
+  callback is serialized (never concurrent with itself).
+- Paths in events are absolute. **Resolve symlinks before subscribing**;
+  backends report canonical paths:
+
+  ```go
+  realDir, err := filepath.EvalSymlinks(dir)
+  ```