FlexLove/modules/ErrorCodes.lua

---@class ErrorCodes
local ErrorCodes = {}

-- Error code categories
ErrorCodes.categories = {
  VAL = "Validation",
  LAY = "Layout",
  REN = "Render",
  THM = "Theme",
  EVT = "Event",
  RES = "Resource",
  SYS = "System",
}

-- Error code definitions
ErrorCodes.codes = {
  -- Validation Errors (VAL_001 - VAL_099)
  VAL_001 = {
    code = "FLEXLOVE_VAL_001",
    category = "VAL",
    description = "Invalid property type",
    suggestion = "Check the property type matches the expected type (e.g., number, string, table)",
  },
  VAL_002 = {
    code = "FLEXLOVE_VAL_002",
    category = "VAL",
    description = "Property value out of range",
    suggestion = "Ensure the value is within the allowed min/max range",
  },
  VAL_003 = {
    code = "FLEXLOVE_VAL_003",
    category = "VAL",
    description = "Required property missing",
    suggestion = "Provide the required property in your element definition",
  },
  VAL_004 = {
    code = "FLEXLOVE_VAL_004",
    category = "VAL",
    description = "Invalid color format",
    suggestion = "Use valid color format: {r, g, b, a} with values 0-1, hex string, or Color object",
  },
  VAL_005 = {
    code = "FLEXLOVE_VAL_005",
    category = "VAL",
    description = "Invalid unit format",
    suggestion = "Use valid unit format: number (px), '50%', '10vw', '5vh', etc.",
  },
  VAL_006 = {
    code = "FLEXLOVE_VAL_006",
    category = "VAL",
    description = "Invalid file path",
    suggestion = "Check that the file path is correct and the file exists",
  },
  VAL_007 = {
    code = "FLEXLOVE_VAL_007",
    category = "VAL",
    description = "Invalid enum value",
    suggestion = "Use one of the allowed enum values for this property",
  },
  VAL_008 = {
    code = "FLEXLOVE_VAL_008",
    category = "VAL",
    description = "Invalid text input",
    suggestion = "Ensure text meets validation requirements (length, pattern, allowed characters)",
  },

  -- Layout Errors (LAY_001 - LAY_099)
  LAY_001 = {
    code = "FLEXLOVE_LAY_001",
    category = "LAY",
    description = "Invalid flex direction",
    suggestion = "Use 'horizontal' or 'vertical' for flexDirection",
  },
  LAY_002 = {
    code = "FLEXLOVE_LAY_002",
    category = "LAY",
    description = "Circular dependency detected",
    suggestion = "Remove circular references in element hierarchy or layout constraints",
  },
  LAY_003 = {
    code = "FLEXLOVE_LAY_003",
    category = "LAY",
    description = "Invalid dimensions (negative or NaN)",
    suggestion = "Ensure width and height are positive numbers",
  },
  LAY_004 = {
    code = "FLEXLOVE_LAY_004",
    category = "LAY",
    description = "Layout calculation overflow",
    suggestion = "Reduce complexity of layout or increase recursion limit",
  },
  LAY_005 = {
    code = "FLEXLOVE_LAY_005",
    category = "LAY",
    description = "Invalid alignment value",
    suggestion = "Use valid alignment values (flex-start, center, flex-end, etc.)",
  },
  LAY_006 = {
    code = "FLEXLOVE_LAY_006",
    category = "LAY",
    description = "Invalid positioning mode",
    suggestion = "Use 'absolute', 'relative', 'flex', or 'grid' for positioning",
  },
  LAY_007 = {
    code = "FLEXLOVE_LAY_007",
    category = "LAY",
    description = "Grid layout error",
    suggestion = "Check grid template columns/rows and item placement",
  },

  -- Rendering Errors (REN_001 - REN_099)
  REN_001 = {
    code = "FLEXLOVE_REN_001",
    category = "REN",
    description = "Invalid render state",
    suggestion = "Ensure element is properly initialized before rendering",
  },
  REN_002 = {
    code = "FLEXLOVE_REN_002",
    category = "REN",
    description = "Texture loading failed",
    suggestion = "Check image path and format, ensure file exists",
  },
  REN_003 = {
    code = "FLEXLOVE_REN_003",
    category = "REN",
    description = "Font loading failed",
    suggestion = "Check font path and format, ensure file exists",
  },
  REN_004 = {
    code = "FLEXLOVE_REN_004",
    category = "REN",
    description = "Invalid color value",
    suggestion = "Color components must be numbers between 0 and 1",
  },
  REN_005 = {
    code = "FLEXLOVE_REN_005",
    category = "REN",
    description = "Clipping stack overflow",
    suggestion = "Reduce nesting depth or check for missing scissor pops",
  },
  REN_006 = {
    code = "FLEXLOVE_REN_006",
    category = "REN",
    description = "Shader compilation failed",
    suggestion = "Check shader code for syntax errors",
  },
  REN_007 = {
    code = "FLEXLOVE_REN_007",
    category = "REN",
    description = "Invalid nine-patch configuration",
    suggestion = "Check nine-patch slice values and image dimensions",
  },

  -- Theme Errors (THM_001 - THM_099)
  THM_001 = {
    code = "FLEXLOVE_THM_001",
    category = "THM",
    description = "Theme file not found",
    suggestion = "Check theme file path and ensure file exists",
  },
  THM_002 = {
    code = "FLEXLOVE_THM_002",
    category = "THM",
    description = "Invalid theme structure",
    suggestion = "Theme must return a table with 'name' and component styles",
  },
  THM_003 = {
    code = "FLEXLOVE_THM_003",
    category = "THM",
    description = "Required theme property missing",
    suggestion = "Ensure theme has required properties (name, base styles, etc.)",
  },
  THM_004 = {
    code = "FLEXLOVE_THM_004",
    category = "THM",
    description = "Invalid component style",
    suggestion = "Component styles must be tables with valid properties",
  },
  THM_005 = {
    code = "FLEXLOVE_THM_005",
    category = "THM",
    description = "Theme loading failed",
    suggestion = "Check theme file for Lua syntax errors",
  },
  THM_006 = {
    code = "FLEXLOVE_THM_006",
    category = "THM",
    description = "Invalid theme color",
    suggestion = "Theme colors must be valid color values (hex, rgba, Color object)",
  },

  -- Event Errors (EVT_001 - EVT_099)
  EVT_001 = {
    code = "FLEXLOVE_EVT_001",
    category = "EVT",
    description = "Invalid event type",
    suggestion = "Use valid event types (mousepressed, textinput, etc.)",
  },
  EVT_002 = {
    code = "FLEXLOVE_EVT_002",
    category = "EVT",
    description = "Event handler error",
    suggestion = "Check event handler function for errors",
  },
  EVT_003 = {
    code = "FLEXLOVE_EVT_003",
    category = "EVT",
    description = "Event propagation error",
    suggestion = "Check event bubbling/capturing logic",
  },
  EVT_004 = {
    code = "FLEXLOVE_EVT_004",
    category = "EVT",
    description = "Invalid event target",
    suggestion = "Ensure event target element exists and is valid",
  },
  EVT_005 = {
    code = "FLEXLOVE_EVT_005",
    category = "EVT",
    description = "Event handler not a function",
    suggestion = "Event handlers must be functions",
  },

  -- Resource Errors (RES_001 - RES_099)
  RES_001 = {
    code = "FLEXLOVE_RES_001",
    category = "RES",
    description = "File not found",
    suggestion = "Check file path and ensure file exists in the filesystem",
  },
  RES_002 = {
    code = "FLEXLOVE_RES_002",
    category = "RES",
    description = "Permission denied",
    suggestion = "Check file permissions and access rights",
  },
  RES_003 = {
    code = "FLEXLOVE_RES_003",
    category = "RES",
    description = "Invalid file format",
    suggestion = "Ensure file format is supported (png, jpg, ttf, etc.)",
  },
  RES_004 = {
    code = "FLEXLOVE_RES_004",
    category = "RES",
    description = "Resource loading failed",
    suggestion = "Check file integrity and format compatibility",
  },
  RES_005 = {
    code = "FLEXLOVE_RES_005",
    category = "RES",
    description = "Image cache error",
    suggestion = "Clear image cache or check memory availability",
  },

  -- System Errors (SYS_001 - SYS_099)
  SYS_001 = {
    code = "FLEXLOVE_SYS_001",
    category = "SYS",
    description = "Memory allocation failed",
    suggestion = "Reduce memory usage or check available memory",
  },
  SYS_002 = {
    code = "FLEXLOVE_SYS_002",
    category = "SYS",
    description = "Stack overflow",
    suggestion = "Reduce recursion depth or check for infinite loops",
  },
  SYS_003 = {
    code = "FLEXLOVE_SYS_003",
    category = "SYS",
    description = "Invalid state",
    suggestion = "Check initialization order and state management",
  },
  SYS_004 = {
    code = "FLEXLOVE_SYS_004",
    category = "SYS",
    description = "Module initialization failed",
    suggestion = "Check module dependencies and initialization order",
  },
}

