cli-kit 3.3.0 → 5.0.0

data/lib/cli/kit/command_registry.rb

@@ -1,64 +1,110 @@
+# typed: true
+
 require 'cli/kit'
 
 module CLI
   module Kit
     class CommandRegistry
-      attr_reader :commands, :aliases
+      extend T::Sig
 
-      module NullContextualResolver
-        def self.command_names
-          []
-        end
+      CommandOrProc = T.type_alias do
+        T.any(T.class_of(CLI::Kit::BaseCommand), T.proc.returns(T.class_of(CLI::Kit::BaseCommand)))
+      end
 
-        def self.aliases
-          {}
-        end
+      sig { returns(T::Hash[String, CommandOrProc]) }
+      attr_reader :commands
 
-        def self.command_class(_name)
-          nil
+      sig { returns(T::Hash[String, String]) }
+      attr_reader :aliases
+
+      module ContextualResolver
+        extend T::Sig
+        extend T::Helpers
+        interface!
+
+        sig { abstract.returns(T::Array[String]) }
+        def command_names; end
+
+        sig { abstract.returns(T::Hash[String, String]) }
+        def aliases; end
+
+        sig { abstract.params(_name: String).returns(T.class_of(CLI::Kit::BaseCommand)) }
+        def command_class(_name); end
+      end
+
+      module NullContextualResolver
+        extend T::Sig
+        extend ContextualResolver
+
+        class << self
+          extend T::Sig
+
+          sig { override.returns(T::Array[String]) }
+          def command_names
+            []
+          end
+
+          sig { override.returns(T::Hash[String, String]) }
+          def aliases
+            {}
+          end
+
+          sig { override.params(_name: String).returns(T.class_of(CLI::Kit::BaseCommand)) }
+          def command_class(_name)
+            raise(CLI::Kit::Abort, 'Cannot be called on the NullContextualResolver since command_names is empty')
+          end
         end
       end
 
-      def initialize(default:, contextual_resolver: nil)
+      sig { params(default: String, contextual_resolver: ContextualResolver).void }
+      def initialize(default:, contextual_resolver: NullContextualResolver)
         @commands = {}
         @aliases  = {}
         @default = default
-        @contextual_resolver = contextual_resolver || NullContextualResolver
+        @contextual_resolver = contextual_resolver
       end
 
+      sig { returns(T::Hash[String, T.class_of(CLI::Kit::BaseCommand)]) }
       def resolved_commands
         @commands.each_with_object({}) do |(k, v), a|
           a[k] = resolve_class(v)
         end
       end
 
+      sig { params(const: CommandOrProc, name: String).void }
       def add(const, name)
         commands[name] = const
       end
 
+      sig { params(name: T.nilable(String)).returns([T.nilable(T.class_of(CLI::Kit::BaseCommand)), String]) }
       def lookup_command(name)
         name = @default if name.to_s.empty?
-        resolve_command(name)
+        resolve_command(T.must(name))
       end
 
+      sig { params(from: String, to: String).void }
       def add_alias(from, to)
         aliases[from] = to unless aliases[from]
       end
 
+      sig { returns(T::Array[String]) }
       def command_names
         @contextual_resolver.command_names + commands.keys
       end
 
+      sig { params(name: String).returns(T::Boolean) }
       def exist?(name)
         !resolve_command(name).first.nil?
       end
 
       private
 
+      sig { params(name: String).returns(String) }
       def resolve_alias(name)
         aliases[name] || @contextual_resolver.aliases.fetch(name, name)
       end
 
+      sig { params(name: String).returns([T.nilable(T.class_of(CLI::Kit::BaseCommand)), String]) }
       def resolve_command(name)
         name = resolve_alias(name)
         resolve_global_command(name) || \
@@ -66,24 +112,30 @@ module CLI
           [nil, name]
       end
 
+      sig { params(name: String).returns(T.nilable([T.class_of(CLI::Kit::BaseCommand), String])) }
       def resolve_global_command(name)
         klass = resolve_class(commands.fetch(name, nil))
-        return nil unless klass&.defined?
+        return nil unless klass
+
         [klass, name]
       rescue NameError
         nil
       end
 
+      sig { params(name: String).returns(T.nilable([T.class_of(CLI::Kit::BaseCommand), String])) }
       def resolve_contextual_command(name)
         found = @contextual_resolver.command_names.include?(name)
         return nil unless found
+
         [@contextual_resolver.command_class(name), name]
       end
 
