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:
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:
No lint for strtol().
Solution:
Add lint, and update existing usages.
Callers that previously got a (garbage) large positive value:
- `indent.c`: use getdigits() (intmax, no int truncation) with def=1 so
overflow/too-large values stay positive and fall through to the
existing "too big" check (E475).
- `file_search.c`: use getdigits() with def=255 so overflow/too-large
values keep the "max expand" (else) branch.
The other conversions (api/command.c, eval/window.c, highlight_group.c,
tui/tui.c) only diverge on pathological overflow inputs where strtol's
result was already garbage and the observable outcome is unchanged.
Improve the vim.iter annotations with richer generics that track element and
tuple types through iterator pipelines, including multi-value stages and
list-specific methods.
Extend the LuaCATS parser and vimdoc generator so those richer generic classes
and overloads round-trip into the generated help. These annotations are only
supported by EmmyLua, so LuaLS still uses a broader fallback in _meta.lua.
AI-assisted: Codex
Problem:
`clint.py` is the last python in our codebase, and beyond that it needs
some cleanup. And it lacks tests, so modifying it can be painful.
Also, we need a way to add ad-hoc lint rules for *Lua*, so it will help
to have our ad-hoc rules for C in the same language (the scripts may
share functions/techniques): https://github.com/neovim/neovim/issues/28372
Solution:
- convert to `clint.lua` (mostly AI-generated, but it now has test
coverage, unlike `clint.py`)
- drop rules that are no longer needed:
- "readability/multiline_string"
- technially still relevant, but very uncommon so doesn't really matter.
- "--line-length"
- Not used in the old clint.py, nor the new clint.lua.
- "comment whitespace" check
- It is enforced by uncrustify.
- "TODO" check
- The `-google-readability-function-size` clang-tidy rule enforces
"TODO(user)" format. (It was already enabled long ago.)
- Move all generator Lua scripts to the `src/gen/`
- Add a `.luarc.json` to `src/gen/`
- Add a `preload.lua` to `src/gen/`
- Add `src` to `package.path` so it aligns with `.luarc.json'
- Fix all `require` statements in `src/gen/` so they are consistent:
- `require('scripts.foo')` -> `require('gen.foo')`
- `require('src.nvim.options')` -> `require('nvim.options')`
- `require('api.dispatch_deprecated')` -> `require('nvim.api.dispatch_deprecated')`
Problem:
LSP spec uses the term "position encoding" where we say "offset encoding".
Solution:
- Rename it everywhere except `vim.lsp.Client.offset_encoding` (which would be breaking).
- Mention "position encoding" in the documentation for `vim.lsp.Client.offset_encoding`.
An implication of this current approach is that `NVIM_API_LEVEL` should be
bumped when a new Lua function is added.
TODO(future): add a lint check which requires `@since` on all new functions.
ref #25416
Some composite/compound types even as basic as `(string|number)[]` are
not currently supported by the luacats LPEG grammar used by gen_vimdoc.
It would be parsed & rendered as just `string|number`.
Changeset adds better support for these types.
Problem:
While LuaCATS's generics system are still considered WIP by luals, they
currently support type captured generics.
See "Capture with Backtick" example:
https://luals.github.io/wiki/annotations/#generic
Solution:
Add support for it in the LuaCATS grammar
Specifically, functions that are run in the context of the test runner
are put in module `test/testutil.lua` while the functions that are run
in the context of the test session are put in
`test/functional/testnvim.lua`.
Closes https://github.com/neovim/neovim/issues/27004.
- Added `@inlinedoc` so single use Lua types can be inlined into the
functions docs. E.g.
```lua
--- @class myopts
--- @inlinedoc
---
--- Documentation for some field
--- @field somefield integer
--- @param opts myOpts
function foo(opts)
end
```
Will be rendered as
```
foo(opts)
Parameters:
- {opts} (table) Object with the fields:
- somefield (integer) Documentation
for some field
```
- Marked many classes with with `@nodoc` or `(private)`.
We can eventually introduce these when we want to.
Problem:
The documentation flow (`gen_vimdoc.py`) has several issues:
- it's not very versatile
- depends on doxygen
- doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C.
- The intermediate XML files and filters makes it too much like a rube goldberg machine.
Solution:
Re-implement the flow using Lua, LPEG and treesitter.
- `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic.
- `lua2dox.lua` is gone!
- No more XML files.
- Doxygen is now longer used and instead we now use:
- LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`).
- LPEG for C parsing (see `scripts/cdoc_parser.lua`)
- Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`).
- Treesitter for Markdown parsing (see `scripts/text_utils.lua`).
- The generated `runtime/doc/*.mpack` files have been removed.
- `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly.
- Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change).
