-- ApiVault API/Event Detail Cross-Links runtime helpers. Generated for ApiVault v0.3.1.
-- Metadata-only. Does not read source files at runtime and does not enable protected/secure execution.
local addonName, ApiVault = ...

ApiVault.DetailLinks = ApiVault.DetailLinks or {}
local Links = ApiVault.DetailLinks

Links.metadata = {
	version = "0.3.2",
	interface = 120007,
	policy = "metadata-only cross-links; no runtime file reads; no protected/secure execution",
	source_archive = "Interface.zip",
	target_package = "ApiVault-v0.3.1.zip",
}

local function asText(value)
	if value == nil then
		return ""
	end
	return tostring(value)
end

local function append(text, line)
	if ApiVault and ApiVault.AppendLine then
		return ApiVault:AppendLine(text, line)
	end
	if text == nil or text == "" then
		return tostring(line or "")
	end
	return tostring(text) .. "\n" .. tostring(line or "")
end

local function bundledPath(filePath)
	if ApiVault.SourceUsage and ApiVault.SourceUsage.ToBundledSourcePath then
		return ApiVault.SourceUsage:ToBundledSourcePath(filePath)
	end
	if type(filePath) == "string" and string.sub(filePath, 1, 10) == "Interface/" then
		return "Interface/AddOns/ApiVault/Examples/" .. filePath
	end
	return filePath or "?"
end

local function ownerTypeForEntry(entry)
	if not entry then
		return nil
	end
	if entry.kind == "Function" then
		return "Function"
	end
	if entry.kind == "Event" then
		return "Event"
	end
	return entry.kind
end

function Links:GetUsage(entry)
	if not entry or not ApiVault.SourceUsage then
		return nil
	end
	if entry.kind == "Function" and ApiVault.SourceUsage.GetAPIUsage then
		return ApiVault.SourceUsage:GetAPIUsage(entry.display)
	end
	if entry.kind == "Event" and ApiVault.SourceUsage.GetEventUsage then
		return ApiVault.SourceUsage:GetEventUsage(entry.display)
	end
	return nil
end

function Links:GetExamples(entry, limit)
	if not entry or not ApiVault.SourceExamples or not ApiVault.SourceExamples.GetForOwner then
		return {}
	end
	return ApiVault.SourceExamples:GetForOwner(entry.display, ownerTypeForEntry(entry), limit or 5) or {}
end

function Links:GetSecurePatterns(entry, limit)
	if not entry or not ApiVault.SecurePatterns then
		return {}
	end
	if entry.kind == "Function" and ApiVault.SecurePatterns.GetForAPI then
		return ApiVault.SecurePatterns:GetForAPI(entry.display, limit or 5) or {}
	end
	return {}
end

function Links:GetAutoRunPolicy(entry)
	if not entry or entry.kind ~= "Function" or not ApiVault.SecurePatterns or not ApiVault.SecurePatterns.GetAutoRunPolicyForAPI then
		return nil, nil
	end
	return ApiVault.SecurePatterns:GetAutoRunPolicyForAPI(entry.display)
end

function Links:GetSummary(entry)
	local usage = self:GetUsage(entry)
	local examples = self:GetExamples(entry, 50)
	local secure = self:GetSecurePatterns(entry, 50)
	local policy, reason = self:GetAutoRunPolicy(entry)
	return {
		sourceUsageRefs = usage and (usage.c or 0) or 0,
		registerUnitEventRefs = usage and (usage.u or 0) or 0,
		sourceUsageModules = usage and usage.m or "",
		sourceExamples = #examples,
		securePatterns = #secure,
		autoRunPolicy = policy or "",
		autoRunReason = reason or "",
	}
end