+      sig { params(class_or_proc: T.nilable(CommandOrProc)).returns(T.nilable(T.class_of(CLI::Kit::BaseCommand))) }
       def resolve_class(class_or_proc)
-        if class_or_proc.is_a?(Class)
-          class_or_proc
-        elsif class_or_proc.respond_to?(:call)
+        case class_or_proc
+        when nil
+          nil
+        when Proc
           class_or_proc.call
         else
           class_or_proc

data/lib/cli/kit/config.rb

@@ -1,11 +1,16 @@
+# typed: true
+
 require 'cli/kit'
 require 'fileutils'
 
 module CLI
   module Kit
     class Config
+      extend T::Sig
+
       XDG_CONFIG_HOME = 'XDG_CONFIG_HOME'
 
+      sig { params(tool_name: String).void }
       def initialize(tool_name:)
         @tool_name = tool_name
       end
@@ -18,22 +23,26 @@ module CLI
       # `name` : the name of the config value you are looking for
       #
       # #### Returns
-      # `value` : the value of the config variable (false if none)
+      # `value` : the value of the config variable (nil if none)
       #
       # #### Example Usage
       # `config.get('name.of.config')`
       #
-      def get(section, name, default: false)
+      sig { params(section: String, name: String, default: T.nilable(String)).returns(T.nilable(String)) }
+      def get(section, name, default: nil)
         all_configs.dig("[#{section}]", name) || default
       end
 
       # Coalesce and enforce the value of a config to a boolean
+      sig { params(section: String, name: String, default: T.nilable(T::Boolean)).returns(T.nilable(T::Boolean)) }
       def get_bool(section, name, default: false)
-        case get(section, name, default: default).to_s
-        when "true"
+        case get(section, name)
+        when 'true'
           true
-        when "false"
+        when 'false'
           false
+        when nil
+          default
         else
           raise CLI::Kit::Abort, "Invalid config: #{section}.#{name} is expected to be true or false"
         end
@@ -49,9 +58,15 @@ module CLI
       # #### Example Usage
       # `config.set('section', 'name.of.config', 'value')`
       #
+      sig { params(section: String, name: String, value: T.nilable(T.any(String, T::Boolean))).void }
       def set(section, name, value)
         all_configs["[#{section}]"] ||= {}
-        all_configs["[#{section}]"][name] = value.nil? ? nil : value.to_s
+        case value
+        when nil
+          T.must(all_configs["[#{section}]"]).delete(name)
+        else
+          T.must(all_configs["[#{section}]"])[name] = value.to_s
+        end
         write_config
       end
 
@@ -64,6 +79,7 @@ module CLI
       # #### Example Usage
       # `config.unset('section', 'name.of.config')`
       #
+      sig { params(section: String, name: String).void }
       def unset(section, name)
         set(section, name, nil)
       end
@@ -76,24 +92,12 @@ module CLI
       # #### Example Usage
       # `config.get_section('section')`
       #
+      sig { params(section: String).returns(T::Hash[String, String]) }
       def get_section(section)
         (all_configs["[#{section}]"] || {}).dup
       end
 
-      # Returns a path from config in expanded form
-      # e.g. shopify corresponds to ~/src/shopify, but is expanded to /Users/name/src/shopify
-      #
-      # #### Example Usage
-      # `config.get_path('srcpath', 'shopify')`
-      #
-      # #### Returns
-      # `path` : the expanded path to the corrsponding value
-      #
-      def get_path(section, name = nil)
-        v = get(section, name)
-        false == v ? v : File.expand_path(v)
-      end
-
+      sig { returns(String) }
       def to_s
         ini.to_s
       end
@@ -103,6 +107,7 @@ module CLI
       # if ENV['XDG_CONFIG_HOME'] is not set, we default to ~/.config, e.g.:
       #   ~/.config/tool/config
       #
+      sig { returns(String) }
       def file
         config_home = ENV.fetch(XDG_CONFIG_HOME, '~/.config')
         File.expand_path(File.join(@tool_name, 'config'), config_home)
@@ -110,20 +115,20 @@ module CLI
 
       private
 
+      sig { returns(T::Hash[String, T::Hash[String, String]]) }
       def all_configs
         ini.ini
       end
 
+      sig { returns(CLI::Kit::Ini) }
       def ini
-        @ini ||= CLI::Kit::Ini
-          .new(file, default_section: "[global]", convert_types: false)
-          .tap(&:parse)
+        @ini ||= CLI::Kit::Ini.new(file).tap(&:parse)
       end
 
+      sig { void }
       def write_config
         all_configs.each do |section, sub_config|
