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 checks for unused code, deprecated calls, return types, and
annotations.

Fix the warnings and replace the deprecated highlight function. Keep
exceptions where old APIs are still needed or the checker gets it wrong.

AI-assisted

Problem: LuaLS struggles with the generics used in Nvim's runtime,
requiring broad diagnostic suppressions. Indexing is also slow.

Solution: Use EmmyLua for type checks in the build and CI. It offers
more sophisticated type checking, substantially better support for
generics, and much better flow analysis.

Correct the affected annotations. Use `@internal`, supported directly by
EmmyLua, instead of `@nodoc` for shared internal declarations, and
support it in the help parser.

AI-assisted

Problem: Every LSP capability that sends a request on a document change
to update its state was using its own buffer-local autocmd to do so.
That means there is a separate autocmd per buffer per active
capability/feature, and the actual code inside the autocmd callback was
virtually identical. The same problem occurred for capabilities that had
components to draw on the screen that had their own decoration providers.

Solution: Introduce a central `LspNotify` autocmd and decoration
provider in the capability module itself. New base class methods
`on_close` and `on_change` that take a client_id have been provided, for
`didClose` and `didOpen`/`didChange` notifications respectively. New
base class method `on_win` that takes topline and botline has been
provided to add extmarks or perform other work when lines of a buffer
are being drawn.

The autocmd callback loops through each active capability instance for
the buffer and calls a corresponding method with the triggering
client_id if it is currently attached to the buffer that triggered the
autocmd. The decoration provider just calls on_win for all active
capabilities on the buffer.

This slightly tweaks folding range to make use of these new client-id
specific callbacks.

Problem:
Malformed server responses with `null` (vim.NIL) values, do not show
clear error messages.


Solution:
Assert two known, specific cases, to avoid user confusion.

When a server supports both document and workspace pull diagnostics,
`on_refresh` only dispatched a `workspace/diagnostic` request.  The
workspace response handler skips buffers with `pull_kind == "document"`
(i.e. all buffers opened by the user), so their diagnostics went stale
until the next `didChange` or `didOpen` event.

Change `on_refresh` to always refresh document-pull buffers via
`textDocument/diagnostic`, regardless of whether the server also
supports workspace diagnostics.  This ensures that opened buffers
see updated diagnostics (e.g. after a save triggers an external
tool like PHPStan) without requiring the user to re-enter insert
mode.

Problem:
Diagnostic tracking used a separate bufstates table and manual
LspDetach/LspNotify autocmd management via _enable()/_refresh(),
duplicating the lifecycle logic already provided by the Capability
framework. This caused inconsistencies in how client attach/detach and
buffer teardown were handled compared to other LSP features.

Solution:
Replace the ad-hoc bufstate tracking and _enable/_refresh pattern in
vim.lsp.diagnostic with a proper Diagnostics subclass of Capability.
This cleans up a few random places in the main lsp module and client
module that were poking the diagnostics. It also fixes some pre-existing
bugs and inconsistencies that were discovered:

- Refresh diagnostics immediately on attach instead of lazily by the
  first didOpen/didChange notification
- Fix Capability.active lookup in M.enable() to key by it_bufnr instead
  of the filter bufnr
- Set lsp defaults before calling the _text_document_did_open_handler in
  Client:on_attach() so defaults are there before any lsp notification
  occurs
- Log (and return early) on any error from a diagnostic request result
  instead of only returning early for server cancelled errors