Adding an overload to an @class changes the result and gives type errors.

[MatthewBlanchard]

How are you using the lua-language-server?

Visual Studio Code Extension (sumneko.lua)

Which OS are you using?

Linux

What is the issue affecting?

Type Checking

Expected Behaviour

Adding an Overload under ---@Class should not change anything about how the type is handled.

Actual Behaviour

Here we have a class declaration and it's exactly how I want.

Adding an overload for the constructor generates warnings? Doesn't really make any sense.

Reproduction steps

Use ---@Class to define a class.
Add ---@overload.
Make sure the class library you're using returns anything but any when extending or creating a new class.

Additional Notes

No response

Log File

No response

[Luke100000]

I debugged into this, understood only half of it, but the problem is that the function type (the overload) does not match its class (expected).

So I assume we need to accept the overload as a valid subtype of its class in function vm.isSubType(uri, child, parent, mark, errs) in vm/type.lua?

For example, right before the last return false:

if parent.cate == "type" and child.type == "doc.type.function" then
    return true
end

I'm certain that this exception is not narrow enough tho.

[tomlau10]

Observation 1

First of all, I found that after enabling type.weakUnionCheck setting, the warning is gone 🤔

• I assume prism.Object:extend() returns Object type
• and then the Row variable with @class and @overload causes this variable to be of type Class | fun():Class
• when type.weakUnionCheck is false (default), the assigned value (Object) must be subtype of all union types
  => clearly Object cannot match fun():Class
• when type.weakUnionCheck is true, the assigned value (Object) only need to match one of the union types
  => Object can match Class, so no warning is generated

Observation 2

Next I found that separating @class / @overload annotation with the assignment statement doesn't generate this warning as well 🤔🤔

---@class Object
local Object = {}

---@return Object
function Object:extend(name)
    return {}
end

---@class Row: Object
---@overload fun(depth: integer, start_slope: number, end_slope: number): Row

---@class Row
local Row = Object:extend("Row") -- no warning
local r = Row() --> r: Row

• so it seems that @overload is attached to the @class instead of the Row variable
• and this warning only generates when writing the @overload with the assignment statement together

edit:

Next I found that separating @Class / @overload annotation with the assignment statement doesn't generate this warning as well 🤔🤔

Seems separating the annotation and assignment statement has some side effect ... 😇

• the standard way

---@class Row: Object
---@overload fun(depth: integer, start_slope: number, end_slope: number): Row
local Row = Object:extend("Row")
local r = Row() --> missing-parameter: This function requires 3 argument(s) but instead it is receiving 0.

• the separated way

---@class Row: Object
---@overload fun(depth: integer, start_slope: number, end_slope: number): Row

---@class Row
local Row = Object:extend("Row")
local r = Row() --> no warning !!

Observation 3

By adding --showsource and --shownode launch flag, some extra debug information will be shown when hovering over the variable. You can add a .vscode/settings.json with the following:

{
    "Lua.misc.parameters": [
        "--showsource",
        "--shownode",
    ],
}

• When writing @overload together with the variable assignment, Row WILL have the doc.type.function infer type
• while writing @overload and variable assignment separately, Row WILL NOT have the function infer type

---

Some thoughts

Since writing @class with @overload and the assignment separately will not affect the function call infer behavior, I think something might be done in the step of parsing the luadocs and binding those annotation to variables. 🤔

• When a variable is annotated with @class, the middle @overload should not be binded to the variable
  => such that the @overload is attached to the class itself, not the variable
• then when the variable doesn't have doc.type.function, no modification is required in function vm.isSubType
• this might be a better way to solve this issue 😄

[tomlau10]

I think I have found a way 🎉

The special handling

• In general we cannot assign a parent class type to a child class type variable

---@class Parent
local Parent = {}

---@class Child: Parent
local Child = {}

---@type Child
local c = Parent -- assign-type-mismatch

• But that's the special handling which allow this when the variable has a @class annotation:
  

  lua-language-server/script/core/diagnostics/assign-type-mismatch.lua

  Lines 105 to 110 in 8d3a4c8

  	-- local Cat = setmetatable({}, {__index = Animal}) 允许逆变
  	if hasMarkClass(source) then
  	if vm.canCastType(uri, valueNode:copy():remove 'table', varNode) then
  	return
  	end
  	end

---@class Parent
local Parent = {}

---@class Child: Parent
local Child = Parent -- the above logic allows this assignment statement
-- because the `Child` variable has a `@class` annotation, and `Child` is a subtype of `Parent`

The proposed solution

So in the above special handling code, we might as well remove the function type in a copy of varNode:

 -- local Cat = setmetatable({}, {__index = Animal}) 允许逆变
 if hasMarkClass(source) then
-    if vm.canCastType(uri, valueNode:copy():remove 'table', varNode) then
+    if vm.canCastType(uri, valueNode:copy():remove 'table', varNode:copy():remove 'function') then
         return
     end
 end

• This way we can ignore the function type when checking the type casting, and can solve this issue 👀
• I didn't dive deep into testing whether this will break things or not, maybe @Luke100000 would like to pick it up from here 😄

[Luke100000]

Thanks @tomlau10 ! With a mix of all 3 observations, I can avoid most issues now :)

Your fix tackles the assignment error, but I found another side effect of overloading:

---@class (exact) MetaClass
---@overload fun(): MetaClass
local MetaClass = { }

setmetatable({}, MetaClass)

It will now complain that MetaClass is not a table, which is true, but without an overload it would not complain.
So I'm not certain whether this is something to fix on a per-diagnosis level, or directly in the type checker.
Didn't test that but using weak union check as you found out probably shuts that off as well.

[tomlau10]

So I'm not certain whether this is something to fix on a per-diagnosis level, or directly in the type checker.

That's a good point 🤔

---

With some more digging in the codebase, I just found another approach:

• when the overload is attached to a class, the annotation object is marked with hideView = true
  

  lua-language-server/script/vm/compiler.lua

  Lines 23 to 39 in 7f76050

  	function vm.bindDocs(source)
  	local docs = source.bindDocs
  	if not docs then
  	return false
  	end
  	for i = #docs, 1, -1 do
  	local doc = docs[i]
  	if doc.type == 'doc.type' then
  	vm.setNode(source, vm.compileNode(doc))
  	return true
  	end
  	if doc.type == 'doc.class' then
  	vm.setNode(source, vm.compileNode(doc))
  	for j = i + 1, #docs do
  	local overload = docs[j]
  	if overload.type == 'doc.overload' then
  	overload.overload.hideView = true

• the hideView attribute is only used here, so we might just skip checking type object if it has hideView attribute inside vm.isSubType logic ?
  

  lua-language-server/script/vm/type.lua

  Lines 421 to 423 in 7f76050

  	if nodeName
  	and not (nodeName == 'nil' and weakNil) and not (skipTable and n.type == 'table')
  	and vm.isSubType(uri, n, parent, mark, errs) == false then

     if  nodeName 
+    and not n.hideView
     and not (nodeName == 'nil' and weakNil) and not (skipTable and n.type == 'table') 
     and vm.isSubType(uri, n, parent, mark, errs) == false then 

---

I tried and this approach solved both the assign-type-mismatch and param-type-mismatch cases 👀 @Luke100000