-          all_configs[section] = sub_config.reject { |_, value| value.nil? }
-          all_configs.delete(section) if all_configs[section].empty?
+          all_configs.delete(section) if sub_config.empty?
         end
         FileUtils.mkdir_p(File.dirname(file))
         File.write(file, to_s)

data/lib/cli/kit/core_ext.rb

@@ -0,0 +1,30 @@
+# typed: strong
+# frozen_string_literal: true
+
+class Exception
+  extend(T::Sig)
+
+  # You'd think instance variables @bug and @silent would work here. They
+  # don't. I'm not sure why. If you, the reader, want to take some time to
+  # figure it out, go ahead and refactor to that.
+
+  sig { returns(T::Boolean) }
+  def bug?
+    true
+  end
+
+  sig { returns(T::Boolean) }
+  def silent?
+    false
+  end
+
+  sig { params(bug: T::Boolean).void }
+  def bug!(bug = true)
+    singleton_class.define_method(:bug?) { bug }
+  end
+
+  sig { params(silent: T::Boolean).void }
+  def silent!(silent = true)
+    singleton_class.define_method(:silent?) { silent }
+  end
+end

data/lib/cli/kit/error_handler.rb

@@ -1,115 +1,182 @@
+# typed: true
+
 require 'cli/kit'
 require 'English'
 
 module CLI
   module Kit
     class ErrorHandler
-      def initialize(log_file:, exception_reporter:, tool_name: nil)
+      extend T::Sig
+
+      ExceptionReporterOrProc = T.type_alias do
+        T.any(T.class_of(ExceptionReporter), T.proc.returns(T.class_of(ExceptionReporter)))
+      end
+
+      sig { params(override_exception_handler: T.proc.params(arg0: Exception).returns(Integer)).void }
+      attr_writer :override_exception_handler
+
+      sig do
+        params(
+          log_file: T.nilable(String),
+          exception_reporter: ExceptionReporterOrProc,
+          tool_name: T.nilable(String),
+          dev_mode: T::Boolean,
+        ).void
+      end
+      def initialize(log_file: nil, exception_reporter: NullExceptionReporter, tool_name: nil, dev_mode: false)
         @log_file = log_file
-        @exception_reporter_or_proc = exception_reporter || NullExceptionReporter
+        @exception_reporter_or_proc = exception_reporter
         @tool_name = tool_name
+        @dev_mode = dev_mode
       end
 
-      module NullExceptionReporter
-        def self.report(_exception, _logs)
-          nil
+      class ExceptionReporter
+        extend T::Sig
+        extend T::Helpers
+        abstract!
+
+        class << self
+          extend T::Sig
+
+          sig { abstract.params(exception: T.nilable(Exception), logs: T.nilable(String)).void }
+          def report(exception, logs = nil); end
         end
       end
 
+      class NullExceptionReporter < ExceptionReporter
+        extend T::Sig
+
+        class << self
+          extend T::Sig
+
+          sig { override.params(_exception: T.nilable(Exception), _logs: T.nilable(String)).void }
+          def report(_exception, _logs = nil)
+            nil
+          end
+        end
+      end
+
+      sig { params(block: T.proc.void).returns(Integer) }
       def call(&block)
-        install!
-        handle_abort(&block)
+        # @at_exit_exception is set if handle_abort decides to submit an error.
+        # $ERROR_INFO is set if we terminate because of a signal.
+        at_exit { report_exception(@at_exit_exception || $ERROR_INFO) }
+        triage_all_exceptions(&block)
       end
 
-      def handle_exception(error)
-        if notify_with = exception_for_submission(error)
-          logs = begin
-            File.read(@log_file)
-          rescue => e
-            "(#{e.class}: #{e.message})"
+      sig { params(error: T.nilable(Exception)).void }
+      def report_exception(error)
+        if (notify_with = exception_for_submission(error))
+          logs = nil
+          if @log_file
+            logs = begin
+              File.read(@log_file)
+            rescue => e
+              "(#{e.class}: #{e.message})"
+            end
           end
           exception_reporter.report(notify_with, logs)
         end
       end
 
-      # maybe we can get rid of this.
-      attr_writer :exception
+      SIGNALS_THAT_ARENT_BUGS = [
+        'SIGTERM', 'SIGHUP', 'SIGINT',
+      ].freeze
 
       private
 
