feat: complete and check the values of declared types

[loaf-scripts]

Changes

Three commits that make the server use the type a value is declared with: completion offers the values the type lists, and assign-type-mismatch reports values the type does not take.

Completion of the values a declared type lists

A value whose type lists what it can be, such as ---@alias State "busy"|"working"|"ready", got no suggestions outside a call. The values are now offered where such a value starts:

• after the = of a local or an assignment, from the ---@type above it or from what the assigned local or class field is declared as,
• after the = of a field in a table typed as a class, from its @field,
• after return, from the @return of the function,
• after == and ~=, from what the other side is declared as.

Details:

• What is listed: strings in quotes, integers as they are, true and false for a boolean, and the nil a listing type allows, last. string? lists nothing.
• Functions: where a function is stored or returned, snippet clients get the function literal with the parameters its fun(...) type names.
• Inside a string: the string values replace the string's contents, including on either side of a comparison.
• Triggers: = and space are trigger characters for these items only; a request triggered by one of them returns nothing else.
• Call arguments: integers, booleans and nil are listed the same way. A typed ( or , still opens the list only for a parameter that lists a string or an integer.
• Not offered: types inferred from assigned values list nothing, and nothing is offered in front of a value that is already written.

---@type lists

A ---@type line that lists several types, as ---@type boolean, string? does above local ok, err = pcall(...), was read up to its first comma, and that one type was given to every name: err was a boolean. The line now types the names one by one, and a name past the end of the list keeps its inferred type. One type still covers every name.

Hovers, the completion above, the class a table constructor is checked against and impossible-comparison follow the type of the name at hand.

assign-type-mismatch for typed variables

The rule only covered the fields of class tables, so a variable took any value whatever its annotation said. It now also checks variables whose type is declared:

---@alias State 1 | 2 | 3 | false | true

---@type State
local state = "test" -- Cannot assign `"test"` to `state` of type `State`

state = "abc"        -- Cannot assign `"abc"` to `state` of type `State`

The rule checks:

• the values of a local or an assignment with a ---@type above it,
• later assignments to a local declared with ---@type,
• later assignments to a parameter documented with @param.

A mismatch is what it is for return-type-mismatch: a different kind of value, or a literal the type does not list. Values whose type is not known pass.

• Declared type, not narrowed: name = "x" inside if not name then passes for a string?.
• nil: = nil needs a type that allows it; a local declared without a value is not reported.
• Calls: a call at the end of the values gives each name the value it returns at that position.
• Not checked: locals without an annotation, and globals in assignments that have no ---@type above them.
• Class fields: a value that a class field rejects is reported once, for the field.

Docs

docs/reference.md has a new "Typed variables" section. docs/rules.md, the rule description, the server README and crates/qbx_lua_ls/docs/protocol.md cover the new completion and the wider rule.

Checks

• cargo fmt --all -- --check and cargo clippy --workspace --all-targets: clean.
• cargo test --workspace: passes at the head of the branch. The ---@type list commit also passes the qbx_luacats and qbx_lua_ls tests on its own.
• New LSP tests values_offer_what_their_declared_type_lists and values_assigned_to_typed_variables_are_checked, and a parser test for ---@type lists.
• For the two diagnostics commits, diffed the published diagnostics before and after on four server trees (QBox, QBcore, ESX and a private one, about 3,800 diagnostics). The only change is two new findings, both a nil stored under a non-optional ---@type. One is in qbx_medical/client/main.lua:51 (---@type number above Hp = nil); the other is in a private resource.
• Checked the State example above against a release build of the server over stdio.
• Not run: a manual check in VS Code.

🤖 Generated with Claude Code