--- Get error information by code
--- @param code string Error code (e.g., "VAL_001" or "FLEXLOVE_VAL_001")
--- @return table? errorInfo Error information or nil if not found
function ErrorCodes.get(code)
  -- Handle both short and full format
  local shortCode = code:gsub("^FLEXLOVE_", "")
  return ErrorCodes.codes[shortCode]
end

--- Get human-readable description for error code
--- @param code string Error code
--- @return string description Error description
function ErrorCodes.describe(code)
  local info = ErrorCodes.get(code)
  if info then
    return info.description
  end
  return "Unknown error code: " .. code
end

--- Get suggested fix for error code
--- @param code string Error code
--- @return string suggestion Suggested fix
function ErrorCodes.getSuggestion(code)
  local info = ErrorCodes.get(code)
  if info then
    return info.suggestion
  end
  return "No suggestion available"
end

--- Get category for error code
--- @param code string Error code
--- @return string category Error category name
function ErrorCodes.getCategory(code)
  local info = ErrorCodes.get(code)
  if info then
    return ErrorCodes.categories[info.category] or info.category
  end
  return "Unknown"
end

--- List all error codes in a category
--- @param category string Category code (e.g., "VAL", "LAY")
--- @return table codes List of error codes in category
function ErrorCodes.listByCategory(category)
  local result = {}
  for code, info in pairs(ErrorCodes.codes) do
    if info.category == category then
      table.insert(result, {
        code = code,
        fullCode = info.code,
        description = info.description,
        suggestion = info.suggestion,
      })
    end
  end
  table.sort(result, function(a, b)
    return a.code < b.code
  end)
  return result
