taski 0.5.0 → 0.7.0

data/lib/taski/execution/tree_progress_display.rb

@@ -27,49 +27,105 @@ module Taski
 
       # Status icons
       ICONS = {
+        # Run lifecycle states
         pending: "⏸",        # Pause for waiting
         running_prefix: "",  # Will use spinner
         completed: "✓",
         failed: "✗",
-        skipped: "⊘"         # Prohibition sign for unselected impl candidates
+        skipped: "⊘",        # Prohibition sign for unselected impl candidates
+        # Clean lifecycle states
+        cleaning_prefix: "",  # Will use spinner
+        clean_completed: "♻",
+        clean_failed: "✗"
       }.freeze
 
-      # Shared helper methods
+      ##
+      # Checks if a class is a Taski::Section subclass.
+      # @param klass [Class] The class to check.
+      # @return [Boolean] true if the class is a Section.
       def self.section_class?(klass)
         defined?(Taski::Section) && klass < Taski::Section
       end
 
+      ##
+      # Checks if a class is nested within another class by name prefix.
+      # @param child_class [Class] The potential nested class.
+      # @param parent_class [Class] The potential parent class.
+      # @return [Boolean] true if child_class name starts with parent_class name and "::".
       def self.nested_class?(child_class, parent_class)
         child_name = child_class.name.to_s
         parent_name = parent_class.name.to_s
         child_name.start_with?("#{parent_name}::")
       end
 
+      # Build a tree structure from a root task class.
+      # This is the shared tree building logic used by both static and progress display.
+      #
+      # @param task_class [Class] The task class to build tree for
+      # @param ancestors [Set] Set of ancestor task classes for circular detection
+      # @return [Hash, nil] Tree node hash or nil if circular
+      #
+      # Tree node structure:
+      #   {
+      #     task_class: Class,       # The task class
+      #     is_section: Boolean,     # Whether this is a Section
+      #     is_circular: Boolean,    # Whether this is a circular reference
+      #     is_impl_candidate: Boolean, # Whether this is an impl candidate
+      #     children: Array<Hash>    # Child nodes
+      #   }
+      def self.build_tree_node(task_class, ancestors = Set.new)
+        is_circular = ancestors.include?(task_class)
+
+        node = {
+          task_class: task_class,
+          is_section: section_class?(task_class),
+          is_circular: is_circular,
+          is_impl_candidate: false,
+          children: []
+        }
+
+        # Don't traverse children for circular references
+        return node if is_circular
+
+        new_ancestors = ancestors + [task_class]
+        dependencies = StaticAnalysis::Analyzer.analyze(task_class).to_a
+        is_section = section_class?(task_class)
+
+        dependencies.each do |dep|
+          child_node = build_tree_node(dep, new_ancestors)
+          child_node[:is_impl_candidate] = is_section && nested_class?(dep, task_class)
+          node[:children] << child_node
+        end
+
+        node
+      end
+
       # Render a static tree structure for a task class (used by Task.tree)
       # @param root_task_class [Class] The root task class
       # @return [String] The rendered tree string
       def self.render_static_tree(root_task_class)
-        renderer = StaticTreeRenderer.new
-        renderer.render(root_task_class)
+        tree = build_tree_node(root_task_class)
+        formatter = StaticTreeFormatter.new
+        formatter.format(tree)
       end
 
-      # Internal renderer for static tree display (no progress tracking)
-      class StaticTreeRenderer
-        def render(root_task_class)
+      # Formatter for static tree display (no progress tracking, uses task numbers)
+      class StaticTreeFormatter
+        def format(tree)
           @task_index_map = {}
-          build_tree(root_task_class, "", false, Set.new)
+          format_node(tree, "", false)
         end
 
         private
 
-        def build_tree(task_class, prefix, is_impl, ancestors)
+        def format_node(node, prefix, is_impl)
+          task_class = node[:task_class]
           type_label = colored_type_label(task_class)
           impl_prefix = is_impl ? "#{COLORS[:impl]}[impl]#{COLORS[:reset]} " : ""
           task_number = get_task_number(task_class)
           name = "#{COLORS[:name]}#{task_class.name}#{COLORS[:reset]}"
 
