Problem:

`vim.validate()` takes two forms when it only needs one.

Solution:

- Teach the fast form all the features of the spec form.
- Deprecate the spec form.
- General optimizations for both forms.
- Add a `message` argument which can be used alongside or in place
  of the `optional` argument.

- Also fix `vim.validate()` for PUC Lua when showing errors for values
  that aren't string or number.

Problem:
The `_watch.watch()` strategy may fail if the given path does not exist:

    …/vim/_watch.lua:101: ENOENT: no such file or directory
    stack traceback:
        [C]: in function 'assert'
        …/vim/_watch.lua:101: in function <…/vim/_watch.lua:61>
        [string "<nvim>"]:5: in main chunk

- `_watch.watch()` actively asserts any error returned by `handle:start()`.
- whereas `_watch.watchdirs()` just ignores the result of `root_handle:start()`.

Servers may send "client/registerCapability" with "workspace/didChangeWatchedFiles"
item(s) (`baseUri`) which do not actually exist on the filesystem:
https://github.com/neovim/neovim/issues/28058#issuecomment-2189929424

    {
      method = "client/registerCapability",
      params = {
        registrations = { {
            method = "workspace/didChangeWatchedFiles",
            registerOptions = {
              watchers = { {
                  globPattern = {
                    baseUri = "file:///Users/does/not/exist",
                    pattern = "**/*.{ts,js,mts,mjs,cjs,cts,json,svelte}"
                  }
                },
    ...
    }

Solution:
- Remove the assert in `_watch.watch()`.
- Show a once-only message for both cases.
- More detailed logging is blocked until we have `nvim_log` / `vim.log`.

fix #28058

inotifywait man page specifies:
The file must be specified with a relative or absolute path according to whether a relative or absolute path is given for watched directories.

So it would only work this way in case the path is relative (which at least for gopls it is not)

This patch replaces fswatch with inotifywait from inotify-toools:

https://github.com/inotify-tools/inotify-tools

fswatch takes ~1min to set up recursively for the Samba source code
directory. inotifywait needs less than a second to do the same thing.

https://github.com/emcrisostomo/fswatch/issues/321

Also it fswatch seems to be unmaintained in the meantime.

Signed-off-by: Andreas Schneider <asn@cryptomilk.org>

Doesn't have a huge impact, but showed up in profile output using
`require("jit.p").start("i1", "/tmp/profile")`

before:

    31%  joinpath
    25%  fs.lua:0
    13%  normalize
    13%  skip
     8%  _watchfunc
     5%  gsplit
     3%  spairs

after:

    34%  skip
    29%  fs.lua:0
    12%  joinpath
     7%  normalize
     5%  _watchfunc
     5%  spairs

Fixes issue reported in the original PR:
https://github.com/neovim/neovim/pull/27810

Signed-off-by: Tomas Slusny <slusnucky@gmail.com>

- Add :h fswatch-limitations that notifies user about default inotify
  limitations on linux and how to adjust them
- Check for Event queue overflow message from fswatch and refer user to
  new documentation

Signed-off-by: Tomas Slusny <slusnucky@gmail.com>

Resolves #27713

Co-authored-by: Tomasz N <przepompownia@users.noreply.github.com>