Add class-level generic constraints, subtype check for generic parents, and iterator fixes

- Parse constraints in class sign parameters: @Class Foo<T: Button>
  now stores T's constraint (extends) for display and future use
- Add doc.generic.name to child map in guide.lua so constraint
  types are walked by the compiler
- Auto-bind class-level generics to methods via post-pass in bindDocs,
  so methods without @Generic inherit their class's type parameters
- Fix subtype check for generic class parents: Child : Parent<T> is
  now recognized as subtype of Parent (handles doc.type.sign extends)
- Fix V[] matching T[] in iterator resolution when T is a generic name
  (direct assignment bypassing resolve() filter)
- Add tests for isearch/ipairs with T[] field types

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: RomanSpector

script/parser/guide.lua

@@ -175,6 +175,7 @@ local childMap = {
     ['doc.field']          = {'field', 'extends', 'comment'},
     ['doc.generic']        = {'#generics', 'comment'},
     ['doc.generic.object'] = {'generic', 'extends', 'comment'},
+    ['doc.generic.name']   = {'extends'},
     ['doc.vararg']         = {'vararg', 'comment'},
     ['doc.type.array']     = {'node'},
     ['doc.type.function']  = {'#args', '#returns', '#signs', 'comment'},

script/parser/luadoc.lua

@@ -485,6 +485,11 @@ local function parseSigns(parent)
             }
             break
         end
+        -- Parse optional constraint: <T: Button>
+        if checkToken('symbol', ':', 1) then
+            nextToken()
+            sign.extends = parseType(sign)
+        end
         signs[#signs+1] = sign
         if checkToken('symbol', ',', 1) then
             nextToken()
@@ -2253,6 +2258,81 @@ local function bindDocs(state)
             end
         end
     end
+
+    -- Second pass: bind class-level generic parameters for methods.
+    -- When a method like QernelContainerTemplate:OnHide has no @generic T,
+    -- the T comes from @class QernelContainerTemplate<T: Button>.
+    local classGenerics = {}
+    for _, doc in ipairs(state.ast.docs) do
+        if doc.type == 'doc.class' and doc.signs then
+            local className = doc.class[1]
+            if className then
+                local signs = {}
+                for _, sign in ipairs(doc.signs) do
+                    signs[sign[1]] = sign
+                end
+                if next(signs) then
+                    classGenerics[className] = signs
+                end
+            end
+        end
+    end
+    if next(classGenerics) then
+        for _, group in ipairs(state.ast.docs.groups) do
+            -- Find the bind source (the function/assignment this doc is attached to)
+            local bindSource
+            for _, doc in ipairs(group) do
+                if doc.bindSource then
+                    bindSource = doc.bindSource
+                    break
+                end
+            end
+            if not bindSource then
+                goto NEXT_GROUP
+            end
+            -- Get the class name from setmethod/setfield source
+            local parent = bindSource.type == 'function'
+                       and bindSource.parent
+            if not parent then
+                goto NEXT_GROUP
+            end
+            local className
+            if parent.type == 'setmethod' or parent.type == 'setfield' then
+                className = parent.node and guide.getKeyName(parent.node)
+            end
+            if not className or not classGenerics[className] then
+                goto NEXT_GROUP
+            end
+            -- Skip if this group already has its own @generic
+            local hasOwnGeneric = false
+            for _, doc in ipairs(group) do
+                if doc.type == 'doc.generic' then
+                    hasOwnGeneric = true
+                    break
+                end
+            end
+            if hasOwnGeneric then
+                goto NEXT_GROUP
+            end
+            -- Bind class-level generics to type names in this group
+            local signs = classGenerics[className]
+            for _, doc in ipairs(group) do
+                if doc.type == 'doc.param'
+                or doc.type == 'doc.return'
+                or doc.type == 'doc.type'
+                or doc.type == 'doc.field'
+                or doc.type == 'doc.overload' then
+                    guide.eachSourceType(doc, 'doc.type.name', function (src)
+                        if signs[src[1]] then
+                            src.type = 'doc.generic.name'
+                            src.generic = signs[src[1]]
+                        end
+                    end)
+                end
+            end
+            ::NEXT_GROUP::
+        end
+    end
 end
 
 local function findTouch(state, doc)

script/vm/sign.lua

@@ -173,8 +173,22 @@ function mt:resolve(uri, args)
             if not handled then
                 for n in node:eachObject() do
                     if n.type == 'doc.type.array' then
-                        -- number[] -> T[]
-                        resolve(object.node, vm.compileNode(n.node))
+                        -- number[] -> T[], or T[] -> V[] (generic element)
+                        local elementNode = vm.compileNode(n.node)
+                        -- When element is a generic name (T[] matching V[]),
+                        -- assign directly since resolve() filters generics
+                        if object.node and object.node.type == 'doc.generic.name' then
+                            local vKey = object.node[1]
+                            for en in elementNode:eachObject() do
+                                if en.type == 'doc.generic.name' then
+                                    resolved[vKey] = vm.createNode(en, resolved[vKey])
+                                    handled = true
+                                end
+                            end
+                        end
+                        if not handled then
+                            resolve(object.node, elementNode)
+                        end
                     elseif n.type == 'doc.type.table' then
                         -- { [integer]: number } -> T[]
                         local tvalueNode = vm.getTableValue(uri, node, 'integer', true)

script/vm/type.lua

@@ -595,6 +595,14 @@ function vm.isSubType(uri, child, parent, mark, errs)
                             mark[childName] = nil
                             return true
                         end
+                        -- Handle generic class parents: Child : Parent<T>
+                        if  ext.type == 'doc.type.sign'
+                        and ext.node and ext.node[1]
+                        and (not isBasicType or guide.isBasicType(ext.node[1]))
+                        and vm.isSubType(uri, ext.node[1], parent, mark, errs) == true then
+                            mark[childName] = nil
+                            return true
+                        end
                     end
                 end
             end

test/type_inference/common.lua

@@ -951,6 +951,74 @@ function listB:foo()
 end
 ]]
 
+TEST '<T>' [[
+---@generic T: table, V
+---@param t T
+---@return fun(table: V[]): V
+---@return T
+local function isearch(t) end
+
+---@class listC<T>: {[integer]:T}
+
+---@generic T
+---@param self listC<T>
+function listC:foo()
+    for <?v?> in isearch(self) do
+    end
+end
+]]
+
+-- Test: field access inside class method
+TEST 'string[]' [[
+---@class listD0
+---@field buttons string[]
+local listD0 = {}
+
+function listD0:foo()
+    local <?b?> = self.buttons
+end
+]]
+
+-- With T[] field type
+TEST '<T>' [[
+---@generic T: table, V
+---@param t T
+---@return fun(table: V[]): V
+---@return T
+local function isearch(t) end
+
+---@class listD<T>: {[integer]:T}
+---@field buttons T[]
+local listD = {}
+
+function listD:foo()
+    for <?v?> in isearch(self.buttons) do
+    end
+end
+]]
+
+-- With list<T> field type — concrete (should work)
+TEST 'string' [[
+---@generic T: table, V
+---@param t T
+---@return fun(table: V[]): V
+---@return T
+local function isearch(t) end
+
+---@class listE<T>: {[integer]:T}
+
+---@type listE<string>
+local strings
+
+for <?v?> in isearch(strings) do
+end
+]]
+
+-- TODO: nested generic resolution (listF<T> field) not yet supported
+-- When @field buttons listF<T>, iterating gives the whole table type
+-- instead of the element. This requires resolving V through nested
+-- generic sign parameters.
+
 TEST 'boolean' [[
 ---@generic T: table, K, V
 ---@param t T