+      # Run the program, handling any errors that occur.
+      #
+      # Errors are printed to stderr unless they're #silent?, and are reported
+      # to bugsnag (by setting @at_exit_exeption for our at_exit handler) if
+      # they're #bug?
+      #
+      # Returns an exit status for the program.
+      sig { params(block: T.proc.void).returns(Integer) }
+      def triage_all_exceptions(&block)
+        begin
+          block.call
+          CLI::Kit::EXIT_SUCCESS
+        rescue Interrupt => e # Ctrl-C
+          # transform message, prevent bugsnag
+          exc = e.exception('Interrupt')
+          CLI::Kit.raise(exc, bug: false)
+        rescue Errno::ENOSPC => e
+          # transform message, prevent bugsnag
+          message = if @tool_name
+            "Your disk is full - {{command:#{@tool_name}}} requires free space to operate"
+          else
+            'Your disk is full - free space is required to operate'
+          end
+          exc = e.exception(message)
+          CLI::Kit.raise(exc, bug: false)
+        end
+      # If SystemExit was raised, e.g. `exit()`, then
+      # return whatever status is attached to the exception
+      # object. The special exit statuses have already been
+      # handled below.
+      rescue SystemExit => e
+        e.status
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        @at_exit_exception = e if e.bug?
+
+        if (eh = @override_exception_handler)
+          return eh.call(e)
+        end
+
+        raise(e) if @dev_mode && e.bug?
+
+        stderr_puts(e.message) unless e.silent?
+        e.bug? ? CLI::Kit::EXIT_BUG : CLI::Kit::EXIT_FAILURE_BUT_NOT_BUG
+      end
+
+      sig { params(error: T.nilable(Exception)).returns(T.nilable(Exception)) }
       def exception_for_submission(error)
+        # happens on normal non-error termination
+        return(nil) if error.nil?
+
+        return(nil) unless error.bug?
+
         case error
-        when nil         # normal, non-error termination
-          nil
-        when Interrupt   # ctrl-c
-          nil
-        when CLI::Kit::Abort, CLI::Kit::AbortSilent # Not a bug
-          nil
         when SignalException
-          skip = %w(SIGTERM SIGHUP SIGINT)
-          skip.include?(error.message) ? nil : error
+          SIGNALS_THAT_ARENT_BUGS.include?(error.message) ? nil : error
         when SystemExit # "exit N" called
           case error.status
           when CLI::Kit::EXIT_SUCCESS # submit nothing if it was `exit 0`
             nil
           when CLI::Kit::EXIT_FAILURE_BUT_NOT_BUG
-            # if it was `exit 30`, translate the exit code to 1, and submit nothing.
-            # 30 is used to signal normal failures that are not indicative of bugs.
-            # However, users should see it presented as 1.
-            exit 1
+            # if it was `exit 30`, translate the exit code to 1, and submit
+            # nothing. 30 is used to signal normal failures that are not
+            # indicative of bugs. However, users should see it presented as 1.
+            exit(1)
           else
-            # A weird termination status happened. `error.exception "message"` will maintain backtrace
-            # but allow us to set a message
-            error.exception("abnormal termination status: #{error.status}")
+            # don't treat this as an exception, simply reraise.
+            # this is indicative of `exit` being called with a
+            # non-zero number, and the requested exit status
+            # needs to be maintained.
+            exit(error.status)
           end
         else
           error
         end
       end
 
-      def install!
-        at_exit { handle_exception(@exception || $ERROR_INFO) }
-      end
-
-      def handle_abort
-        yield
-        CLI::Kit::EXIT_SUCCESS
-      rescue CLI::Kit::GenericAbort => e
-        is_bug    = e.is_a?(CLI::Kit::Bug) || e.is_a?(CLI::Kit::BugSilent)
-        is_silent = e.is_a?(CLI::Kit::AbortSilent) || e.is_a?(CLI::Kit::BugSilent)
-
-        print_error_message(e) unless is_silent
-        (@exception = e) if is_bug
-
-        CLI::Kit::EXIT_FAILURE_BUT_NOT_BUG
-      rescue Interrupt
-        $stderr.puts(format_error_message("Interrupt"))
-        CLI::Kit::EXIT_FAILURE_BUT_NOT_BUG
-      rescue Errno::ENOSPC
-        message = if @tool_name
-          "Your disk is full - {{command:#{@tool_name}}} requires free space to operate"
-        else
-          "Your disk is full - free space is required to operate"
-        end
-        $stderr.puts(format_error_message(message))
-        CLI::Kit::EXIT_FAILURE_BUT_NOT_BUG
+      sig { params(message: String).void }
+      def stderr_puts(message)
+        $stderr.puts(CLI::UI.fmt("{{red:#{message}}}"))
+      rescue Errno::EPIPE, Errno::EIO
+        nil
       end
 
