rubycli 0.1.2 → 0.1.5

data/lib/rubycli.rb

@@ -12,11 +12,15 @@ require_relative 'rubycli/type_utils'
 require_relative 'rubycli/documentation_registry'
 require_relative 'rubycli/json_coercer'
 require_relative 'rubycli/eval_coercer'
+require_relative 'rubycli/arguments/token_stream'
+require_relative 'rubycli/arguments/value_converter'
+require_relative 'rubycli/argument_mode_controller'
 require_relative 'rubycli/argument_parser'
 require_relative 'rubycli/help_renderer'
 require_relative 'rubycli/result_emitter'
 require_relative 'rubycli/cli'
 require_relative 'rubycli/command_line'
+require_relative 'rubycli/constant_capture'
 
 module Rubycli
   class Error < StandardError; end
@@ -40,6 +44,13 @@ module Rubycli
       @eval_coercer ||= EvalCoercer.new
     end
 
+    def argument_mode_controller
+      @argument_mode_controller ||= ArgumentModeController.new(
+        json_coercer: json_coercer,
+        eval_coercer: eval_coercer
+      )
+    end
+
     def argument_parser
       @argument_parser ||= ArgumentParser.new(
         environment: environment,
@@ -57,6 +68,10 @@ module Rubycli
       @result_emitter ||= ResultEmitter.new(environment: environment)
     end
 
+    def constant_capture
+      @constant_capture ||= ConstantCapture.new
+    end
+
     def cli
       @cli ||= CLI.new(
         environment: environment,
@@ -68,7 +83,10 @@ module Rubycli
     end
 
     def run(target, args = ARGV, cli_mode = true)
-      cli.run(target, args.dup, cli_mode)
+      status = cli.run(target, args.dup, cli_mode)
+      return status unless cli_mode
+
+      exit(status.to_i)
     end
 
     def parse_arguments(args, method = nil)
@@ -106,15 +124,11 @@ module Rubycli
     end
 
     def json_mode?
-      json_coercer.json_mode?
+      argument_mode_controller.json_mode?
     end
 
     def with_json_mode(enabled = true)
-      if enabled && eval_mode?
-        raise Rubycli::ArgumentError, '--json-args and --eval-args cannot be used together'
-      end
-
-      json_coercer.with_json_mode(enabled) { yield }
+      argument_mode_controller.with_json_mode(enabled) { yield }
     end
 
     def coerce_json_value(value)
@@ -122,15 +136,15 @@ module Rubycli
     end
 
     def eval_mode?
-      eval_coercer.eval_mode?
+      argument_mode_controller.eval_mode?
     end
 
-    def with_eval_mode(enabled = true)
-      if enabled && json_mode?
-        raise Rubycli::ArgumentError, '--json-args and --eval-args cannot be used together'
-      end
+    def eval_lax_mode?
+      eval_coercer.eval_lax_mode?
+    end
 
-      eval_coercer.with_eval_mode(enabled) { yield }
+    def with_eval_mode(enabled = true, **options)
+      argument_mode_controller.with_eval_mode(enabled, **options) { yield }
     end
 
     def coerce_eval_value(value)
@@ -138,25 +152,7 @@ module Rubycli
     end
 
     def apply_argument_coercions(pos_args, kw_args)
-      if json_mode? && eval_mode?
-        raise Rubycli::ArgumentError, '--json-args and --eval-args cannot be used together'
-      end
-
-      if json_mode?
-        pos_args.map! { |value| coerce_json_value(value) }
-        kw_args.keys.each do |key|
-          kw_args[key] = coerce_json_value(kw_args[key])
-        end
-      end
-
-      return unless eval_mode?
-
-      pos_args.map! { |value| coerce_eval_value(value) }
-      kw_args.keys.each do |key|
-        kw_args[key] = coerce_eval_value(kw_args[key])
-      end
-    rescue ArgumentError => e
-      raise Rubycli::ArgumentError, e.message
+      argument_mode_controller.apply_argument_coercions(pos_args, kw_args)
     end
 
     def apply_json_coercion(pos_args, kw_args)
@@ -168,6 +164,44 @@ module Rubycli
     class Error < Rubycli::Error; end
     class PreScriptError < Error; end
 
+    ConstantCandidate = Struct.new(
+      :name,
+      :constant,
+      :class_methods,
+      :instance_methods,
+      keyword_init: true
+    ) do
+      def callable?(instantiate: false)
+        return true if class_methods.any?
+
+        instantiate && instance_methods.any?
+      end
+
+      def matches?(base_name)
+        name.split('::').last == base_name
+      end
+
+      def instance_only?
+        instance_methods.any? && class_methods.empty?
+      end
+
+      def summary
+        parts = []
+        parts << "class: #{format_methods(class_methods)}" if class_methods.any?
+        parts << "instance: #{format_methods(instance_methods)}" if instance_methods.any?
+        parts << 'no CLI methods' if parts.empty?
+        parts.join(' | ')
+      end
+
+      private
+
+      def format_methods(methods)
+        list = methods.first(3).map(&:to_s)
+        list << '...' if methods.size > 3
+        list.join(', ')
+      end
+    end
+
     module_function
 
     def execute(
@@ -177,36 +211,81 @@ module Rubycli
       new: false,
       json: false,
       eval_args: false,
-      pre_scripts: []
+      eval_lax: false,
+      pre_scripts: [],
+      constant_mode: nil
     )
       raise ArgumentError, 'target_path must be specified' if target_path.nil? || target_path.empty?
-      original_program_name = $PROGRAM_NAME
       if json && eval_args
-        raise Error, '--json-args and --eval-args cannot be used together'
+        raise Error, '--json-args cannot be combined with --eval-args or --eval-lax'
       end
 
-      full_path = find_target_path(target_path)
-      load full_path
-      $PROGRAM_NAME = File.basename(full_path)
-      defined_constants = constants_defined_in_file(full_path)
-
-      constant_name = class_name || infer_class_name(full_path)
-      target = constantize(
-        constant_name,
-        defined_constants: defined_constants,
-        full_path: full_path
+      runner_target, full_path = prepare_runner_target(
+        target_path,
+        class_name,
+        new: new,
+        pre_scripts: pre_scripts,
+        constant_mode: constant_mode
       )
-      runner_target = new ? instantiate_target(target) : target
-      runner_target = apply_pre_scripts(pre_scripts, target, runner_target)
 
+      original_program_name = $PROGRAM_NAME
+      original_argv = nil
+      $PROGRAM_NAME = File.basename(full_path)
       original_argv = ARGV.dup
       ARGV.replace(Array(cli_args).dup)
-      run_with_modes(runner_target, json: json, eval_args: eval_args)
+      run_with_modes(runner_target, json: json, eval_args: eval_args, eval_lax: eval_lax)
     ensure
       $PROGRAM_NAME = original_program_name if original_program_name
       ARGV.replace(original_argv) if original_argv
     end
 
+    def check(
+      target_path,
+      class_name = nil,
+      new: false,
+      pre_scripts: [],
+      constant_mode: nil
+    )
+      raise ArgumentError, 'target_path must be specified' if target_path.nil? || target_path.empty?
+      previous_doc_check = Rubycli.environment.doc_check_mode?
+      Rubycli.environment.clear_documentation_issues!
+      Rubycli.environment.enable_doc_check!
+
+      runner_target, full_path = prepare_runner_target(
+        target_path,
+        class_name,
+        new: new,
+        pre_scripts: pre_scripts,
+        constant_mode: constant_mode
+      )
+
+      original_program_name = $PROGRAM_NAME
+      $PROGRAM_NAME = File.basename(full_path)
+
+      catalog = Rubycli.cli.command_catalog_for(runner_target)
+      Array(catalog&.entries).each do |entry|
+        method_obj = entry&.method
+        Rubycli.documentation_registry.metadata_for(method_obj) if method_obj
+      end
+
+      if catalog&.entries&.empty? && runner_target.respond_to?(:call)
+        method_obj = runner_target.method(:call) rescue nil
+        Rubycli.documentation_registry.metadata_for(method_obj) if method_obj
+      end
+
+      issues = Rubycli.environment.documentation_issues
+      if issues.empty?
+        puts 'rubycli documentation OK'
+        0
+      else
+        warn "[ERROR] rubycli documentation check failed (#{issues.size} issue#{issues.size == 1 ? '' : 's'})"
+        1
+      end
+    ensure
+      Rubycli.environment.disable_doc_check! unless previous_doc_check
+      $PROGRAM_NAME = original_program_name if original_program_name
+    end
+
     def apply_pre_scripts(sources, base_target, initial_target)
       Array(sources).reduce(initial_target) do |current_target, source|
         result = evaluate_pre_script(source, base_target, current_target)
@@ -251,12 +330,6 @@ module Rubycli
       end
     end
 
-    def infer_class_name(path)
-      base = File.basename(path, '.rb')
-      base_const = camelize(base)
-      detect_constant_for_file(path, base_const) || base_const
-    end
-
     def camelize(name)
       name.split(/[^a-zA-Z0-9]+/).reject(&:empty?).map { |part|
         part[0].upcase + part[1..].downcase
@@ -288,106 +361,175 @@ module Rubycli
       raise Error, "Failed to instantiate target: #{e.message}"
     end
 
-    def run_with_modes(target, json:, eval_args:)
+    def run_with_modes(target, json:, eval_args:, eval_lax:)
       runner = proc { Rubycli.run(target) }
 
       if json
         Rubycli.with_json_mode(true, &runner)
       elsif eval_args
-        Rubycli.with_eval_mode(true, &runner)
+        Rubycli.with_eval_mode(true, lax: eval_lax, &runner)
       else
         runner.call
       end
     end
 
-    def detect_constant_for_file(path, base_const)
-      full_path = File.expand_path(path)
-      candidates = runtime_constant_candidates(full_path, base_const)
-      candidates.find { |name| constant_defined?(name) }
-    end
+    def prepare_runner_target(
+      target_path,
+      class_name,
+      new: false,
+      pre_scripts: [],
+      constant_mode: nil
+    )
+      full_path = find_target_path(target_path)
+      capture = Rubycli.constant_capture
+      capture.capture(full_path) { load full_path }
+      constant_mode ||= Rubycli.environment.constant_resolution_mode
+      candidates = build_constant_candidates(full_path, capture.constants_for(full_path))
+      defined_constants = candidates.map(&:name)
+
+      target = if class_name
+                 constantize(
+                   class_name,
+                   defined_constants: defined_constants,
+                   full_path: full_path
+                 )
+               else
+                 select_constant_candidate(
+                   full_path,
+                   camelize(File.basename(full_path, '.rb')),
+                   candidates,
+                   constant_mode,
+                   instantiate: new
+                 )
+               end
 
-    def constants_defined_in_file(path)
-      return [] unless Module.method_defined?(:const_source_location)
+      runner_target = new ? instantiate_target(target) : target
+      runner_target = apply_pre_scripts(pre_scripts, target, runner_target)
+      [runner_target, full_path]
+    end
 
-      normalized = File.expand_path(path)
-      ObjectSpace.each_object(Module).each_with_object([]) do |mod, memo|
-        mod_name = module_name_for(mod)
-        next if mod_name.nil?
+    def build_constant_candidates(path, constant_names)
+      normalized = normalize_path(path)
+      Array(constant_names).each_with_object([]) do |const_name, memo|
+        constant = safe_constant_lookup(const_name)
+        next unless constant.is_a?(Module)
 
-        safe_module_constants(mod).each do |const_name|
-          location = safe_const_source_location(mod, const_name)
-          next unless location && location[0]
-          next unless File.expand_path(location[0]) == normalized
+        class_methods = collect_defined_methods(constant.singleton_class, normalized)
+        instance_methods = collect_defined_methods(constant, normalized)
 
-          memo << qualified_constant_name(mod_name, const_name.to_s)
-        end
-      end.uniq.sort_by { |name| [name.count('::'), name] }
+        memo << ConstantCandidate.new(
+          name: const_name,
+          constant: constant,
+          class_methods: class_methods,
+          instance_methods: instance_methods
+        )
+      end
     end
 
-    def runtime_constant_candidates(full_path, base_const)
-      return [] unless Module.method_defined?(:const_source_location)
-
-      normalized = File.expand_path(full_path)
-      ObjectSpace.each_object(Module).each_with_object([]) do |mod, memo|
-        mod_name = module_name_for(mod)
-        next unless mod_name
-        next unless safe_const_defined?(mod, base_const)
+    def collect_defined_methods(owner, normalized_path)
+      owner.public_instance_methods(false).each_with_object([]) do |method_name, memo|
+        method_object = owner.instance_method(method_name)
+        location = method_object.source_location
+        next unless location && normalize_path(location[0]) == normalized_path
 
-        location = safe_const_source_location(mod, base_const)
-        next unless location && File.expand_path(location[0]) == normalized
-
-        memo << qualified_constant_name(mod_name, base_const)
-      end.uniq.sort_by { |name| [-name.count('::'), name] }
+        memo << method_name
+      end
+    rescue TypeError
+      []
     end
 
-    def module_name_for(mod)
-      return '' if mod.equal?(Object)
-
-      name = mod.name
-      return nil if name.nil? || name.start_with?('#<')
+    def safe_constant_lookup(name)
+      parts = name.split('::').reject(&:empty?)
+      context = Object
 
-      name
-    end
+      parts.each do |const_name|
+        return nil unless context.const_defined?(const_name, false)
 
-    def qualified_constant_name(mod_name, base_const)
-      mod_name.empty? ? base_const : "#{mod_name}::#{base_const}"
-    end
+        context = context.const_get(const_name)
+      end
 
-    def safe_module_constants(mod)
-      mod.constants(false)
+      context
     rescue NameError
-      []
+      nil
     end
 
-    def safe_const_defined?(mod, const_name)
-      mod.const_defined?(const_name, false)
-    rescue NameError
-      false
-    end
+    def select_constant_candidate(path, base_const, candidates, constant_mode, instantiate: false)
+      if candidates.empty?
+        raise Error, build_missing_constant_message(
+          base_const,
+          [],
+          path,
+          details: 'Rubycli could not detect any constants in this file.'
+        )
+      end
 
-    def safe_const_source_location(mod, const_name)
-      return nil unless mod.respond_to?(:const_source_location)
+      matching = candidates.find { |candidate| candidate.matches?(base_const) }
+      if matching
+        return matching.constant if matching.callable?(instantiate: instantiate)
+
+        detail = if matching.instance_only?
+                   "#{matching.name} only defines instance methods in this file. Run with --new to instantiate before invoking CLI commands."
+                 else
+                   "#{matching.name} does not define any CLI-callable methods in this file. Add a public class or instance method defined in this file."
+                 end
+        raise Error, build_missing_constant_message(
+          base_const,
+          candidates.map(&:name),
+          path,
+          details: detail
+        )
+      end
 
-      mod.const_source_location(const_name, false)
-    rescue NameError
-      nil
-    end
+      callable = candidates.select { |candidate| candidate.callable?(instantiate: instantiate) }
+      if callable.empty?
+        raise Error, build_missing_constant_message(
+          base_const,
+          candidates.map(&:name),
+          path,
+          details: 'Rubycli detected constants in this file, but none define CLI-callable methods. Add a public class or instance method defined in this file.'
+        )
+      end
 
-    def constant_defined?(name)
-      parts = name.split('::').reject(&:empty?)
-      context = Object
+      if constant_mode == :auto && callable.size == 1
+        return callable.first.constant
+      end
 
-      parts.each do |const_name|
-        return false unless context.const_defined?(const_name, false)
+      details = build_ambiguous_constant_details(callable, path)
+      raise Error, build_missing_constant_message(
+        base_const,
+        candidates.map(&:name),
+        path,
+        details: details
+      )
+    end
 
-        context = context.const_get(const_name)
+    def build_ambiguous_constant_details(candidates, path)
+      command_target = File.basename(path)
+      if candidates.size == 1
+        candidate = candidates.first
+        lines = []
+        lines << "This file defines #{candidate.name}, but its name does not match #{command_target}."
+        lines << 'Re-run by specifying the constant explicitly:'
+        lines << "  rubycli #{command_target} #{candidate.name} ..."
+        lines << 'Alternatively pass --auto-target (or RUBYCLI_AUTO_TARGET=auto) to auto-select it.'
+        return lines.join("\n")
       end
-      true
-    rescue NameError
-      false
+
+      lines = ['Multiple CLI-capable constants were found in this file:']
+      candidates.each do |candidate|
+        hint = candidate.instance_only? ? ' (instance methods only; use --new)' : ''
+        lines << "  - #{candidate.name}: #{candidate.summary}#{hint}"
+      end
+      lines << "Specify one explicitly, e.g. rubycli #{command_target} MyRunner"
+      lines << 'Or pass --auto-target to allow Rubycli to auto-select a single candidate.'
+      lines.join("\n")
     end
 
-    def build_missing_constant_message(name, defined_constants, full_path)
+    def normalize_path(path)
+      File.expand_path(path.to_s)
+    end
+
+    def build_missing_constant_message(name, defined_constants, full_path, details: nil)
       lines = ["Could not find definition: #{name}"]
       lines << "  Loaded file: #{File.expand_path(full_path)}" if full_path
 
@@ -399,6 +541,8 @@ module Rubycli
         lines << "  Rubycli could not detect any publicly exposable constants in this file."
       end
 
+      lines << "  #{details}" if details
+
       lines << "  Ensure the CLASS_OR_MODULE argument is correct when invoking the CLI."
       lines.join("\n")
     end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rubycli
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.5
 platform: ruby
 authors:
 - inakaegg
 bindir: exe
 cert_chain: []
-date: 2025-11-06 00:00:00.000000000 Z
+date: 2025-11-09 00:00:00.000000000 Z
 dependencies: []
 description: Rubycli turns plain Ruby classes and modules into command-line interfaces
   by reading their documentation comments, inspired by Python Fire but tailored for
@@ -25,9 +25,15 @@ files:
 - README.md
 - exe/rubycli
 - lib/rubycli.rb
+- lib/rubycli/argument_mode_controller.rb
 - lib/rubycli/argument_parser.rb
+- lib/rubycli/arguments/token_stream.rb
+- lib/rubycli/arguments/value_converter.rb
 - lib/rubycli/cli.rb
 - lib/rubycli/command_line.rb
+- lib/rubycli/constant_capture.rb
+- lib/rubycli/documentation/comment_extractor.rb
+- lib/rubycli/documentation/metadata_parser.rb
 - lib/rubycli/documentation_registry.rb
 - lib/rubycli/environment.rb
 - lib/rubycli/eval_coercer.rb