rubycli 0.1.1 → 0.1.4

data/lib/rubycli/argument_mode_controller.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Rubycli
+  # Coordinates json/eval argument modes and enforces mutual exclusion.
+  class ArgumentModeController
+    def initialize(json_coercer:, eval_coercer:)
+      @json_coercer = json_coercer
+      @eval_coercer = eval_coercer
+    end
+
+    def json_mode?
+      @json_coercer.json_mode?
+    end
+
+    def eval_mode?
+      @eval_coercer.eval_mode?
+    end
+
+    def with_json_mode(enabled = true, &block)
+      enforce_mutual_exclusion!(:json, enabled)
+      @json_coercer.with_json_mode(enabled, &block)
+    end
+
+    def with_eval_mode(enabled = true, **options, &block)
+      enforce_mutual_exclusion!(:eval, enabled)
+      @eval_coercer.with_eval_mode(enabled, **options, &block)
+    end
+
+    def apply_argument_coercions(positional_args, keyword_args)
+      ensure_modes_compatible!
+
+      if json_mode?
+        coerce_values!(positional_args, keyword_args) { |value| @json_coercer.coerce_json_value(value) }
+      end
+
+      if eval_mode?
+        coerce_values!(positional_args, keyword_args) { |value| @eval_coercer.coerce_eval_value(value) }
+      end
+    rescue ::ArgumentError => e
+      raise Rubycli::ArgumentError, e.message
+    end
+
+    private
+
+    def enforce_mutual_exclusion!(mode, enabled)
+      return unless enabled
+
+      case mode
+      when :json
+        raise Rubycli::ArgumentError, '--json-args cannot be combined with --eval-args or --eval-lax' if eval_mode?
+      when :eval
+        raise Rubycli::ArgumentError, '--json-args cannot be combined with --eval-args or --eval-lax' if json_mode?
+      end
+    end
+
+    def ensure_modes_compatible!
+      if json_mode? && eval_mode?
+        raise Rubycli::ArgumentError, '--json-args cannot be combined with --eval-args or --eval-lax'
+      end
+    end
+
+    def coerce_values!(positional_args, keyword_args)
+      positional_args.map! { |value| yield(value) }
+      keyword_args.keys.each do |key|
+        keyword_args[key] = yield(keyword_args[key])
+      end
+    end
+  end
+end

data/lib/rubycli/argument_parser.rb

@@ -1,4 +1,6 @@
 require_relative 'type_utils'
+require_relative 'arguments/token_stream'
+require_relative 'arguments/value_converter'
 
 module Rubycli
   class ArgumentParser
@@ -9,6 +11,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)
@@ -24,21 +27,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,
@@ -46,12 +49,12 @@ 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}"
@@ -84,8 +87,7 @@ module Rubycli
 
     def process_option_token(
       token,
-      args,
-      current_index,
+      stream,
       kw_param_names,
       kw_args,
       cli_aliases,
@@ -107,21 +109,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"
@@ -135,40 +135,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]
+    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)
@@ -203,21 +193,7 @@ module Rubycli
     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/
+      @value_converter.convert(arg)
     end
 
 
@@ -286,7 +262,7 @@ module Rubycli
       when 'String'
         ->(value) { value }
       when 'Integer', 'Fixnum'
-        ->(value) { Integer(value, 10) }
+        ->(value) { Integer(value) }
       when 'Float'
         ->(value) { Float(value) }
       when 'Numeric'
@@ -324,10 +300,25 @@ module Rubycli
     end
 
     def convert_option_value(keyword, value, option_meta, type_converters)
+      if Rubycli.eval_mode? || Rubycli.json_mode?
+        return convert_arg(value)
+      end
+
       converter = type_converters[keyword]
