graph_lib.lua

-- Graph data structures for code index
-- Manages symbol table, references, and derived indexes
-- Entry kind: library.lua

---------------------------------------------------------------------------
-- Create a new empty index state
---------------------------------------------------------------------------

local function new_state()
    return {
        -- Core data
        symbols = {},           -- id → Symbol
        references = {},        -- flat array of all Reference
        files = {},             -- path → FileInfo

        -- Derived indexes (rebuilt after indexing)
        symbol_by_name = {},    -- short_name → {symbol_ids}
        symbols_by_file = {},   -- file → {symbol_ids}
        refs_to = {},           -- target_fqn → {Reference}
        refs_from = {},         -- source_symbol → {Reference}
        namespace_to_file = {}, -- namespace → file_path
        file_imports = {},      -- file → {imported_fqns}
        children_of = {},       -- parent_fqn → {child_fqns} (extends/implements)
        parent_of = {},         -- child_fqn → parent_fqn (extends)

        -- Meta
        indexed_at = nil,
        file_count = 0,
        symbol_count = 0,
        ref_count = 0,
        project = nil,
    }
end

---------------------------------------------------------------------------
-- Adding data
---------------------------------------------------------------------------

--- Add a file's extraction results to the state
-- @param state IndexState
-- @param file_path string
-- @param extraction table  {namespace, imports, symbols, references}
local function add_file(state, file_path, extraction)
    -- Store file info
    state.files[file_path] = {
        path = file_path,
        namespace = extraction.namespace,
        imports = extraction.imports,
        symbols = {},
    }

    -- Add symbols
    for _, sym in ipairs(extraction.symbols) do
        state.symbols[sym.id] = sym
        table.insert(state.files[file_path].symbols, sym.id)
    end

    -- Add references
    for _, ref in ipairs(extraction.references) do
        table.insert(state.references, ref)
    end
end

---------------------------------------------------------------------------
-- Build derived indexes
---------------------------------------------------------------------------

--- Rebuild all derived indexes from core data
-- Call after all files have been added
-- @param state IndexState
local function rebuild_indexes(state)
    -- Reset derived
    state.symbol_by_name = {}
    state.symbols_by_file = {}
    state.refs_to = {}
    state.refs_from = {}
    state.namespace_to_file = {}
    state.file_imports = {}
    state.children_of = {}
    state.parent_of = {}

    -- Index symbols
    for id, sym in pairs(state.symbols) do
        -- By short name
        if not state.symbol_by_name[sym.name] then
            state.symbol_by_name[sym.name] = {}
        end
        table.insert(state.symbol_by_name[sym.name], id)

        -- By file
        if sym.file then
            if not state.symbols_by_file[sym.file] then
                state.symbols_by_file[sym.file] = {}
            end
            table.insert(state.symbols_by_file[sym.file], id)
        end

        -- Inheritance: extends
        if sym["extends"] then
            state.parent_of[id] = sym["extends"]
            if not state.children_of[sym["extends"]] then
                state.children_of[sym["extends"]] = {}
            end
            table.insert(state.children_of[sym["extends"]], id)
        end

        -- Inheritance: implements
        if sym["implements"] then
            for _, iface in ipairs(sym["implements"]) do
                if not state.children_of[iface] then
                    state.children_of[iface] = {}
                end
                table.insert(state.children_of[iface], id)
            end
        end
    end

    -- Index files by namespace
    for path, info in pairs(state.files) do
        if info.namespace then
            state.namespace_to_file[info.namespace] = path
        end

        -- Import index per file
        state.file_imports[path] = {}
        for _, imp in ipairs(info.imports or {}) do
            table.insert(state.file_imports[path], imp.fqn)
        end
    end

    -- Index references
    for _, ref in ipairs(state.references) do
        -- By target (resolved FQN preferred, fallback to raw name)
        local target = ref.to_resolved or ref.to_name
        if target then
            if not state.refs_to[target] then
                state.refs_to[target] = {}
            end
            table.insert(state.refs_to[target], ref)
        end

        -- By source symbol
        if ref.from_symbol then
            if not state.refs_from[ref.from_symbol] then
                state.refs_from[ref.from_symbol] = {}
            end
            table.insert(state.refs_from[ref.from_symbol], ref)
        end
    end

    -- Counts
    state.symbol_count = 0
    for _ in pairs(state.symbols) do state.symbol_count = state.symbol_count + 1 end
    state.ref_count = #state.references
    state.file_count = 0
    for _ in pairs(state.files) do state.file_count = state.file_count + 1 end
