-- Require external modules and libraries
require "lib.util.debug"
require "lib.util.list"
require "lib.util.parse_transition"
require "lib.util.validators"

lume = require "lib.lume"

-- Global constants
ROOT_NAME      = "HSM"
TIMER_NAME     = "_HSM_TIMER_"
TERMINAL_STATE = "ExitHSM"

-- Build the path from a given state up to the root.
-- @param state (table) The starting state node.
-- @return (table) Array of nodes from the starting state up to the root.
path_to_root = (state) ->
  path = {}
  while state
    table.insert(path, state)
    state = state.parent
  path

-- Recursively construct a state node.
--
-- Each node is augmented with a reference to its parent, transitions, timers,
-- and, if it is the root, a reference to the full state_map.
--
-- @param name (string) The name of the state.
-- @param def (table) The state definition table.
-- @param parent (table or nil) The parent state node.
-- @param state_map (table) Global mapping of state names to nodes.
-- @return (table) The constructed state node.
build_node = (name, def, parent, state_map) ->
  -- Validate state name (except for the ROOT)
  unless name == ROOT_NAME or is_valid_symbol name
    error "Invalid state name: #{name}"

  -- Initialize node with default properties.
  node =
    name: name
    parent: parent
    transitions: {}
    timers: {}
    default: def.default or nil

  -- Ensure state is defined only once.
  if state_map[name]
    error "State #{name} defined more than once"
  state_map[name] = node

  -- Process transitions defined as array entries.
  for index, transition_str in ipairs def
    transition = parse_transition(transition_str) -- parse_transition does validation
    if transition.type == "on"
      node.transitions[transition.event] = transition.target
    else
      -- For "every" or "after" transitions, generate a unique timer event name.
      event_name = "#{TIMER_NAME}#{name}__#{#node.timers + 1}"
      once = transition.type == "after"
      duration = transition.duration
      node.transitions[event_name] = transition.target
      table.insert(node.timers, {once: once, duration: duration, event: event_name})

  -- Process nested states (ignore keys that are not strings or are "default").
  for key, value in pairs def
    if type(key) == "string" and key != "default"
      build_node(key, value, node, state_map)

  -- If this is the root node, attach the full state_map.
  unless parent
    node.state_map = state_map

  node

-- Build the hierarchical state machine (HSM) graph.
--
-- This function takes a machine definition and recursively constructs the HSM
-- by creating nodes and then converting transition targets (state names) into
-- actual node references.
--
-- @param def (table) The machine definition.
-- @return (table) The root state node of the HSM.
build_hsm = (def) ->
  -- Prepopulate state_map with a terminal state.
  root = build_node(ROOT_NAME, def, nil, {
    [TERMINAL_STATE]: { name: TERMINAL_STATE, transitions: {}, timers: {} }
  })

  -- Grab a reference to the state map
  states = root.state_map

  -- Convert default and normal transitions from state names to node references.
  for name, state in pairs states
    -- update default transitions
    if state.default
      state.default = states[state.default]
    -- update normal transitions
    if state.transitions
      for event, target in pairs state.transitions
        unless states[target]
          error "State #{target} referenced, but never defined"
        state.transitions[event] = states[target] -- change string to node reference here

  root

