Combined method and class generics does not resolve types properly

[RuiBEAT]

Hello!

First of all, I want to thank you for your work. I recently discovered LuaCATS, and it’s a great system for working with Lua that offers typing and autocompletion.

I’m building my own framework with Lua using concepts like classes, interfaces, exceptions, inheritance, polymorphism… even a bit of IoC via DI. So far, I’ve been adding LuaCATS annotations, and everything has been working correctly. However, right now I’m creating a class that offers methods similar to those in C#’s LINQ, and I’ve hit a snag. Although the hierarchy is much larger, I’ve managed to boil it down to a minimal example that I’d like to share with you. The issue is that this LINQ-style class has a generic type T that defines the types of values it will iterate over. On the other hand, I have an ‘aggregate’ method that has its own generic types, TAccum and TResult. When I use it, I can’t figure out how to ensure everything resolves correctly for the method’s user: either the class generics resolve, or the method generics resolve. Here’s the minimal example:

---@class MyClass<T>
local MyClass = {}

---@generic TAccum, TResult
---@param seed TAccum
---@param accum fun(acc: TAccum, index: integer, value: T): TAccum
---@param result fun(accum: TAccum): TResult
function MyClass:my_func(seed, accum, result)
 -- Whatever...
end


---@type MyClass<string>
local myClass

local res = myClass:my_func("banana", 
   function(acc, index, value)
      return acc .. value
   end, 
   function(acc) 
      return acc
   end)

In the code above, the method's generics are resolved correctly, and accum is displayed with the correct type in the anonymous functions passed as parameters. However, although the class is correctly identified as a MyClass<string>, the anonymous function does not identify the type of T in the parameter, and throws a warning when attempting to return T instead of string. I tried adding the method as a field like this:

---@class MyClass<T>
---@field my_func fun<TAccum, TResult>(self: MyClass<T>, acc: TAccum, accum: (fun(acc: TAccum, index: integer, value: T): TAccum), result: (fun(accum: TAccum): TResult) ): TResult
local MyClass = {}

...and in that case, the type T of the value is recognized correctly, but the generic TAccum of the first parameter is identified as “unknown.” I haven't figured out how to get all of them to resolve correctly. I'd really appreciate it if you could help me out with this.

Thank you in advance for your help!

[RuiBEAT]

I've found that specifying the unspecified self parameter as the class type helps infer the input parameters of methods. However, I still can't get the return parameter type to be inferred. At this point "res" is unknown...

---@generic T
---@class MyClass<T>
local MyClass = {}

---@generic T, TAccum, TResult
---@param self MyClass<T> # This makes the trick
---@param seed TAccum
---@param accum fun(acc: TAccum, index: integer, value: T): TAccum
---@param result fun(accum: TAccum): TResult
function MyClass:my_func(seed, accum, result)
	return result(accum)
end


---@type MyClass<string>
local myClass

local res = myClass:my_func("banana", 
   function(acc, index, value)
      return acc .. value
   end, 
   function(acc) 
      return acc
   end
)

[tomlau10]

I used claude code (with deepseek-v4-flash) to debug this issue.
With a few sessions and I gave it some programmer insight, root cause seems found.
Here is the full analysis report 🤔

edit: PR created: #3439

TL;DR

The Bug

