Problem:
- annotation-usage-error and code-style-check are disabled.
- vim.inspect relies on a dummy self-assignment for docgen, and its help
omits parameter and option details.
- LuaLS fallback types obscure iterator inference.
- Docgen hardcodes public function names and appends separately sorted
files, leaving shared helpers under the inspector heading.
Solution:
- Enable annotation-usage-error and code-style-check, and fix misplaced
annotations.
- Document vim.inspect's callable module directly, removing the dummy
assignment. Describe its parameters, option defaults and process
callback.
- Remove LuaLS iterator fallbacks, correct iterator signatures and check
values that the improved inference identifies as optional.
- Parse callable modules, require bindings and parent module references.
Derive public names and inherited function docs from these links,
including missing help for vim.async.semaphore() and vim.version().
- Export vim.lsp.tagfunc directly with lazy loading and document its
implementation instead of maintaining a wrapper.
- Group files in section_order, replacing append_only and merge_files.
Merge declarations before sorting each section, placing shared helpers
in the main vim section and keeping vim.inspect in alphabetical order.
- Add basic parser coverage for callable modules and module links.
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
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:
`inspect_tree()` documents `title` as
`string|fun(bufnr:integer):string|nil`, but the implementation handles
only `nil` and function values. A string title leaves `title` unset and
fails the assertion below.
Solution:
Use the string as the title.
Problem:
Cannot assign Lua functions/closures to "func" ('completefunc',
'tagfun', …) or "expr" ('foldexpr', 'indentexpr', …) options.
Solution:
- Store "func"/"expr" options as `Callback` instead of string.
- Delete oceans of copy-pasted code.
- BREAKING: LuaRef returned via RPC/Vimscript is now represented as
`"<Lua N: file:line>"` (like what `:map` shows) instead of `nil`.
- Note: `man.vim` still uses `v:lua` string, bc it's a vimscript ftplugin.
Helped-by: Lewis Russell <lewis6991@gmail.com>
Problem:
`nvim_create_autocmd` is too verbose and its `callback` requires extra
"nesting".
Solution:
Introduce `nvim_on`. Start using it internally. Then we can get a feel
for how it should look before making it public.
Problem:
`:help dev-name-common` states that "buf" should be used instead of
"buffer" but there are cases where buffer is mentioned in the lua API.
Solution:
- Rename occurrences of "buffer" to "buf" for consistency with the
documentation.
- Support (but deprecate) "buffer" for backwards compatibility.
Co-authored-by: Justin M. Keyes <justinkz@gmail.com>
Problem:
:InspectTree don't show luadoc injection lua file. Since luadoc share
the same "root" with comment in their common primary (lua) tree.
Current logic simply show the largest (comment injection) and ignore all
smaller one (luadoc injection).
Solution:
Handle different lang injections separately. Then sort them by
byte_length to ensure the draw tree consistent.
fix(treesitter): more distinctive highlight for EditQuery captures
Problem: EditQuery shows captures in the source buffer using the Title
highlight group, which could be too similar to Normal.
Solution: Use a virtual text diagnostic highlight group: they are
displayed in a similar manner to the query captures so we can assume
that the color scheme should have appropriate styling applied to make
them visible.
Although powerful -- especially with chained modifiers --, the
readability (and therefore maintainability) of `fnamemodify()` and its
modifiers is often worse than a function name, giving less context and
having to rely on `:h filename-modifiers`. However, it is used plenty in
the Lua stdlib:
- 16x for the basename: `fnamemodify(path, ':t')`
- 7x for the parents: `fnamemodify(path, ':h')`
- 7x for the stem (filename w/o extension): `fnamemodify(path, ':r')`
- 6x for the absolute path: `fnamemodify(path, ':p')`
- 2x for the suffix: `fnamemodify(path, ':e')`
- 2x relative to the home directory: `fnamemodify(path, ':~')`
- 1x relative to the cwd: `fnamemodify(path, ':.')`
The `fs` module in the stdlib provides a cleaner interface for most of
these path operations: `vim.fs.basename` instead of `':t'`,
`vim.fs.dirname` instead of `':h'`, `vim.fs.abspath` instead of `':p'`.
This commit refactors the runtime to use these instead of fnamemodify.
Not all fnamemodify calls are removed; some have intrinsic differences
in behavior with the `vim.fs` replacement or do not yet have a
replacement in the Lua module, i.e. `:~`, `:.`, `:e` and `:r`.
Problem:
When the `#offset!` directive is used with `:EditQuery`, the query does not take the offset into consideration when creating the extmark to preview the capture.
Solution:
Use the capture metadata to modify the node range before creating the extmark.
Problem:
`:EditQuery` command accepts a language argument, but it doesn't
highlight properly for injected languages.
Solution:
- Fully parse with the root language and then filter the query on the
child trees that are of the language requested.
- Also support completion (`EditQuery <tab>`).
Now `:InspectTree` will show missing nodes as e.g. `(MISSING identifier)`
or `(MISSING ";")` rather than just `(identifier)` or `";"`. This is
doable because the `MISSING` keyword is now valid query syntax.
Co-authored-by: Christian Clason <c.clason@uni-graz.at>
Problem: When there is a tree view opened by :InspectTree and the
source buffer is open in multiple windows, closing one of the source
windows will lead to the tree view being closed as well.
Regression by #31181.
Solution: Check how many source windows are open when trying to
quit one. If there are more than one, keep the tree view(s) open.
If the only source window is closed, also close the tree view(s).
fix#31196
Problem: Quitting source buffer for ```:InspectTree``` command raises
```E855``` when source buffer and tree views are the only open buffers.
Solution: Add ```QuitPre``` event to autocmd handling closing/hiding the
source buffer to close all open tree views. This allows nvim to quit
when source and tree buffers are the only open windows.
Problem: The window opened :InspectTree or :EditQuery isn't closed when
the source buffer is unloaded, even though it is closed when
the buffer is hidden.
Solution: Also close the window on BufUnload.
Problem: For :InspectTree, indent size (`&shiftwidth`) for the tree
viewer may be incorrect.
This is because the tree viewer buffer with the filetype `query` does
not explicitly configures the tab size, which can mismatch with the
default indent size (2) assumed by TSTreeView's implementation.
Solution: Set shiftwidth to be the same as TSTreeViewOpts specifies,
which defaults to 2.
Problem:
EditQuery shows swapfile ATTENTION, but this buffer is not intended for
preservation (and the dialog breaks the UX).
Solution:
Set 'noswapfile' on the buffer before renaming it.
**Problem:** `vim.treesitter.get_parser` will throw an error if no parser
can be found.
- This means the caller is responsible for wrapping it in a `pcall`,
which is easy to forget
- It also makes it slightly harder to potentially memoize `get_parser`
in the future
- It's a bit unintuitive since many other `get_*` style functions
conventionally return `nil` if no object is found (e.g. `get_node`,
`get_lang`, `query.get`, etc.)
**Solution:** Return `nil` if no parser can be found or created
- This requires a function signature change, and some new assertions in
places where the parser will always (or should always) be found.
- This commit starts by making this change internally, since it is
breaking. Eventually it will be rolled out to the public API.
**Problem:** With anonymous nodes toggled in the inspect tree, only
named nodes will be highlighted when moving the cursor in the source
code buffer.
**Solution:** Retrieve the anonymous node at the cursor (when toggled on
in the inspect tree) and highlight them when appropriate, for better
clarity/specificity.
Problem:
1. When interacting with multiple :InspectTree and the source buffer
windows there is a high chance of errors due to the window ids not
being updated and validated.
2. Not all InspectTree windows were closed when the source buffer was
closed.
Solution:
1. Update InspectTree window id on `CursorMoved` event and validate
source buffer window id before trying to navigate to it.
2. Close all InspectTree windows
Some parsers for, e.g., LaTeX or PHP have anonymous nodes like `"\"` or `"\text"` that behave wonkily (especially the first example) in the `InspectTree` window, so this PR escapes them by adding another backslash in front of them
- 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:
- `:InspectTree` was showing node ranges in 1-based indexing, i.e., in
vim cursor position (lnum, col). However, treesitter API adopts
0-based indexing to represent ranges (Range4). This can often be
confusing for developers and plugin authors when debugging code
written with treesiter APIs.
Solution:
- Change to 0-based indexing from 1-based indexing to show node ranges
in `:InspectTree`.
- Note: To make things not complicated, we do not provide an option or
keymap to configure which indexing mode to use.
Lewis Russell