can not complete param for "overload" functions

[ZSaberLv0]

How are you using the lua-language-server?

NeoVim

Which OS are you using?

MacOS

What is the issue affecting?

Completion

Expected Behaviour

complete param for all overload functions

Actual Behaviour

can only complete params whose param count exactly matches

Reproduction steps

1. create a lib.lua

   ---@meta test_lib
   
   ---@param p0 string|'aa'|'bb'
   function test(p0) end
   ---@param p0 string|'cc'|'dd'
   ---@param p1 number
   function test(p0, p1) end
   

2. create a test.lua (| is the cursor position)

   test(|)
   

3. input ' (single quote) to complete, and only the first function's p0 can be completed

   

4. if the input is test(|, 0), then the second function's p0 can be completed

   

Additional Notes

No response

Log File

No response

[tomlau10]

Once you inputted a '' there, the function signature is type narrowed to fun(p0: string|'aa'|'bb').
If you don't type '' and trigger completion directly, it should show all the enum values 🤔

I think this is a correct behavior?
otherwise the function type narrow feature will be broken? 😕

---

or maybe you should mark p1 as optional param p1?
then a test('') will not type narrow into fun(p0: string|'aa'|'bb') only
and the completion will give you all aa|bb|cc|dd 🤔

[ZSaberLv0]

it's expected, but not convenient

---

---@meta lib

---@param p0 number
function test(p0) end
---@param p0 string|'aa'|'bb'
---@param p1 number
function test(p0, p1) end

this also can not be completed, so the main issue is the , (param count), not the '' (param type)

maybe, it's better to match candidate functions by param type? ignoring missing params
this should be more convenient, since user usually are inputing following params one by one

[tomlau10]

this also can not be completed, so the main issue is the , (param count), not the '' (param type)

It can be completed, provided that you don't type the '' beforehand.

• such that the current function call has no args
• then the internal function type narrowing don't trigger.
• so in some sense you are right, the param count is one of the factors affecting function type narrow

I can understand the issue here, in which this is not convenient and unintuitive.
But I currently have no idea how to improve it correctly without breaking the exiting function type narrowing feature 😕 .

---

maybe, it's better to match candidate functions by param type ?

I once dug deep into the function type narrow feature related code when I was trying to implement:

• fix: improve function type narrow by checking params' literal identical #2822
• and fix: improve type narrow with literal alias param during completion and signature help #2932

The existing type narrow feature logic is actually quite complicated. ☹
Its not just checking function param count, nor just by param types.

the core logic is vm.getExactMatchedFunctions located in vm/function.lua:

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