end

---------------------------------------------------------------------------
-- Query helpers
---------------------------------------------------------------------------

--- Find a symbol by name (short or FQN)
-- @param state IndexState
-- @param name string
-- @param kind string|nil  Optional kind filter
-- @return {Symbol}
local function find_symbol(state, name, kind)
    local results = {}

    -- Try exact FQN match first
    if state.symbols[name] then
        local sym = state.symbols[name]
        if not kind or sym.kind == kind then
            table.insert(results, sym)
        end
        return results
    end

    -- Try FQN with :: (method)
    -- e.g. "OrderService::process" should match "App\Services\OrderService::process"
    if string.find(name, "::") then
        for id, sym in pairs(state.symbols) do
            if string.find(id, name, 1, true) then
                if not kind or sym.kind == kind then
                    table.insert(results, sym)
                end
            end
        end
        if #results > 0 then return results end
    end

    -- Try short name
    local ids = state.symbol_by_name[name]
    if ids then
        for _, id in ipairs(ids) do
            local sym = state.symbols[id]
            if sym and (not kind or sym.kind == kind) then
                table.insert(results, sym)
            end
        end
    end

    return results
end

--- Find all references pointing to a symbol
-- @param state IndexState
-- @param symbol_id string  FQN of the target symbol
-- @return {Reference}
local function find_refs_to(state, symbol_id)
    local refs = state.refs_to[symbol_id] or {}

    -- Also check short name matches
    local sym = state.symbols[symbol_id]
    if sym then
        local short_refs = state.refs_to[sym.name]
        if short_refs then
            for _, ref in ipairs(short_refs) do
                -- Avoid duplicates
                local dup = false
                for _, existing in ipairs(refs) do
                    if existing.from_file == ref.from_file
                        and existing.line == ref.line then
                        dup = true
                        break
                    end
                end
                if not dup then
                    table.insert(refs, ref)
                end
            end
        end
    end

    return refs
end

--- Find all references made by a symbol
-- @param state IndexState
-- @param symbol_id string
-- @return {Reference}
local function find_refs_from(state, symbol_id)
    return state.refs_from[symbol_id] or {}
end

--- Get file that defines a namespace
-- @param state IndexState
-- @param namespace string
-- @return string|nil  File path
local function file_for_namespace(state, namespace)
    return state.namespace_to_file[namespace]
end

--- Get file that defines a symbol
-- @param state IndexState
-- @param symbol_id string
-- @return string|nil
local function file_for_symbol(state, symbol_id)
    local sym = state.symbols[symbol_id]
    return sym and sym.file
end

--- Get all children (subclasses/implementors) of a symbol
-- @param state IndexState
-- @param symbol_id string
-- @return {string}  Child symbol IDs
local function children_of(state, symbol_id)
    return state.children_of[symbol_id] or {}
end

--- Get parent (superclass) of a symbol
-- @param state IndexState
-- @param symbol_id string
-- @return string|nil
local function parent_of(state, symbol_id)
    return state.parent_of[symbol_id]
end

--- Compute statistics
-- @param state IndexState
-- @return table
local function stats(state)
    local by_kind = {}
    for _, sym in pairs(state.symbols) do
        by_kind[sym.kind] = (by_kind[sym.kind] or 0) + 1
    end

    local ref_by_kind = {}
    for _, ref in ipairs(state.references) do
        ref_by_kind[ref.kind] = (ref_by_kind[ref.kind] or 0) + 1
    end

    local ns_count = 0
    for _ in pairs(state.namespace_to_file) do ns_count = ns_count + 1 end

    local import_count = 0
    for _, imps in pairs(state.file_imports) do
        import_count = import_count + #imps
    end

    return {
        files = state.file_count,
        symbols = state.symbol_count,
        references = state.ref_count,
        namespaces = ns_count,
        imports = import_count,
        symbols_by_kind = by_kind,
        refs_by_kind = ref_by_kind,
    }
end

--- Clear all data
local function clear(state)
    local fresh = new_state()
    for k, v in pairs(fresh) do
        state[k] = v
    end
end

return {
    new_state = new_state,
    add_file = add_file,
    rebuild_indexes = rebuild_indexes,
    find_symbol = find_symbol,
    find_refs_to = find_refs_to,
    find_refs_from = find_refs_from,
    file_for_namespace = file_for_namespace,
    file_for_symbol = file_for_symbol,
    children_of = children_of,
    parent_of = parent_of,
    stats = stats,
    clear = clear,
}