rubycli 0.1.2 → 0.1.5

data/lib/rubycli/argument_parser.rb

@@ -1,5 +1,8 @@
-require 'psych'
+require 'did_you_mean'
+
 require_relative 'type_utils'
+require_relative 'arguments/token_stream'
+require_relative 'arguments/value_converter'
 
 module Rubycli
   class ArgumentParser
@@ -10,6 +13,7 @@ module Rubycli
       @documentation_registry = documentation_registry
       @json_coercer = json_coercer
       @debug_logger = debug_logger
+      @value_converter = Arguments::ValueConverter.new
     end
 
     def parse(args, method = nil)
@@ -25,21 +29,21 @@ module Rubycli
       option_lookup = build_option_lookup(option_defs)
       type_converters = build_type_converter_map(option_defs)
 
-      i = 0
-      while i < args.size
-        token = args[i]
+      stream = Arguments::TokenStream.new(args)
+
+      until stream.finished?
+        token = stream.current
 
         if token == '--'
-          rest_tokens = (args[(i + 1)..-1] || []).map { |value| convert_arg(value) }
+          stream.advance
+          rest_tokens = stream.consume_remaining.map { |value| convert_arg(value) }
           pos_args.concat(rest_tokens)
           break
-        end
-
-        if option_token?(token)
-          i = process_option_token(
+        elsif option_token?(token)
+          stream.advance
+          process_option_token(
             token,
-            args,
-            i,
+            stream,
             kw_param_names,
             kw_args,
             cli_aliases,
@@ -47,18 +51,26 @@ module Rubycli
             type_converters
           )
         elsif assignment_token?(token)
+          stream.advance
           process_assignment_token(token, kw_args)
         else
           pos_args << convert_arg(token)
+          stream.advance
         end
-
-        i += 1
       end
 
       debug_log "Final parsed - pos_args: #{pos_args.inspect}, kw_args: #{kw_args.inspect}"
       [pos_args, kw_args]
     end
 
+    def validate_inputs(method_obj, positional_args, keyword_args)
+      return unless method_obj
+
+      metadata = @documentation_registry.metadata_for(method_obj)
+      validate_positional_arguments(method_obj, metadata, positional_args)
+      validate_keyword_arguments(metadata, keyword_args)
+    end
+
     private
 
     def debug_log(message)
@@ -85,8 +97,7 @@ module Rubycli
 
     def process_option_token(
       token,
-      args,
-      current_index,
+      stream,
       kw_param_names,
       kw_args,
       cli_aliases,
@@ -108,21 +119,19 @@ module Rubycli
       requires_value = option_meta ? option_meta[:requires_value] : nil
       option_label = option_meta&.long || "--#{final_key.tr('_', '-')}"
 
-      value_capture, current_index = if embedded_value
-                                       [embedded_value, current_index]
-                                     elsif option_meta
-                                       capture_option_value(
-                                         option_meta,
-                                         args,
-                                         current_index,
-                                         requires_value
-                                       )
-                                     elsif current_index + 1 < args.size && !looks_like_option?(args[current_index + 1])
-                                       current_index += 1
-                                       [args[current_index], current_index]
-                                     else
-                                       ['true', current_index]
-                                     end
+      value_capture = if embedded_value
+                        embedded_value
+                      elsif option_meta
+                        capture_option_value(
+                          option_meta,
+                          stream,
+                          requires_value
+                        )
+                      elsif (next_token = stream.current) && !looks_like_option?(next_token)
+                        stream.consume
+                      else
+                        'true'
+                      end
 
       if requires_value && (value_capture.nil? || value_capture == 'true')
         raise ArgumentError, "Option '#{option_label}' requires a value"
@@ -136,40 +145,30 @@ module Rubycli
       )
 
       kw_args[final_key_sym] = converted_value
-      current_index
-    end
-
-    def capture_option_value(option_meta, args, current_index, requires_value)
-      new_index = current_index
-      value = if option_meta[:boolean_flag]
-                if new_index + 1 < args.size && TypeUtils.boolean_string?(args[new_index + 1])
-                  new_index += 1
-                  args[new_index]
-                else
-                  'true'
-                end
-              elsif option_meta[:optional_value]
-                if new_index + 1 < args.size && !looks_like_option?(args[new_index + 1])
-                  new_index += 1
-                  args[new_index]
-                else
-                  true
-                end
-              elsif requires_value == false
-                'true'
-              elsif requires_value
-                if new_index + 1 >= args.size
-                  raise ArgumentError, "Option '#{option_meta.long}' requires a value"
-                end
-                new_index += 1
-                args[new_index]
-              elsif new_index + 1 < args.size && !looks_like_option?(args[new_index + 1])
-                new_index += 1
-                args[new_index]
-              else
-                'true'
-              end
-      [value, new_index]
+    end
+    def capture_option_value(option_meta, stream, requires_value)
+      if option_meta[:boolean_flag]
+        if (next_token = stream.current) && TypeUtils.boolean_string?(next_token)
+          return stream.consume
+        end
+        return 'true'
+      elsif option_meta[:optional_value]
+        if (next_token = stream.current) && !looks_like_option?(next_token)
+          return stream.consume
+        end
+        return true
+      elsif requires_value == false
+        return 'true'
+      elsif requires_value
+        next_token = stream.current
+        raise ArgumentError, "Option '#{option_meta.long}' requires a value" unless next_token
+
+        return stream.consume
+      elsif (next_token = stream.current) && !looks_like_option?(next_token)
+        return stream.consume
+      else
+        return 'true'
+      end
     end
 
     def process_assignment_token(token, kw_args)
@@ -204,65 +203,236 @@ module Rubycli
     end
 
     def convert_arg(arg)
-      return arg if Rubycli.eval_mode? || Rubycli.json_mode?
-      return arg unless arg.is_a?(String)
+      @value_converter.convert(arg)
+    end
+
+    def validate_positional_arguments(method_obj, metadata, positional_args)
+      return if positional_args.nil? || positional_args.empty?
+
+      positional_map = metadata[:positionals_map] || {}
+      ordered_params = method_obj.parameters.select { |type, _| %i[req opt].include?(type) }
+
+      ordered_params.each_with_index do |(_, name), index|
+        definition = positional_map[name]
+        next unless definition
+        next if index >= positional_args.size
+
+        label = definition.label || definition.placeholder || name.to_s.upcase
+        enforce_value_against_definition(definition, positional_args[index], label)
+      end
+    end
+
+    def validate_keyword_arguments(metadata, keyword_args)
+      return if keyword_args.nil? || keyword_args.empty?
+
+      option_lookup = build_option_lookup(metadata[:options] || [])
+      keyword_args.each do |key, value|
+        definition = option_lookup[key.to_sym]
+        next unless definition
+
+        label = definition.long || "--#{key.to_s.tr('_', '-')}"
+        enforce_value_against_definition(definition, value, label)
+      end
+    end
+
+    def enforce_value_against_definition(definition, value, label)
+      return unless definition
+
+      return if type_allowed?(definition.types, value)
+
+      Array(value.is_a?(Array) ? value : [value]).each do |entry|
+        next if literal_allowed?(definition.allowed_values, entry)
+        next if type_allowed?(definition.types, entry)
+
+        message = build_invalid_value_message(definition, entry, label)
+        @environment.handle_input_violation(message)
+      end
+    end
+
+    def build_invalid_value_message(definition, entry, label)
+      description = allowed_value_description(definition)
+      formatted_value = format_literal_value(entry)
+
+      message = if description
+        "#{label} must be #{description} (received #{formatted_value})"
+      else
+        "Value #{formatted_value} for #{label} is not allowed"
+      end
+
+      suggestions = literal_suggestions(definition, entry)
+      return message if suggestions.empty?
+
+      suggestion_text = suggestions.size == 1 ? suggestions.first : suggestions.join(', ')
+      "#{message}. Did you mean #{suggestion_text}?"
+    end
 
-      trimmed = arg.strip
-      return arg if trimmed.empty?
+    def literal_allowed?(allowed_entries, value)
+      entries = Array(allowed_entries).compact
+      return false if entries.empty?
 
-      if literal_like?(trimmed)
-        literal = try_literal_parse(arg)
-        return literal unless literal.equal?(LITERAL_PARSE_FAILURE)
+      entries.any? { |entry| literal_match?(entry[:value], value) }
+    end
+
+    def literal_match?(candidate, value)
+      case candidate
+      when Symbol
+        value.is_a?(Symbol) && value == candidate
+      when String
+        value.is_a?(String) && value == candidate
+      when Integer
+        value.is_a?(Integer) && value == candidate
+      when Float
+        value.is_a?(Float) && value == candidate
+      when TrueClass, FalseClass
+        value == candidate
+      when NilClass
+        value.nil?
+      else
+        value == candidate
       end
+    end
+
+    def type_allowed?(types, value)
+      tokens = Array(types).compact
+      return false if tokens.empty?
 
-      return nil if null_literal?(trimmed)
+      tokens.any? { |token| matches_type_token?(token, value) }
+    end
+
+    def allowed_value_description(definition)
+      literal_descriptions = Array(definition.allowed_values).map { |entry| format_literal_value(entry[:value]) }.reject(&:empty?)
+      type_descriptions = Array(definition.types)
+                          .map { |token| token.to_s.strip }
+                          .reject { |token| token.empty? || literal_hint_token?(token) }
+      combined = (literal_descriptions + type_descriptions).uniq.reject(&:empty?)
+      return nil if combined.empty?
 
-      lower = trimmed.downcase
-      return true if lower == 'true'
-      return false if lower == 'false'
-      return arg.to_i if integer_string?(trimmed)
-      return arg.to_f if float_string?(trimmed)
+      return combined.first if combined.size == 1
 
-      arg
+      "one of #{combined.join(', ')}"
     end
 
-    def integer_string?(str)
-      str =~ /\A-?\d+\z/
+    def literal_suggestions(definition, entry)
+      literals = Array(definition.allowed_values).map { |allowed| allowed[:value] }.compact
+      return [] if literals.empty?
+      return [] unless entry.is_a?(String) || entry.is_a?(Symbol)
+
+      candidates = literals.select { |value| value.is_a?(String) || value.is_a?(Symbol) }
+      return [] if candidates.empty?
+
+      lookup = {}
+      dictionary = candidates.each_with_object([]) do |candidate, memo|
+        key = candidate.to_s
+        lookup[key] ||= candidate
+        memo << key unless memo.include?(key)
+      end
+
+      spell_checker = DidYouMean::SpellChecker.new(dictionary: dictionary)
+      matches = spell_checker.correct(entry.to_s)
+      return [] if matches.empty?
+
+      matches.take(3).map { |match| format_literal_value(lookup[match]) }
+    rescue LoadError, NameError
+      []
     end
 
-    def float_string?(str)
-      str =~ /\A-?\d+\.\d+\z/
+    def matches_type_token?(token, value)
+      normalized = token.to_s.strip
+      return true if normalized.empty?
+
+      if (inner = array_inner_type(normalized))
+        return false unless value.is_a?(Array)
+        return value.all? { |element| matches_type_token?(inner, element) }
+      end
+
+      case normalized
+      when 'Boolean'
+        value.is_a?(TrueClass) || value.is_a?(FalseClass)
+      when 'JSON'
+        value.is_a?(Hash) || value.is_a?(Array)
+      when 'nil', 'NilClass'
+        value.nil?
+      else
+        klass = constant_for_token(normalized)
+        return value.is_a?(klass) if klass
+
+        false
+      end
     end
 
-    LITERAL_PARSE_FAILURE = Object.new
+    def array_inner_type(token)
+      if token.end_with?('[]')
+        token[0..-3]
+      elsif token.start_with?('Array<') && token.end_with?('>')
+        token[6..-2].strip
+      else
+        nil
+      end
+    end
 
-    def try_literal_parse(value)
-      return LITERAL_PARSE_FAILURE unless value.is_a?(String)
+    def nil_type_token?(token)
+      token.to_s.strip.casecmp('nil').zero? || token.to_s.strip.casecmp('NilClass').zero?
+    end
 
-      trimmed = value.strip
-      return value if trimmed.empty?
+    def safe_constant_lookup(name)
+      parts = name.to_s.split('::').reject(&:empty?)
+      return nil if parts.empty?
 
-      literal = Psych.safe_load(trimmed, aliases: false)
-      return literal unless literal.nil? && !null_literal?(trimmed)
+      context = Object
+      parts.each do |const_name|
+        return nil unless context.const_defined?(const_name, false)
 
-      LITERAL_PARSE_FAILURE
-    rescue Psych::SyntaxError, Psych::DisallowedClass, Psych::Exception
-      LITERAL_PARSE_FAILURE
+        context = context.const_get(const_name)
+      end
+      context
+    rescue NameError
+      nil
     end
 
-    def null_literal?(value)
-      return false unless value
+    def constant_for_token(token)
+      normalized = token.to_s
+      case normalized
+      when 'Fixnum'
+        return Integer
+      when 'Date', 'DateTime'
+        require 'date'
+      when 'Time'
+        require 'time'
+      when 'BigDecimal', 'Decimal'
+        require 'bigdecimal'
+      when 'Pathname'
+        require 'pathname'
+      when 'Struct'
+        return Struct
+      end
 
-      %w[null ~].include?(value.downcase)
+      safe_constant_lookup(normalized)
+    rescue LoadError
+      safe_constant_lookup(normalized)
     end
 
-    def literal_like?(value)
-      return false unless value
-      return true if value.start_with?('[', '{', '"', "'")
-      return true if value.start_with?('---')
-      return true if value.match?(/\A(?:true|false|null|nil)\z/i)
+    def format_literal_value(value)
+      case value
+      when Symbol
+        ":#{value}"
+      when String
+        value.inspect
+      when Integer, Float
+        value.to_s
+      when TrueClass, FalseClass
+        value.to_s
+      when NilClass
+        'nil'
+      else
+        value.inspect
+      end
+    end
 
-      false
+    def literal_hint_token?(token)
+      token = token.to_s.strip
+      return false if token.empty?
+
+      token.start_with?('%i[', '%I[', '%w[', '%W[')
     end
 
 
@@ -342,7 +512,15 @@ module Rubycli
         ->(value) { value.to_sym }
       when 'BigDecimal', 'Decimal'
         require 'bigdecimal'
-        ->(value) { BigDecimal(value) }
+        ->(value) {
+          return value if value.is_a?(BigDecimal)
+
+          if value.is_a?(String)
+            BigDecimal(value)
+          else
+            BigDecimal(value.to_s)
+          end
+        }
       when 'Date'
         require 'date'
         ->(value) { Date.parse(value) }
@@ -351,6 +529,13 @@ module Rubycli
         ->(value) { Time.parse(value) }
       when 'JSON', 'Hash'
         ->(value) { JSON.parse(value) }
+      when 'Pathname'
+        require 'pathname'
+        ->(value) {
+          return value if value.is_a?(Pathname)
+
+          Pathname.new(value.to_s)
+        }
       else
         if normalized.start_with?('Array<') && normalized.end_with?('>')
           inner = normalized[6..-2].strip

data/lib/rubycli/arguments/token_stream.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Rubycli
+  module Arguments
+    # Lightweight mutable cursor over CLI tokens.
+    class TokenStream
+      def initialize(tokens)
+        @tokens = Array(tokens).dup
+        @index = 0
+      end
+
+      def current
+        @tokens[@index]
+      end
+
+      def peek(offset = 1)
+        @tokens[@index + offset]
+      end
+
+      def advance(count = 1)
+        @index += count
+      end
+
+      def consume
+        value = current
+        advance
+        value
+      end
+
+      def consume_remaining
+        remaining = @tokens[@index..] || []
+        @index = @tokens.length
+        remaining
+      end
+
+      def finished?
+        @index >= @tokens.length
+      end
+    end
+  end
+end

data/lib/rubycli/arguments/value_converter.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'psych'
+
+module Rubycli
+  module Arguments
+    # Converts raw CLI tokens into Ruby primitives when safe to do so.
+    class ValueConverter
+      LITERAL_PARSE_FAILURE = Object.new
+
+      def convert(value)
+        return value if Rubycli.eval_mode? || Rubycli.json_mode?
+        return value unless value.is_a?(String)
+
+        trimmed = value.strip
+        return value if trimmed.empty?
+
+        if symbol_literal?(trimmed)
+          symbol_value = trimmed.delete_prefix(':')
+          return symbol_value.to_sym unless symbol_value.empty?
+        end
+
+        if literal_like?(trimmed)
+          literal = try_literal_parse(value)
+          return literal unless literal.equal?(LITERAL_PARSE_FAILURE)
+        end
+
+        return nil if null_literal?(trimmed)
+
+        lower = trimmed.downcase
+        return true if lower == 'true'
+        return false if lower == 'false'
+        return value.to_i if integer_string?(trimmed)
+        return value.to_f if float_string?(trimmed)
+
+        value
+      end
+
+      private
+
+      def symbol_literal?(value)
+        return false unless value
+
+        value.start_with?(':') && value.length > 1 && value[1..].match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+      end
+
+      def integer_string?(str)
+        str =~ /\A-?\d+\z/
+      end
+
+      def float_string?(str)
+        str =~ /\A-?\d+\.\d+\z/
+      end
+
+      def try_literal_parse(value)
+        return LITERAL_PARSE_FAILURE unless value.is_a?(String)
+
+        trimmed = value.strip
+        return value if trimmed.empty?
+
+        literal = Psych.safe_load(trimmed, aliases: false)
+        return literal unless literal.nil? && !null_literal?(trimmed)
+
+        LITERAL_PARSE_FAILURE
+      rescue Psych::SyntaxError, Psych::DisallowedClass, Psych::Exception
+        LITERAL_PARSE_FAILURE
+      end
+
+      def null_literal?(value)
+        return false unless value
+
+        %w[null ~].include?(value.downcase)
+      end
+
+      def literal_like?(value)
+        return false unless value
+        return true if value.start_with?('[', '{', '"', "'")
+        return true if value.start_with?('---')
+        return true if value.match?(/\A(?:true|false|null|nil)\z/i)
+
+        false
+      end
+    end
+  end
+end