rubycli 0.1.1

data/lib/rubycli/argument_parser.rb

@@ -0,0 +1,343 @@
+require_relative 'type_utils'
+
+module Rubycli
+  class ArgumentParser
+    include TypeUtils
+
+    def initialize(environment:, documentation_registry:, json_coercer:, debug_logger:)
+      @environment = environment
+      @documentation_registry = documentation_registry
+      @json_coercer = json_coercer
+      @debug_logger = debug_logger
+    end
+
+    def parse(args, method = nil)
+      pos_args = []
+      kw_args = {}
+
+      kw_param_names = extract_keyword_parameter_names(method)
+      debug_log "Available keyword parameters: #{kw_param_names.inspect}"
+
+      metadata = method ? @documentation_registry.metadata_for(method) : { options: [], returns: [], summary: nil }
+      option_defs = metadata[:options] || []
+      cli_aliases = build_cli_alias_map(option_defs)
+      option_lookup = build_option_lookup(option_defs)
+      type_converters = build_type_converter_map(option_defs)
+
+      i = 0
+      while i < args.size
+        token = args[i]
+
+        if token == '--'
+          rest_tokens = (args[(i + 1)..-1] || []).map { |value| convert_arg(value) }
+          pos_args.concat(rest_tokens)
+          break
+        end
+
+        if option_token?(token)
+          i = process_option_token(
+            token,
+            args,
+            i,
+            kw_param_names,
+            kw_args,
+            cli_aliases,
+            option_lookup,
+            type_converters
+          )
+        elsif assignment_token?(token)
+          process_assignment_token(token, kw_args)
+        else
+          pos_args << convert_arg(token)
+        end
+
+        i += 1
+      end
+
+      debug_log "Final parsed - pos_args: #{pos_args.inspect}, kw_args: #{kw_args.inspect}"
+      [pos_args, kw_args]
+    end
+
+    private
+
+    def debug_log(message)
+      return unless @debug_logger
+
+      @debug_logger.call(message)
+    end
+
+    def extract_keyword_parameter_names(method)
+      return [] unless method
+
+      method.parameters
+            .select { |type, _| %i[key keyreq].include?(type) }
+            .map { |_, name| name.to_s }
+    end
+
+    def option_token?(token)
+      token =~ /\A-{1,2}([a-zA-Z0-9_-]+)(?:=(.*))?\z/
+    end
+
+    def assignment_token?(token)
+      !split_assignment_token(token).nil?
+    end
+
+    def process_option_token(
+      token,
+      args,
+      current_index,
+      kw_param_names,
+      kw_args,
+      cli_aliases,
+      option_lookup,
+      type_converters
+    )
+      token =~ /\A-{1,2}([a-zA-Z0-9_-]+)(?:=(.*))?\z/
+      cli_key = Regexp.last_match(1).tr('-', '_')
+      embedded_value = Regexp.last_match(2)
+
+      resolved_cli_key = cli_aliases.fetch(cli_key, cli_key)
+      debug_log "Processing option '#{Regexp.last_match(1)}' -> '#{resolved_cli_key}'"
+
+      resolved_key = resolve_keyword_parameter(resolved_cli_key, kw_param_names)
+      final_key = resolved_key || resolved_cli_key
+      final_key_sym = final_key.to_sym
+
+      option_meta = option_lookup[final_key_sym]
+      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
+
+      if requires_value && (value_capture.nil? || value_capture == 'true')
+        raise ArgumentError, "Option '#{option_label}' requires a value"
+      end
+
+      converted_value = convert_option_value(
+        final_key_sym,
+        value_capture,
+        option_meta,
+        type_converters
+      )
+
+      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 process_assignment_token(token, kw_args)
+      key, value = split_assignment_token(token)
+      kw_args[key.to_sym] = convert_arg(value)
+    end
+
+    def split_assignment_token(token)
+      return nil unless token&.include?('=')
+
+      key, value = token.split('=', 2)
+      return nil if key.nil? || key.empty? || value.nil?
+      return nil unless key.match?(/\A[a-zA-Z_]\w*\z/)
+
+      [key, value]
+    end
+
+    def resolve_keyword_parameter(cli_key, kw_param_names)
+      exact_match = kw_param_names.find { |name| name == cli_key }
+      return exact_match if exact_match
+
+      matching_keys = kw_param_names.select { |name| name.start_with?(cli_key) }
+      debug_log "Prefix matching for '#{cli_key}': found #{matching_keys.inspect}"
+
+      if matching_keys.size == 1
+        debug_log "Unambiguous prefix match found: '#{matching_keys.first}'"
+        matching_keys.first
+      else
+        debug_log "No unique match found for '#{cli_key}'"
+        nil
+      end
+    end
+
+    def convert_arg(arg)
+      return nil if arg.nil? || arg.casecmp('nil').zero?
+      return true if arg.casecmp('true').zero?
+      return false if arg.casecmp('false').zero?
+      return arg.to_i if integer_string?(arg)
+      return arg.to_f if float_string?(arg)
+
+      arg
+    end
+
+    def integer_string?(str)
+      str =~ /\A-?\d+\z/
+    end
+
+    def float_string?(str)
+      str =~ /\A-?\d+\.\d+\z/
+    end
+
+
+    def build_cli_alias_map(option_defs)
+      option_defs.each_with_object({}) do |opt, memo|
+        next unless opt.short
+
+        key = opt.short.delete_prefix('-')
+        memo[key] = opt.keyword.to_s
+      end
+    end
+
+    def build_option_lookup(option_defs)
+      option_defs.each_with_object({}) do |opt, memo|
+        memo[opt.keyword] = opt
+      end
+    end
+
+    def build_type_converter_map(option_defs)
+      option_defs.each_with_object({}) do |opt, memo|
+        next if opt.types.nil? || opt.types.empty?
+
+        converter = build_converter_for_types(opt.types)
+        memo[opt.keyword] = converter if converter
+      end
+    end
+
+    def build_converter_for_types(types)
+      return nil if types.empty?
+
+      allow_nil = types.any? { |type| nil_type?(type) }
+      converters = types.map { |type| converter_for_single_type(type) }.compact
+
+      return nil if converters.empty? && !allow_nil
+
+      lambda do |value|
+        return nil if value.nil? && allow_nil
+
+        if allow_nil && value.is_a?(String) && value.strip.casecmp('nil').zero?
+          next nil
+        end
+
+        if converters.empty?
+          value
+        else
+          last_error = nil
+          converters.each do |converter|
+            begin
+              result = converter.call(value)
+              return result
+            rescue StandardError => e
+              last_error = e
+            end
+          end
+          raise last_error || ArgumentError.new("Could not convert value '#{value}'")
+        end
+      end
+    end
+
+    def converter_for_single_type(type)
+      normalized = type.to_s.strip
+
+      return nil if nil_type?(normalized)
+
+      case normalized
+      when 'String'
+        ->(value) { value }
+      when 'Integer', 'Fixnum'
+        ->(value) { Integer(value, 10) }
+      when 'Float'
+        ->(value) { Float(value) }
+      when 'Numeric'
+        ->(value) { Float(value) }
+      when 'Boolean', 'TrueClass', 'FalseClass'
+        ->(value) { TypeUtils.convert_boolean(value) }
+      when 'Symbol'
+        ->(value) { value.to_sym }
+      when 'BigDecimal', 'Decimal'
+        require 'bigdecimal'
+        ->(value) { BigDecimal(value) }
+      when 'Date'
+        require 'date'
+        ->(value) { Date.parse(value) }
+      when 'Time', 'DateTime'
+        require 'time'
+        ->(value) { Time.parse(value) }
+      when 'JSON', 'Hash'
+        ->(value) { JSON.parse(value) }
+      else
+        if normalized.start_with?('Array<') && normalized.end_with?('>')
+          inner = normalized[6..-2].strip
+          element_converter = converter_for_single_type(inner)
+          ->(value) { TypeUtils.parse_list(value).map { |item| element_converter ? element_converter.call(item) : item } }
+        elsif normalized.end_with?('[]')
+          inner = normalized[0..-3]
+          element_converter = converter_for_single_type(inner)
+          ->(value) { TypeUtils.parse_list(value).map { |item| element_converter ? element_converter.call(item) : item } }
+        elsif normalized == 'Array'
+          ->(value) { TypeUtils.parse_list(value) }
+        else
+          nil
+        end
+      end
+    end
+
+    def convert_option_value(keyword, value, option_meta, type_converters)
+      converter = type_converters[keyword]
+      return convert_arg(value) unless converter
+
+      converter.call(value)
+    rescue StandardError => e
+      option_label = option_meta&.long || option_meta&.short || keyword
+      raise ArgumentError, "Value '#{value}' for option '#{option_label}' is invalid: #{e.message}"
+    end
+
+    def looks_like_option?(token)
+      return false unless token
+      return false if token == '--'
+
+      token.start_with?('-') && !(token =~ /\A-?\d+(\.\d+)?\z/)
+    end
+  end
+end