-      return convert_arg(value) unless converter
+      converted_value = convert_arg(value)
+      return converted_value unless converter
+
+      original_input = value if value.is_a?(String)
+      expects_list = option_meta && option_meta.types.any? { |type|
+        type.to_s.end_with?('[]') || type.to_s.start_with?('Array<')
+      }
+
+      value_for_converter = converted_value
+      if expects_list && original_input && converted_value.is_a?(Numeric) && original_input.include?(',')
+        value_for_converter = original_input
+      end
 
-      converter.call(value)
+      converter.call(value_for_converter)
     rescue StandardError => e
       option_label = option_meta&.long || option_meta&.short || keyword
       raise ArgumentError, "Value '#{value}' for option '#{option_label}' is invalid: #{e.message}"

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,74 @@
+# 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 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 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

data/lib/rubycli/cli.rb

@@ -37,7 +37,7 @@ module Rubycli
 
       if should_show_help?(args)
         @help_renderer.print_help(target, catalog)
-        exit(0)
+        return 0
       end
 
       command = args.shift
@@ -105,7 +105,7 @@ module Rubycli
         error_msg = "Command '#{command}' is not available."
         puts error_msg
         @help_renderer.print_help(target, catalog)
-        exit(1)
+        1
       end
     end
 
@@ -116,6 +116,7 @@ module Rubycli
       begin
         result = Rubycli.call_target(target, pos_args, kw_args)
         @result_emitter.emit(result)
+        0
       rescue StandardError => e
         handle_execution_error(e, command, method, pos_args, kw_args, cli_mode)
       end
@@ -132,15 +133,16 @@ module Rubycli
     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)
+        return 0
       end
 
       begin
         result = method_obj.call
         debug_log "Parameterless method returned: #{result.inspect}"
         if result
-          run(result, args, false)
+          return run(result, args, false)
         end
+        0
       rescue StandardError => e
         handle_execution_error(e, command, method_obj, [], {}, cli_mode)
       end
@@ -152,12 +154,13 @@ module Rubycli
 
       if should_show_method_help?(pos_args, kw_args)
         puts usage_for_method(command, method_obj)
-        exit(0)
+        return 0
       end
 
       begin
         result = Rubycli.call_target(method_obj, pos_args, kw_args)
         @result_emitter.emit(result)
+        0
       rescue StandardError => e
         handle_execution_error(e, command, method_obj, pos_args, kw_args, cli_mode)
       end
@@ -181,7 +184,7 @@ module Rubycli
       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)
+        1
       else
         raise error
       end

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 | --eval-args] TARGET_PATH [CLASS_OR_MODULE] [-- CLI_ARGS...]
+      Usage: rubycli [--new|-n] [--pre-script=<src>] [--json-args|-j | --eval-args|-e | --eval-lax|-E] <target-path> [<class-or-module>] [-- <cli-args>...]
 
       Examples:
         rubycli scripts/sample_runner.rb echo --message hello
@@ -12,14 +12,18 @@ module Rubycli
 
       Options:
         --new, -n            Instantiate the class/module before invoking CLI commands
-        --pre-script SRC     Evaluate Ruby code and use its result as the exposed target (--init alias)
-        --json-args          Treat all following arguments as JSON
-        --eval-args          Evaluate following arguments as Ruby code
-        (Note: --json-args and --eval-args are mutually exclusive)
+        --pre-script=<src>   Evaluate Ruby code and use its result as the exposed target (--init alias; also accepts space-separated form)
+        --json-args, -j      Parse all following arguments strictly as JSON (no YAML literals)
+        --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
+        (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.)
 
-      When CLASS_OR_MODULE is omitted, Rubycli infers it from the file name in CamelCase.
+      When <class-or-module> is omitted, Rubycli infers it from the file name in CamelCase.
+      Arguments are parsed as safe literals by default; pick a mode above if you need strict JSON or Ruby eval.
       Method return values are printed to STDOUT by default.
-      CLI_ARGS are forwarded to Rubycli unchanged.
+      <cli-args> are forwarded to Rubycli unchanged.
     USAGE
 
     module_function
