Problem: watchdirs() keeps its state in large nested callbacks in
_watch.lua, which makes its directory tracking logic harder to change.

Solution: Move the backend into its own module and store its state in a
WatchDirs instance. Split setup, event handling and cleanup into
methods. Extend the existing test to cover cancellation while a
directory stat is pending.

AI-assisted

Problem: watchdirs() scans and watches every directory that is not
excluded, even when a glob only matches files in one subtree. Some
language servers register absolute dependency filenames separately.
Neovim uses the workspace root for these string globs, so each extra
registration can scan and allocate libuv handles across the whole tree.

Solution: Keep each glob's literal directory prefix with its compiled
matcher. A directory must be allowed by both the include filter and at
least one watch rule. Skip unrelated subtrees, including new directories
created later. Keep ancestors watched so matching directories can still
be found. Report events only when they match the full patterns.

For example, watching /project for /project/src/**/*.lua only needs the
src tree and /project itself:

    /project/            watched
    |-- src/             watched
    |   `-- lib/         watched
    |-- tests/           skipped
    |   `-- fixtures/    skipped
    `-- vendor/          skipped
        `-- pkg/         skipped

With no exclusions, this uses three watches instead of seven.

The gain can be large, but depends on the server's patterns and the
workspace layout. Separate watches for absolute dependency filenames can
skip most directories.

For example, a test workspace has 213 directories, including 201 under
build/. The two dependency files in this example are under packages/ and
styles/, so their watches can skip build/. Before this change, each
watch starts at the workspace root, scans all 213 directories and
creates 213 libuv handles.

With this change:

- Haskell Language Server: a separate watch for
  /project/packages/demo/demo.cabal watches four directories: the
  project root, packages/, demo/ and its src/ child. This cuts that
  watch's scans and handles by 98%. With one broad source watch and this
  dependency watch, the total falls by 49%.
- Tailwind CSS v4: a separate watch for the imported
  /project/styles/themes/colors.css watches three directories: the
  project root, styles/ and themes/. This cuts that watch's scans and
  handles by 99%. With two broad watches and this dependency watch, the
  total falls by 33%.

The broad watches still cover all 213 directories. The saving comes from
avoiding repeated scans and extra handles for each dependency watch.

Most servers with watch registrations in the survey do not benefit.
Their patterns match throughout the watch root, or their watches already
start at the relevant directory. In both cases, the glob prefix cannot
exclude more directories.

AI-assisted

Problem: Argument type mismatches are excluded from EmmyLua checks.

Solution: Correct runtime annotations and calls, document local checker
workarounds, and enable the diagnostic.

AI-assisted

Enable EmmyLua's assign-type-mismatch diagnostic after correcting the
runtime annotations and assignments it flags.

Correct option, tuple, and return types, and use separate locals when a
value changes representation. Add guards and narrow casts where needed
so the runtime passes the stricter check. Regenerate the affected docs.

AI-assisted

Enable EmmyLua's need-check-nil diagnostic and resolve nullable values
through more precise types, explicit invariants, and guards for missing
runtime state. Keep analyzer-specific workarounds local and update the
affected API documentation.

Exclude the bundled re.lua from analysis so its nil-check warnings do
not fail CI.

AI-assisted

Problem:

LSP servers can register identical file watchers before removing old
registrations. Each registration creates another watcher tree, making
setup and teardown expensive in large workspaces.

Solution:

Move glob compilation into vim._watch and accept rules for multiple
roots alongside existing single-path and LPeg inputs. Share compatible
backends until their last subscription is cancelled.

Ref: #23291

AI-assisted

Problem: Watcher failures are reported inconsistently, and callers
cannot detect when a watcher is no longer usable.

Solution: Route startup and event failures and unexpected inotifywait
exits through an optional on_error callback. Log to nvim-watch.log by
default. Ignore disappearing child directories and exits caused by
cancellation. Let LSP log failures and notify once per message, using
INFO for missing roots and ERROR otherwise, without interrupting
registration.

AI-assisted

- call-non-callable
- missing-fields
- redefined-label
- redefined-local
- undefined-field
- unreachable-code

Promote redefined-local and unreachable-code to warnings.

Fix DOS line-ending handling for multiline semantic tokens, and support
intersection types in the help parser.

AI-assisted

Problem:
The LSP client excludes paths such as Git objects and installed
dependencies from file watching. However, watchdirs() still traverses
these subtrees before filtering which directories receive watchers,
paying the filesystem and Lua traversal cost for excluded content.

Solution:
Prune excluded subdirectories during the initial walk, and document
that excluding a directory also excludes its descendants.

Using the LSP client's existing **/node_modules/*/** exclusion on a
synthetic macOS tree with 100 installed packages and 4,000 files:
                     Before  After
  Directory scans       503    103
  Entries inspected    4502    202
  Directory watchers    103    103

The measurements use real filesystem calls and watcher handles, with
identical watcher paths for this exclusion.

Ref: #23291

AI-assisted