cli-kit 4.0.0 → 5.0.1

data/lib/cli/kit/ini.rb

@@ -1,3 +1,7 @@
+# typed: true
+
+require 'cli/kit'
+
 module CLI
   module Kit
     # INI is a language similar to JSON or YAML, but simplied
@@ -13,87 +17,76 @@ module CLI
     # See the ini_test.rb file for more examples
     #
     class Ini
+      extend T::Sig
+
+      sig { returns(T::Hash[String, T::Hash[String, String]]) }
       attr_accessor :ini
 
-      def initialize(path = nil, config: nil, default_section: nil, convert_types: true)
+      sig do
+        params(path: T.nilable(String), config: T.nilable(String), default_section: String).void
+      end
+      def initialize(path = nil, config: nil, default_section: '[global]')
         @config = if path && File.exist?(path)
           File.readlines(path)
         elsif config
           config.lines
         end
         @ini = {}
-        @current_key = nil
-        @default_section = default_section
-        @convert_types = convert_types
+        @current_key = default_section
       end
 
+      sig { returns(T::Hash[String, T::Hash[String, String]]) }
       def parse
         return @ini if @config.nil?
 
         @config.each do |l|
           l.strip!
 
-          # If section, then set current key, this will nest the setting
           if section_designator?(l)
             @current_key = l
-
-          # A new line will reset the current key
-          elsif l.strip.empty?
-            @current_key = nil
-
-          # Otherwise set the values
           else
             k, v = l.split('=', 2).map(&:strip)
-            set_val(k, v)
+            set_val(k, v) if k && v
           end
         end
+
         @ini
       end
 
+      sig { returns(String) }
       def git_format
-        to_ini(@ini, git_format: true).flatten.join("\n")
+        to_ini(git_format: true)
       end
 
+      sig { returns(String) }
       def to_s
-        to_ini(@ini).flatten.join("\n")
+        to_ini
       end
 
       private
 
-      def to_ini(h, git_format: false)
+      sig { params(git_format: T::Boolean).returns(String) }
+      def to_ini(git_format: false)
         optional_tab = git_format ? "\t" : ''
         str = []
-        h.each do |k, v|
-          if section_designator?(k)
-            str << '' unless str.empty? || git_format
-            str << k
-            str << to_ini(v, git_format: git_format)
-          else
+        @ini.each do |section_designator, section|
+          str << '' unless str.empty? || git_format
+          str << section_designator
+          section.each do |k, v|
             str << "#{optional_tab}#{k} = #{v}"
           end
         end
-        str
+        str.join("\n")
       end
 
+      sig { params(key: String, val: String).void }
       def set_val(key, val)
-        return if key.nil? && val.nil?
-
-        current_key = @current_key || @default_section
-        if current_key
-          @ini[current_key] ||= {}
-          @ini[current_key][key] = typed_val(val)
-        else
-          @ini[key] = typed_val(val)
-        end
-      end
-
-      def typed_val(val)
-        return val.to_s unless @convert_types
-        return val.to_i if val =~ /^-?[0-9]+$/
-        return val.to_f if val =~ /^-?[0-9]+\.[0-9]*$/
-        val.to_s
+        current_key = @current_key
+        @ini[current_key] ||= {}
+        @ini[current_key][key] = val
       end
 
+      sig { params(k: String).returns(T::Boolean) }
       def section_designator?(k)
         k.start_with?('[') && k.end_with?(']')
       end

data/lib/cli/kit/levenshtein.rb

@@ -1,3 +1,5 @@
+# typed: true
+
 # Copyright (c) 2014-2016 Yuki Nishijima
 
 # MIT License
@@ -21,13 +23,18 @@
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
+require 'cli/kit'
+
 module CLI
   module Kit
     module Levenshtein
+      extend T::Sig
+
       # This code is based directly on the Text gem implementation
       # Copyright (c) 2006-2013 Paul Battley, Michael Neumann, Tim Fletcher.
       #
       # Returns a value representing the "cost" of transforming str1 into str2
+      sig { params(str1: String, str2: String).returns(Integer) }
       def distance(str1, str2)
         n = str1.length
         m = str2.length