-          # Detect circular reference
-          if ancestors.include?(task_class)
+          if node[:is_circular]
             circular_marker = "#{COLORS[:impl]}(circular)#{COLORS[:reset]}"
             return "#{impl_prefix}#{task_number} #{name} #{type_label} #{circular_marker}\n"
           end
@@ -79,26 +135,21 @@ module Taski
           # Register task number if not already registered
           @task_index_map[task_class] = @task_index_map.size + 1 unless @task_index_map.key?(task_class)
 
-          new_ancestors = ancestors + [task_class]
-          dependencies = StaticAnalysis::Analyzer.analyze(task_class).to_a
-          is_section = TreeProgressDisplay.section_class?(task_class)
-
-          dependencies.each_with_index do |dep, index|
-            is_last = (index == dependencies.size - 1)
-            is_impl_candidate = is_section && TreeProgressDisplay.nested_class?(dep, task_class)
-            result += render_dependency_branch(dep, prefix, is_last, is_impl_candidate, new_ancestors)
+          node[:children].each_with_index do |child, index|
+            is_last = (index == node[:children].size - 1)
+            result += format_child_branch(child, prefix, is_last)
           end
 
           result
         end
 
-        def render_dependency_branch(dep, prefix, is_last, is_impl, ancestors)
+        def format_child_branch(child, prefix, is_last)
           connector = is_last ? "└── " : "├── "
           extension = is_last ? "    " : "│   "
-          dep_tree = build_tree(dep, "#{prefix}#{extension}", is_impl, ancestors)
+          child_tree = format_node(child, "#{prefix}#{extension}", child[:is_impl_candidate])
 
           result = "#{prefix}#{COLORS[:tree]}#{connector}#{COLORS[:reset]}"
-          lines = dep_tree.lines
+          lines = child_tree.lines
           result += lines.first
           lines.drop(1).each { |line| result += line }
           result
@@ -118,17 +169,71 @@ module Taski
         end
       end
 
-      class TaskProgress
-        attr_accessor :state, :start_time, :end_time, :error, :duration
-        attr_accessor :is_impl_candidate
+      # Tracks the progress of a group within a task
+      class GroupProgress
+        attr_accessor :name, :state, :start_time, :end_time, :duration, :error, :last_message
 
-        def initialize
+        def initialize(name)
+          @name = name
           @state = :pending
           @start_time = nil
           @end_time = nil
-          @error = nil
           @duration = nil
+          @error = nil
+          @last_message = nil
+        end
+      end
+
+      class TaskProgress
+        # Run lifecycle tracking
+        attr_accessor :run_state, :run_start_time, :run_end_time, :run_error, :run_duration
+        # Clean lifecycle tracking
+        attr_accessor :clean_state, :clean_start_time, :clean_end_time, :clean_error, :clean_duration
+        # Display properties
+        attr_accessor :is_impl_candidate
+        # Group tracking
+        attr_accessor :groups, :current_group_index
+
+        def initialize
+          # Run lifecycle
+          @run_state = :pending
+          @run_start_time = nil
+          @run_end_time = nil
+          @run_error = nil
+          @run_duration = nil
+          # Clean lifecycle
+          @clean_state = nil  # nil means clean hasn't started
+          @clean_start_time = nil
+          @clean_end_time = nil
+          @clean_error = nil
+          @clean_duration = nil
+          # Display
           @is_impl_candidate = false
+          # Groups
+          @groups = []
+          @current_group_index = nil
+        end
+
+        # For backward compatibility - returns the most relevant state for display
+        def state
+          @clean_state || @run_state
+        end
+
+        # Legacy accessors for backward compatibility
+        def start_time
+          @clean_start_time || @run_start_time
+        end
+
+        def end_time
+          @clean_end_time || @run_end_time
+        end
+
+        def error
+          @clean_error || @run_error
+        end
+
+        def duration
+          @clean_duration || @run_duration
         end
       end
 