When a generic class method has a @return type referencing method-level generics (not in the class's own generic parameters), the return type resolves to unknown even though Round 1 of the inference engine gets it right.

Minimal reproduction:

---@generic T
---@class MyClass<T>
local MyClass = {}

---@generic R
---@param val R
---@return R                                    -- explicit @return is required
function MyClass:pass(val) return val end

---@type MyClass<string>
local myClass

local res = myClass:pass(42)
-- Expected: integer
-- Actual (without fix): unknown   (R unresolved)

Root Cause

bindReturnOfFunction() has two resolution passes:

1. Round 1 — resolves all generics via the method's sign (R=integer) ✅
2. Receiver block — extracts class generic map {T=string} from the receiver, clones the @return doc with it, and overwrites the result. Since R is not in {T=string}, the cloned node stays unresolved ❌

Fix

Scout before clone. Before cloning the return doc, scan it for doc.generic.name nodes not present in the class genericMap. If found, skip the receiver block and keep Round 1's result.

+local onlyClassGenerics = true
+guide.eachSourceType(rtn, 'doc.generic.name', function(src)
+    if not genericMap[src[1]] then
+        onlyClassGenerics = false
+    end
+end)
+if onlyClassGenerics then
     local newRtn = vm.cloneObject(rtn, genericMap)
     ...
+end

Note

This fix only addresses the overwrite bug — the receiver block undoing Round 1's correct resolution. You must still explicitly annotate your method with ---@return <generic> for the return type to resolve at all. The fix does not infer return types that were never annotated.

toggle to show the detailed report

Generic TResult Resolution Bug in bindReturnOfFunction

Root Cause

In bindReturnOfFunction() (compiler.lua), there are two code paths that resolve the return type:

1. Round 1 (lines ~1687-1718): Full generic resolution via generic:resolve() using the method's sign. This correctly resolves ALL generics (e.g., T=string, R=integer).

2. Receiver self-generic block (lines ~1772-1810): Extracts the class generic map from the receiver's concrete type (e.g., MyClass<string> → {T=string}), then clones the @return annotation with this map. This resolves class-level generics from the receiver's concrete type — essential for cases like:

---@class Box<T>
---@return T  -- T is a class generic, resolved from Box<string>
function Box:getValue() end
local v = b:getValue()  -- v: string ✓ (resolved by receiver block)

The bug: When BOTH paths run, the receiver block always runs after Round 1. Its genericMap only contains class generics (e.g., {T=string}). When it clones the @return R annotation, R is NOT in this map, so the cloned node has no _resolved. This overwrites Round 1's correctly resolved returnNode=integer with an unresolved R, which the downstream source-set code rejects (it refuses to apply unresolved doc.generic.name nodes).

Round 1:  returnNode = integer  ✅  (R resolved via method sign)
   ↓
Receiver block:  returnNode = R(unresolved)  ❌  (R not in {T=string})
   ↓
Source-set:  vm.setNode never called → call.return stays unknown

The Fix

The receiver block is still needed for class-generic-only returns (Box<T> + @return T). But when the return type references method-level generics not in the class genericMap, we should skip the receiver block entirely and keep Round 1's result.

The fix adds a scout before clone: scan the return doc for doc.generic.name nodes, and only proceed with cloning if all referenced generics are present in the class genericMap:

@@ -1752,13 +1752,25 @@
                                             if rtn.returnIndex == index then
-                                                local newRtn = vm.cloneObject(rtn, genericMap)
-                                                if newRtn then
-                                                    returnNode = vm.compileNode(newRtn)
-                                                    for rnode in returnNode:eachObject() do
-                                                        if rnode.type == 'generic' then
-                                                            returnNode = rnode:resolve(guide.getUri(source), args)
-                                                            break
+                                                -- Only clone if the return type only references class-level generics
+                                                -- (i.e. generics that exist in the genericMap from the receiver).
+                                                -- Method-level generics (e.g. V not in {T=string}) are
+                                                -- already resolved correctly in the first round above.
+                                                local onlyClassGenerics = true
+                                                guide.eachSourceType(rtn, 'doc.generic.name', function(src)
+                                                    if not genericMap[src[1]] then
+                                                        onlyClassGenerics = false
+                                                    end
+                                                end)
+                                                if onlyClassGenerics then
+                                                    local newRtn = vm.cloneObject(rtn, genericMap)
+                                                    if newRtn then
+                                                        returnNode = vm.compileNode(newRtn)
+                                                        for rnode in returnNode:eachObject() do
+                                                            if rnode.type == 'generic' then
+                                                                returnNode = rnode:resolve(guide.getUri(source), args)
+                                                                break
+                                                            end
                                                         end
                                                     end
                                                 end

How it works for each case:

Case	Return doc references	Generic map	Scout result	Action
Box<T> + @return T	{T}	{T=string}	All in map ✅	Clone & resolve normally
MyClass<T> + @return R	{R}	{T=string}	R NOT in map ❌	Skip clone, keep Round 1 result
MyClass<T> + @return T, R	{T, R}	{T=string}	R NOT in map ❌	Skip clone, keep Round 1 result
MyClass<T> + @return integer	{}	{T=string}	No generics found ✅	Clone (no-op), same result

Rationale

The receiver block's genericMap only contains class generics extracted from the receiver's concrete type. This is:

• Sufficient for class-generic-only returns (the T is in the map)
• Insufficient when the return type references method-level generics (R is not in the map)

Checking upfront avoids unnecessary cloning and never produces a regression. Round 1's correct resolution is preserved by not running the receiver block when it cannot fully resolve the return type.

Files Changed

• script/vm/compiler.lua — Scout-before-clone guard in bindReturnOfFunction() receiver block (around line 1748)