Add fsnotify on configuration files through Options struct Watch bool

[andreimerlescu]

Developer Experience

figs := figtree.With(figtree.Options{
    ConfigFile: "config.yaml",
    Watch:      true,
    Tracking:   true,
})
if err := figs.Load(); err != nil {
    log.Fatal(err)
}

// Everything below already existed — no new API needed
for mutation := range figs.Mutations() {
    log.Printf("%s changed: %v → %v", mutation.Property, mutation.Old, mutation.New)
}

Watcher watcher.go

// watcher.go
package figtree

import (
	"fmt"
	"log"
	"path/filepath"
	"sync"
	"time"

	"github.com/fsnotify/fsnotify"
)

// ============================================================================
// OPTIONS ADDITIONS
// ============================================================================

// These fields are added to the existing Options struct.
// Shown here isolated for clarity — merge into your existing Options{}.
//
//   type Options struct {
//       // ... existing fields ...
//       Watch         bool          // enable fsnotify file watching
//       WatchDebounce time.Duration // how long to wait before reloading after a change (default 100ms)
//       OnWatchError  func(err error) // optional hook for watch errors; defaults to log.Println
//   }

const defaultWatchDebounce = 100 * time.Millisecond

// ============================================================================
// WATCHER STATE — lives inside the tree struct
// ============================================================================

// watcherState is embedded in the tree struct.
// Add `watcher watcherState` to your existing tree struct definition.
type watcherState struct {
	mu          sync.Mutex
	fsw         *fsnotify.Watcher
	watchedPath string   // absolute path of the file being watched
	active      bool
	stopCh      chan struct{}
}

// ============================================================================
// INTERNAL: called at the end of any successful Load/Parse that resolved a file
// ============================================================================

// activateWatch is called internally after any successful file-based load.
// path is the resolved absolute path of the config file that was loaded.
// It is a no-op if Options.Watch is false or if already watching.
func (t *tree) activateWatch(path string) {
	if !t.options.Watch {
		return
	}

	absPath, err := filepath.Abs(path)
	if err != nil {
		t.handleWatchError(fmt.Errorf("figtree watcher: could not resolve absolute path for %q: %w", path, err))
		return
	}

	t.watcher.mu.Lock()
	defer t.watcher.mu.Unlock()

	// Already watching this exact file — nothing to do
	if t.watcher.active && t.watcher.watchedPath == absPath {
		return
	}

	// Clean up any prior watcher
	t.teardownWatchLocked()

	fsw, err := fsnotify.NewWatcher()
	if err != nil {
		t.handleWatchError(fmt.Errorf("figtree watcher: failed to create fsnotify watcher: %w", err))
		return
	}

	if err := fsw.Add(absPath); err != nil {
		_ = fsw.Close()
		t.handleWatchError(fmt.Errorf("figtree watcher: failed to watch %q: %w", absPath, err))
		return
	}

	stopCh := make(chan struct{})
	t.watcher.fsw         = fsw
	t.watcher.watchedPath = absPath
	t.watcher.active      = true
	t.watcher.stopCh      = stopCh

	go t.watchLoop(fsw, absPath, stopCh)
}

// ============================================================================
// WATCH LOOP — goroutine that processes fsnotify events
// ============================================================================

func (t *tree) watchLoop(fsw *fsnotify.Watcher, path string, stopCh <-chan struct{}) {
	debounce := t.options.WatchDebounce
	if debounce <= 0 {
		debounce = defaultWatchDebounce
	}

	var (
		debounceTimer *time.Timer
		timerMu       sync.Mutex
	)

	scheduleReload := func() {
		timerMu.Lock()
		defer timerMu.Unlock()
		if debounceTimer != nil {
			debounceTimer.Reset(debounce)
			return
		}
		debounceTimer = time.AfterFunc(debounce, func() {
			timerMu.Lock()
			debounceTimer = nil
			timerMu.Unlock()
			t.reloadFromWatch(path)
		})
	}

	for {
		select {
		case <-stopCh:
			timerMu.Lock()
			if debounceTimer != nil {
				debounceTimer.Stop()
				debounceTimer = nil
			}
			timerMu.Unlock()
			return

		case event, ok := <-fsw.Events:
			if !ok {
				return
			}
			// React to writes and renames (rename covers atomic-write editors)
			if event.Has(fsnotify.Write) || event.Has(fsnotify.Rename) {
				scheduleReload()
			}
			// If the file was removed entirely, surface an error but keep watching
			if event.Has(fsnotify.Remove) {
				t.handleWatchError(fmt.Errorf("figtree watcher: watched file %q was removed", path))
			}

		case err, ok := <-fsw.Errors:
			if !ok {
				return
			}
			t.handleWatchError(fmt.Errorf("figtree watcher: fsnotify error on %q: %w", path, err))
		}
	}
}

// ============================================================================
// RELOAD — re-parses the file and feeds diffs into the mutation pipeline
// ============================================================================

// reloadFromWatch re-parses the watched config file.
// It compares new values against current values and calls Store() for any
// that changed — which naturally triggers validators, callbacks, rules,
// and the Mutations() channel exactly as a programmatic Store() would.
func (t *tree) reloadFromWatch(path string) {
	// Load the raw key-value map from the file without touching the live tree
	incoming, err := t.parseFileToMap(path)
	if err != nil {
		t.handleWatchError(fmt.Errorf("figtree watcher: reload parse error on %q: %w", path, err))
		return
	}

	for key, newRawValue := range incoming {
		fig := t.Fig(key)
		if fig == nil {
			// Key in file not registered in tree — skip silently
			// (same behaviour as initial Load)
			continue
		}

		// Convert and store — Store() handles rules, validators, callbacks,
		// and emits to Mutations() if tracking is enabled.
		// A RulePreventChange or RulePanicOnChange will reject it here
		// exactly as it would reject a manual Store() call.
		storeErr := t.storeFromRaw(fig.Mutagenesis, key, newRawValue)
		if storeErr != nil {
			t.handleWatchError(fmt.Errorf(
				"figtree watcher: could not apply reloaded value for key %q: %w",
				key, storeErr,
			))
		}
	}
}

// parseFileToMap re-parses the file at path and returns a flat
// map[string]string of raw string values, routing to the correct
// parser based on file extension. This is the same routing table
// used by LoadFile/ParseFile but returns raw values rather than
// immediately storing them.
func (t *tree) parseFileToMap(path string) (map[string]interface{}, error) {
	ext := strings.ToLower(filepath.Ext(path))

	f, err := os.Open(path)
	if err != nil {
		return nil, fmt.Errorf("could not open %q: %w", path, err)
	}
	defer f.Close()

	// Route to the parser table you build per the format discussion
	parser, ok := t.parserFor(ext)
	if !ok {
		return nil, fmt.Errorf("no parser registered for extension %q", ext)
	}

	return parser(f)
}