local function appendUsageLocations(text, entry, usage, limit)
	limit = limit or 6
	local locations = usage and usage.l or {}
	if type(locations) ~= "table" or #locations == 0 then
		return append(text, "- source samples: none indexed")
	end
	text = append(text, "- source samples:")
	for index, loc in ipairs(locations) do
		if index > limit then
			text = append(text, "  ... +" .. tostring(#locations - limit) .. " more stored samples")
			break
		end
		local filePath = bundledPath(loc[1])
		local lineNumber = loc[2] or "?"
		local moduleName = loc[3] or "?"
		local context = loc[4] or ""
		if entry and entry.kind == "Event" then
			context = tostring(loc[4] or "RegisterEvent") .. " / " .. tostring(loc[5] or "")
		end
		text = append(text, "  " .. tostring(index) .. ". " .. tostring(filePath) .. ":" .. tostring(lineNumber) .. " [" .. tostring(moduleName) .. "] " .. tostring(context))
	end
	return text
end

local function appendExamples(text, examples, limit)
	limit = limit or 5
	if type(examples) ~= "table" or #examples == 0 then
		return append(text, "- examples: none indexed")
	end
	text = append(text, "- examples:")
	for index, example in ipairs(examples) do
		if index > limit then
			text = append(text, "  ... +" .. tostring(#examples - limit) .. " more examples")
			break
		end
		text = append(text, "  " .. tostring(index) .. ". " .. tostring(example.addonPath or example.sourcePath or "?") .. ":" .. tostring(example.line or "?") .. " [" .. tostring(example.module or "?") .. "]")
		text = append(text, "     " .. tostring(example.kind or "?") .. " / " .. tostring(example.riskClass or "?") .. " / " .. tostring(example.contextLabel or ""))
		if example.generatedSnippet and example.generatedSnippet ~= "" then
			text = append(text, "     snippet: " .. tostring(example.generatedSnippet))
		end
		if example.uncertainNotes and example.uncertainNotes ~= "" then
			text = append(text, "     notes: " .. tostring(example.uncertainNotes))
		end
	end
	return text
end

local function appendSecure(text, secure, limit)
	limit = limit or 5
	if type(secure) ~= "table" or #secure == 0 then
		return append(text, "- secure patterns: none indexed for this owner")
	end
	text = append(text, "- secure patterns:")
	for index, entry in ipairs(secure) do
		if index > limit then
			text = append(text, "  ... +" .. tostring(#secure - limit) .. " more secure references")
			break
		end
		text = append(text, "  " .. tostring(index) .. ". " .. tostring(entry.patternName or "?") .. " / " .. tostring(entry.riskClass or "?") .. " / " .. tostring(entry.autoRunPolicy or "inspect-only"))
		text = append(text, "     " .. tostring(entry.addonPath or entry.sourcePath or "?") .. ":" .. tostring(entry.line or "?") .. " [" .. tostring(entry.module or "?") .. "] " .. tostring(entry.contextLabel or ""))
	end
	return text
end

function Links:AppendAPIDetail(text, entry, systemInfo, objectInfo, limit)
	if not entry or (entry.kind ~= "Function" and entry.kind ~= "Event" and entry.kind ~= "Table") then
		return text
	end
	limit = limit or 6
	local usage = self:GetUsage(entry)
	local examples = self:GetExamples(entry, limit)
	local secure = self:GetSecurePatterns(entry, limit)
	local summary = self:GetSummary(entry)

	text = append(text, "")
	text = append(text, "Developer cross-links:")
	text = append(text, "- policy: generated metadata only; no source files are read at runtime")
	text = append(text, "- source doc: " .. tostring(systemInfo and systemInfo.file or "?"))
	text = append(text, "- owner: " .. tostring(entry.display or "?") .. " / " .. tostring(entry.kind or "?"))
	text = append(text, "- risk: " .. tostring(entry.risk or "?") .. " (" .. tostring(entry.riskReason or "?") .. ")")

	if entry.kind == "Function" then
		text = append(text, "- arguments: " .. tostring(objectInfo and #(objectInfo.args or {}) or 0) .. " / returns: " .. tostring(objectInfo and #(objectInfo.rets or {}) or 0))
	elseif entry.kind == "Event" then
		text = append(text, "- payload fields: " .. tostring(objectInfo and #(objectInfo.payload or {}) or 0))
	elseif entry.kind == "Table" then
		text = append(text, "- fields: " .. tostring(objectInfo and #(objectInfo.fields or {}) or 0) .. " / values: " .. tostring(objectInfo and #(objectInfo.values or {}) or 0))
	end

	if usage then
		text = append(text, "- source usage refs: " .. tostring(summary.sourceUsageRefs))
		if entry.kind == "Event" then
			text = append(text, "- RegisterUnitEvent refs: " .. tostring(summary.registerUnitEventRefs))
		end
		if summary.sourceUsageModules and summary.sourceUsageModules ~= "" then
			text = append(text, "- source usage modules: " .. tostring(summary.sourceUsageModules))
		end
		text = appendUsageLocations(text, entry, usage, limit)
	else
		text = append(text, "- source usage refs: 0")
	end

	text = appendExamples(text, examples, limit)

	if entry.kind == "Function" then
		local policy, reason = self:GetAutoRunPolicy(entry)
		if policy and policy ~= "" then
			text = append(text, "- secure auto-run policy: " .. tostring(policy) .. " (" .. tostring(reason or "secure pattern") .. ")")
		end
		text = appendSecure(text, secure, limit)
	elseif entry.kind == "Event" then
		text = append(text, "- secure patterns: event entries are listener metadata; no automatic secure execution is added")
	end

	text = append(text, "- uncertainty: source-backed metadata does not prove safe runtime behavior; validate in-game where context/combat matters")
	return text
end

function Links:DescribeAPIDetail(entry, systemInfo, objectInfo, limit)
	return self:AppendAPIDetail("", entry, systemInfo, objectInfo, limit or 6)
end
