Problem:
The magic globals `it`, `describe`, etc., are more trouble than they are
worth.
- Hooking into `after_each` requires `getfenv()` hacks.
- They confuse luals/emmylua, because the top-level `.luarc.json` isn't
merged with `test/.luarc.json` (apparently a luals limitation?)
- They totally defeat discoverability because the user just has to
"know" about the various magic symbols.
So they harm DX, which means they serve no purpose at all.
Solution:
- Expose the test API from `testutil`, so tests can call `t.it()`,
`t.describe()`, etc., in the conventional way.
- Drop `getfenv()` hacks.
- Drop the `setfenv()` injection in `load_chunk`.
- Drop `test/_meta.lua`.
Problem:
Sampling a transient busy=1 pulse is racy under load.
Solution:
Set a long debounce, assert the stable state, then use a short debounce
to let the reload clear it.
Problem:
Any random ftplugin or other autocmd, can throw an error when
`:checktime` reloads a buffer. This causes a trace which makes it look
like an issue with `autoread.lua`.
vim.schedule callback: …/runtime/lua/nvim/autoread.lua:146:
FileType Autocommands for "*"..function <SNR>1_LoadFTPlugin[20] ..script
…/runtime/ftplugin/help.lua: Vim(runtime):E5113: Lua chunk:
…/runtime/lua/vim/treesitter.lua:216: Index out of bounds
stack traceback:
[C]: in function 'nvim_buf_get_text'
…/runtime/lua/vim/treesitter.lua:216: in function 'get_node_text'
…/runtime/lua/vim/treesitter/query.lua:558: in function 'handler'
…/runtime/lua/vim/treesitter/query.lua:843: in function '_match_predicates'
…/runtime/lua/vim/treesitter/query.lua:1082: in function '(for generator)'
…/runtime/ftplugin/help.lua:91: in function 'runnables'
…/runtime/ftplugin/help.lua:124: in main chunk
[C]: in function 'checktime'
…/runtime/lua/nvim/autoread.lua:146: in function <…/runtime/lua/nvim/autoread.lua:138>
Solution:
Use pcall() and surface the error via nvim_echo.
Problem:
Old 'autoread' only did `:checktime` on focus-change and shell (":!")
commands, and only for non-hidden buffers. Since 'autoread' is now
driven by OS filewatcher events, buffers are updated much more eagerly.
This should be surfaced to the user somehow, either via a carefully
placed notification, or a minimal UI indicator.
A "notification" would be noisy, unless it is conditional on specific
circumstances (e.g. when "many" buffers are updated).
Solution:
Use the existing 'busy' buffer-local option as a subtle hint about
activity.
Problem:
The 'autoread' option only checks for file changes reactively — on
FocusGained, :checktime, CmdlineEnter, etc. — by polling timestamps.
External changes are not detected until the user interacts with Neovim.
Solution:
Add a core module (runtime/lua/nvim/autoread.lua) enabled from
runtime/plugin/autoread.lua that watches each buffer's file using
vim._watch.watch() (libuv fs_event). On change detection it calls
:checktime, which invokes the existing buf_check_timestamp() logic
for reload/prompt handling. Watchers are managed via autocmds tied
to buffer lifecycle events and respect the 'autoread' option (global
and buffer-local).