end

--- Search error codes by keyword
--- @param keyword string Keyword to search for
--- @return table codes Matching error codes
function ErrorCodes.search(keyword)
  keyword = keyword:lower()
  local result = {}
  for code, info in pairs(ErrorCodes.codes) do
    local searchText = (code .. " " .. info.description .. " " .. info.suggestion):lower()
    if searchText:find(keyword, 1, true) then
      table.insert(result, {
        code = code,
        fullCode = info.code,
        description = info.description,
        suggestion = info.suggestion,
        category = ErrorCodes.categories[info.category],
      })
    end
  end
  return result
end

--- Get all error codes
--- @return table codes All error codes
function ErrorCodes.listAll()
  local result = {}
  for code, info in pairs(ErrorCodes.codes) do
    table.insert(result, {
      code = code,
      fullCode = info.code,
      description = info.description,
      suggestion = info.suggestion,
      category = ErrorCodes.categories[info.category],
    })
  end
  table.sort(result, function(a, b)
    return a.code < b.code
  end)
  return result
end

--- Format error message with code
--- @param code string Error code
--- @param message string Error message
--- @return string formattedMessage Formatted error message with code
function ErrorCodes.formatMessage(code, message)
  local info = ErrorCodes.get(code)
  if info then
    return string.format("[%s] %s", info.code, message)
  end
  return message
end

--- Validate that all error codes are unique and properly formatted
--- @return boolean, string? Returns true if valid, or false with error message
function ErrorCodes.validate()
  local seen = {}
  local fullCodes = {}

  for code, info in pairs(ErrorCodes.codes) do
    -- Check for duplicates
    if seen[code] then
      return false, "Duplicate error code: " .. code
    end
    seen[code] = true

    if fullCodes[info.code] then
      return false, "Duplicate full error code: " .. info.code
    end
    fullCodes[info.code] = true

    -- Check format
    if not code:match("^[A-Z]+_[0-9]+$") then
      return false, "Invalid code format: " .. code .. " (expected CATEGORY_NUMBER)"
    end

    -- Check full code format
    local expectedFullCode = "FLEXLOVE_" .. code
    if info.code ~= expectedFullCode then
      return false, "Mismatched full code for " .. code .. ": expected " .. expectedFullCode .. ", got " .. info.code
    end

    -- Check required fields
    if not info.description or info.description == "" then
      return false, "Missing description for " .. code
    end
    if not info.suggestion or info.suggestion == "" then
      return false, "Missing suggestion for " .. code
    end
    if not info.category or info.category == "" then
      return false, "Missing category for " .. code
    end
  end

  return true, nil
end

return ErrorCodes