// ============================================================================
// TEARDOWN
// ============================================================================

// StopWatch gracefully shuts down the file watcher.
// Safe to call multiple times. Exported so the caller can shut down
// cleanly on SIGINT/SIGTERM alongside context cancellation.
func (t *tree) StopWatch() {
	t.watcher.mu.Lock()
	defer t.watcher.mu.Unlock()
	t.teardownWatchLocked()
}

// teardownWatchLocked stops the watch goroutine and closes fsnotify.
// Caller must hold t.watcher.mu.
func (t *tree) teardownWatchLocked() {
	if !t.watcher.active {
		return
	}
	close(t.watcher.stopCh)
	_ = t.watcher.fsw.Close()
	t.watcher.active      = false
	t.watcher.watchedPath = ""
	t.watcher.fsw         = nil
	t.watcher.stopCh      = nil
}

// ============================================================================
// ERROR HANDLER
// ============================================================================

// handleWatchError routes watch errors to the user-supplied OnWatchError
// hook if set, otherwise falls back to log.Println.
func (t *tree) handleWatchError(err error) {
	if t.options.OnWatchError != nil {
		t.options.OnWatchError(err)
		return
	}
	log.Println(err)
}

Modify loading.go

// In loading.go — end of Load()
func (t *tree) Load() error {
    // ... existing logic that resolves t.resolvedConfigPath ...
    if err := t.loadFromFile(t.resolvedConfigPath); err != nil {
        return err
    }
    t.activateWatch(t.resolvedConfigPath) // ADD THIS
    return nil
}

// In loading.go — end of LoadFile()
func (t *tree) LoadFile(path string) error {
    if err := t.loadFromFile(path); err != nil {
        return err
    }
    t.activateWatch(path) // ADD THIS
    return nil
}

// In parsing.go — end of ParseFile()
func (t *tree) ParseFile(path string) error {
    if err := t.parseFromFile(path); err != nil {
        return err
    }
    t.activateWatch(path) // ADD THIS
    return nil
}

// Parse() with no file is a no-op for the watcher — flags and env
// have no filesystem path to watch.

Modify Fruit Interface

// Add to the Fruit interface in types.go
type Fruit interface {
    // ... existing methods ...
    StopWatch()
}

Dependency

Update go.mod with:

require (
    github.com/fsnotify/fsnotify v1.7.0
)

Update vars.go

// vars.go — additions only, merge into existing file

const (
    // ... existing consts unchanged ...

    defaultWatchDebounce = 100 * time.Millisecond
)

// WatchDebounce is the default delay between a filesystem event and a reload.
// Override before calling Load/LoadFile/ParseFile if your editor needs longer.
var WatchDebounce = defaultWatchDebounce

Update types.go

type Loadable interface {
    Load() error
    LoadFile(path string) error
    Reload() error
    StopWatch() // ADDED — graceful shutdown of the fsnotify watcher
}



// watcherState holds all fsnotify lifecycle state for the figTree.
// It is embedded by value in figTree so zero value is safe — active=false
// means the watcher is dormant and no goroutine is running.
type watcherState struct {
    mu          sync.Mutex
    fsw         *fsnotify.Watcher // nil when inactive
    watchedPath string            // absolute path currently watched
    active      bool
    stopCh      chan struct{}      // closed to signal watchLoop to exit
}

// Options allow you enable mutation tracking on your figs.Grow
type Options struct {
    ConfigFile string

    // Tracking creates a buffered channel that allows you to select { case mutation, ok := <-figs.Mutations(): }
    Tracking bool

    // Germinate enables the option to filter os.Args that begin with -test. prefix
    Germinate bool

    // Harvest allows you to set the buffer size of the Mutations channel
    Harvest int

    // Pollinate will enable Getters to lookup the environment for changes on every read
    Pollinate bool

    // IgnoreEnvironment is a part of free will, it lets us disregard our environment (ENV vars)
    IgnoreEnvironment bool

    // Watch enables automatic fsnotify watching of whatever config file was
    // resolved during Load(), LoadFile(), ParseFile(). When a change is
    // detected the file is re-parsed and diffed against live values; any
    // changed key flows through the normal Store() pipeline — validators,
    // callbacks, rules, and the Mutations() channel all fire exactly as they
    // would for a programmatic Store() call.
    Watch bool

    // WatchDebounce is how long to wait after a filesystem event before
    // triggering a reload. Defaults to WatchDebounce (100ms). Increase this
    // if your editor writes config files in multiple flushes (vim, some IDEs).
    WatchDebounce time.Duration

    // OnWatchError is an optional hook called whenever the watcher encounters
    // an error — parse failures, fsnotify errors, rejected Store() calls on
    // reload. If nil, errors are written to log.Println.
    OnWatchError func(err error)
}

// figTree stores figs that are defined by their name and figFruit as well as
// a mutations channel and tracking bool for Options.Tracking
type figTree struct {
    ConfigFilePath string
    GlobalRules    []RuleKind
    harvest        int
    pollinate      bool
    figs           map[string]*figFruit
    values         *sync.Map
    withered       map[string]witheredFig
    aliases        map[string]string
    sourceLocker   sync.RWMutex
    mu             sync.RWMutex
    tracking       bool
    problems       []error
    mutationsCh    chan Mutation
    flagSet        *flag.FlagSet
    filterTests    bool
    angel          *atomic.Bool
    ignoreEnv      bool

    // watcher holds fsnotify state; zero value is safe (inactive)
    watcher      watcherState

    // watchDebounce and onWatchError are copied out of Options at With() time
    watchEnabled  bool
    watchDebounce time.Duration
    onWatchError  func(err error)
}

Update figtree.go

func With(opts Options) Plant {
    angel := atomic.Bool{}
    angel.Store(true)

    debounce := opts.WatchDebounce
    if debounce <= 0 {
        debounce = WatchDebounce
    }

    fig := &figTree{
        ConfigFilePath: opts.ConfigFile,
        ignoreEnv:      opts.IgnoreEnvironment,
        filterTests:    opts.Germinate,
        pollinate:      opts.Pollinate,
        tracking:       opts.Tracking,
        harvest:        opts.Harvest,
        angel:          &angel,
        problems:       make([]error, 0),
        aliases:        make(map[string]string),
        figs:           make(map[string]*figFruit),
        values:         &sync.Map{},
        withered:       make(map[string]witheredFig),
        mu:             sync.RWMutex{},
        mutationsCh:    make(chan Mutation),
        flagSet:        flag.NewFlagSet(os.Args[0], flag.ContinueOnError),

        // watch options
        watchEnabled:  opts.Watch,
        watchDebounce: debounce,
        onWatchError:  opts.OnWatchError,
    }
    fig.flagSet.Usage = fig.Usage
    angel.Store(false)

    if opts.IgnoreEnvironment {
        os.Clearenv()
    }
    return fig
}