@@ -143,7 +248,15 @@ module Taski
         @root_task_class = nil
         @tree_structure = nil
         @section_impl_map = {}  # Section -> selected impl class
-        @last_line_count = 0
+        @output_capture = nil  # ThreadOutputCapture for getting task output
+      end
+
+      # Set the output capture for getting task output
+      # @param capture [ThreadOutputCapture] The output capture instance
+      def set_output_capture(capture)
+        @monitor.synchronize do
+          @output_capture = capture
+        end
       end
 
       # Set the root task to build tree structure
@@ -183,7 +296,7 @@ module Taski
       end
 
       # @param task_class [Class] The task class to update
-      # @param state [Symbol] The new state (:pending, :running, :completed, :failed)
+      # @param state [Symbol] The new state (:pending, :running, :completed, :failed, :cleaning, :clean_completed, :clean_failed)
       # @param duration [Float] Duration in milliseconds (for completed tasks)
       # @param error [Exception] Error object (for failed tasks)
       def update_task(task_class, state:, duration: nil, error: nil)
@@ -191,15 +304,33 @@ module Taski
           progress = @tasks[task_class]
           return unless progress
 
-          progress.state = state
-          progress.duration = duration if duration
-          progress.error = error if error
-
           case state
+          # Run lifecycle states
+          when :pending
+            progress.run_state = :pending
           when :running
-            progress.start_time = Time.now
-          when :completed, :failed
-            progress.end_time = Time.now
+            progress.run_state = :running
+            progress.run_start_time = Time.now
+          when :completed
+            progress.run_state = :completed
+            progress.run_end_time = Time.now
+            progress.run_duration = duration if duration
+          when :failed
+            progress.run_state = :failed
+            progress.run_end_time = Time.now
+            progress.run_error = error if error
+          # Clean lifecycle states
+          when :cleaning
+            progress.clean_state = :cleaning
+            progress.clean_start_time = Time.now
+          when :clean_completed
+            progress.clean_state = :clean_completed
+            progress.clean_end_time = Time.now
+            progress.clean_duration = duration if duration
+          when :clean_failed
+            progress.clean_state = :clean_failed
+            progress.clean_end_time = Time.now
+            progress.clean_error = error if error
           end
         end
       end
@@ -212,6 +343,50 @@ module Taski
         end
       end
 
+      # Update group state for a task.
+      # Called by ExecutionContext when group lifecycle events occur.
+      #
+      # @param task_class [Class] The task class containing the group
+      # @param group_name [String] The name of the group
+      # @param state [Symbol] The new state (:running, :completed, :failed)
+      # @param duration [Float, nil] Duration in milliseconds (for completed groups)
+      # @param error [Exception, nil] Error object (for failed groups)
+      def update_group(task_class, group_name, state:, duration: nil, error: nil)
+        @monitor.synchronize do
+          progress = @tasks[task_class]
+          return unless progress
+
+          case state
+          when :running
+            # Create new group and set as current
+            group = GroupProgress.new(group_name)
+            group.state = :running
+            group.start_time = Time.now
+            progress.groups << group
+            progress.current_group_index = progress.groups.size - 1
+          when :completed
+            # Find the group by name and mark completed
+            group = progress.groups.find { |g| g.name == group_name && g.state == :running }
+            if group
+              group.state = :completed
+              group.end_time = Time.now
+              group.duration = duration
+            end
+            progress.current_group_index = nil
+          when :failed
+            # Find the group by name and mark failed
+            group = progress.groups.find { |g| g.name == group_name && g.state == :running }
+            if group
+              group.state = :failed
+              group.end_time = Time.now
+              group.duration = duration
+              group.error = error
+            end
+            progress.current_group_index = nil
+          end
+        end
+      end
+
       def start
         should_start = false
         @monitor.synchronize do
@@ -226,8 +401,8 @@ module Taski
 
         return unless should_start
 