data/lib/rubycli/cli.rb

@@ -0,0 +1,341 @@
+require 'set'
+
+module Rubycli
+  class CLI
+    CommandEntry = Struct.new(:command, :method, :category, :aliases, keyword_init: true) do
+      def all_commands
+        [command] + aliases
+      end
+    end
+
+    CommandCatalog = Struct.new(:entries, :alias_map, :duplicates, keyword_init: true) do
+      def lookup(command)
+        alias_map[command]
+      end
+
+      def entries_for(category)
+        entries.select { |entry| entry.category == category }
+      end
+
+      def commands
+        entries.map(&:command)
+      end
+    end
+
+    def initialize(environment:, argument_parser:, documentation_registry:, help_renderer:, result_emitter:)
+      @environment = environment
+      @argument_parser = argument_parser
+      @documentation_registry = documentation_registry
+      @help_renderer = help_renderer
+      @result_emitter = result_emitter
+      @file_cache = {}
+    end
+
+    def run(target, args = ARGV, cli_mode = true)
+      debug_log "Starting rubycli with args: #{args.inspect}"
+      catalog = command_catalog(target)
+
+      if should_show_help?(args)
+        @help_renderer.print_help(target, catalog)
+        exit(0)
+      end
+
+      command = args.shift
+      entry = resolve_command_entry(catalog, command)
+
+      if entry.nil?
+        handle_missing_method(target, catalog, command, args, cli_mode)
+      else
+        execute_method(entry.method, command, args, cli_mode)
+      end
+    end
+
+    def available_commands(target)
+      command_catalog(target).commands.sort
+    end
+
+    def find_method(target, command)
+      catalog = command_catalog(target)
+      entry = catalog.lookup(command)
+      entry ||= catalog.lookup(normalize_command(command)) if command.include?('-')
+      entry&.method
+    end
+
+    def usage_for_method(command, method)
+      @help_renderer.usage_for_method(command, method)
+    end
+
+    def method_description(method)
+      @help_renderer.method_description(method)
+    end
+
+    def command_catalog_for(target)
+      command_catalog(target)
+    end
+
+    private
+
+    def debug_log(message)
+      return unless @environment.debug?
+
+      puts "[DEBUG] #{message}"
+    end
+
+    def should_show_help?(args)
+      args.empty? || ['help', '--help', '-h'].include?(args[0])
+    end
+
+    def resolve_command_entry(catalog, command)
+      entry = catalog.lookup(command)
+      return entry if entry
+
+      return entry unless command.include?('-')
+
+      normalized = normalize_command(command)
+      debug_log "Tried snake_case conversion: #{command} -> #{normalized}" if normalized != command
+      catalog.lookup(normalized)
+    end
+
+    def handle_missing_method(target, catalog, command, args, cli_mode)
+      if target.respond_to?(:call)
+        debug_log "Target is callable, treating as lambda/proc"
+        args.unshift(command)
+        execute_callable(target, args, command, cli_mode)
+      else
+        error_msg = "Command '#{command}' is not available."
+        puts error_msg
+        @help_renderer.print_help(target, catalog)
+        exit(1)
+      end
+    end
+
+    def execute_callable(target, args, command, cli_mode)
+      method = target.method(:call)
+      pos_args, kw_args = @argument_parser.parse(args, method)
+      Rubycli.apply_argument_coercions(pos_args, kw_args)
+      begin
+        result = Rubycli.call_target(target, pos_args, kw_args)
+        @result_emitter.emit(result)
+      rescue StandardError => e
+        handle_execution_error(e, command, method, pos_args, kw_args, cli_mode)
+      end
+    end
+
+    def execute_method(method_obj, command, args, cli_mode)
+      if method_obj.parameters.empty? && !args.empty?
+        execute_parameterless_method(method_obj, command, args, cli_mode)
+      else
+        execute_method_with_params(method_obj, command, args, cli_mode)
+      end
+    end
+
+    def execute_parameterless_method(method_obj, command, args, cli_mode)
+      if help_requested_for_parameterless?(args)
+        puts usage_for_method(command, method_obj)
+        exit(0)
+      end
+
+      begin
+        result = method_obj.call
+        debug_log "Parameterless method returned: #{result.inspect}"
+        if result
+          run(result, args, false)
+        end
+      rescue StandardError => e
+        handle_execution_error(e, command, method_obj, [], {}, cli_mode)
+      end
+    end
+
+    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)
+        exit(0)
+      end
+
+      begin
+        result = Rubycli.call_target(method_obj, pos_args, kw_args)
+        @result_emitter.emit(result)
+      rescue StandardError => e
+        handle_execution_error(e, command, method_obj, pos_args, kw_args, cli_mode)
+      end
+    end
+
+    def should_show_method_help?(pos_args, kw_args)
+      (kw_args.key?(:help) && kw_args.delete(:help)) || pos_args.include?('help')
+    end
+
+    def help_requested_for_parameterless?(args)
+      return false if args.nil? || args.empty?
+
+      args.all? { |arg| help_argument?(arg) }
+    end
+
+    def help_argument?(arg)
+      %w[help --help -h].include?(arg)
+    end
+
+    def handle_execution_error(error, command, method_obj, pos_args, kw_args, cli_mode)
+      if cli_mode && !arguments_match?(method_obj, pos_args, kw_args) && usage_error?(error)
+        puts "Error: #{error.message}"
+        puts usage_for_method(command, method_obj)
+        exit(1)
+      else
+        raise error
+      end
+    end
+
+    def usage_error?(error)
+      msg = error.message
+      msg.include?('wrong number of arguments') ||
+        msg.include?('missing keyword') ||
+        msg.include?('unknown keyword') ||
+        msg.include?('no implicit conversion')
+    end
+
+    def arguments_match?(method, pos_args, kw_args)
+      return false unless method
+
+      params = method.parameters
+      positional_match = check_positional_arguments(params, pos_args)
+      keyword_match = check_keyword_arguments(params, kw_args)
+
+      positional_match && keyword_match
+    end
+
+    def check_positional_arguments(params, pos_args)
+      req_pos = params.count { |type, _| type == :req }
+      opt_pos = params.count { |type, _| type == :opt }
+      has_rest = params.any? { |type, _| type == :rest }
+
+      if has_rest
+        pos_args.size >= req_pos
+      else
+        (req_pos..(req_pos + opt_pos)).cover?(pos_args.size)
+      end
+    end
+
+    def check_keyword_arguments(params, kw_args)
+      known_keys = params.select { |t, _| %i[key keyreq keyrest].include?(t) }.map { |_, n| n }
+      unknown_keys = kw_args.keys - known_keys
+      req_kw = params.select { |type, _| type == :keyreq }.map { |_, name| name }
+      has_keyrest = params.any? { |type, _| type == :keyrest }
+
+      required_keywords_present = req_kw.all? { |k| kw_args.key?(k) }
+      no_unknown_keywords = has_keyrest || unknown_keys.empty?
+
+      required_keywords_present && no_unknown_keywords
+    end
+
+    def command_catalog(target)
+      if target.is_a?(Module) || target.is_a?(Class)
+        entries = collect_singleton_entries(target)
+        alias_map = build_alias_map(entries)
+        CommandCatalog.new(entries: entries, alias_map: alias_map, duplicates: Set.new)
+      else
+        build_instance_catalog(target)
+      end
+    end
+
+    def collect_singleton_entries(target)
+      method_names = target.singleton_class.public_instance_methods(false)
+      method_names.each_with_object([]) do |name, memo|
+        method_obj = safe_method_lookup(target, name)
+        next unless exposable_method?(method_obj)
+
+        memo << CommandEntry.new(command: name.to_s, method: method_obj, category: :class, aliases: [])
+      end.sort_by { |entry| entry.command }
+    end
+
+    def build_instance_catalog(target)
+      instance_methods = collect_instance_methods(target)
+      class_methods = collect_class_methods(target)
+
+      duplicate_names = instance_methods.keys & class_methods.keys
+      entries = []
+
+      instance_methods.keys.sort.each do |name|
+        method_obj = instance_methods[name]
+        aliases = duplicate_names.include?(name) ? ["instance::#{name}"] : []
+        entries << CommandEntry.new(command: name, method: method_obj, category: :instance, aliases: aliases)
+      end
+
+      class_methods.keys.sort.each do |name|
+        method_obj = class_methods[name]
+        entries << CommandEntry.new(command: "class::#{name}", method: method_obj, category: :class, aliases: [])
+      end
+
+      alias_map = build_alias_map(entries)
+      CommandCatalog.new(entries: entries, alias_map: alias_map, duplicates: duplicate_names.sort)
+    end
+
+    def collect_instance_methods(target)
+      collect_method_map(target.public_methods(false)) { |name| safe_method_lookup(target, name) }
+    end
+
+    def collect_class_methods(target)
+      klass = target.class
+      collect_method_map(klass.singleton_class.public_instance_methods(false)) { |name| safe_method_lookup(klass, name) }
+    end
+
+    def collect_method_map(method_names)
+      method_names.each_with_object({}) do |name, memo|
+        method_obj = yield(name)
+        next unless exposable_method?(method_obj)
+
+        memo[name.to_s] = method_obj
+      end
+    end
+
+    def safe_method_lookup(target, name)
+      target.method(name)
+    rescue NameError
+      nil
+    end
+
+    def exposable_method?(method_obj)
+      return false unless method_obj&.source_location
+      return false if accessor_generated_method?(method_obj)
+
+      true
+    end
+
+    def build_alias_map(entries)
+      entries.each_with_object({}) do |entry, memo|
+        entry.all_commands.each do |command|
+          memo[command] = entry
+        end
+      end
+    end
+
+    def normalize_command(command)
+      return command unless command
+
+      if command.start_with?('class::')
+        base = command.split('class::', 2).last
+        "class::#{base.tr('-', '_')}"
+      elsif command.start_with?('instance::')
+        base = command.split('instance::', 2).last
+        "instance::#{base.tr('-', '_')}"
+      else
+        command.tr('-', '_')
+      end
+    end
+
+    def accessor_generated_method?(method_obj)
+      location = method_obj.source_location
+      return false unless location
+
+      file, line = location
+      lines = (@file_cache[file] ||= File.readlines(file, chomp: true))
+      line_content = lines[line - 1]
+      return false unless line_content
+
+      line_content.match?(/\battr_(reader|writer|accessor)\b/)
+    rescue Errno::ENOENT
+      false
+    end
+  end
+end