Add watcher.go

package figtree

import (
    "fmt"
    "log"
    "os"
    "path/filepath"
    "strings"
    "sync"
    "time"

    "github.com/fsnotify/fsnotify"
)

// ============================================================================
// PUBLIC: StopWatch
// ============================================================================

// StopWatch gracefully shuts down the file watcher. It is safe to call
// multiple times and safe to call when Watch was never activated.
// Call this alongside your context cancellation on SIGINT/SIGTERM:
//
//	case sig := <-sigCh:
//	    figs.StopWatch()
//	    cancel()
func (tree *figTree) StopWatch() {
    tree.watcher.mu.Lock()
    defer tree.watcher.mu.Unlock()
    tree.teardownWatchLocked()
}

// ============================================================================
// INTERNAL: activateWatch
// ============================================================================

// activateWatch is called at the end of any successful file-based load.
// It is a no-op when Options.Watch is false or when the same file is already
// being watched. When a different file was previously watched, the old watcher
// is cleanly torn down before the new one starts.
func (tree *figTree) activateWatch(path string) {
    if !tree.watchEnabled {
        return
    }

    absPath, err := filepath.Abs(path)
    if err != nil {
        tree.handleWatchError(fmt.Errorf(
            "figtree watcher: could not resolve absolute path for %q: %w", path, err,
        ))
        return
    }

    tree.watcher.mu.Lock()
    defer tree.watcher.mu.Unlock()

    // Already watching this exact file — nothing to do
    if tree.watcher.active && tree.watcher.watchedPath == absPath {
        return
    }

    // Tear down any prior watcher cleanly before starting a new one
    tree.teardownWatchLocked()

    fsw, err := fsnotify.NewWatcher()
    if err != nil {
        tree.handleWatchError(fmt.Errorf(
            "figtree watcher: failed to create fsnotify watcher: %w", err,
        ))
        return
    }

    if err := fsw.Add(absPath); err != nil {
        _ = fsw.Close()
        tree.handleWatchError(fmt.Errorf(
            "figtree watcher: failed to add %q to watcher: %w", absPath, err,
        ))
        return
    }

    stopCh := make(chan struct{})
    tree.watcher.fsw         = fsw
    tree.watcher.watchedPath = absPath
    tree.watcher.active      = true
    tree.watcher.stopCh      = stopCh

    go tree.watchLoop(fsw, absPath, stopCh)
}

// ============================================================================
// INTERNAL: watchLoop
// ============================================================================

// watchLoop runs in its own goroutine for the lifetime of the watch.
// It debounces rapid filesystem events — editors like vim and many IDEs
// write files in multiple flushes; without debouncing a single save would
// trigger several redundant reloads.
func (tree *figTree) watchLoop(fsw *fsnotify.Watcher, path string, stopCh <-chan struct{}) {
    debounce := tree.watchDebounce
    if debounce <= 0 {
        debounce = WatchDebounce
    }

    var (
        timerMu       sync.Mutex
        debounceTimer *time.Timer
    )

    scheduleReload := func() {
        timerMu.Lock()
        defer timerMu.Unlock()
        if debounceTimer != nil {
            // Push the deadline forward — still one reload after activity stops
            debounceTimer.Reset(debounce)
            return
        }
        debounceTimer = time.AfterFunc(debounce, func() {
            timerMu.Lock()
            debounceTimer = nil
            timerMu.Unlock()
            tree.reloadFromWatch(path)
        })
    }

    cancelTimer := func() {
        timerMu.Lock()
        defer timerMu.Unlock()
        if debounceTimer != nil {
            debounceTimer.Stop()
            debounceTimer = nil
        }
    }

    for {
        select {
        case <-stopCh:
            cancelTimer()
            return

        case event, ok := <-fsw.Events:
            if !ok {
                // fsnotify closed its own channel — watcher is gone
                cancelTimer()
                return
            }
            switch {
            case event.Has(fsnotify.Write):
                // Standard in-place save
                scheduleReload()

            case event.Has(fsnotify.Rename):
                // Atomic-write editors (vim, IntelliJ) rename a temp file
                // over the target; re-add the path so we keep watching it
                // then schedule a reload
                _ = fsw.Add(path)
                scheduleReload()

            case event.Has(fsnotify.Remove):
                // File was deleted — surface error but stay alive in case it
                // is recreated (e.g. a deployment pipeline replacing the file)
                tree.handleWatchError(fmt.Errorf(
                    "figtree watcher: watched file %q was removed", path,
                ))
            }

        case err, ok := <-fsw.Errors:
            if !ok {
                cancelTimer()
                return
            }
            tree.handleWatchError(fmt.Errorf(
                "figtree watcher: fsnotify error on %q: %w", path, err,
            ))
        }
    }
}

// ============================================================================
// INTERNAL: reloadFromWatch
// ============================================================================

// reloadFromWatch re-parses the watched file and feeds changed values back
// through the normal Store() pipeline. This means:
//   - RulePreventChange rejects a file-driven update the same as a manual one
//   - RulePanicOnChange panics on a file-driven update the same as a manual one
//   - WithValidator() runs on every reloaded value
//   - CallbackAfterChange fires for every key whose value changed
//   - Mutations() channel receives every file-driven change automatically
//
// Keys present in the file but not registered in the tree are silently skipped,
// matching the behaviour of the initial Load/ParseFile call.
func (tree *figTree) reloadFromWatch(path string) {
    incoming, err := tree.parseFileToRawMap(path)
    if err != nil {
        tree.handleWatchError(fmt.Errorf(
            "figtree watcher: reload parse error on %q: %w", path, err,
        ))
        return
    }

    for key, rawValue := range incoming {
        // Resolve alias to canonical name if needed
        canonicalKey := key
        tree.mu.RLock()
        for alias, name := range tree.aliases {
            if strings.EqualFold(alias, key) {
                canonicalKey = name
                break
            }
        }
        tree.mu.RUnlock()

        fig := tree.Fig(canonicalKey)
        if fig == nil {
            // Not registered — skip, same as initial load behaviour
            continue
        }

        // Use the existing Set path on the live Value so validators,
        // callbacks, rules, and mutation tracking all fire naturally
        value, fromErr := tree.from(canonicalKey)
        if fromErr != nil || value == nil {
            tree.handleWatchError(fmt.Errorf(
                "figtree watcher: could not retrieve fig %q during reload: %w",
                canonicalKey, fromErr,
            ))
            continue
        }

        setErr := value.Set(fmt.Sprintf("%v", rawValue))
        if setErr != nil {
            tree.handleWatchError(fmt.Errorf(
                "figtree watcher: could not apply reloaded value for key %q: %w",
                canonicalKey, setErr,
            ))
            continue
        }

        tree.values.Store(canonicalKey, value)
    }
}