-        # Hide cursor (outside monitor to avoid holding lock during I/O)
-        @output.print "\e[?25l"
+        @output.print "\e[?25l"  # Hide cursor
+        @output.print "\e7"      # Save cursor position (before any tree output)
         @renderer_thread = Thread.new do
           loop do
             break unless @running
@@ -251,8 +426,7 @@ module Taski
         return unless should_stop
 
         @renderer_thread&.join
-        # Show cursor
-        @output.print "\e[?25h"
+        @output.print "\e[?25h"  # Show cursor
         render_final
       end
 
@@ -262,38 +436,10 @@ module Taski
       def build_tree_structure
         return unless @root_task_class
 
-        @tree_structure = build_tree_node(@root_task_class, Set.new)
+        @tree_structure = self.class.build_tree_node(@root_task_class)
         register_tasks_from_tree(@tree_structure)
       end
 
-      # Build a single tree node
-      def build_tree_node(task_class, ancestors)
-        return nil if ancestors.include?(task_class)
-
-        node = {
-          task_class: task_class,
-          is_section: section_class?(task_class),
-          children: [],
-          is_impl_candidate: false
-        }
-
-        new_ancestors = ancestors + [task_class]
-        dependencies = StaticAnalysis::Analyzer.analyze(task_class).to_a
-        is_section = section_class?(task_class)
-
-        dependencies.each do |dep|
-          child_node = build_tree_node(dep, new_ancestors)
-          if child_node
-            # Only mark as impl candidate if parent is Section AND
-            # the dependency is a nested class of that Section
-            child_node[:is_impl_candidate] = is_section && nested_class?(dep, task_class)
-            node[:children] << child_node
-          end
-        end
-
-        node
-      end
-
       # Register all tasks from tree structure
       def register_tasks_from_tree(node)
         return unless node
@@ -310,29 +456,25 @@ module Taski
       end
 
       def render_live
+        # Poll for new output from task pipes
+        @output_capture&.poll
+
         lines = nil
-        line_count = nil
 
         @monitor.synchronize do
           @spinner_index += 1
           lines = build_tree_display
-          line_count = @last_line_count
         end
 
         return if lines.nil? || lines.empty?
 
-        # Move cursor up to beginning of display area
-        if line_count && line_count > 0
-          @output.print "\e[#{line_count}A\r"
-        end
+        # Restore cursor to saved position (from start) and clear
+        @output.print "\e8"  # Restore cursor position
+        @output.print "\e[J" # Clear from cursor to end of screen
 
         # Redraw all lines
         lines.each do |line|
-          @output.print "\e[K#{line}\n"
-        end
-
-        @monitor.synchronize do
-          @last_line_count = lines.length
+          @output.print "#{line}\n"
         end
 
         @output.flush
@@ -343,12 +485,9 @@ module Taski
           lines = build_tree_display
           return if lines.empty?
 
-          # Clear previous animated output
-          if @last_line_count && @last_line_count > 0
-            @last_line_count.times do
-              @output.print "\e[1A\e[K"
-            end
-          end
+          # Restore cursor to saved position (from start) and clear
+          @output.print "\e8"  # Restore cursor position
+          @output.print "\e[J" # Clear from cursor to end of screen
 
           # Print final state
           lines.each { |line| @output.puts line }
@@ -431,11 +570,12 @@ module Taski
           return "#{COLORS[:dim]}#{ICONS[:skipped]}#{COLORS[:reset]} #{impl_prefix}#{name} #{type_label}#{suffix}"
         end
 
-        status_icon = task_status_icon(progress.state, is_selected)
+        status_icons = combined_status_icons(progress)
         name = "#{COLORS[:name]}#{task_class.name}#{COLORS[:reset]}"
-        details = task_details(progress)
+        details = combined_task_details(progress)
+        output_suffix = task_output_suffix(task_class, progress.state)
 