+      sig { returns(T.class_of(ExceptionReporter)) }
       def exception_reporter
-        if @exception_reporter_or_proc.respond_to?(:report)
-          @exception_reporter_or_proc
-        else
+        case @exception_reporter_or_proc
+        when Proc
           @exception_reporter_or_proc.call
+        else
+          @exception_reporter_or_proc
         end
       end
-
-      def format_error_message(msg)
-        CLI::UI.fmt("{{red:#{msg}}}")
-      end
-
-      def print_error_message(e)
-        $stderr.puts(format_error_message(e.message))
-      end
     end
   end
 end

data/lib/cli/kit/executor.rb

@@ -1,3 +1,5 @@
+# typed: true
+
 require 'cli/kit'
 require 'English'
 require 'fileutils'
@@ -5,61 +7,77 @@ require 'fileutils'
 module CLI
   module Kit
     class Executor
+      extend T::Sig
+
+      sig { params(log_file: String).void }
       def initialize(log_file:)
         FileUtils.mkpath(File.dirname(log_file))
         @log_file = log_file
       end
 
+      sig { params(command: T.class_of(CLI::Kit::BaseCommand), command_name: String, args: T::Array[String]).void }
       def call(command, command_name, args)
         with_traps do
           with_logging do |id|
+            command.call(args, command_name)
+          rescue => e
             begin
-              command.call(args, command_name)
-            rescue => e
-              begin
-                $stderr.puts "This command ran with ID: #{id}"
-                $stderr.puts "Please include this information in any issues/report along with relevant logs"
-              rescue SystemCallError
-                # Outputting to stderr is best-effort.  Avoid raising another error when outputting debug info so that
-                # we can detect and log the original error, which may even be the source of this error.
-                nil
-              end
-              raise e
+              $stderr.puts "This command ran with ID: #{id}"
+              $stderr.puts 'Please include this information in any issues/report along with relevant logs'
+            rescue SystemCallError
+              # Outputting to stderr is best-effort.  Avoid raising another error when outputting debug info so that
+              # we can detect and log the original error, which may even be the source of this error.
+              nil
             end
+            raise e
           end
         end
       end
 
       private
 
+      sig do
+        type_parameters(:T).params(block: T.proc.params(id: String).returns(T.type_parameter(:T)))
+          .returns(T.type_parameter(:T))
+      end
       def with_logging(&block)
-        return yield unless @log_file
         CLI::UI.log_output_to(@log_file) do
-          CLI::UI::StdoutRouter.with_id(on_streams: [CLI::UI::StdoutRouter.duplicate_output_to]) do |id|
+          CLI::UI::StdoutRouter.with_id(on_streams: [CLI::UI::StdoutRouter.duplicate_output_to].compact) do |id|
             block.call(id)
           end
         end
       end
 
-      def with_traps
+      sig { type_parameters(:T).params(block: T.proc.returns(T.type_parameter(:T))).returns(T.type_parameter(:T)) }
+      def with_traps(&block)
         twrap('QUIT', method(:quit_handler)) do
-          twrap('INFO', method(:info_handler)) do
-            yield
-          end
+          twrap('INFO', method(:info_handler), &block)
         end
       end
 
-      def twrap(signal, handler)
+      sig do
+        type_parameters(:T).params(signal: String, handler: Method,
+          block: T.proc.returns(T.type_parameter(:T))).returns(T.type_parameter(:T))
+      end
+      def twrap(signal, handler, &block)
         return yield unless Signal.list.key?(signal)
 
         begin
-          prev_handler = trap(signal, handler)
+          begin
+            prev_handler = trap(signal, handler)
+            installed = true
+          rescue ArgumentError
+            # If we couldn't install a signal handler because the signal is
+            # reserved, remember not to uninstall it later.
+            installed = false
+          end
           yield
         ensure
-          trap(signal, prev_handler)
+          trap(signal, prev_handler) if installed
         end
       end
 
+      sig { params(_sig: T.untyped).void }
       def quit_handler(_sig)
         z = caller
         CLI::UI.raw do
@@ -69,6 +87,7 @@ module CLI
         exit(CLI::Kit::EXIT_FAILURE_BUT_NOT_BUG)
       end
 
+      sig { params(_sig: T.untyped).void }
       def info_handler(_sig)
         z = caller
         CLI::UI.raw do