rubycli 0.1.7 → 0.2.0

data/lib/rubycli.rb

@@ -2,9 +2,6 @@
 
 require 'json'
 
-feature_path = File.expand_path(__FILE__)
-$LOADED_FEATURES << feature_path unless $LOADED_FEATURES.include?(feature_path)
-
 require_relative 'rubycli/version'
 require_relative 'rubycli/environment'
 require_relative 'rubycli/types'
@@ -127,8 +124,8 @@ module Rubycli
       argument_mode_controller.json_mode?
     end
 
-    def with_json_mode(enabled = true)
-      argument_mode_controller.with_json_mode(enabled) { yield }
+    def with_json_mode(enabled = true, &block)
+      argument_mode_controller.with_json_mode(enabled, &block)
     end
 
     def coerce_json_value(value)
@@ -143,8 +140,8 @@ module Rubycli
       eval_coercer.eval_lax_mode?
     end
 
-    def with_eval_mode(enabled = true, **options)
-      argument_mode_controller.with_eval_mode(enabled, **options) { yield }
+    def with_eval_mode(enabled = true, **options, &block)
+      argument_mode_controller.with_eval_mode(enabled, **options, &block)
     end
 
     def coerce_eval_value(value)
@@ -159,453 +156,7 @@ module Rubycli
       apply_argument_coercions(pos_args, kw_args)
     end
   end
