php_extractor.lua

-- PHP-specific Tree-sitter extraction for code graph indexing
-- Extracts: namespace, imports, class/interface/trait definitions,
--           methods, functions, and all reference types
-- Entry kind: library.lua

local treesitter = require("treesitter")

---------------------------------------------------------------------------
-- Tree-sitter query patterns for PHP definitions
---------------------------------------------------------------------------

local def_queries = {}

-- Namespace declaration
def_queries.namespace = [[
    (namespace_definition
        name: (namespace_name) @name
    ) @ns
]]

-- Classes with optional extends/implements
def_queries.classes = [[
    (class_declaration
        name: (name) @name
    ) @class
]]

-- Interfaces
def_queries.interfaces = [[
    (interface_declaration
        name: (name) @name
    ) @interface
]]

-- Traits
def_queries.traits = [[
    (trait_declaration
        name: (name) @name
    ) @trait
]]

-- Enums
def_queries.enums = [[
    (enum_declaration
        name: (name) @name
    ) @enum
]]

-- Methods inside classes/interfaces/traits
def_queries.methods = [[
    (method_declaration
        name: (name) @name
    ) @method
]]

-- Top-level functions
def_queries.functions = [[
    (function_definition
        name: (name) @name
    ) @func
]]

-- Class constants
def_queries.class_constants = [[
    (class_declaration
        body: (declaration_list
            (const_declaration
                (const_element
                    name: (name) @name
                )
            ) @const
        )
    )
]]

---------------------------------------------------------------------------
-- Tree-sitter query patterns for PHP references
---------------------------------------------------------------------------

local ref_queries = {}

-- use statements (imports)
ref_queries.imports = [[
    (namespace_use_declaration) @use_decl
]]

-- new ClassName(...)
ref_queries.instantiations = [[
    (object_creation_expression
        (name) @class
    ) @new

    (object_creation_expression
        (qualified_name) @class
    ) @new_qualified
]]

-- ClassName::method() — static calls
ref_queries.static_calls = [[
    (scoped_call_expression
        scope: (name) @class
        name: (name) @method
    ) @static_call

    (scoped_call_expression
        scope: (qualified_name) @class
        name: (name) @method
    ) @static_call_qualified
]]

-- ClassName::$prop or ClassName::CONST
ref_queries.static_access = [[
    (scoped_property_access_expression
        scope: (name) @class
        name: (name) @property
    ) @static_prop
]]

-- $obj->method()
ref_queries.member_calls = [[
    (member_call_expression
        object: (variable_name) @object
        name: (name) @method
    ) @member_call
]]

-- $obj->property
ref_queries.member_access = [[
    (member_access_expression
        object: (variable_name) @object
        name: (name) @property
    ) @member_access
]]

-- Type hints in parameters
ref_queries.param_types = [[
    (simple_parameter
        type: (named_type (name) @type)
    ) @param

    (simple_parameter
        type: (optional_type (named_type (name) @type))
    ) @nullable_param

    (simple_parameter
        type: (union_type (named_type (name) @type))
    ) @union_param
]]

-- Return types
ref_queries.return_types = [[
    (function_definition
        return_type: (named_type (name) @type)
    ) @func_return

    (method_declaration
        return_type: (named_type (name) @type)
    ) @method_return

    (function_definition
        return_type: (union_type (named_type (name) @type))
    ) @func_union_return

    (method_declaration
        return_type: (union_type (named_type (name) @type))
    ) @method_union_return
]]

-- Property type declarations
ref_queries.property_types = [[
    (property_declaration
        type: (named_type (name) @type)
    ) @prop_type

    (property_declaration
        type: (optional_type (named_type (name) @type))
    ) @nullable_prop
]]

-- extends
ref_queries["extends"] = [[
    (class_declaration
        (base_clause
            (name) @parent
        )
    ) @extends

    (class_declaration
        (base_clause
            (qualified_name) @parent
        )
    ) @extends_qualified

    (interface_declaration
        (base_clause
            (name) @parent
        )
    ) @iface_extends
]]