// ============================================================================
// INTERNAL: parseFileToRawMap
// ============================================================================

// parseFileToRawMap opens the file at path, detects its format from the
// extension, and returns a flat map[string]interface{} of raw values.
// It uses the same extension routing as loadFile() so behaviour is consistent.
func (tree *figTree) parseFileToRawMap(path string) (map[string]interface{}, error) {
    f, err := os.Open(path)
    if err != nil {
        return nil, fmt.Errorf("could not open %q: %w", path, err)
    }
    defer f.Close()

    ext := strings.ToLower(filepath.Ext(path))

    switch ext {
    case ".yaml", ".yml":
        return parseYAMLReader(f)
    case ".json":
        return parseJSONReader(f)
    case ".ini":
        return parseINIReader(f)
    default:
        return nil, fmt.Errorf("unsupported config file extension %q", ext)
    }
}

// ============================================================================
// INTERNAL: teardownWatchLocked
// ============================================================================

// teardownWatchLocked stops the watch goroutine and closes the fsnotify
// watcher. Caller MUST hold tree.watcher.mu before calling this.
func (tree *figTree) teardownWatchLocked() {
    if !tree.watcher.active {
        return
    }
    // Signal the watchLoop goroutine to exit
    close(tree.watcher.stopCh)
    // Close the fsnotify watcher — this also closes fsw.Events and fsw.Errors,
    // causing the goroutine's channel selects to drain and exit cleanly
    _ = tree.watcher.fsw.Close()

    tree.watcher.active      = false
    tree.watcher.watchedPath = ""
    tree.watcher.fsw         = nil
    tree.watcher.stopCh      = nil
}

// ============================================================================
// INTERNAL: handleWatchError
// ============================================================================

// handleWatchError routes watch errors to the user-supplied OnWatchError hook
// when set, otherwise falls back to log.Println. This keeps watch errors
// visible without forcing a fatal or panic on what are often transient issues.
func (tree *figTree) handleWatchError(err error) {
    if tree.onWatchError != nil {
        tree.onWatchError(err)
        return
    }
    log.Println(err)
}

Update loading.go

package figtree

import (
    "errors"
    "flag"
    "fmt"
    "os"
    "path/filepath"
    "strings"

    check "github.com/andreimerlescu/checkfs"
    "github.com/andreimerlescu/checkfs/file"
)

// Reload will readEnv on each flag in the configurable package
func (tree *figTree) Reload() error {
    tree.readEnv()
    return tree.validateAll()
}

func (tree *figTree) preLoadOrParse() error {
    tree.mu.RLock()
    defer tree.mu.RUnlock()
    for name, fig := range tree.figs {
        value, err := tree.from(name)
        if err != nil {
            return err
        }
        if value.Err != nil {
            return value.Err
        }
        if fig.Error != nil {
            return fig.Error
        }
    }
    return tree.checkFigErrors()
}

// Load uses the EnvironmentKey and the DefaultJSONFile, DefaultYAMLFile, and
// DefaultINIFile to run ParseFile if it exists. When Options.Watch is true,
// the first config file that successfully loads is automatically watched for
// changes via fsnotify.
func (tree *figTree) Load() (err error) {
    preloadErr := tree.preLoadOrParse()
    if preloadErr != nil {
        return preloadErr
    }
    if !tree.HasRule(RuleNoFlags) {
        tree.activateFlagSet()
        args := os.Args[1:]
        if tree.filterTests {
            args = filterTestFlags(args)
        }
        err = tree.flagSet.Parse(args)
        if err != nil {
            err2 := tree.checkFigErrors()
            if err2 != nil {
                err = errors.Join(err, err2)
            }
            return ErrLoadFailure{"flags", err}
        }
        err = tree.loadFlagSet()
        if err != nil {
            return err
        }
    }
    first := ""
    if !tree.HasRule(RuleNoEnv) {
        first = os.Getenv(EnvironmentKey)
    }
    files := []string{
        first,
        tree.ConfigFilePath,
        ConfigFilePath,
        filepath.Join(".", DefaultJSONFile),
        filepath.Join(".", DefaultINIFile),
    }
    loadedPath := "" // track which file actually loaded
    for i := 0; i < len(files); i++ {
        f := files[i]
        if f == "" {
            continue
        }
        if err := check.File(f, file.Options{Exists: true}); err == nil {
            if err := tree.loadFile(f); err != nil {
                return ErrLoadFailure{f, err}
            }
            if loadedPath == "" {
                loadedPath = f // record the first file that succeeded
            }
        }
    }
    tree.readEnv()
    err = tree.checkFigErrors()
    if err != nil {
        return fmt.Errorf("checkFigErrors() threw err: %w", err)
    }
    if err = tree.validateAll(); err != nil {
        return err
    }

    // Activate fsnotify watch on the resolved config file — no-op when
    // Options.Watch is false or when no file was found
    if loadedPath != "" {
        tree.activateWatch(loadedPath) // ADDED
    }

    return nil
}

// LoadFile accepts a path and uses it to populate the figTree.
// When Options.Watch is true and the file exists, it is automatically
// watched for changes via fsnotify after a successful load.
func (tree *figTree) LoadFile(path string) (err error) {
    preloadErr := tree.preLoadOrParse()
    if preloadErr != nil {
        return preloadErr
    }
    if !tree.HasRule(RuleNoFlags) {
        tree.activateFlagSet()
        args := os.Args[1:]
        if tree.filterTests {
            args = filterTestFlags(args)
        }
        err = tree.flagSet.Parse(args)
        if err != nil {
            err2 := tree.checkFigErrors()
            if err2 != nil {
                err = errors.Join(err, err2)
            }
            return err
        }
    }
    var loadErr error
    if loadErr = check.File(path, file.Options{Exists: true}); loadErr == nil {
        if err2 := tree.loadFile(path); err2 != nil {
            return ErrLoadFailure{path, err2}
        }
        tree.readEnv()
        err3 := tree.loadFlagSet()
        if err3 != nil {
            return err3
        }
        err4 := tree.validateAll()
        if err4 != nil {
            return ErrValidationFailure{err4}
        }

        tree.activateWatch(path) // ADDED — file confirmed to exist and loaded

        return nil
    }
    err3 := tree.loadFlagSet()
    if err3 != nil {
        return err3
    }
    tree.readEnv()
    err4 := tree.checkFigErrors()
    if err4 != nil {
        return fmt.Errorf("failed to checkFigErrors: %w", err4)
    }
    err5 := tree.validateAll()
    if err5 != nil {
        return ErrValidationFailure{err5}
    }
    return ErrLoadFailure{path, loadErr}
    // Note: no activateWatch here — we only watch files that actually loaded
}