-- Plan a transition from a source state to a destination state.
--
-- This function follows any default transitions from the destination state,
-- then computes the exit and entry paths by finding the least common ancestor
-- (LCA) of the source and final destination.
--
-- @param src (table) The current state node.
-- @param dst (table) The target state node.
-- @return (table) A table with `exit` (states to exit) and `entry` (states to enter).
plan_transition = lume.memoize (src, dst) ->
  -- Follow default transitions to get the final destination.
  seen = {}
  final_dst = dst
  while final_dst.default
    if seen[final_dst]
      error "Cycle detected in default transitions (in state #{final_dst.name})!"
    seen[final_dst] = true
    final_dst = final_dst.default

  -- Build paths from both source and destination to the root.
  src_path = path_to_root(src)
  dst_path = path_to_root(final_dst)

  -- Remove the common tail to determine the least common ancestor.
  while #src_path > 0 and #dst_path > 0 and src_path[#src_path] == dst_path[#dst_path]
    table.remove(src_path, #src_path)
    table.remove(dst_path, #dst_path)

  plan =
    exit: src_path
    entry: reverse(dst_path)

  -- If transitioning to the terminal state, no entry actions are needed.
  if final_dst.name == TERMINAL_STATE
    plan.entry = {}

  plan

-- Create an HSM runtime class from a machine definition.
--
-- The returned class provides methods for state transitions, updating timers,
-- handling events, and invoking state entry/update/exit actions.
--
-- @param machine_def (table) The machine definition.
-- @return (class) The HSM runtime class.
export create_hsm = (machine_def) ->

  root = build_hsm(machine_def)

  class HSMRuntime
    -- Constructor: initializes the runtime state and binds state action methods.
    new: =>
      @root = root
      @cur_state = nil
      @timers = {}  -- Map: state node -> list of timer objects
      @event_queue = {}
      @is_handling = false
      @in_transition = false
      @MAX_EVENTS_PER_UPDATE = 10

      -- Bind action methods (entry, update, exit) for each state.
      default_msg = (action) -> print "*** WARNING ***  Using default #{action} HSM action function. Override to suppress this message."
      for name, state in pairs @root.state_map
        state.entry  = @["on#{name}Entry"] or (=> default_msg "on#{name}Entry")
        state.update = @["on#{name}Update"] or ((dt) -> default_msg "on#{name}Update")
        state.exit   = @["on#{name}Exit"] or (=> default_msg "on#{name}Exit")

      -- Transition into the initial state and return self.
      @transition(@root)
      @

    -- Initialize timers for a given state.
    --
    -- @param state (table) The state node whose timers should be created.
    init_timers: (state) =>
      if state.timers
        @timers[state] = lume.map state.timers, (t) ->
          {
            once: t.once
            duration: t.duration
            event: t.event -- TODO: change this from event to target state
            elapsed: 0
          }

    -- Destroy timers associated with a state.
    --
    -- @param state (table) The state node whose timers should be removed.
    destroy_timers: (state) =>
      @timers[state] = nil

    -- Update timers across all active states.
    --
    -- Called during each update cycle; increments timer elapsed times,
    -- checks for timer firing (including overshoot), and triggers events.
    --
    -- @param dt (number) The delta time since the last update.
    -- @return (boolean) false if there is no current state, otherwise true.
    update_timers: (dt) =>
      return false unless @cur_state
      max_timer = nil

      -- Iterate over timers for each state.
      for state, timers in pairs @timers
        for timer in *timers
          continue unless timer.duration
          timer.elapsed += dt
          timer.overshoot = timer.elapsed - timer.duration
          if timer.overshoot > 0 and (not max_timer or timer.overshoot > max_timer.overshoot)
            max_timer = timer

      -- If a timer fired, trigger its event.
      if max_timer
        if max_timer.once
          max_timer.duration = nil
          max_timer.elapsed = nil
        else
          max_timer.elapsed = max_timer.elapsed % max_timer.duration
        @trigger(max_timer.event)

      true

    -- Transition from the current state to a destination state.
    --
    -- This method computes the exit/entry plan, calls exit actions (and destroys timers)
    -- for states being exited, then calls entry actions (and initializes timers) for states
    -- being entered.
    --
    -- @param dst (table) The target state node.
    -- @return (boolean) true if no actual state change occurred.
    transition: (dst) =>
      @in_transition = true
      starting_state = @cur_state
      plan = plan_transition(@cur_state, dst)

      -- Exit states: destroy timers and invoke exit actions.
      for state in *plan.exit
        @destroy_timers(state)
        @cur_state = state
        if state.exit then state.exit(self)
        if state == @root
          @cur_state = nil  -- HSM terminated
          @in_transition = false
          return

      -- Enter new states: initialize timers and invoke entry actions.
      for state in *plan.entry
        @init_timers(state)
        if state.entry then state.entry(self)
        @cur_state = state

      @in_transition = false

      -- process events that we might've accumulated during transition
      @drain_events()

      starting_state == @cur_state

    -- Update the HSM.
    --
    -- Processes timers and then calls update actions from the current state upward.
    --
    -- @param dt (number) Delta time.
    -- @return (boolean) true if there is a current state; false otherwise.
    update: (dt) =>
      -- exit if the HSM is terminated
      return false unless @cur_state

      -- update our timers
      @update_timers(dt)

      -- Propagate update actions from current state up through ancestors.
      s = @cur_state
      while s
        if s.update then s.update(self, dt)
        s = s.parent

      -- Process any events in our queue, some of which might've just happened
      @drain_events()

      true

    -- Process an event.
    --
    -- Processes an event by checking to see if the current state or any of its
    -- parents handles it. If none, the event is just discarded. Once an event
    -- is handled by any state, it's discarded.
    --
    -- @param event (string) Event.
    process_event: (event) =>
      -- search from current state to root looking for one to handle this
      s = @cur_state
      while s
        if s.transitions[event]
          -- found a state that handles event, transition
          @transition(s.transitions[event])
          return
        s = s.parent

    -- Drain events in the @event_queue.
    --
    -- Processes events in the queue up to @MAX_EVENTS_PER_UPDATE.
    drain_events: () =>
      num = math.min(@MAX_EVENTS_PER_UPDATE, #@event_queue)
      count = 0
      while count < num and #@event_queue > 0
        @process_event(table.remove(@event_queue, 1))

    -- Handle an event by checking the current state and its ancestors.
    --
    -- If a transition for the event is found, the HSM will transition accordingly.
    --
    -- @param event (string) The event to trigger.
    -- @return (boolean) false if there is no current state; true otherwise.
    trigger: (event) =>
      return false unless @cur_state

      if @is_handling or @in_transition
        -- if we're processing an event now, just queue it up
        table.insert(@event_queue, event)
      else
        -- if we're not processing anything, do it immediately
        @is_handling = true
        @process_event(event)
        @is_handling = false

      true

  HSMRuntime