-- implements
ref_queries["implements"] = [[
    (class_declaration
        (class_interface_clause
            (name) @interface
        )
    ) @implements

    (class_declaration
        (class_interface_clause
            (qualified_name) @interface
        )
    ) @implements_qualified
]]

-- use TraitName inside class body
ref_queries.trait_use = [[
    (use_declaration
        (name) @trait
    ) @use_trait

    (use_declaration
        (qualified_name) @trait
    ) @use_trait_qualified
]]

-- instanceof
ref_queries.instanceof = [[
    (instanceof_expression
        right: (name) @class
    ) @instanceof

    (instanceof_expression
        right: (qualified_name) @class
    ) @instanceof_qualified
]]

-- catch (ExceptionType $e)
ref_queries.catch_types = [[
    (catch_clause
        type: (type_list
            (named_type (name) @type)
        )
    ) @catch

    (catch_clause
        type: (type_list
            (named_type (qualified_name) @type)
        )
    ) @catch_qualified
]]

-- Plain function calls
ref_queries.function_calls = [[
    (function_call_expression
        function: (name) @func
    ) @call

    (function_call_expression
        function: (qualified_name) @func
    ) @qualified_call
]]

---------------------------------------------------------------------------
-- Safe query execution
---------------------------------------------------------------------------

local function safe_captures(lang, pattern, root, code)
    if not pattern then return {} end
    local query, err = treesitter.query(lang, pattern)
    if err then return {} end
    local captures = query:captures(root, code)
    return captures or {}
end

local function group_by_name(captures)
    local groups = {}
    for _, cap in ipairs(captures) do
        if not groups[cap.name] then
            groups[cap.name] = {}
        end
        table.insert(groups[cap.name], cap)
    end
    return groups
end

---------------------------------------------------------------------------
-- High-level extraction: definitions
---------------------------------------------------------------------------

--- Extract the namespace from a parsed PHP file
-- @param root Node  Root node of parsed tree
-- @param code string  Source code
-- @return string|nil  Namespace string
local function extract_namespace(root, code)
    local caps = safe_captures("php", def_queries.namespace, root, code)
    local groups = group_by_name(caps)
    if groups["name"] and #groups["name"] > 0 then
        return groups["name"][1].text
    end
    return nil
end