func (tree *figTree) loadFlagSet() (e error) {
    defer func() {
        if e != nil {
            _, _ = fmt.Fprintf(os.Stderr, "loadFlagSet() err: %s", e.Error())
        }
    }()
    tree.flagSet.VisitAll(func(f *flag.Flag) {
        flagName := f.Name
        for alias, name := range tree.aliases {
            if strings.EqualFold(alias, f.Name) {
                flagName = name
            }
        }
        value, err := tree.from(flagName)
        if err != nil || value == nil {
            e = ErrLoadFailure{flagName, err}
            return
        }
        switch value.Mutagensis {
        case tMap:
            merged := value.Flesh().ToMap()
            withered := tree.withered[flagName]
            witheredValue := withered.Value.Flesh().ToMap()
            flagged, err := toStringMap(f.Value)
            if err != nil {
                e = ErrLoadFailure{flagName, err}
                return
            }
            result := make(map[string]string)
            if PolicyMapAppend {
                for k, v := range witheredValue {
                    result[k] = v
                }
            }
            for k, v := range merged {
                result[k] = v
            }
            for k, v := range flagged {
                result[k] = v
            }
            err = value.Assign(result)
            if err != nil {
                e = ErrLoadFailure{flagName, err}
                return
            }
        case tList:
            merged, err := toStringSlice(value.Value)
            if err != nil {
                e = ErrLoadFailure{flagName, err}
                return
            }
            flagged, err := toStringSlice(f.Value)
            if err != nil {
                e = ErrLoadFailure{flagName, err}
                return
            }
            unique := make(map[string]bool)
            for _, v := range merged {
                unique[v] = true
            }
            for _, v := range flagged {
                unique[v] = true
            }
            var newValue []string
            for k := range unique {
                newValue = append(newValue, k)
            }
            err = value.Assign(newValue)
            if err != nil {
                e = ErrLoadFailure{flagName, err}
                return
            }
        default:
            v := f.Value.String()
            err := value.Set(v)
            if err != nil {
                e = ErrLoadFailure{flagName, fmt.Errorf("failed to value.Set(%s): %w", f.Value.String(), err)}
                return
            }
        }
        tree.values.Store(flagName, value)
    })
    return nil
}

Update parsing.go

func (tree *figTree) ParseFile(filename string) error {
    // ... your existing ParseFile body unchanged ...

    // At the point where you would have returned nil after a successful parse:
    tree.activateWatch(filename) // ADDED
    return nil
}

[andreimerlescu]

Testing Watcher in watcher_test.go

package figtree

import (
	"os"
	"path/filepath"
	"sync"
	"testing"
	"time"

	"github.com/stretchr/testify/assert"
	"github.com/stretchr/testify/require"
)

// ============================================================================
// HELPERS
// ============================================================================

// watcherTestFile writes content to a named file inside t.TempDir() and
// returns the absolute path. The file is cleaned up automatically when the
// test ends.
func watcherTestFile(t *testing.T, name, content string) string {
	t.Helper()
	path := filepath.Join(t.TempDir(), name)
	require.NoError(t, os.WriteFile(path, []byte(content), 0644))
	return path
}

// overwriteFile replaces the content of an existing file. Used to simulate
// an in-place editor save (Write event).
func overwriteFile(t *testing.T, path, content string) {
	t.Helper()
	require.NoError(t, os.WriteFile(path, []byte(content), 0644))
}

// atomicWriteFile simulates an atomic-write editor (vim, IntelliJ) by writing
// to a temp file in the same directory and renaming it over the target,
// producing a Rename event rather than a Write event.
func atomicWriteFile(t *testing.T, path, content string) {
	t.Helper()
	dir := filepath.Dir(path)
	tmp, err := os.CreateTemp(dir, ".figtree-atomic-*")
	require.NoError(t, err)
	_, err = tmp.WriteString(content)
	require.NoError(t, err)
	require.NoError(t, tmp.Close())
	require.NoError(t, os.Rename(tmp.Name(), path))
}

// waitForMutation blocks until a Mutation arrives on figs.Mutations() or the
// timeout expires. Returns the mutation and true on success, zero value and
// false on timeout.
func waitForMutation(figs Plant, timeout time.Duration) (Mutation, bool) {
	select {
	case m, ok := <-figs.Mutations():
		if !ok {
			return Mutation{}, false
		}
		return m, true
	case <-time.After(timeout):
		return Mutation{}, false
	}
}

// drainMutations reads all pending mutations within drainFor duration.
// Useful to flush noise before asserting a specific subsequent mutation.
func drainMutations(figs Plant, drainFor time.Duration) []Mutation {
	var collected []Mutation
	deadline := time.After(drainFor)
	for {
		select {
		case m, ok := <-figs.Mutations():
			if !ok {
				return collected
			}
			collected = append(collected, m)
		case <-deadline:
			return collected
		}
	}
}

const (
	watchTimeout  = 2 * time.Second  // how long to wait for a mutation to arrive
	watchDrain    = 150 * time.Millisecond // how long to drain noise
	testDebounce  = 50 * time.Millisecond  // fast debounce for tests — no need to wait 100ms
)

// ============================================================================
// ACTIVATION TESTS
// ============================================================================

func TestWatcher_NotActivatedByDefault(t *testing.T) {
	// Watch: false (default) — watcher must never start
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{Germinate: true, Tracking: true})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.LoadFile(path))

	// watcher must be inactive
	tree := figs.(*figTree)
	tree.watcher.mu.Lock()
	active := tree.watcher.active
	tree.watcher.mu.Unlock()
	assert.False(t, active, "watcher should not be active when Watch option is false")
}

func TestWatcher_ActivatedOnLoadFile(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	tree := figs.(*figTree)
	tree.watcher.mu.Lock()
	active := tree.watcher.active
	watched := tree.watcher.watchedPath
	tree.watcher.mu.Unlock()

	assert.True(t, active, "watcher should be active after LoadFile with Watch:true")
	absPath, _ := filepath.Abs(path)
	assert.Equal(t, absPath, watched, "watched path should be the absolute path of the loaded file")
}

