rubycli 0.1.4 → 0.1.6

data/lib/rubycli/argument_parser.rb

@@ -1,3 +1,5 @@
+require 'did_you_mean'
+
 require_relative 'type_utils'
 require_relative 'arguments/token_stream'
 require_relative 'arguments/value_converter'
@@ -61,6 +63,14 @@ module Rubycli
       [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)
@@ -196,6 +206,235 @@ module Rubycli
       @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
+
+    def literal_allowed?(allowed_entries, value)
+      entries = Array(allowed_entries).compact
+      return false if entries.empty?
+
+      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?
+
+      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?
+
+      return combined.first if combined.size == 1
+
+      "one of #{combined.join(', ')}"
+    end
+
+    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 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
+
+    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 nil_type_token?(token)
+      token.to_s.strip.casecmp('nil').zero? || token.to_s.strip.casecmp('NilClass').zero?
+    end
+
+    def safe_constant_lookup(name)
+      parts = name.to_s.split('::').reject(&:empty?)
+      return nil if parts.empty?
+
+      context = Object
+      parts.each do |const_name|
+        return nil unless context.const_defined?(const_name, false)
+
+        context = context.const_get(const_name)
+      end
+      context
+    rescue NameError
+      nil
+    end
+
+    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
+
+      safe_constant_lookup(normalized)
+    rescue LoadError
+      safe_constant_lookup(normalized)
+    end
+
+    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
+
+    def literal_hint_token?(token)
+      token = token.to_s.strip
+      return false if token.empty?
+
+      token.start_with?('%i[', '%I[', '%w[', '%W[')
+    end
+
 
     def build_cli_alias_map(option_defs)
       option_defs.each_with_object({}) do |opt, memo|
@@ -273,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) }
@@ -282,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/value_converter.rb

@@ -15,6 +15,11 @@ module Rubycli
         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)
@@ -33,6 +38,12 @@ module Rubycli
 
       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

data/lib/rubycli/cli.rb

@@ -48,6 +48,9 @@ module Rubycli
       else
         execute_method(entry.method, command, args, cli_mode)
       end
+    rescue Rubycli::ArgumentError => e
+      warn "[ERROR] #{e.message}"
+      1
     end
 
     def available_commands(target)
@@ -113,6 +116,7 @@ module Rubycli
       method = target.method(:call)
       pos_args, kw_args = @argument_parser.parse(args, method)
       Rubycli.apply_argument_coercions(pos_args, kw_args)
+      @argument_parser.validate_inputs(method, pos_args, kw_args)
       begin
         result = Rubycli.call_target(target, pos_args, kw_args)
         @result_emitter.emit(result)
@@ -151,11 +155,11 @@ module Rubycli
     def execute_method_with_params(method_obj, command, args, cli_mode)
       pos_args, kw_args = @argument_parser.parse(args, method_obj)
       Rubycli.apply_argument_coercions(pos_args, kw_args)
-
       if should_show_method_help?(pos_args, kw_args)
         puts usage_for_method(command, method_obj)
         return 0
       end
+      @argument_parser.validate_inputs(method_obj, pos_args, kw_args)
 
       begin
         result = Rubycli.call_target(method_obj, pos_args, kw_args)

data/lib/rubycli/command_line.rb

@@ -3,7 +3,7 @@
 module Rubycli
   module CommandLine
     USAGE = <<~USAGE
-      Usage: rubycli [--new|-n] [--pre-script=<src>] [--json-args|-j | --eval-args|-e | --eval-lax|-E] <target-path> [<class-or-module>] [-- <cli-args>...]
+      Usage: rubycli [--new|-n] [--pre-script=<src>] [--json-args|-j | --eval-args|-e | --eval-lax|-E] [--strict] [--check|-c] <target-path> [<class-or-module>] [-- <cli-args>...]
 
       Examples:
         rubycli scripts/sample_runner.rb echo --message hello
@@ -17,6 +17,8 @@ module Rubycli
         --eval-args, -e      Evaluate following arguments as Ruby code
         --eval-lax, -E       Evaluate as Ruby but fall back to raw strings when parsing fails
         --auto-target, -a    Auto-select the only callable constant when names don't match
+        --strict             Enforce documented input types/choices (invalid values abort)
+        --check, -c          Validate documentation/comments without executing commands
         (Note: --json-args cannot be combined with --eval-args or --eval-lax)
         (Note: Every option that accepts a value understands both --flag=value and --flag value forms.)
 
@@ -42,6 +44,7 @@ module Rubycli
       eval_mode = false
       eval_lax_mode = false
       constant_mode = nil
+      check_mode = false
       pre_script_sources = []
 
       loop do
@@ -64,7 +67,7 @@ module Rubycli
           flag = args.shift
           src = args.shift
           unless src
-            warn "#{flag} requires a file path or inline Ruby code"
+            warn "[ERROR] #{flag} requires a file path or inline Ruby code"
             return 1
           end
           context = File.file?(src) ? File.expand_path(src) : "(inline #{flag})"
@@ -79,8 +82,19 @@ module Rubycli
           eval_mode = true
           eval_lax_mode = true
           args.shift
+        when '--strict'
+          Rubycli.environment.enable_strict_input!
+          args.shift
+        when '--check', '-c'
+          check_mode = true
+          Rubycli.environment.enable_doc_check!
+          args.shift
         when '--print-result'
-         args.shift
+          args.shift
+        when '--debug'
+          args.shift
+          warn "[ERROR] --debug flag has been removed; set RUBYCLI_DEBUG=true instead."
+          return 1
         when '--auto-target', '-a'
           constant_mode = :auto
           args.shift
@@ -106,10 +120,32 @@ module Rubycli
       args.shift if args.first == '--'
 
       if json_mode && eval_mode
-        warn '--json-args cannot be combined with --eval-args or --eval-lax'
+        warn '[ERROR] --json-args cannot be combined with --eval-args or --eval-lax'
+        return 1
+      end
+
+      if check_mode && (json_mode || eval_mode)
+        warn '[ERROR] --check cannot be combined with --json-args or --eval-args'
         return 1
       end
 
+      if check_mode && !args.empty?
+        warn '[ERROR] --check does not accept command arguments'
+        return 1
+      end
+
+      Rubycli.environment.clear_documentation_issues!
+
+      if check_mode
+        return Rubycli::Runner.check(
+          target_path,
+          class_or_module,
+          new: new_flag,
+          pre_scripts: pre_script_sources,
+          constant_mode: constant_mode
+        )
+      end
+
       Rubycli::Runner.execute(
         target_path,
         class_or_module,
@@ -124,10 +160,10 @@ module Rubycli
 
       0
     rescue Rubycli::Runner::PreScriptError => e
-      warn e.message
+      warn "[ERROR] #{e.message}"
       1
     rescue Rubycli::Runner::Error => e
-      warn e.message
+      warn "[ERROR] #{e.message}"
       1
     end
   end