@@ -35,7 +42,7 @@ module CLI
         return n if m.zero?
 
         d = (0..m).to_a
-        x = nil
+        x = 0
 
         # to avoid duplicating an enumerable object, create it outside of the loop
         str2_codepoints = str2.codepoints
@@ -45,9 +52,9 @@ module CLI
           while j < m
             cost = char1 == str2_codepoints[j] ? 0 : 1
             x = min3(
-              d[j + 1] + 1, # insertion
-              i + 1,      # deletion
-              d[j] + cost # substitution
+              T.must(d[j + 1]) + 1, # insertion
+              i + 1, # deletion
+              T.must(d[j]) + cost, # substitution
             )
             d[j] = i
             i = x
@@ -67,6 +74,7 @@ module CLI
       # faster than `[a, b, c].min` and puts less GC pressure.
       # See https://github.com/yuki24/did_you_mean/pull/1 for a performance
       # benchmark.
+      sig { params(a: Integer, b: Integer, c: Integer).returns(Integer) }
       def min3(a, b, c)
         if a < b && a < c
           a

data/lib/cli/kit/logger.rb

@@ -1,15 +1,21 @@
+# typed: true
+
+require 'cli/kit'
 require 'logger'
 require 'fileutils'
 
 module CLI
   module Kit
     class Logger
+      extend T::Sig
+
       MAX_LOG_SIZE = 5 * 1024 * 1000 # 5MB
       MAX_NUM_LOGS = 10
 
       # Constructor for CLI::Kit::Logger
       #
       # @param debug_log_file [String] path to the file where debug logs should be stored
+      sig { params(debug_log_file: String, env_debug_name: String).void }
       def initialize(debug_log_file:, env_debug_name: 'DEBUG')
         FileUtils.mkpath(File.dirname(debug_log_file))
         @debug_logger = ::Logger.new(debug_log_file, MAX_NUM_LOGS, MAX_LOG_SIZE)
@@ -21,6 +27,7 @@ module CLI
       #
       # @param msg [String] the message to log
       # @param debug [Boolean] determines if the debug logger will receive the log (default true)
+      sig { params(msg: String, debug: T::Boolean).void }
       def info(msg, debug: true)
         $stdout.puts CLI::UI.fmt(msg)
         @debug_logger.info(format_debug(msg)) if debug
@@ -31,6 +38,7 @@ module CLI
       #
       # @param msg [String] the message to log
       # @param debug [Boolean] determines if the debug logger will receive the log (default true)
+      sig { params(msg: String, debug: T::Boolean).void }
       def warn(msg, debug: true)
         $stdout.puts CLI::UI.fmt("{{yellow:#{msg}}}")
         @debug_logger.warn(format_debug(msg)) if debug
@@ -41,6 +49,7 @@ module CLI
       #
       # @param msg [String] the message to log
       # @param debug [Boolean] determines if the debug logger will receive the log (default true)
+      sig { params(msg: String, debug: T::Boolean).void }
       def error(msg, debug: true)
         $stderr.puts CLI::UI.fmt("{{red:#{msg}}}")
         @debug_logger.error(format_debug(msg)) if debug
@@ -51,6 +60,7 @@ module CLI
       #
       # @param msg [String] the message to log
       # @param debug [Boolean] determines if the debug logger will receive the log (default true)
+      sig { params(msg: String, debug: T::Boolean).void }
       def fatal(msg, debug: true)
         $stderr.puts CLI::UI.fmt("{{red:{{bold:Fatal:}} #{msg}}}")
         @debug_logger.fatal(format_debug(msg)) if debug
@@ -60,6 +70,7 @@ module CLI
       # Logs to the debug file, taking into account CLI::UI::StdoutRouter.current_id
       #
       # @param msg [String] the message to log
+      sig { params(msg: String).void }
       def debug(msg)
         $stdout.puts CLI::UI.fmt(msg) if debug?
         @debug_logger.debug(format_debug(msg))
@@ -67,15 +78,18 @@ module CLI
 
       private
 