-        "#{status_icon} #{impl_prefix}#{name} #{type_label}#{details}"
+        "#{status_icons} #{impl_prefix}#{name} #{type_label}#{details}#{output_suffix}"
       end
 
       def format_unknown_task(task_class, is_selected = true)
@@ -450,12 +590,26 @@ module Taski
         end
       end
 
-      def task_status_icon(state, is_selected)
-        # If not selected (either direct impl candidate or child of unselected), show skipped
-        unless is_selected
-          return "#{COLORS[:dim]}#{ICONS[:skipped]}#{COLORS[:reset]}"
-        end
+      ##
+      # Returns combined status icons for both run and clean phases.
+      # Shows run icon first, then clean icon if clean phase has started.
+      # @param [TaskProgress] progress - The task progress object with run_state and clean_state.
+      # @return [String] The combined ANSI-colored icons.
+      def combined_status_icons(progress)
+        run_icon = run_status_icon(progress.run_state)
+
+        # If clean phase hasn't started, only show run icon
+        return run_icon unless progress.clean_state
 
+        clean_icon = clean_status_icon(progress.clean_state)
+        "#{run_icon} #{clean_icon}"
+      end
+
+      ##
+      # Returns the status icon for run phase.
+      # @param [Symbol] state - The run state (:pending, :running, :completed, :failed).
+      # @return [String] The ANSI-colored icon.
+      def run_status_icon(state)
         case state
         when :completed
           "#{COLORS[:success]}#{ICONS[:completed]}#{COLORS[:reset]}"
@@ -468,10 +622,36 @@ module Taski
         end
       end
 
+      ##
+      # Returns the status icon for clean phase.
+      # @param [Symbol] state - The clean state (:cleaning, :clean_completed, :clean_failed).
+      # @return [String] The ANSI-colored icon.
+      def clean_status_icon(state)
+        case state
+        when :cleaning
+          "#{COLORS[:running]}#{spinner_char}#{COLORS[:reset]}"
+        when :clean_completed
+          "#{COLORS[:success]}#{ICONS[:clean_completed]}#{COLORS[:reset]}"
+        when :clean_failed
+          "#{COLORS[:error]}#{ICONS[:clean_failed]}#{COLORS[:reset]}"
+        else
+          ""
+        end
+      end
+
+      ##
+      # Returns the current spinner character for animation.
+      # Cycles through SPINNER_FRAMES based on the current spinner index.
+      # @return [String] The current spinner frame character.
       def spinner_char
         SPINNER_FRAMES[@spinner_index % SPINNER_FRAMES.length]
       end
 
+      ##
+      # Returns a colored type label for the task class.
+      # @param task_class [Class] The task class to get the label for.
+      # @param is_selected [Boolean] Whether the task is selected (affects color).
+      # @return [String] The colored type label (Section or Task).
       def type_label_for(task_class, is_selected = true)
         if section_class?(task_class)
           is_selected ? "#{COLORS[:section]}(Section)#{COLORS[:reset]}" : "#{COLORS[:dim]}(Section)#{COLORS[:reset]}"
@@ -480,24 +660,131 @@ module Taski
         end
       end
 
-      def task_details(progress)
-        case progress.state
+      ##
+      # Returns combined details for both run and clean phases.
+      # @param [TaskProgress] progress - Progress object with run_state, clean_state, etc.
+      # @return [String] Combined details for both phases.
+      def combined_task_details(progress)
+        run_detail = run_phase_details(progress)
+        clean_detail = clean_phase_details(progress)
+
+        if clean_detail.empty?
+          run_detail
+        else
+          "#{run_detail}#{clean_detail}"
+        end
+      end
+
+      ##
+      # Returns details for the run phase only.
+      # @param [TaskProgress] progress - Progress object.
+      # @return [String] Run phase details.
+      def run_phase_details(progress)
+        case progress.run_state
         when :completed
-          " #{COLORS[:success]}(#{progress.duration}ms)#{COLORS[:reset]}"
+          return "" unless progress.run_duration
+          " #{COLORS[:success]}(#{progress.run_duration}ms)#{COLORS[:reset]}"
         when :failed
           " #{COLORS[:error]}(failed)#{COLORS[:reset]}"
         when :running
-          elapsed = ((Time.now - progress.start_time) * 1000).round(0)
+          return "" unless progress.run_start_time
+          elapsed = ((Time.now - progress.run_start_time) * 1000).round(0)
           " #{COLORS[:running]}(#{elapsed}ms)#{COLORS[:reset]}"
         else
           ""
         end
       end
 
+      ##
+      # Returns details for the clean phase only.
+      # @param [TaskProgress] progress - Progress object.
+      # @return [String] Clean phase details.
+      def clean_phase_details(progress)
+        case progress.clean_state
+        when :cleaning
+          return "" unless progress.clean_start_time
+          elapsed = ((Time.now - progress.clean_start_time) * 1000).round(0)
+          " #{COLORS[:running]}(cleaning #{elapsed}ms)#{COLORS[:reset]}"
+        when :clean_completed
+          return "" unless progress.clean_duration
+          " #{COLORS[:success]}(cleaned #{progress.clean_duration}ms)#{COLORS[:reset]}"
+        when :clean_failed
+          " #{COLORS[:error]}(clean failed)#{COLORS[:reset]}"
+        else
+          ""
+        end
+      end
+
+      # Get task output suffix to display next to task
+      ##
+      # Produces a trailing output suffix for a task when it is actively producing output.
+      #
+      # Fetches the last captured stdout/stderr line for the given task and returns a
+      # formatted, dimmed suffix containing that line only when the task `state` is
+      # `:running` or `:cleaning` and an output capture is available. The returned
+      # string is truncated to fit the terminal width (with a minimum visible length)
+      # and includes surrounding dim/reset color codes.
+      # @param [Class] task_class - The task class whose output to query.
+      # @param [Symbol] state - The task lifecycle state (only `:running` and `:cleaning` produce output).
+      # @return [String] A formatted, possibly truncated output suffix prefixed with a dim pipe, or an empty string when no output should be shown.
+      def task_output_suffix(task_class, state)
+        return "" unless state == :running || state == :cleaning
+        return "" unless @output_capture
+
+        last_line = @output_capture.last_line_for(task_class)
+        return "" unless last_line && !last_line.empty?
+
+        # Get current group name if any
+        progress = @tasks[task_class]
+        group_prefix = ""
+        if progress&.current_group_index
+          current_group = progress.groups[progress.current_group_index]
+          group_prefix = "#{current_group.name}: " if current_group
+        end
+
+        # Truncate if too long (leave space for tree structure)
+        terminal_cols = terminal_width
+        max_output_length = terminal_cols - 50
+        max_output_length = 20 if max_output_length < 20
+
+        full_output = "#{group_prefix}#{last_line}"
+        truncated = if full_output.length > max_output_length
+          full_output[0, max_output_length - 3] + "..."
+        else
+          full_output
+        end
+
+        " #{COLORS[:dim]}| #{truncated}#{COLORS[:reset]}"
+      end
+
+      ##
+      # Returns the terminal width in columns.
+      # Defaults to 80 if the output IO doesn't support winsize.
+      # @return [Integer] The terminal width in columns.
+      def terminal_width
+        if @output.respond_to?(:winsize)
+          _, cols = @output.winsize
+          cols || 80
+        else
+          80
+        end
+      end
+
+      ##
+      # Checks if a class is a Taski::Section subclass.
+      # Delegates to the class method.
+      # @param klass [Class] The class to check.
+      # @return [Boolean] true if the class is a Section.
       def section_class?(klass)
         self.class.section_class?(klass)
       end
 
+      ##
+      # Checks if a class is nested within another class.
+      # Delegates to the class method.
+      # @param child_class [Class] The potential nested class.
+      # @param parent_class [Class] The potential parent class.
+      # @return [Boolean] true if child_class is nested within parent_class.
       def nested_class?(child_class, parent_class)
         self.class.nested_class?(child_class, parent_class)
       end