--- Extract use/import statements
-- @param root Node
-- @param code string
-- @return {Import}  Array of {fqn, alias}
local function extract_imports(root, code)
    local caps = safe_captures("php", ref_queries.imports, root, code)
    local groups = group_by_name(caps)
    local imports = {}

    local decls = groups["use_decl"] or {}
    for _, decl in ipairs(decls) do
        -- Parse the use declaration text to extract FQN and optional alias
        local text = decl.text
        -- Remove "use " prefix and trailing ";"
        local body = string.match(text, "^use%s+(.+);%s*$")
        if body then
            -- Handle grouped use: use Foo\{Bar, Baz}
            local prefix, group = string.match(body, "^(.+)\\{(.+)}$")
            if prefix and group then
                for item in string.gmatch(group, "([^,]+)") do
                    item = string.match(item, "^%s*(.-)%s*$") -- trim
                    local name, alias = string.match(item, "^(.+)%s+as%s+(.+)$")
                    if not name then name = item end
                    local fqn = prefix .. "\\" .. name
                    fqn = string.gsub(fqn, "^\\", "")
                    table.insert(imports, {
                        fqn = fqn,
                        alias = alias,
                    })
                end
            else
                -- Single use: use Foo\Bar or use Foo\Bar as Baz
                -- May also be: use function Foo\bar or use const Foo\BAR
                local kind_prefix = string.match(body, "^(function%s+)")
                    or string.match(body, "^(const%s+)")
                if kind_prefix then
                    body = string.sub(body, #kind_prefix + 1)
                end

                local name, alias = string.match(body, "^(.+)%s+as%s+(.+)$")
                if not name then name = body end
                name = string.match(name, "^%s*(.-)%s*$") -- trim
                name = string.gsub(name, "^\\", "")
                table.insert(imports, {
                    fqn = name,
                    alias = alias and string.match(alias, "^%s*(.-)%s*$"),
                })
            end
        end
    end

    return imports
end

--- Get node start/end positions
local function node_pos(node)
    local sp = node:start_point()
    local ep = node:end_point()
    return sp.row + 1, ep.row + 1
end

--- Extract class/interface/trait/enum definitions
-- @param root Node
-- @param code string
-- @param namespace string|nil
-- @return {Symbol}  Array of type symbols
local function extract_types(root, code, namespace)
    local symbols = {}

    local type_configs = {
        {query = def_queries.classes, kind = "class"},
        {query = def_queries.interfaces, kind = "interface"},
        {query = def_queries.traits, kind = "trait"},
        {query = def_queries.enums, kind = "enum"},
    }

    for _, cfg in ipairs(type_configs) do
        local caps = safe_captures("php", cfg.query, root, code)
        local groups = group_by_name(caps)
        local names = groups["name"] or {}
        local decls = groups[cfg.kind] or {}

        for i, name_cap in ipairs(names) do
            local short_name = name_cap.text
            local fqn = namespace and (namespace .. "\\" .. short_name) or short_name
            local decl = decls[i]
            local line, end_line = node_pos(decl and decl.node or name_cap.node)

            local sym = {
                id = fqn,
                name = short_name,
                kind = cfg.kind,
                line = line,
                end_line = end_line,
                namespace = namespace,
            }

            table.insert(symbols, sym)
        end
    end

    return symbols
end

--- Extract method definitions (needs parent class context)
-- @param root Node
-- @param code string
-- @param namespace string|nil
-- @return {Symbol}  Array of method symbols with parent info to be resolved later
local function extract_methods(root, code, namespace)
    local symbols = {}
    local caps = safe_captures("php", def_queries.methods, root, code)
    local groups = group_by_name(caps)
    local names = groups["name"] or {}
    local decls = groups["method"] or {}

    for i, name_cap in ipairs(names) do
        local short_name = name_cap.text
        local decl = decls[i]
        local line, end_line = node_pos(decl and decl.node or name_cap.node)

        -- Walk up from method to find enclosing class/interface/trait
        local parent_name = nil
        local parent_node = name_cap.node:parent()
        while parent_node do
            local kind = parent_node:kind()
            if kind == "class_declaration"
                or kind == "interface_declaration"
                or kind == "trait_declaration"
                or kind == "enum_declaration" then
                local name_child = parent_node:child_by_field_name("name")
                if name_child then
                    parent_name = name_child:text()
                end
                break
            end
            parent_node = parent_node:parent()
        end

        local parent_fqn = nil
        if parent_name then
            parent_fqn = namespace and (namespace .. "\\" .. parent_name) or parent_name
        end

        local method_id = parent_fqn
            and (parent_fqn .. "::" .. short_name)
            or short_name

        -- Detect visibility from the method declaration node
        local visibility = "public"
        if decl and decl.node then
            local decl_text = decl.text or ""
            if string.find(decl_text, "^%s*private") then
                visibility = "private"
            elseif string.find(decl_text, "^%s*protected") then
                visibility = "protected"
            end
        end

        local is_static = false
        if decl and decl.text then
            is_static = string.find(decl.text, "static%s") ~= nil
        end

        table.insert(symbols, {
            id = method_id,
            name = short_name,
            kind = "method",
            line = line,
            end_line = end_line,
            namespace = namespace,
            parent = parent_fqn,
            visibility = visibility,
            is_static = is_static,
        })
    end

    return symbols
end

--- Extract top-level function definitions
-- @param root Node
-- @param code string
-- @param namespace string|nil
-- @return {Symbol}
local function extract_functions(root, code, namespace)
    local symbols = {}
    local caps = safe_captures("php", def_queries.functions, root, code)
    local groups = group_by_name(caps)
    local names = groups["name"] or {}
    local decls = groups["func"] or {}

    for i, name_cap in ipairs(names) do
        local short_name = name_cap.text
        local fqn = namespace and (namespace .. "\\" .. short_name) or short_name
        local decl = decls[i]
        local line, end_line = node_pos(decl and decl.node or name_cap.node)

        table.insert(symbols, {
            id = fqn,
            name = short_name,
            kind = "function",
            line = line,
            end_line = end_line,
            namespace = namespace,
        })
    end

    return symbols
end

---------------------------------------------------------------------------
-- High-level extraction: references
---------------------------------------------------------------------------

--- Find the enclosing symbol (class::method or function) for a node
local function find_enclosing_symbol(node, namespace)
    local current = node:parent()
    local method_name = nil
    local class_name = nil

    while current do
        local kind = current:kind()
        if kind == "method_declaration" and not method_name then
            local n = current:child_by_field_name("name")
            if n then method_name = n:text() end
        elseif kind == "function_definition" and not method_name then
            local n = current:child_by_field_name("name")
            if n then
                local fn_name = n:text()
                return namespace and (namespace .. "\\" .. fn_name) or fn_name
            end
        elseif (kind == "class_declaration"
            or kind == "interface_declaration"
            or kind == "trait_declaration"
            or kind == "enum_declaration") then
            local n = current:child_by_field_name("name")
            if n then class_name = n:text() end
            break
        end
        current = current:parent()
    end

    if class_name then
        local fqn = namespace and (namespace .. "\\" .. class_name) or class_name
        if method_name then
            return fqn .. "::" .. method_name
        end
        return fqn
    end

    return nil
end

--- Extract all references from a parsed PHP file
-- @param root Node
-- @param code string
-- @param file_path string
-- @param namespace string|nil
-- @return {Reference}
local function extract_references(root, code, file_path, namespace)
    local refs = {}

    -- Helper to add references from a query
    local function collect(query_pattern, ref_kind, capture_name)
        local caps = safe_captures("php", query_pattern, root, code)
        local groups = group_by_name(caps)
        local targets = groups[capture_name] or {}

        for _, cap in ipairs(targets) do
            local text = cap.text
            -- Clean qualified names
            text = string.gsub(text, "^\\", "")
            local line = cap.node:start_point().row + 1
            local from_sym = find_enclosing_symbol(cap.node, namespace)

            table.insert(refs, {
                from_file = file_path,
                from_symbol = from_sym,
                to_name = text,
                kind = ref_kind,
                line = line,
            })
        end
    end

    -- Collect all reference types
    collect(ref_queries.instantiations, "instantiation", "class")
    collect(ref_queries.static_calls, "static_call", "class")
    collect(ref_queries.static_access, "static_access", "class")
    collect(ref_queries.param_types, "type_hint", "type")
    collect(ref_queries.return_types, "type_hint", "type")
    collect(ref_queries.property_types, "type_hint", "type")
    collect(ref_queries["extends"], "extends", "parent")
    collect(ref_queries["implements"], "implements", "interface")
    collect(ref_queries.trait_use, "trait_use", "trait")
    collect(ref_queries.instanceof, "instanceof", "class")
    collect(ref_queries.catch_types, "catch_type", "type")
    collect(ref_queries.function_calls, "function_call", "func")

    -- Member calls need special handling — capture both object and method
    local mcaps = safe_captures("php", ref_queries.member_calls, root, code)
    local mgroups = group_by_name(mcaps)
    local objects = mgroups["object"] or {}
    local methods = mgroups["method"] or {}

    for i, method_cap in ipairs(methods) do
        local obj = objects[i]
        local obj_name = obj and obj.text or "$unknown"
        local method_name = method_cap.text
        local line = method_cap.node:start_point().row + 1
        local from_sym = find_enclosing_symbol(method_cap.node, namespace)

        table.insert(refs, {
            from_file = file_path,
            from_symbol = from_sym,
            to_name = method_name,
            kind = "method_call",
            line = line,
            receiver = obj_name,
        })
    end

    -- Static call methods (we already captured the class above, now capture method names)
    local scaps = safe_captures("php", ref_queries.static_calls, root, code)
    local sgroups = group_by_name(scaps)
    local sclasses = sgroups["class"] or {}
    local smethods = sgroups["method"] or {}

    for i, method_cap in ipairs(smethods) do
        local cls = sclasses[i]
        local cls_name = cls and cls.text or "unknown"
        cls_name = string.gsub(cls_name, "^\\", "")
        local method_name = method_cap.text
        local line = method_cap.node:start_point().row + 1
        local from_sym = find_enclosing_symbol(method_cap.node, namespace)

        table.insert(refs, {
            from_file = file_path,
            from_symbol = from_sym,
            to_name = cls_name .. "::" .. method_name,
            kind = "static_method_call",
            line = line,
        })
    end

    return refs
end

---------------------------------------------------------------------------
-- Full file extraction
---------------------------------------------------------------------------

--- Extract all definitions and references from a PHP file
-- @param code string  PHP source code
-- @param file_path string  File path (for reference tracking)
-- @return table {namespace, imports, symbols, references}, error
local function extract_file(code, file_path)
    local tree, err = treesitter.parse("php", code)
    if err then
        return nil, "Parse failed for " .. file_path .. ": " .. tostring(err)
    end

    local root = tree:root_node()
    local ns = extract_namespace(root, code)
    local imports = extract_imports(root, code)

    -- Collect all symbols
    local symbols = {}
    local types = extract_types(root, code, ns)
    for _, s in ipairs(types) do table.insert(symbols, s) end

    local methods = extract_methods(root, code, ns)
    for _, s in ipairs(methods) do table.insert(symbols, s) end

    local functions = extract_functions(root, code, ns)
    for _, s in ipairs(functions) do table.insert(symbols, s) end

    -- Set file path on all symbols
    for _, s in ipairs(symbols) do
        s.file = file_path
    end

    -- Extract references
    local references = extract_references(root, code, file_path, ns)

    -- Extract extends/implements into type symbols
    local ext_caps = safe_captures("php", ref_queries["extends"], root, code)
    local ext_groups = group_by_name(ext_caps)
    local parents = ext_groups["parent"] or {}
    -- Attach extends info to class symbols
    if #parents > 0 then
        for _, sym in ipairs(symbols) do
            if sym.kind == "class" then
                -- Find the extends for this class by checking proximity
                for _, p in ipairs(parents) do
                    local p_line = p.node:start_point().row + 1
                    if p_line >= sym.line and p_line <= (sym.end_line or sym.line + 1) then
                        sym["extends"] = string.gsub(p.text, "^\\", "")
                        break
                    end
                end
            end
        end
    end

    local impl_caps = safe_captures("php", ref_queries["implements"], root, code)
    local impl_groups = group_by_name(impl_caps)
    local interfaces = impl_groups["interface"] or {}
    if #interfaces > 0 then
        for _, sym in ipairs(symbols) do
            if sym.kind == "class" then
                sym["implements"] = {}
                for _, iface in ipairs(interfaces) do
                    local i_line = iface.node:start_point().row + 1
                    if i_line >= sym.line and i_line <= (sym.end_line or sym.line + 1) then
                        local name = string.gsub(iface.text, "^\\", "")
                        table.insert(sym["implements"], name)
                    end
                end
                if #sym["implements"] == 0 then
                    sym["implements"] = nil
                end
            end
        end
    end

    -- Trait uses
    local trait_caps = safe_captures("php", ref_queries.trait_use, root, code)
    local trait_groups = group_by_name(trait_caps)
    local traits = trait_groups["trait"] or {}
    if #traits > 0 then
        for _, sym in ipairs(symbols) do
            if sym.kind == "class" or sym.kind == "trait" then
                sym.uses = {}
                for _, t in ipairs(traits) do
                    local t_line = t.node:start_point().row + 1
                    if t_line >= sym.line and t_line <= (sym.end_line or sym.line + 1) then
                        local name = string.gsub(t.text, "^\\", "")
                        table.insert(sym.uses, name)
                    end
                end
                if #sym.uses == 0 then
                    sym.uses = nil
                end
            end
        end
    end

    return {
        namespace = ns,
        imports = imports,
        symbols = symbols,
        references = references,
    }, nil
end

return {
    extract_file = extract_file,
    extract_namespace = extract_namespace,
    extract_imports = extract_imports,
    extract_types = extract_types,
    extract_methods = extract_methods,
    extract_functions = extract_functions,
    extract_references = extract_references,

    -- Expose query patterns for testing/debugging
    def_queries = def_queries,
    ref_queries = ref_queries,
}