+      sig { params(msg: String).returns(String) }
       def format_debug(msg)
         msg = CLI::UI.fmt(msg)
         return msg unless CLI::UI::StdoutRouter.current_id
-        "[#{CLI::UI::StdoutRouter.current_id[:id]}] #{msg}"
+
+        "[#{CLI::UI::StdoutRouter.current_id&.fetch(:id, nil)}] #{msg}"
       end
 
+      sig { returns(T::Boolean) }
       def debug?
         val = ENV[@env_debug_name]
-        val && val != '0' && val != ''
+        !!val && val != '0' && val != ''
       end
     end
   end

data/lib/cli/kit/opts.rb

@@ -0,0 +1,301 @@
+# typed: true
+
+require 'cli/kit'
+
+module CLI
+  module Kit
+    class Opts
+      extend T::Sig
+
+      module Mixin
+        extend T::Sig
+        include Kernel
+
+        module MixinClassMethods
+          extend T::Sig
+
+          sig { params(included_module: Module).void }
+          def include(included_module)
+            super
+            return unless included_module.is_a?(MixinClassMethods)
+
+            included_module.tracked_methods.each { |m| track_method(m) }
+          end
+
+          # No signature - Sorbet uses method_added internally, so can't verify it
+          def method_added(method_name) # rubocop:disable Sorbet/EnforceSignatures
+            super
+            track_method(method_name)
+          end
+
+          sig { params(method_name: Symbol).void }
+          def track_method(method_name)
+            @tracked_methods ||= []
+            @tracked_methods << method_name unless @tracked_methods.include?(method_name)
+          end
+
+          sig { returns(T::Array[Symbol]) }
+          def tracked_methods
+            @tracked_methods || []
+          end
+        end
+
+        class << self
+          extend T::Sig
+
+          sig { params(klass: Module).void }
+          def included(klass)
+            klass.extend(MixinClassMethods)
+          end
+        end
+
+        sig do
+          params(
+            name: Symbol,
+            short: T.nilable(String),
+            long: T.nilable(String),
+            desc: T.nilable(String),
+            default: T.any(NilClass, String, T.proc.returns(String)),
+          ).returns(T.nilable(String))
+        end
+        def option(name: infer_name, short: nil, long: nil, desc: nil, default: nil)
+          unless default.nil?
+            raise(ArgumentError, 'declare options with non-nil defaults using `option!` instead of `option`')
+          end
+
+          case @obj
+          when Args::Definition
+            @obj.add_option(
+              name, short: short, long: long, desc: desc, default: default
+            )
+            '(result unavailable)'
+          when Args::Evaluation
+            @obj.opt.send(name)
+          end
+        end
+
+        sig do
+          params(
+            name: Symbol,
+            short: T.nilable(String),
+            long: T.nilable(String),
+            desc: T.nilable(String),
+            default: T.any(NilClass, String, T.proc.returns(String)),
+          ).returns(String)
+        end
+        def option!(name: infer_name, short: nil, long: nil, desc: nil, default: nil)
+          case @obj
+          when Args::Definition
+            @obj.add_option(
+              name, short: short, long: long, desc: desc, default: default
+            )
+            '(result unavailable)'
+          when Args::Evaluation
+            @obj.opt.send(name)
+          end
+        end
+
+        sig do
+          params(
+            name: Symbol,
+            short: T.nilable(String),
+            long: T.nilable(String),
+            desc: T.nilable(String),
+            default: T.any(T::Array[String], T.proc.returns(T::Array[String])),
+          ).returns(T::Array[String])
+        end
+        def multi_option(name: infer_name, short: nil, long: nil, desc: nil, default: [])
+          case @obj
+          when Args::Definition
+            @obj.add_option(
+              name, short: short, long: long, desc: desc, default: default, multi: true
+            )
+            ['(result unavailable)']
+          when Args::Evaluation
+            @obj.opt.send(name)
+          end
+        end
+
+        sig do
+          params(
+            name: Symbol,
+            short: T.nilable(String),
+            long: T.nilable(String),
+            desc: T.nilable(String),
+          ).returns(T::Boolean)
+        end
+        def flag(name: infer_name, short: nil, long: nil, desc: nil)
+          case @obj
+          when Args::Definition
+            @obj.add_flag(name, short: short, long: long, desc: desc)
+            false
+          when Args::Evaluation
+            @obj.flag.send(name)
+          end
+        end
+
+        sig { params(name: Symbol, desc: T.nilable(String)).returns(String) }
+        def position!(name: infer_name, desc: nil)
+          case @obj
+          when Args::Definition
+            @obj.add_position(name, desc: desc, required: true, multi: false)
+            '(result unavailable)'
+          when Args::Evaluation
+            @obj.position.send(name)
+          end
+        end
+
+        sig do
+          params(
+            name: Symbol,
+            desc: T.nilable(String),
+            default: T.any(NilClass, String, T.proc.returns(String)),
+            skip: T.any(
+              NilClass,
+              T.proc.returns(T::Boolean),
+              T.proc.params(arg0: String).returns(T::Boolean),
+            ),
+          ).returns(T.nilable(String))
+        end
+        def position(name: infer_name, desc: nil, default: nil, skip: nil)
+          case @obj
+          when Args::Definition
+            @obj.add_position(name, desc: desc, required: false, multi: false, default: default, skip: skip)
+            '(result unavailable)'
+          when Args::Evaluation
+            @obj.position.send(name)
+          end
+        end
+
+        sig { params(name: Symbol, desc: T.nilable(String)).returns(T::Array[String]) }
+        def rest(name: infer_name, desc: nil)
+          case @obj
+          when Args::Definition
+            @obj.add_position(name, desc: desc, required: false, multi: true)
+            ['(result unavailable)']
+          when Args::Evaluation
+            @obj.position.send(name)
+          end
+        end
+
+        private
+
+        sig { returns(Symbol) }
+        def infer_name
+          to_skip = 1
+          Kernel.caller_locations.each do |loc|
+            next if loc.path =~ /sorbet-runtime/
+
+            if to_skip > 0
+              to_skip -= 1
+              next
+            end
+            return(T.must(loc.label&.to_sym))
+          end
+          raise(ArgumentError, 'could not infer name')
+        end
+      end
+      include(Mixin)
+
+      DEFAULT_OPTIONS = [:helpflag]
+
+      sig { returns(T::Boolean) }
+      def helpflag
+        flag(name: :help, short: '-h', long: '--help', desc: 'Show this help message')
+      end
+
+      sig { returns(T::Array[String]) }
+      def unparsed
+        obj = assert_result!
+        obj.unparsed
+      end
+
+      sig do
+        params(
+          block: T.nilable(
+            T.proc.params(arg0: Symbol, arg1: T.nilable(String)).void,
+          ),
+        ).returns(T.untyped)
+      end
+      def each_option(&block)
+        return(enum_for(:each_option)) unless block_given?
+
+        obj = assert_result!
+        obj.defn.options.each do |opt|
+          name = opt.name
+          value = obj.opt.send(name)
+          yield(name, value)
+        end
+      end
+
+      sig do
+        params(
+          block: T.nilable(
+            T.proc.params(arg0: Symbol, arg1: T::Boolean).void,
+          ),
+        ).returns(T.untyped)
+      end
+      def each_flag(&block)
+        return(enum_for(:each_flag)) unless block_given?
+
+        obj = assert_result!
+        obj.defn.flags.each do |flag|
+          name = flag.name
+          value = obj.flag.send(name)
+          yield(name, value)
+        end
+      end
+
+      sig { params(name: String).returns(T.nilable(T.any(String, T::Boolean))) }
+      def [](name)
+        obj = assert_result!
+        if obj.opt.respond_to?(name)
+          obj.opt.send(name)
+        elsif obj.flag.respond_to?(name)
+          obj.flag.send(name)
+        end
+      end
+
+      sig { params(name: String).returns(T.nilable(String)) }
+      def lookup_option(name)
+        obj = assert_result!
+        obj.opt.send(name)
+      rescue NoMethodError
+        # TODO: should we raise a KeyError?
+        nil
+      end
+
+      sig { params(name: String).returns(T::Boolean) }
+      def lookup_flag(name)
+        obj = assert_result!
+        obj.flag.send(name)
+      rescue NoMethodError
+        false
+      end
+
+      sig { returns(Args::Evaluation) }
+      def assert_result!
+        raise(NotImplementedError, 'not implemented') if @obj.is_a?(Args::Definition)
+
+        @obj
+      end
+
+      sig { params(defn: Args::Definition).void }
+      def define!(defn)
+        @obj = defn
+        T.cast(self.class, Mixin::MixinClassMethods).tracked_methods.each do |m|
+          send(m)
+        end
+        DEFAULT_OPTIONS.each do |m|
+          send(m)
+        end
+      end
+
+      sig { params(ev: Args::Evaluation).void }
+      def evaluate!(ev)
+        @obj = ev
+        ev.resolve_positions!
+      end
+    end
+  end
+end