func TestWatcher_ActivatedOnLoad(t *testing.T) {
	// Load() searches a list of candidate paths; give it a real yaml file
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{
		Germinate:     true,
		Tracking:      true,
		Watch:         true,
		WatchDebounce: testDebounce,
		ConfigFile:    path,
	})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.Load())
	defer figs.StopWatch()

	tree := figs.(*figTree)
	tree.watcher.mu.Lock()
	active := tree.watcher.active
	tree.watcher.mu.Unlock()
	assert.True(t, active, "watcher should be active after Load() with Watch:true")
}

func TestWatcher_ActivatedOnParseFile(t *testing.T) {
	exts := []string{"yaml", "json", "ini"}
	contents := map[string]string{
		"yaml": "name: andrei\n",
		"json": `{"name":"andrei"}`,
		"ini":  "[default]\nname=andrei\n",
	}
	for _, ext := range exts {
		t.Run(ext, func(t *testing.T) {
			path := watcherTestFile(t, "config."+ext, contents[ext])
			figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
			figs = figs.NewString("name", "", "name")
			require.NoError(t, figs.ParseFile(path))
			defer figs.StopWatch()

			tree := figs.(*figTree)
			tree.watcher.mu.Lock()
			active := tree.watcher.active
			tree.watcher.mu.Unlock()
			assert.True(t, active, "watcher should be active after ParseFile with Watch:true")
		})
	}
}

// ============================================================================
// STOPWATCH TESTS
// ============================================================================

func TestWatcher_StopWatch_IdempotentWhenNeverStarted(t *testing.T) {
	// StopWatch on a tree that never watched must not panic
	figs := With(Options{Germinate: true})
	assert.NotPanics(t, func() { figs.StopWatch() })
}

func TestWatcher_StopWatch_IdempotentWhenCalledTwice(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.LoadFile(path))

	assert.NotPanics(t, func() {
		figs.StopWatch()
		figs.StopWatch() // second call must be safe
	})
}

func TestWatcher_StopWatch_DeactivatesWatcher(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.LoadFile(path))

	figs.StopWatch()

	tree := figs.(*figTree)
	tree.watcher.mu.Lock()
	active := tree.watcher.active
	tree.watcher.mu.Unlock()
	assert.False(t, active, "watcher should be inactive after StopWatch()")
}

func TestWatcher_StopWatch_NoMutationsAfterStop(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.LoadFile(path))

	figs.StopWatch()

	// Write the file after stopping — no mutation should arrive
	overwriteFile(t, path, "name: yeshua\n")
	_, received := waitForMutation(figs, 300*time.Millisecond)
	assert.False(t, received, "no mutation should arrive after StopWatch()")
}

// ============================================================================
// WRITE EVENT — in-place save
// ============================================================================

func TestWatcher_WriteEvent_StringMutation(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	assert.Equal(t, "andrei", *figs.String("name"))

	drainMutations(figs, watchDrain)
	overwriteFile(t, path, "name: yeshua\n")

	m, received := waitForMutation(figs, watchTimeout)
	require.True(t, received, "expected a mutation after file write")
	assert.Equal(t, "name", m.Property)
	assert.Equal(t, "yeshua", *figs.String("name"))
}

func TestWatcher_WriteEvent_IntMutation(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "workers: 4\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewInt("workers", 1, "workers")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)
	overwriteFile(t, path, "workers: 16\n")

	m, received := waitForMutation(figs, watchTimeout)
	require.True(t, received, "expected a mutation after file write")
	assert.Equal(t, "workers", m.Property)
	assert.Equal(t, 16, *figs.Int("workers"))
}

func TestWatcher_WriteEvent_BoolMutation(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "debug: false\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewBool("debug", false, "debug")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)
	overwriteFile(t, path, "debug: true\n")

	m, received := waitForMutation(figs, watchTimeout)
	require.True(t, received, "expected a mutation after file write")
	assert.Equal(t, "debug", m.Property)
	assert.True(t, *figs.Bool("debug"))
}

func TestWatcher_WriteEvent_Float64Mutation(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "threshold: 0.5\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewFloat64("threshold", 0.0, "threshold")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)
	overwriteFile(t, path, "threshold: 0.99\n")

	m, received := waitForMutation(figs, watchTimeout)
	require.True(t, received, "expected a mutation after file write")
	assert.Equal(t, "threshold", m.Property)
	assert.InDelta(t, 0.99, *figs.Float64("threshold"), 0.001)
}

func TestWatcher_WriteEvent_Int64Mutation(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "maxRetries: 3\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewInt64("maxRetries", 1, "maxRetries")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)
	overwriteFile(t, path, "maxRetries: 10\n")

	m, received := waitForMutation(figs, watchTimeout)
	require.True(t, received, "expected a mutation after file write")
	assert.Equal(t, "maxRetries", m.Property)
	assert.Equal(t, int64(10), *figs.Int64("maxRetries"))
}

func TestWatcher_WriteEvent_DurationMutation(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "timeout: 5s\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewDuration("timeout", time.Second, "timeout")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)
	overwriteFile(t, path, "timeout: 30s\n")

	m, received := waitForMutation(figs, watchTimeout)
	require.True(t, received, "expected a mutation after file write")
	assert.Equal(t, "timeout", m.Property)
	assert.Equal(t, 30*time.Second, *figs.Duration("timeout"))
}

func TestWatcher_WriteEvent_ListMutation(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "servers: \"primary,replica\"\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewList("servers", []string{"primary"}, "servers")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)
	overwriteFile(t, path, "servers: \"primary,replica,canary\"\n")

	m, received := waitForMutation(figs, watchTimeout)
	require.True(t, received, "expected a mutation after file write")
	assert.Equal(t, "servers", m.Property)
	assert.Contains(t, *figs.List("servers"), "canary")
}

func TestWatcher_WriteEvent_MapMutation(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "labels: \"env=prod,version=1\"\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewMap("labels", map[string]string{"env": "prod"}, "labels")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)
	overwriteFile(t, path, "labels: \"env=staging,version=2\"\n")

	m, received := waitForMutation(figs, watchTimeout)
	require.True(t, received, "expected a mutation after file write")
	assert.Equal(t, "labels", m.Property)
	assert.Equal(t, "staging", (*figs.Map("labels"))["env"])
}

// ============================================================================
// RENAME EVENT — atomic-write editors
// ============================================================================

func TestWatcher_RenameEvent_StringMutation(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)
	atomicWriteFile(t, path, "name: yeshua\n")

	m, received := waitForMutation(figs, watchTimeout)
	require.True(t, received, "expected a mutation after atomic rename")
	assert.Equal(t, "name", m.Property)
	assert.Equal(t, "yeshua", *figs.String("name"))
}