Lines 386 to 424 in 119355c

	---@param func parser.object
	---@param args? parser.object[]
	---@return parser.object[]?
	function vm.getExactMatchedFunctions(func, args)
	local funcs = vm.getMatchedFunctions(func, args)
	if not args or not funcs then
	return funcs
	end
	if #funcs == 1 then
	return funcs
	end
	local uri = guide.getUri(func)
	local matchScores = {}
	for i, n in ipairs(funcs) do
	matchScores[i] = calcFunctionMatchScore(uri, args, n)
	end
	local maxMatchScore = math.max(table.unpack(matchScores))
	if maxMatchScore == -1 then
	-- all should be removed
	return nil
	end
	local minMatchScore = math.min(table.unpack(matchScores))
	if minMatchScore == maxMatchScore then
	-- all should be kept
	return funcs
	end
	-- remove functions that have matchScore < maxMatchScore
	local needRemove = {}
	for i, matchScore in ipairs(matchScores) do
	if matchScore < maxMatchScore then
	needRemove[#needRemove + 1] = i
	end
	end
	util.tableMultiRemove(funcs, needRemove)
	return funcs
	end

• it will first call vm.getMatchedFunctions to check if the call argument count matched any candidate functions' signature.
  • If they are not matched, then that function will be filtered out
  • in this 1st pass, no param type is considered
• Besides, you can see that there is a if not args => return (all) funcs early return logic
  This probably explains that if you don't type '' when you trigger completion, you can get completion of all function candidates.

now let's take a look into vm.getMatchedFunctions

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

Lines 426 to 455 in 119355c

	---@param func parser.object
	---@param args? parser.object[]
	---@param mark? table
	---@return parser.object[]?
	function vm.getMatchedFunctions(func, args, mark)
	local funcs = {}
	local node = vm.compileNode(func)
	for n in node:eachObject() do
	if n.type == 'function'
	or n.type == 'doc.type.function' then
	funcs[#funcs+1] = n
	end
	end
	local amin, amax = vm.countList(args, mark)
	local matched = {}
	for _, n in ipairs(funcs) do
	local min, max = vm.countParamsOfFunction(n)
	if amin >= min and amax <= max then
	matched[#matched+1] = n
	end
	end
	if #matched == 0 then
	return nil
	else
	return matched
	end
	end

• local amin, amax = vm.countList(args, mark) means the current function call signature's min/max arg count
  => this will be 1, 1 for test(''), because there is already 1 argument supplied
• then it will test against all function candidates
  • for fun test(p0) => 1, 1 (min arg is 1, max arg is also 1)
  • for fun test(p0, p1) => 2, 2 (min/max arg requires 2)
  • => that's why fun test(p0, p1) is filtered out when you type test('')

removing the checking for argument count?

• I tried to remove the whole argument count, by just doing do return funcs end after the 1st forloop of vm.getMatchedFunctions

 function vm.getMatchedFunctions(func, args, mark) 
     local funcs = {} 
     local node = vm.compileNode(func) 
     for n in node:eachObject() do 
         if n.type == 'function' 
         or n.type == 'doc.type.function' then 
             funcs[#funcs+1] = n 
         end 
     end 
+    do return funcs end

• this makes your completion works! 👀
  but... will randomly trigger some unknow errors in the later part of the logic 😇
• so current I have no idea how to properly fix/optimize this
• might require help from extension authors 🙈

[tomlau10]

🤔 Just another idea:

• need a way to detect that we are doing argument completion inside the logic of vm.getMatchedFunctions
• and when we are doing completion, we should ignore the amin >= min check
  i.e. we are still in the middle of typing the function call => don't limit matched functions by looking the min argument requirement
• in this way, when we are completing the 1st argument of test('')
  it should match both the test(p0) and test(p0, p1) signatures, to provide the completion items

but I have no idea how to implement the during argument completion detection 😕

---

edit

seems it cannot work this way 😇

• I tried to print the traceback when triggering argument completion
• it will first compile call.node which is the already type narrowed state of the call test('')
  => function test(p0: number)
  and then try to find out what are the possible values in 1st arg position
• since in the current function type narrow logic, a test('') will be narrowed to function test(p0: number)
  (due to existing param count, function test(p0: string|'aa'|'bb', p1: number) is filtered out)
  => no 'aa'|'bb' will appear in function function param list
• this compile state is cached, and is not triggered every time you do completion
  so detecting we are doing argument completion approach will not work

[tomlau10]

I still think that this is somewhat unachievable 😇

• Let's say we remove the argument count checking when doing function type narrow
• Consider the following snippet

---@meta lib

---@param p0 number
---@return number
function test(p0) end

---@param p0 number
---@param p1 'aa'|'bb'
---@return string
function test(p0, p1) end

• both overload has p0: number as 1st arg
• but they will have different return values depending on 2nd arg exists or not
• the expected function type narrow behavior

local r1 = test(0) --> r1: number
local r2 = test(0, 'aa') --> r2: string

• but ⚠ if we remove the argument count check in type narrow
  then test(0) will not be narrowed to fun(p0: number): number
  it will have both signatures fun(p0: number): number, fun(p0: number, p1: 'aa'|bb'): string
  since no more signature filter based on arguments count

local r1 = test(0) --> r1: number|string

=> the return type will then be inaccurate 🐛

---

but I found an non-perfect fix

at least for the use case when completing the 1st arg 🤔

• I noticed that after doing function type narrow in matchCall() of vm/compiler.lua
  the original unfiltered function signatures are stored in newNode.originNode
  

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

  Lines 654 to 685 in 119355c

  	---@param source parser.object
  	local function matchCall(source)
  	local call = source.parent
  	if not call
  	or call.type ~= 'call'
  	or call.node ~= source then
  	return
  	end
  	local myNode = vm.getNode(source)
  	if not myNode then
  	return
  	end
  	local funcs = vm.getExactMatchedFunctions(source, call.args)
  	if not funcs then
  	return
  	end
  	local needRemove
  	for n in myNode:eachObject() do
  	if n.type == 'function'
  	or n.type == 'doc.type.function' then
  	if not util.arrayHas(funcs, n) then
  	if not needRemove then
  	needRemove = vm.createNode()
  	end
  	needRemove:merge(n)
  	end
  	end
  	end
  	if needRemove then
  	local newNode = myNode:copy()
  	newNode:removeNode(needRemove)
  	newNode.originNode = myNode

• then during the compilation of a call arg, we can check if we are completing at 1st arg position
  if true => we use this unfiltered callNode.originNode to get all possible values
  otherwise => keep the existing behavior which only get possible values from filtered function list
  

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

  Lines 1096 to 1114 in 119355c

  	---@param arg parser.object
  	---@param call parser.object
  	---@param index? integer
  	---@return vm.node?
  	function vm.compileCallArg(arg, call, index)
  	if not index then
  	for i, carg in ipairs(call.args) do
  	if carg == arg then
  	index = i
  	break
  	end
  	end
  	if not index then
  	return nil
  	end
  	end
  	local callNode = vm.compileNode(call.node)
  	compileCallArgNode(arg, call, callNode, 0, index)

       local callNode = vm.compileNode(call.node)
  +    if index == 1 and call.args and #call.args == 1 then
  +        -- when completing the 1st arg and we only typed 1 arg so far
  +        -- we want all possible values from all function signatures
  +        callNode = callNode.originNode or callNode
  +    end
       compileCallArgNode(arg, call, callNode, 0, index)

• this can fix the case that, when completing the 1st arg and we only typed 1 arg so far
  => we should always use all possible values from all function signatures 🤔