data/lib/cli/kit/parse_args.rb

@@ -0,0 +1,55 @@
+# typed: true
+
+module CLI
+  module Kit
+    module ParseArgs
+      # because sorbet type-checking takes the pedantic route that module doesn't include Kernel, therefore
+      # this is necessary (even tho it's ~probably fine~)
+      include Kernel
+      extend T::Sig
+
+      # T.untyped is used in two places. The interpretation of dynamic values from the provided `opts`
+      # and the resulting args[:opts] is pretty broad. There seems to be minimal value in expressing a
+      # tighter subset of T.untyped.
+
+      sig { params(args: String, opts_defn: T::Hash[Symbol, T::Array[T.untyped]]).returns(T::Hash[Symbol, T.untyped]) }
+      def parse_args(args, opts_defn)
+        start_opts, parser_config = opts_defn.reduce([{}, []]) do |(ini, pcfg), (n, cfg)|
+          (vals, desc, short, klass) = cfg
+          (init_val, def_val) = Array(vals)
+
+          [
+            init_val.nil? ? ini : ini.merge(n => init_val),
+            pcfg + [[n, short, desc, def_val, klass]],
+          ]
+        end
+
+        require('optparse')
+
+        acc_opts = {}
+        prsr = OptionParser.new do |opt_p|
+          parser_config.each do |(n, short, desc, def_val, klass)|
+            (_, mark) = short.split(' ')
+            long = "--#{n.to_s.tr("_", "-")}" + (mark.nil? ? '' : " #{mark}")
+            opt_args = klass.nil? ? [short, long, desc] : [short, long, klass, desc]
+
+            T.unsafe(opt_p).on(*opt_args) do |v|
+              acc_opts[n] = if acc_opts.key?(n)
+                Array(acc_opts[n]) + Array(v || def_val)
+              else
+                v || def_val
+              end
+            end
+          end
+        end
+
+        arg_v = args.strip.split(/\s+/).map(&:strip)
+        sub = prsr.parse(arg_v)
+
+        { opts: start_opts.merge(acc_opts) }.tap do |a|
+          a[:sub] = sub if sub
+        end
+      end
+    end
+  end
+end

data/lib/cli/kit/resolver.rb

@@ -1,13 +1,19 @@
+# typed: true
+
 require 'cli/kit'
 
 module CLI
   module Kit
     class Resolver
+      extend T::Sig
+
+      sig { params(tool_name: String, command_registry: CLI::Kit::CommandRegistry).void }
       def initialize(tool_name:, command_registry:)
         @tool_name = tool_name
         @command_registry = command_registry
       end
 
+      sig { params(args: T::Array[String]).returns([T.class_of(CLI::Kit::BaseCommand), String, T::Array[String]]) }
       def call(args)
         args = args.dup
         command_name = args.shift
@@ -24,6 +30,7 @@ module CLI
 
       private
 
+      sig { params(name: T.nilable(String)).void }
       def command_not_found(name)
         CLI::UI::Frame.open('Command not found', color: :red, timing: false) do
           $stderr.puts(CLI::UI.fmt("{{command:#{@tool_name} #{name}}} was not found"))
@@ -52,6 +59,7 @@ module CLI
         end
       end
 
+      sig { returns(T::Array[String]) }
       def commands_and_aliases
         @command_registry.command_names + @command_registry.aliases.keys
       end