-
-  module Runner
-    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(
-      target_path,
-      class_name = nil,
-      cli_args = nil,
-      new: false,
-      new_args: nil,
-      json: false,
-      eval_args: false,
-      eval_lax: false,
-      pre_scripts: [],
-      constant_mode: nil
-    )
-      raise ArgumentError, 'target_path must be specified' if target_path.nil? || target_path.empty?
-      if json && eval_args
-        raise Error, '--json-args cannot be combined with --eval-args or --eval-lax'
-      end
-
-      runner_target, full_path = prepare_runner_target(
-        target_path,
-        class_name,
-        new: new,
-        new_args: new_args,
-        json_mode: json,
-        eval_mode: eval_args,
-        eval_lax: eval_lax,
-        pre_scripts: pre_scripts,
-        constant_mode: constant_mode
-      )
-
-      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, 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,
-      new_args: nil,
-      pre_scripts: [],
-      constant_mode: nil,
-      json_mode: false,
-      eval_mode: false,
-      eval_lax: false
-    )
-      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,
-        new_args: new_args,
-        json_mode: json_mode,
-        eval_mode: eval_mode,
-        eval_lax: eval_lax,
-        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)
-        result.nil? ? current_target : result
-      end
-    end
-
-    def evaluate_pre_script(source, base_target, current_target)
-      code, context = read_pre_script_code(source)
-      pre_binding = Object.new.instance_eval { binding }
-      pre_binding.local_variable_set(:target, base_target)
-      pre_binding.local_variable_set(:current, current_target)
-      pre_binding.local_variable_set(:instance, current_target)
-
-      Rubycli.with_eval_mode(true) do
-        pre_binding.eval(code, context)
-      end
-    rescue Errno::ENOENT
-      raise PreScriptError, "Pre-script file not found: #{context}"
-    rescue StandardError => e
-      raise PreScriptError, "Failed to evaluate pre-script (#{context}): #{e.message}"
-    end
-
-    def read_pre_script_code(source)
-      value = source[:value]
-      inline_context = source[:context] || '(inline pre-script)'
-
-      if !value.nil? && File.file?(value)
-        [File.read(value), File.expand_path(value)]
-      else
-        [String(value), inline_context]
-      end
-    end
-
-    def find_target_path(path)
-      if File.file?(path)
-        File.expand_path(path)
-      elsif File.file?("#{path}.rb")
-        File.expand_path("#{path}.rb")
-      else
-        raise Error, "File not found: #{path}"
-      end
-    end
-
-    def camelize(name)
-      name.split(/[^a-zA-Z0-9]+/).reject(&:empty?).map { |part|
-        part[0].upcase + part[1..].downcase
-      }.join
-    end
-
-    def constantize(name, defined_constants: nil, full_path: nil)
-      parts = name.to_s.split('::').reject(&:empty?)
-      raise Error, "Unable to resolve class/module name: #{name.inspect}" if parts.empty?
-
-      parts.reduce(Object) do |context, const_name|
-        context.const_get(const_name)
-      end
-    rescue NameError
-      message = build_missing_constant_message(name, defined_constants, full_path)
-      raise Error.new(message), cause: nil
-    end
-
-    def instantiate_target(target, initializer_args = nil)
-      positional_args, keyword_args = Array(initializer_args || [[], {}])
-      positional_args ||= []
-      keyword_args ||= {}
-
-      case target
-      when Class
-        if keyword_args.empty?
-          target.new(*positional_args)
-        else
-          target.new(*positional_args, **keyword_args)
-        end
-      when Module
-        Object.new.extend(target)
-      else
-        target
-      end
-    rescue ArgumentError => e
-      raise Error, "Failed to instantiate target: #{e.message}"
-    end
-
-    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, lax: eval_lax, &runner)
-      else
-        runner.call
-      end
-    end
-
-    def parse_initializer_arguments(raw_value, target, json_mode:, eval_mode:, eval_lax:)
-      return [[], {}] if raw_value.nil?
-      raise Rubycli::ArgumentError, '--json-args cannot be combined with --eval-args or --eval-lax' if json_mode && eval_mode
-
-      initializer_method = initializer_method_for(target)
-      tokens = Array(raw_value)
-
-      positional_args = []
-      keyword_args = {}
-
-      Rubycli.argument_mode_controller.with_json_mode(json_mode) do
-        Rubycli.argument_mode_controller.with_eval_mode(eval_mode, lax: eval_lax) do
-          positional_args, keyword_args = Rubycli.argument_parser.parse(tokens.dup, initializer_method)
-          Rubycli.apply_argument_coercions(positional_args, keyword_args)
-          Rubycli.argument_parser.validate_inputs(initializer_method, positional_args, keyword_args)
-        end
-      end
-
-      [positional_args || [], keyword_args || {}]
-    rescue Rubycli::ArgumentError => e
-      raise Runner::Error, "Failed to parse --new arguments: #{e.message}"
-    end
-
-    def initializer_method_for(target)
-      return nil unless target.is_a?(Class)
-
-      target.instance_method(:initialize) rescue nil
-    end
-
-    def prepare_runner_target(
-      target_path,
-      class_name,
-      new: false,
-      new_args: nil,
-      json_mode: false,
-      eval_mode: false,
-      eval_lax: 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
-
-      initializer_args = new ? parse_initializer_arguments(new_args, target, json_mode: json_mode, eval_mode: eval_mode, eval_lax: eval_lax) : nil
-
-      runner_target = new ? instantiate_target(target, initializer_args) : target
-      runner_target = apply_pre_scripts(pre_scripts, target, runner_target)
-      [runner_target, full_path]
-    end
-
-    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)
-
-        class_methods = collect_defined_methods(constant.singleton_class, normalized)
-        instance_methods = collect_defined_methods(constant, normalized)
-
-        memo << ConstantCandidate.new(
-          name: const_name,
-          constant: constant,
-          class_methods: class_methods,
-          instance_methods: instance_methods
-        )
-      end
-    end
-
-    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
-
-        memo << method_name
-      end
-    rescue TypeError
-      []
-    end
-
-    def safe_constant_lookup(name)
-      parts = name.split('::').reject(&: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 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
-
-      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
-
-      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
-
-      if constant_mode == :auto && callable.size == 1
-        return callable.first.constant
-      end
-
-      details = build_ambiguous_constant_details(callable, path)
-      raise Error, build_missing_constant_message(
-        base_const,
-        candidates.map(&:name),
-        path,
-        details: details
-      )
-    end
-
-    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
-
-      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 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 << ''
-      lines << "Loaded file: #{File.expand_path(full_path)}" if full_path
-
-      if defined_constants && !defined_constants.empty?
-        sample = defined_constants.first(5)
-        suffix = defined_constants.size > sample.size ? " ... (#{defined_constants.size} total)" : ''
-        lines << "Constants found in this file: #{sample.join(', ')}#{suffix}"
-      else
-        lines << 'Rubycli could not detect any publicly exposable constants in this file.'
-      end
-
-      if details
-        lines << ''
-        lines << details
-      end
-
-      lines << ''
-      lines << 'Hint: Ensure the CLASS_OR_MODULE argument is correct when invoking the CLI.'
-      lines.join("\n")
-    end
-  end
 end
+
+# Defined after the Rubycli module so that Runner::Error can subclass Rubycli::Error.
+require_relative 'rubycli/runner'

metadata

@@ -1,14 +1,56 @@
 --- !ruby/object:Gem::Specification
 name: rubycli
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.2.0
 platform: ruby
 authors:
 - inakaegg
 bindir: exe
 cert_chain: []
-date: 2025-11-16 00:00:00.000000000 Z
-dependencies: []
+date: 2026-07-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
 description: Rubycli turns plain Ruby classes and modules into command-line interfaces
   by reading their documentation comments, inspired by Python Fire but tailored for
   Ruby tooling.
@@ -23,6 +65,17 @@ files:
 - LICENSE
 - README.ja.md
 - README.md
+- examples/documentation_style_showcase.rb
+- examples/fallback_example.rb
+- examples/fallback_example_with_extra_docs.rb
+- examples/hello_app.rb
+- examples/hello_app_with_docs.rb
+- examples/hello_app_with_require.rb
+- examples/mismatched_constant_runner.rb
+- examples/multi_constant_runner.rb
+- examples/new_mode_runner.rb
+- examples/strict_choices_demo.rb
+- examples/typed_arguments_demo.rb
 - exe/rubycli
 - lib/rubycli.rb
 - lib/rubycli/argument_mode_controller.rb
@@ -40,6 +93,7 @@ files:
 - lib/rubycli/help_renderer.rb
 - lib/rubycli/json_coercer.rb
 - lib/rubycli/result_emitter.rb
+- lib/rubycli/runner.rb
 - lib/rubycli/type_utils.rb
 - lib/rubycli/types.rb
 - lib/rubycli/version.rb
@@ -49,8 +103,9 @@ licenses:
 metadata:
   homepage_uri: https://github.com/inakaegg/rubycli
   documentation_uri: https://github.com/inakaegg/rubycli#readme
-  changelog_uri: https://github.com/inakaegg/rubycli/releases
+  changelog_uri: https://github.com/inakaegg/rubycli/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/inakaegg/rubycli/issues
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib