cli-ui 2.3.1 → 2.6.0

data/lib/cli/ui/spinner/spin_group.rb

@@ -10,23 +10,17 @@ module CLI
         DEFAULT_FINAL_GLYPH = ->(success) { success ? CLI::UI::Glyph::CHECK : CLI::UI::Glyph::X }
 
         class << self
-          extend T::Sig
-
-          sig { returns(Mutex) }
+          #: Mutex
           attr_reader :pause_mutex
 
-          sig { returns(T::Boolean) }
+          #: -> bool
           def paused?
             @paused
           end
 
-          sig do
-            type_parameters(:T)
-              .params(block: T.proc.returns(T.type_parameter(:T)))
-              .returns(T.type_parameter(:T))
-          end
+          #: [T] { -> T } -> T
           def pause_spinners(&block)
-            previous_paused = T.let(nil, T.nilable(T::Boolean))
+            previous_paused = nil #: bool?
             @pause_mutex.synchronize do
               previous_paused = @paused
               @paused = true
@@ -42,8 +36,6 @@ module CLI
         @pause_mutex = Mutex.new
         @paused = false
 
-        extend T::Sig
-
         # Initializes a new spin group
         # This lets you add +Task+ objects to the group to multi-thread work
         #
@@ -67,15 +59,7 @@ module CLI
         #
         # https://user-images.githubusercontent.com/3074765/33798558-c452fa26-dce8-11e7-9e90-b4b34df21a46.gif
         #
-        sig do
-          params(
-            auto_debrief: T::Boolean,
-            interrupt_debrief: T::Boolean,
-            max_concurrent: Integer,
-            work_queue: T.nilable(WorkQueue),
-            to: IOLike,
-          ).void
-        end
+        #: (?auto_debrief: bool, ?interrupt_debrief: bool, ?max_concurrent: Integer, ?work_queue: WorkQueue?, ?to: io_like) -> void
         def initialize(auto_debrief: true, interrupt_debrief: false, max_concurrent: 0, work_queue: nil, to: $stdout)
           @m = Mutex.new
           @tasks = []
@@ -85,10 +69,7 @@ module CLI
           @start = Time.new
           @stopped = false
           @internal_work_queue = work_queue.nil?
-          @work_queue = T.let(
-            work_queue || WorkQueue.new(max_concurrent.zero? ? 1024 : max_concurrent),
-            WorkQueue,
-          )
+          @work_queue = work_queue || WorkQueue.new(max_concurrent.zero? ? 1024 : max_concurrent) #: WorkQueue
           if block_given?
             yield self
             wait(to: to)
@@ -96,20 +77,21 @@ module CLI
         end
 
         class Task
-          extend T::Sig
-
-          sig { returns(String) }
+          #: String
           attr_reader :title, :stdout, :stderr
 
-          sig { returns(T::Boolean) }
+          #: bool
           attr_reader :success
 
-          sig { returns(T::Boolean) }
+          #: bool
           attr_reader :done
 
-          sig { returns(T.nilable(Exception)) }
+          #: Exception?
           attr_reader :exception
 
+          #: Integer?
+          attr_reader :progress_percentage
+
           # Initializes a new Task
           # This is managed entirely internally by +SpinGroup+
           #
@@ -118,16 +100,7 @@ module CLI
           # * +title+ - Title of the task
           # * +block+ - Block for the task, will be provided with an instance of the spinner
           #
-          sig do
-            params(
-              title: String,
-              final_glyph: T.proc.params(success: T::Boolean).returns(T.any(Glyph, String)),
-              merged_output: T::Boolean,
-              duplicate_output_to: IO,
-              work_queue: WorkQueue,
-              block: T.proc.params(task: Task).returns(T.untyped),
-            ).void
-          end
+          #: (String title, final_glyph: ^(bool success) -> (Glyph | String), merged_output: bool, duplicate_output_to: IO, work_queue: WorkQueue) { (Task task) -> untyped } -> void
           def initialize(title, final_glyph:, merged_output:, duplicate_output_to:, work_queue:, &block)
             @title = title
             @final_glyph = final_glyph
@@ -149,16 +122,18 @@ module CLI
             @done = false
             @exception = nil
             @success = false
+            @progress_percentage = nil
+            @wants_progress_mode = false
           end
 
-          sig { params(block: T.proc.params(task: Task).void).void }
+          #: { (Task task) -> void } -> void
           def on_done(&block)
             @on_done = block
           end
 
           # Checks if a task is finished
           #
-          sig { returns(T::Boolean) }
+          #: -> bool
           def check
             return true if @done
             return false unless @future.completed?
@@ -196,7 +171,7 @@ module CLI
           # * +force+ - force rerender of the task
           # * +width+ - current terminal width to format for
           #
-          sig { params(index: Integer, force: T::Boolean, width: Integer).returns(String) }
+          #: (Integer index, ?bool force, ?width: Integer) -> String
           def render(index, force = true, width: CLI::UI::Terminal.width)
             @m.synchronize do
               if !CLI::UI.enable_cursor? || force || @always_full_render || @force_full_render
@@ -215,7 +190,7 @@ module CLI
           #
           # * +title+ - title to change the spinner to
           #
-          sig { params(new_title: String).void }
+          #: (String new_title) -> void
           def update_title(new_title)
             @m.synchronize do
               @always_full_render = new_title =~ Formatter::SCAN_WIDGET
@@ -224,9 +199,39 @@ module CLI
             end
           end
 
+          # Set progress percentage (0-100) and switch to progress mode
+          #: (Integer percentage) -> void
+          def set_progress(percentage) # rubocop:disable Naming/AccessorMethodName
+            @m.synchronize do
+              @progress_percentage = percentage.clamp(0, 100)
+              @wants_progress_mode = true
+            end
+          end
+
+          # Switch back to indeterminate mode
+          #: -> void
+          def clear_progress
+            @m.synchronize do
+              @progress_percentage = nil
+              @wants_progress_mode = false
+            end
+          end
+
+          # Check if this task wants progress mode
+          #: -> bool
+          def wants_progress_mode?
+            @m.synchronize { @wants_progress_mode }
+          end
+
+          # Get current progress percentage
+          #: -> Integer?
+          def current_progress
+            @m.synchronize { @progress_percentage }
+          end
+
           private
 
-          sig { params(index: Integer, terminal_width: Integer).returns(String) }
+          #: (Integer index, Integer terminal_width) -> String
           def full_render(index, terminal_width)
             o = +''
 
@@ -242,7 +247,7 @@ module CLI
             o
           end
 
-          sig { params(index: Integer).returns(String) }
+          #: (Integer index) -> String
           def partial_render(index)
             o = +''
 
@@ -252,7 +257,7 @@ module CLI
             o
           end
 
-          sig { params(index: Integer).returns(String) }
+          #: (Integer index) -> String
           def glyph(index)
             if @done
               final_glyph = @final_glyph.call(@success)
@@ -272,12 +277,12 @@ module CLI
             end
           end
 
-          sig { returns(String) }
+          #: -> String
           def inset
             @inset ||= CLI::UI::Frame.prefix
           end
 
-          sig { returns(Integer) }
+          #: -> Integer
           def inset_width
             @inset_width ||= CLI::UI::ANSI.printing_width(inset)
           end
@@ -295,15 +300,7 @@ module CLI
         #   spin_group.add('Title') { |spinner| sleep 1.0 }
         #   spin_group.wait
         #
-        sig do
-          params(
-            title: String,
-            final_glyph: T.proc.params(success: T::Boolean).returns(T.any(Glyph, String)),
-            merged_output: T::Boolean,
-            duplicate_output_to: IO,
-            block: T.proc.params(task: Task).void,
-          ).void
-        end
+        #: (String title, ?final_glyph: ^(bool success) -> (Glyph | String), ?merged_output: bool, ?duplicate_output_to: IO) { (Task task) -> void } -> void
         def add(
           title,
           final_glyph: DEFAULT_FINAL_GLYPH,
@@ -323,7 +320,7 @@ module CLI
           end
         end
 
-        sig { void }
+        #: -> void
         def stop
           # If we already own the mutex (called from within another synchronized block),
           # set stopped directly to avoid deadlock
@@ -342,7 +339,7 @@ module CLI
           @work_queue.interrupt
         end
 
-        sig { returns(T::Boolean) }
+        #: -> bool
         def stopped?
           if @m.owned?
             @stopped
@@ -363,93 +360,88 @@ module CLI
         #   spin_group.add('Title') { |spinner| sleep 1.0 }
         #   spin_group.wait
         #
-        sig { params(to: IOLike).returns(T::Boolean) }
+        #: (?to: io_like) -> bool
         def wait(to: $stdout)
-          idx = 0
+          result = false #: bool
 
-          consumed_lines = 0
+          CLI::UI::ProgressReporter.with_progress(mode: :indeterminate, to: to, delay_start: true) do |reporter|
+            idx = 0
+            consumed_lines = 0
 
-          @work_queue.close if @internal_work_queue
+            @work_queue.close if @internal_work_queue
 
-          tasks_seen = @tasks.map { false }
-          tasks_seen_done = @tasks.map { false }
+            tasks_seen = @tasks.map { false }
+            tasks_seen_done = @tasks.map { false }
 
-          loop do
-            break if stopped?
+            current_mode = :indeterminate #: Symbol
+            first_render = true #: bool
 
-            done_count = 0
+            loop do
+              break if stopped?
 
-            width = CLI::UI::Terminal.width
+              done_count = 0
+              width = CLI::UI::Terminal.width
 
-            self.class.pause_mutex.synchronize do
-              next if self.class.paused?
+              # Update progress mode based on task states
+              current_mode = update_progress_mode(reporter, current_mode, first_render)
 
-              @m.synchronize do
-                CLI::UI.raw do
-                  force_full_render = false
+              self.class.pause_mutex.synchronize do
+                next if self.class.paused?
 
-                  unless @puts_above.empty?
-                    to.print(CLI::UI::ANSI.cursor_up(consumed_lines)) if CLI::UI.enable_cursor?
-                    while (message = @puts_above.shift)
-                      to.print(CLI::UI::ANSI.insert_lines(message.lines.count)) if CLI::UI.enable_cursor?
-                      message.lines.each do |line|
-                        to.print(CLI::UI::Frame.prefix + CLI::UI.fmt(line))
-                      end
-                      to.print("\n")
-                    end
-                    # we descend with newlines rather than ANSI.cursor_down as the inserted lines may've
-                    # pushed the spinner off the front of the buffer, so we can't move back down below it
-                    to.print("\n" * consumed_lines) if CLI::UI.enable_cursor?
+                @m.synchronize do
+                  CLI::UI.raw do
+                    # Render any messages above the spinner
+                    force_full_render = render_puts_above(to, consumed_lines)
 
-                    force_full_render = true
-                  end
-
-                  @tasks.each.with_index do |task, int_index|
-                    nat_index = int_index + 1
-                    task_done = task.check
-                    done_count += 1 if task_done
-
-                    if CLI::UI.enable_cursor?
-                      if nat_index > consumed_lines
-                        to.print(task.render(idx, true, width: width) + "\n")
-                        consumed_lines += 1
-                      else
-                        offset = consumed_lines - int_index
-                        move_to = CLI::UI::ANSI.cursor_up(offset) + "\r"
-                        move_from = "\r" + CLI::UI::ANSI.cursor_down(offset)
-
-                        to.print(move_to + task.render(idx, idx.zero? || force_full_render, width: width) + move_from)
-                      end
-                    elsif !tasks_seen[int_index] || (task_done && !tasks_seen_done[int_index])
-                      to.print(task.render(idx, true, width: width) + "\n")
-                    end
-
-                    tasks_seen[int_index] = true
-                    tasks_seen_done[int_index] ||= task_done
+                    # Render all tasks
+                    done_count, consumed_lines = render_tasks(
+                      to: to,
+                      tasks_seen: tasks_seen,
+                      tasks_seen_done: tasks_seen_done,
+                      consumed_lines: consumed_lines,
+                      idx: idx,
+                      force_full_render: force_full_render,
+                      width: width,
+                    )
                   end
                 end
               end
+
+              break if done_count == @tasks.size
+
+              # After first render, start the progress reporter in indeterminate mode
+              if first_render
+                reporter.force_set_indeterminate
+                first_render = false
+              end
+
+              idx = (idx + 1) % GLYPHS.size
+              Spinner.index = idx
+              sleep(PERIOD)
             end
 
-            break if done_count == @tasks.size
+            # Show error state briefly if tasks failed
+            success = all_succeeded?
+            unless success
+              reporter.set_error
+              sleep(0.5)
+            end
 
-            idx = (idx + 1) % GLYPHS.size
-            Spinner.index = idx
-            sleep(PERIOD)
+            result = if @auto_debrief
+              debrief(to: to)
+            else
+              all_succeeded?
+            end
           end
 
-          if @auto_debrief
-            debrief(to: to)
-          else
-            all_succeeded?
-          end
+          result
         rescue Interrupt
           @work_queue.interrupt
           debrief(to: to) if @interrupt_debrief
           stopped? ? false : raise
         end
 
-        sig { params(message: String).void }
+        #: (String message) -> void
         def puts_above(message)
           @m.synchronize do
             @puts_above << message
@@ -457,32 +449,110 @@ module CLI
         end
 
         # Provide an alternative debriefing for failed tasks
-        sig do
-          params(
-            block: T.proc.params(title: String, exception: T.nilable(Exception), out: String, err: String).void,
-          ).void
-        end
+        #: { (String title, Exception? exception, String out, String err) -> void } -> void
         def failure_debrief(&block)
           @failure_debrief = block
         end
 
         # Provide a debriefing for successful tasks
-        sig do
-          params(
-            block: T.proc.params(title: String, out: String, err: String).void,
-          ).void
-        end
+        #: { (String title, String out, String err) -> void } -> void
         def success_debrief(&block)
           @success_debrief = block
         end
 
-        sig { returns(T::Boolean) }
+        #: -> bool
         def all_succeeded?
           @m.synchronize do
             @tasks.all?(&:success)
           end
         end
 
+        private
+
+        # Update progress reporter mode based on task progress states
+        #: (CLI::UI::ProgressReporter::Reporter reporter, Symbol current_mode, bool first_render) -> Symbol
+        def update_progress_mode(reporter, current_mode, first_render)
+          # Don't emit OSC on first iteration
+          return current_mode if first_render
+
+          # Check if any task wants progress mode
+          task_with_progress = @tasks.find(&:wants_progress_mode?)
+
+          if task_with_progress
+            progress = task_with_progress.current_progress
+            if progress
+              reporter.force_set_progress(progress)
+              if current_mode != :progress
+                # Switch to progress mode
+                :progress
+              else
+                # Update progress
+                current_mode
+              end
+            else
+              current_mode
+            end
+          elsif current_mode != :indeterminate
+            # No task wants progress, switch back to indeterminate
+            reporter.force_set_indeterminate
+            :indeterminate
+          else
+            current_mode
+          end
+        end
+
+        # Render messages that should appear above the spinner
+        #: (io_like to, Integer consumed_lines) -> bool
+        def render_puts_above(to, consumed_lines)
+          return false if @puts_above.empty?
+
+          to.print(CLI::UI::ANSI.cursor_up(consumed_lines)) if CLI::UI.enable_cursor?
+          while (message = @puts_above.shift)
+            to.print(CLI::UI::ANSI.insert_lines(message.lines.count)) if CLI::UI.enable_cursor?
+            message.lines.each do |line|
+              to.print(CLI::UI::Frame.prefix + CLI::UI.fmt(line))
+            end
+            to.print("\n")
+          end
+          # we descend with newlines rather than ANSI.cursor_down as the inserted lines may've
+          # pushed the spinner off the front of the buffer, so we can't move back down below it
+          to.print("\n" * consumed_lines) if CLI::UI.enable_cursor?
+
+          true # force full render needed
+        end
+
+        # Render all tasks
+        #: (to: io_like, tasks_seen: Array[bool], tasks_seen_done: Array[bool], consumed_lines: Integer, idx: Integer, force_full_render: bool, width: Integer) -> [Integer, Integer]
+        def render_tasks(to:, tasks_seen:, tasks_seen_done:, consumed_lines:, idx:, force_full_render:, width:)
+          done_count = 0
+
+          @tasks.each.with_index do |task, int_index|
+            nat_index = int_index + 1
+            task_done = task.check
+            done_count += 1 if task_done
+
+            if CLI::UI.enable_cursor?
+              if nat_index > consumed_lines
+                to.print(task.render(idx, true, width: width) + "\n")
+                consumed_lines += 1
+              else
+                offset = consumed_lines - int_index
+                move_to = CLI::UI::ANSI.cursor_up(offset) + "\r"
+                move_from = "\r" + CLI::UI::ANSI.cursor_down(offset)
+
+                to.print(move_to + task.render(idx, idx.zero? || force_full_render, width: width) + move_from)
+              end
+            elsif !tasks_seen[int_index] || (task_done && !tasks_seen_done[int_index])
+              to.print(task.render(idx, true, width: width) + "\n")
+            end
+
+            tasks_seen[int_index] = true
+            tasks_seen_done[int_index] ||= task_done
+          end
+
+          [done_count, consumed_lines]
+        end
+
         # Debriefs failed tasks is +auto_debrief+ is true
         #
         # ==== Options
@@ -490,7 +560,7 @@ module CLI
         # * +:to+ - Target stream, like $stdout or $stderr. Can be anything with print and puts methods,
         #   or under Sorbet, IO or StringIO. Defaults to $stdout
         #
-        sig { params(to: IOLike).returns(T::Boolean) }
+        #: (?to: io_like) -> bool
         def debrief(to: $stdout)
           @m.synchronize do
             @tasks.each do |task|

data/lib/cli/ui/spinner.rb

@@ -6,8 +6,6 @@ require 'cli/ui'
 module CLI
   module UI
     module Spinner
-      extend T::Sig
-
       autoload :Async,      'cli/ui/spinner/async'
       autoload :SpinGroup,  'cli/ui/spinner/spin_group'
 
@@ -25,9 +23,7 @@ module CLI
       GLYPHS = colors.zip(RUNES).map { |c, r| c + r + CLI::UI::Color::RESET.code }.freeze
 
       class << self
-        extend T::Sig
-
-        sig { returns(T.nilable(Integer)) }
+        #: Integer?
         attr_accessor(:index)
 
         # We use this from CLI::UI::Widgets::Status to render an additional
@@ -40,15 +36,13 @@ module CLI
         # While it would be possible to stitch through some connection between
         # the SpinGroup and the Widgets included in its title, this is simpler
         # in practice and seems unlikely to cause issues in practice.
-        sig { returns(String) }
+        #: -> String
         def current_rune
           RUNES[index || 0]
         end
       end
 
       class << self
-        extend T::Sig
-
         # Adds a single spinner
         # Uses an interactive session to allow the user to pick an answer
         # Can use arrows, y/n, numbers (1/2), and vim bindings to control
@@ -73,14 +67,7 @@ module CLI
         #
         #   CLI::UI::Spinner.spin('Title') { sleep 1.0 }
         #
-        sig do
-          params(
-            title: String,
-            auto_debrief: T::Boolean,
-            to: IOLike,
-            block: T.proc.params(task: SpinGroup::Task).void,
-          ).returns(T::Boolean)
-        end
+        #: (String title, ?auto_debrief: bool, ?to: io_like) { (SpinGroup::Task task) -> void } -> bool
         def spin(title, auto_debrief: true, to: $stdout, &block)
           sg = SpinGroup.new(auto_debrief: auto_debrief)
           sg.add(title, &block)