@@ -36,6 +40,8 @@ module Rubycli
       new_flag = false
       json_mode = false
       eval_mode = false
+      eval_lax_mode = false
+      constant_mode = nil
       pre_script_sources = []
 
       loop do
@@ -63,13 +69,20 @@ module Rubycli
           end
           context = File.file?(src) ? File.expand_path(src) : "(inline #{flag})"
           pre_script_sources << { value: src, context: context }
-        when '--json-args'
+        when '--json-args', '-j'
           json_mode = true
           args.shift
-        when '--eval-args'
+        when '--eval-args', '-e'
           eval_mode = true
           args.shift
+        when '--eval-lax', '-E'
+          eval_mode = true
+          eval_lax_mode = true
+          args.shift
         when '--print-result'
+         args.shift
+        when '--auto-target', '-a'
+          constant_mode = :auto
           args.shift
         when '--'
           args.shift
@@ -93,7 +106,7 @@ module Rubycli
       args.shift if args.first == '--'
 
       if json_mode && eval_mode
-        warn '--json-args and --eval-args cannot be used at the same time'
+        warn '--json-args cannot be combined with --eval-args or --eval-lax'
         return 1
       end
 
@@ -104,13 +117,18 @@ module Rubycli
         new: new_flag,
         json: json_mode,
         eval_args: eval_mode,
-        pre_scripts: pre_script_sources
+        eval_lax: eval_lax_mode,
+        pre_scripts: pre_script_sources,
+        constant_mode: constant_mode
       )
 
       0
     rescue Rubycli::Runner::PreScriptError => e
       warn e.message
       1
+    rescue Rubycli::Runner::Error => e
+      warn e.message
+      1
     end
   end
 end

data/lib/rubycli/constant_capture.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Rubycli
+  # Observes constants defined while loading a file.
+  class ConstantCapture
+    def initialize
+      @captured = Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def capture(file)
+      trace = TracePoint.new(:class) do |tp|
+        location = tp.path
+        next unless location && same_file?(file, location)
+
+        constant_name = qualified_name_for(tp.self)
+        next unless constant_name
+
+        @captured[file] << constant_name
+      end
+
+      trace.enable
+      yield
+    ensure
+      trace&.disable
+    end
+
+    def constants_for(file)
+      Array(@captured[normalize(file)]).uniq
+    end
+
+    private
+
+    def same_file?(target, candidate)
+      normalize(target) == normalize(candidate)
+    end
+
+    def normalize(file)
+      File.expand_path(file.to_s)
+    end
+
+    def qualified_name_for(target)
+      return nil unless target.respond_to?(:name)
+
+      name = target.name
+      return nil unless name && !name.empty? && !name.start_with?('#<')
+
+      name
+    end
+  end
+end

data/lib/rubycli/documentation/comment_extractor.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Rubycli
+  module Documentation
+    # Extracts contiguous comment blocks that appear immediately before a method.
+    class CommentExtractor
+      def initialize
+        @file_cache = {}
+      end
+
+      def extract(file, line_number)
+        return [] unless file && line_number
+
+        lines = cached_lines_for(file)
+        index = line_number - 2
+        block = []
+
+        while index >= 0
+          line = lines[index]
+          break unless comment_line?(line)
+
+          block << line
+          index -= 1
+        end
+
+        block.reverse.map { |line| strip_comment_prefix(line) }
+      rescue Errno::ENOENT
+        []
+      end
+
+      def reset!
+        @file_cache.clear
+      end
+
+      private
+
+      def cached_lines_for(file)
+        @file_cache[file] ||= File.readlines(file, chomp: true)
+      end
+
+      def comment_line?(line)
+        return false unless line
+
+        line.lstrip.start_with?('#')
+      end
+
+      def strip_comment_prefix(line)
+        line.lstrip.sub(/^#/, '').lstrip
+      end
+    end
+  end
+end