func TestWatcher_RenameEvent_IntMutation(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "workers: 2\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewInt("workers", 1, "workers")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)
	atomicWriteFile(t, path, "workers: 8\n")

	m, received := waitForMutation(figs, watchTimeout)
	require.True(t, received, "expected a mutation after atomic rename")
	assert.Equal(t, "workers", m.Property)
	assert.Equal(t, 8, *figs.Int("workers"))
}

// ============================================================================
// NO MUTATION when value is unchanged
// ============================================================================

func TestWatcher_NoMutation_WhenValueUnchanged(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)

	// Write same value — Store() should detect no change and emit no mutation
	overwriteFile(t, path, "name: andrei\n")

	_, received := waitForMutation(figs, 400*time.Millisecond)
	assert.False(t, received, "no mutation should arrive when the value did not change")
}

// ============================================================================
// UNREGISTERED KEYS in file are silently skipped
// ============================================================================

func TestWatcher_UnregisteredKeyInFile_Skipped(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)

	// Add an unregistered key alongside the registered one
	overwriteFile(t, path, "name: andrei\nunknown_key: whatever\n")

	// No mutation for name (unchanged), no panic for unknown_key
	_, received := waitForMutation(figs, 400*time.Millisecond)
	assert.False(t, received, "unregistered keys should be silently skipped")
}

// ============================================================================
// RULE: RulePreventChange blocks file-driven updates
// ============================================================================

func TestWatcher_RulePreventChange_BlocksFileUpdate(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")

	var watchErr error
	var errMu sync.Mutex

	figs := With(Options{
		Germinate:     true,
		Tracking:      true,
		Watch:         true,
		WatchDebounce: testDebounce,
		OnWatchError: func(err error) {
			errMu.Lock()
			watchErr = err
			errMu.Unlock()
		},
	})
	figs = figs.NewString("name", "", "name")
	figs = figs.WithRule("name", RulePreventChange)
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)
	overwriteFile(t, path, "name: yeshua\n")

	// Give the watcher time to process
	time.Sleep(testDebounce + 200*time.Millisecond)

	// Value must be unchanged
	assert.Equal(t, "andrei", *figs.String("name"),
		"RulePreventChange must block file-driven update")

	// No mutation should have been emitted
	_, received := waitForMutation(figs, 200*time.Millisecond)
	assert.False(t, received, "no mutation should arrive when RulePreventChange is active")
}

// ============================================================================
// VALIDATOR: file-driven update rejected by validator
// ============================================================================

func TestWatcher_Validator_RejectsInvalidFileUpdate(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "port: 8080\n")

	var watchErrs []error
	var errMu sync.Mutex

	figs := With(Options{
		Germinate:     true,
		Tracking:      true,
		Watch:         true,
		WatchDebounce: testDebounce,
		OnWatchError: func(err error) {
			errMu.Lock()
			watchErrs = append(watchErrs, err)
			errMu.Unlock()
		},
	})
	figs = figs.NewInt("port", 8080, "port")
	figs = figs.WithValidator("port", AssureIntInRange(1024, 65535))
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)

	// Write a value outside the valid range
	overwriteFile(t, path, "port: 80\n")

	time.Sleep(testDebounce + 200*time.Millisecond)

	// Value must remain 8080
	assert.Equal(t, 8080, *figs.Int("port"),
		"validator must reject out-of-range value from file reload")

	// OnWatchError must have been called
	errMu.Lock()
	hasErr := len(watchErrs) > 0
	errMu.Unlock()
	assert.True(t, hasErr, "OnWatchError should be called when validator rejects a reloaded value")
}

// ============================================================================
// CALLBACK: CallbackAfterChange fires on file-driven update
// ============================================================================

func TestWatcher_Callback_FiresOnFileUpdate(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewString("name", "", "name")

	var callbackFired bool
	var callbackMu sync.Mutex
	figs = figs.WithCallback("name", CallbackAfterChange, func(value interface{}) error {
		callbackMu.Lock()
		callbackFired = true
		callbackMu.Unlock()
		return nil
	})

	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)
	overwriteFile(t, path, "name: yeshua\n")

	time.Sleep(testDebounce + 300*time.Millisecond)

	callbackMu.Lock()
	fired := callbackFired
	callbackMu.Unlock()
	assert.True(t, fired, "CallbackAfterChange should fire when file update changes a value")
}

// ============================================================================
// DEBOUNCE: rapid writes produce only one reload
// ============================================================================

func TestWatcher_Debounce_RapidWritesProduceOneMutation(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{
		Germinate:     true,
		Tracking:      true,
		Watch:         true,
		WatchDebounce: 200 * time.Millisecond, // longer debounce to absorb the burst
	})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)

	// Write the file 5 times in rapid succession
	for i := 0; i < 5; i++ {
		overwriteFile(t, path, "name: yeshua\n")
		time.Sleep(10 * time.Millisecond)
	}

	// Collect all mutations that arrive within a generous window
	var mutations []Mutation
	deadline := time.After(600 * time.Millisecond)
collect:
	for {
		select {
		case m, ok := <-figs.Mutations():
			if !ok {
				break collect
			}
			mutations = append(mutations, m)
		case <-deadline:
			break collect
		}
	}

	// Debounce must collapse the burst — we expect exactly 1, allow 2 at most
	// for edge cases where the timer fired between writes
	assert.LessOrEqual(t, len(mutations), 2,
		"debounce should collapse rapid writes into at most 2 mutations, got %d", len(mutations))
	assert.GreaterOrEqual(t, len(mutations), 1,
		"at least 1 mutation should arrive after rapid writes")
}

// ============================================================================
// MULTI-KEY: multiple keys change in one file write
// ============================================================================

func TestWatcher_MultiKey_AllChangedKeysEmitMutations(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\nworkers: 4\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewString("name", "", "name")
	figs = figs.NewInt("workers", 1, "workers")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)
	overwriteFile(t, path, "name: yeshua\nworkers: 16\n")

	// Collect mutations for up to watchTimeout
	received := make(map[string]bool)
	deadline := time.After(watchTimeout)
collect:
	for {
		select {
		case m, ok := <-figs.Mutations():
			if !ok {
				break collect
			}
			received[m.Property] = true
			if received["name"] && received["workers"] {
				break collect
			}
		case <-deadline:
			break collect
		}
	}

	assert.True(t, received["name"], "mutation for 'name' should be received")
	assert.True(t, received["workers"], "mutation for 'workers' should be received")
	assert.Equal(t, "yeshua", *figs.String("name"))
	assert.Equal(t, 16, *figs.Int("workers"))
}

// ============================================================================
// RE-WATCH: calling LoadFile again with a different file switches the watcher
// ============================================================================

func TestWatcher_ReWatch_SwitchesToNewFile(t *testing.T) {
	pathA := watcherTestFile(t, "config-a.yaml", "name: andrei\n")
	pathB := watcherTestFile(t, "config-b.yaml", "name: yeshua\n")

	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.LoadFile(pathA))
	defer figs.StopWatch()

	absA, _ := filepath.Abs(pathA)
	tree := figs.(*figTree)
	tree.watcher.mu.Lock()
	assert.Equal(t, absA, tree.watcher.watchedPath, "should be watching file A")
	tree.watcher.mu.Unlock()

	// Load a different file — watcher should switch
	require.NoError(t, figs.LoadFile(pathB))

	absB, _ := filepath.Abs(pathB)
	tree.watcher.mu.Lock()
	assert.Equal(t, absB, tree.watcher.watchedPath, "should now be watching file B")
	tree.watcher.mu.Unlock()

	drainMutations(figs, watchDrain)

	// Write to B — mutation must arrive
	overwriteFile(t, pathB, "name: changed\n")
	m, received := waitForMutation(figs, watchTimeout)
	require.True(t, received, "mutation should arrive from new watched file")
	assert.Equal(t, "name", m.Property)

	// Write to A — must NOT trigger mutation (no longer watched)
	drainMutations(figs, watchDrain)
	overwriteFile(t, pathA, "name: ghost\n")
	_, receivedFromA := waitForMutation(figs, 400*time.Millisecond)
	assert.False(t, receivedFromA, "writes to old file must not trigger mutations after re-watch")
}

// ============================================================================
// FORMAT COVERAGE: Write events across all supported formats
// ============================================================================

func TestWatcher_WriteEvent_AllFormats(t *testing.T) {
	type formatCase struct {
		ext      string
		initial  string
		updated  string
		key      string
		expected string
	}
	cases := []formatCase{
		{
			ext:      "yaml",
			initial:  "name: andrei\n",
			updated:  "name: yeshua\n",
			key:      "name",
			expected: "yeshua",
		},
		{
			ext:      "json",
			initial:  `{"name":"andrei"}`,
			updated:  `{"name":"yeshua"}`,
			key:      "name",
			expected: "yeshua",
		},
		{
			ext:      "ini",
			initial:  "[default]\nname=andrei\n",
			updated:  "[default]\nname=yeshua\n",
			key:      "name",
			expected: "yeshua",
		},
	}

	for _, tc := range cases {
		tc := tc
		t.Run(tc.ext, func(t *testing.T) {
			path := watcherTestFile(t, "config."+tc.ext, tc.initial)
			figs := With(Options{
				Germinate:     true,
				Tracking:      true,
				Watch:         true,
				WatchDebounce: testDebounce,
			})
			figs = figs.NewString(tc.key, "", tc.key)
			require.NoError(t, figs.ParseFile(path))
			defer figs.StopWatch()

			drainMutations(figs, watchDrain)
			overwriteFile(t, path, tc.updated)

			m, received := waitForMutation(figs, watchTimeout)
			require.True(t, received, "expected mutation after %s file write", tc.ext)
			assert.Equal(t, tc.key, m.Property)
			assert.Equal(t, tc.expected, *figs.String(tc.key))
		})
	}
}

// ============================================================================
// OnWatchError hook
// ============================================================================

func TestWatcher_OnWatchError_CalledOnParseFailure(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")

	var errs []error
	var errMu sync.Mutex

	figs := With(Options{
		Germinate:     true,
		Tracking:      true,
		Watch:         true,
		WatchDebounce: testDebounce,
		OnWatchError: func(err error) {
			errMu.Lock()
			errs = append(errs, err)
			errMu.Unlock()
		},
	})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)

	// Write deliberately malformed YAML
	overwriteFile(t, path, "name: [\nbad yaml\n")

	time.Sleep(testDebounce + 300*time.Millisecond)

	errMu.Lock()
	count := len(errs)
	errMu.Unlock()
	assert.Greater(t, count, 0, "OnWatchError should be called when reloaded file is unparseable")
}

func TestWatcher_OnWatchError_DefaultsToLogWhenNil(t *testing.T) {
	// When OnWatchError is nil the tree must not panic — it falls back to log.Println
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{
		Germinate:     true,
		Tracking:      true,
		Watch:         true,
		WatchDebounce: testDebounce,
		// OnWatchError intentionally omitted
	})
	figs = figs.NewString("name", "", "name")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)

	// Write malformed content — handleWatchError must not panic
	assert.NotPanics(t, func() {
		overwriteFile(t, path, "name: [\nbad yaml\n")
		time.Sleep(testDebounce + 300*time.Millisecond)
	})
}

// ============================================================================
// ALIAS: aliased key in file resolves to canonical fig
// ============================================================================

func TestWatcher_Alias_ResolvedOnFileUpdate(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "name: andrei\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewString("name", "", "name")
	figs = figs.WithAlias("name", "n")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	drainMutations(figs, watchDrain)

	// File uses the canonical key — alias resolution must still work internally
	overwriteFile(t, path, "name: yeshua\n")
	m, received := waitForMutation(figs, watchTimeout)
	require.True(t, received, "mutation should arrive via canonical key")
	assert.Equal(t, "name", m.Property)
	assert.Equal(t, "yeshua", *figs.String("name"))
	// alias getter must reflect the same value
	assert.Equal(t, "yeshua", *figs.String("n"))
}

// ============================================================================
// CONCURRENT SAFETY: multiple goroutines reading while watcher writes
// ============================================================================

func TestWatcher_ConcurrentReads_NoRaceCondition(t *testing.T) {
	path := watcherTestFile(t, "config.yaml", "workers: 1\n")
	figs := With(Options{Germinate: true, Tracking: true, Watch: true, WatchDebounce: testDebounce})
	figs = figs.NewInt("workers", 1, "workers")
	require.NoError(t, figs.LoadFile(path))
	defer figs.StopWatch()

	var wg sync.WaitGroup
	stop := make(chan struct{})

	// 8 readers hammering figs.Int("workers") concurrently
	for i := 0; i < 8; i++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			for {
				select {
				case <-stop:
					return
				default:
					_ = figs.Int("workers")
				}
			}
		}()
	}

	// Drive 3 file updates while readers run
	for i := 2; i <= 4; i++ {
		overwriteFile(t, path, "workers: "+string(rune('0'+i))+"\n")
		time.Sleep(testDebounce + 80*time.Millisecond)
	}

	close(stop)
	wg.Wait()
	// If -race detector does not fire, the test passes
}