rubycli 0.1.1

data/lib/rubycli/environment.rb

@@ -0,0 +1,77 @@
+module Rubycli
+  # Environment captures runtime flags and configuration derived from ENV / argv.
+  class Environment
+    def initialize(env: ENV, argv: nil)
+      @env = env
+      @argv = argv
+      @debug = env['RUBYCLI_DEBUG'] == 'true'
+      @print_result = env['RUBYCLI_PRINT_RESULT'] == 'true'
+      scrub_argv_flags!
+    end
+
+    def debug?
+      @debug
+    end
+
+    def print_result?
+      @print_result
+    end
+
+    def strict_mode?
+      value = fetch_env_value('RUBYCLI_STRICT', 'OFF')
+      !%w[off 0 false].include?(value.downcase)
+    end
+
+    def allow_param_comments?
+      value = fetch_env_value('RUBYCLI_ALLOW_PARAM_COMMENT', 'ON')
+      %w[on 1 true].include?(value.downcase)
+    end
+
+    def handle_documentation_issue(message, file: nil, line: nil)
+      location = nil
+      if file
+        expanded = File.expand_path(file)
+        relative_prefix = File.expand_path(Dir.pwd) + '/'
+        display_path = expanded.start_with?(relative_prefix) ? expanded.delete_prefix(relative_prefix) : expanded
+        location = line ? "#{display_path}:#{line}" : display_path
+      end
+
+      formatted_message = if location
+        "#{location} #{message}"
+      else
+        message
+      end
+
+      warn "[WARN] Rubycli documentation mismatch: #{formatted_message}" if strict_mode?
+    end
+
+    def enable_print_result!
+      @print_result = true
+    end
+
+    private
+
+    def fetch_env_value(key, default)
+      (@env.fetch(key, default) || default).to_s.strip.downcase
+    end
+
+    def scrub_argv_flags!
+      return unless @argv
+
+      remove_all_flags!(@argv, '--debug') { @debug = true }
+      remove_all_flags!(@argv, '--print-result') { @print_result = true }
+    end
+
+    def remove_all_flags!(argv, flag)
+      found = false
+      loop do
+        index = argv.index(flag)
+        break unless index
+
+        argv.delete_at(index)
+        found = true
+      end
+      yield if found && block_given?
+    end
+  end
+end

data/lib/rubycli/eval_coercer.rb

@@ -0,0 +1,42 @@
+module Rubycli
+  class EvalCoercer
+    THREAD_KEY = :rubycli_eval_mode
+    EVAL_BINDING = Object.new.instance_eval { binding }
+
+    def eval_mode?
+      Thread.current[THREAD_KEY] == true
+    end
+
+    def with_eval_mode(enabled = true)
+      previous = Thread.current[THREAD_KEY]
+      Thread.current[THREAD_KEY] = enabled
+      yield
+    ensure
+      Thread.current[THREAD_KEY] = previous
+    end
+
+    def coerce_eval_value(value)
+      case value
+      when String
+        evaluate_string(value)
+      when Array
+        value.map { |item| coerce_eval_value(item) }
+      when Hash
+        value.transform_values { |item| coerce_eval_value(item) }
+      else
+        value
+      end
+    rescue StandardError => e
+      raise Rubycli::ArgumentError, "Failed to evaluate Ruby code: #{e.message}"
+    end
+
+    private
+
+    def evaluate_string(expression)
+      trimmed = expression.strip
+      return trimmed if trimmed.empty?
+
+      EVAL_BINDING.eval(trimmed)
+    end
+  end
+end

data/lib/rubycli/help_renderer.rb

@@ -0,0 +1,298 @@
+require_relative "type_utils"
+
+module Rubycli
+  class HelpRenderer
+    include TypeUtils
+
+    def initialize(documentation_registry:)
+      @documentation_registry = documentation_registry
+    end
+
+    def print_help(target, catalog)
+      puts "Usage: #{File.basename($PROGRAM_NAME)} COMMAND [arguments]"
+      puts
+
+      instance_entries = catalog.entries_for(:instance)
+      class_entries = catalog.entries_for(:class)
+      groups = []
+      groups << { label: "Instance methods", entries: instance_entries } unless instance_entries.empty?
+      groups << { label: "Class methods", entries: class_entries } unless class_entries.empty?
+
+      if groups.empty?
+        puts "No commands available."
+        return
+      end
+
+      puts "Available commands:"
+      groups.each do |group|
+        puts "  #{group[:label]}:"
+        group[:entries].each do |entry|
+          description = method_description(entry.method)
+          line = "    #{entry.command.ljust(20)}"
+          line += " #{description}" unless description.empty?
+          puts line.rstrip
+
+          unless entry.aliases.empty?
+            puts "      Aliases: #{entry.aliases.join(", ")}"
+          end
+        end
+        puts unless group.equal?(groups.last)
+      end
+
+      if catalog.duplicates.any?
+        puts "Methods with the same name can be invoked via instance::NAME / class::NAME."
+      end
+
+      puts
+      puts "Detailed command help: #{File.basename($PROGRAM_NAME)} COMMAND help"
+      puts "Enable debug logging: --debug or RUBYCLI_DEBUG=true"
+    end
+
+    def method_description(method_obj)
+      metadata = @documentation_registry.metadata_for(method_obj)
+      summary = metadata[:summary]
+      return summary if summary && !summary.empty?
+
+      params = method_obj.parameters
+      return "(no arguments)" if params.empty?
+
+      param_desc = params.map { |type, name|
+        case type
+        when :req then "<#{name}>"
+        when :opt then "[<#{name}>]"
+        when :rest then "[<#{name}>...]"
+        when :keyreq then "--#{name.to_s.tr("_", "-")}=<value>"
+        when :key then "[--#{name.to_s.tr("_", "-")}=<value>]"
+        when :keyrest then "[--<option>...]"
+        end
+      }.compact.join(" ")
+
+      param_desc.empty? ? "(no arguments)" : param_desc
+    end
+
+    def usage_for_method(command, method)
+      metadata = @documentation_registry.metadata_for(method)
+      params_str = format_method_parameters(method.parameters, metadata)
+      usage_lines = ["Usage: #{File.basename($PROGRAM_NAME)} #{command} #{params_str}".strip]
+
+      options = metadata[:options] || []
+      positionals_in_order = ordered_positionals(method, metadata)
+
+      if positionals_in_order.any?
+        labels = positionals_in_order.map { |info| info[:label] }
+        max_label_length = labels.map(&:length).max || 0
+
+        usage_lines << ""
+        usage_lines << "Positional arguments:"
+        positionals_in_order.each do |info|
+          definition = info[:definition]
+          description_parts = []
+          if definition&.inline_type_annotation && definition.inline_type_text
+            description_parts << definition.inline_type_text
+          end
+          type_info = positional_type_display(definition)
+          if type_info && type_info_first?(definition)
+            description_parts << type_info
+          end
+          description_parts << info[:description] if info[:description]
+          description_parts << type_info if type_info && !type_info_first?(definition)
+          default_text = positional_default_display(definition)
+          description_parts << default_text if default_text
+          description_text = description_parts.join(' ')
+          line = "  #{info[:label].ljust(max_label_length)}"
+          line += "  #{description_text}" unless description_text.empty?
+          usage_lines << line
+        end
+      end
+
+      if options.any?
+        option_labels = options.map { |opt| option_flag_with_placeholder(opt) }
+        max_label_length = option_labels.map(&:length).max || 0
+
+        usage_lines << "" unless usage_lines.last == ""
+        usage_lines << "Options:"
+        options.each_with_index do |opt, idx|
+          label = option_labels[idx]
+          description_parts = []
+          if opt.inline_type_annotation && opt.inline_type_text
+            description_parts << opt.inline_type_text
+          end
+          type_info = option_type_display(opt)
+          if type_info && type_info_first?(opt)
+            description_parts << type_info
+          end
+          description_parts << opt.description if opt.description
+          description_parts << type_info if type_info && !type_info_first?(opt)
+          default_info = option_default_display(opt)
+          description_parts << default_info if default_info
+          description_text = description_parts.join(' ')
+          line = "  #{label.ljust(max_label_length)}"
+          line += "  #{description_text}" unless description_text.empty?
+          usage_lines << line
+        end
+      end
+
+      returns = metadata[:returns] || []
+      if returns.any?
+        usage_lines << "" unless usage_lines.last == ""
+        usage_lines << "Return values:"
+        returns.each do |ret|
+          type_label = (ret.types || []).join(" | ")
+          line = "  #{type_label}"
+          line += "  #{ret.description}" if ret.description && !ret.description.empty?
+          usage_lines << line
+        end
+      end
+
+      usage_lines.pop while usage_lines.last == ""
+      usage_block = usage_lines.join("\n")
+
+      sections = []
+      summary_lines = metadata[:summary_lines] || []
+      summary_block = summary_lines.join("\n").rstrip
+      sections << summary_block unless summary_block.empty?
+      sections << usage_block unless usage_block.empty?
+      detail_lines = metadata[:detail_lines] || []
+      detail_block = detail_lines.join("\n").rstrip
+      sections << detail_block unless detail_block.empty?
+
+      sections.join("\n\n")
+    end
+
+    private
+
+    def format_method_parameters(parameters, metadata)
+      option_map = (metadata[:options] || []).each_with_object({}) { |opt, h| h[opt[:keyword]] = opt }
+      positional_map = metadata[:positionals_map] || {}
+
+      parameters.map { |type, name|
+        case type
+        when :req
+          doc = positional_map[name]
+          label = doc&.label || name.to_s.upcase
+          "<#{label}>"
+        when :opt
+          doc = positional_map[name]
+          label = doc&.label || name.to_s.upcase
+          "[<#{label}>]"
+        when :rest then "[<#{name}>...]"
+        when :keyreq
+          opt = option_map[name]
+          if opt
+            if opt.doc_format == :auto_generated
+              auto_generated_option_usage_label(name, opt)
+            else
+              option_flag_with_placeholder(opt)
+            end
+          else
+            "--#{name.to_s.tr('_', '-')}=<value>"
+          end
+        when :key
+          opt = option_map[name]
+          label = if opt
+            if opt.doc_format == :auto_generated
+              auto_generated_option_usage_label(name, opt)
+            else
+              option_flag_with_placeholder(opt)
+            end
+          else
+            "--#{name.to_s.tr('_', '-')}=<value>"
+          end
+          "[#{label}]"
+        when :keyrest then "[--<option>...]"
+        else ""
+        end
+      }.reject(&:empty?).join(" ")
+    end
+
+    def auto_generated_option_usage_label(name, opt)
+      base_flag = "--#{name.to_s.tr('_', '-')}"
+      return base_flag if opt.boolean_flag
+
+      "#{base_flag}=<value>"
+    end
+
+    def ordered_positionals(method, metadata)
+      positional_map = metadata[:positionals_map] || {}
+      method.parameters.each_with_object([]) do |(type, name), memo|
+        next unless %i[req opt].include?(type)
+
+        definition = positional_map[name]
+        label = if definition
+            type == :opt ? "[#{definition.label}]" : definition.label
+          else
+            base = name.to_s.upcase
+            type == :opt ? "[#{base}]" : base
+          end
+        description = definition&.description
+        memo << { label: label, description: description, definition: definition }
+      end
+    end
+
+    def positional_type_display(definition)
+      return nil unless definition
+      return nil if definition.inline_type_annotation
+      return nil if definition.types.nil? || definition.types.empty?
+
+      unique_types = definition.types.reject(&:empty?).uniq
+      return nil if unique_types.empty?
+
+      if definition.respond_to?(:doc_format) && definition.doc_format == :rubycli
+        "[#{unique_types.join(', ')}]"
+      else
+        "(type: #{unique_types.join(' | ')})"
+      end
+    end
+
+    def positional_default_display(definition)
+      return nil unless definition && definition.default_value
+      return nil if definition.default_value.to_s.empty?
+
+      "(default: #{definition.default_value})"
+    end
+
+    def option_flag_with_placeholder(opt)
+      flags = [opt.short, opt.long].compact
+      flags = ["--#{opt.keyword.to_s.tr("_", "-")}"] if flags.empty?
+      flag_label = flags.join(", ")
+      placeholder = option_value_placeholder(opt)
+      if placeholder
+        "#{flag_label} #{placeholder}"
+      else
+        flag_label
+      end
+    end
+
+    def option_value_placeholder(opt)
+      return nil if opt.boolean_flag
+      return opt.value_name if opt.value_name && !opt.value_name.empty?
+
+      first_non_nil_type = opt.types&.find { |type| !nil_type?(type) && !boolean_type?(type) }
+      first_non_nil_type
+    end
+
+    def option_type_display(opt)
+      return nil if opt.inline_type_annotation
+      return nil if opt.types.nil? || opt.types.empty?
+
+      unique_types = opt.types.reject(&:empty?).uniq
+      return nil if unique_types.empty?
+
+      if opt.respond_to?(:doc_format) && opt.doc_format == :rubycli
+        "[#{unique_types.join(', ')}]"
+      else
+        "(type: #{unique_types.join(' | ')})"
+      end
+    end
+
+    def option_default_display(opt)
+      return nil if opt.default_value.nil? || opt.default_value.to_s.empty?
+
+      "(default: #{opt.default_value})"
+    end
+
+    def type_info_first?(definition)
+      definition.respond_to?(:doc_format) && definition.doc_format == :rubycli
+    end
+  end
+end

data/lib/rubycli/json_coercer.rb

@@ -0,0 +1,32 @@
+module Rubycli
+  class JsonCoercer
+    THREAD_KEY = :rubycli_json_mode
+
+    def json_mode?
+      Thread.current[THREAD_KEY] == true
+    end
+
+    def with_json_mode(enabled = true)
+      previous = Thread.current[THREAD_KEY]
+      Thread.current[THREAD_KEY] = enabled
+      yield
+    ensure
+      Thread.current[THREAD_KEY] = previous
+    end
+
+    def coerce_json_value(value)
+      case value
+      when String
+        JSON.parse(value)
+      when Array
+        value.map { |item| coerce_json_value(item) }
+      when Hash
+        value.transform_values { |item| coerce_json_value(item) }
+      else
+        value
+      end
+    rescue JSON::ParserError => e
+      raise Rubycli::ArgumentError, "Failed to parse as JSON: #{e.message}"
+    end
+  end
+end

data/lib/rubycli/result_emitter.rb

@@ -0,0 +1,41 @@
+module Rubycli
+  class ResultEmitter
+    def initialize(environment:)
+      @environment = environment
+    end
+
+    def emit(result)
+      return unless @environment.print_result?
+      return if result.nil?
+      return if result.is_a?(Module) || result.is_a?(Class)
+
+      formatted = format_result_output(result)
+      return if formatted.nil? || (formatted.respond_to?(:empty?) && formatted.empty?)
+
+      puts formatted
+    end
+
+    private
+
+    def format_result_output(result)
+      case result
+      when String
+        result
+      when Numeric, TrueClass, FalseClass
+        result.to_s
+      when Array, Hash
+        JSON.pretty_generate(result)
+      else
+        if result.respond_to?(:to_h)
+          JSON.pretty_generate(result.to_h)
+        elsif result.respond_to?(:to_ary)
+          JSON.pretty_generate(result.to_ary)
+        else
+          result.inspect
+        end
+      end
+    rescue JSON::GeneratorError
+      result.inspect
+    end
+  end
+end

data/lib/rubycli/type_utils.rb

@@ -0,0 +1,128 @@
+module Rubycli
+  module TypeUtils
+    module_function
+
+    def nil_type?(type)
+      %w[nil NilClass].include?(type)
+    end
+
+    def boolean_type?(type)
+      %w[Boolean TrueClass FalseClass].include?(type)
+    end
+
+    def normalize_type_list(types)
+      Array(types).compact.flat_map { |type| normalize_type_token(type) }.map(&:strip).reject(&:empty?).uniq
+    end
+
+    def normalize_type_token(token)
+      trimmed = token.to_s.strip
+      trimmed = trimmed.delete_prefix('@')
+      return '' if trimmed.empty?
+
+      if trimmed.include?('<') && trimmed.end_with?('>')
+        trimmed
+      elsif trimmed.end_with?('[]')
+        base = trimmed[0..-3]
+        base = base.capitalize if base == base.downcase
+        "#{base}[]"
+      else
+        trimmed
+      end
+    end
+
+    def analyze_placeholder(value_placeholder)
+      return { optional: false, list: false, base: nil } unless value_placeholder
+
+      trimmed = value_placeholder.strip
+      optional = trimmed.start_with?('[') && trimmed.end_with?(']')
+      core = optional ? trimmed[1..-2].strip : trimmed.dup
+      sanitized = core.gsub(/\[|\]/, '')
+      sanitized = sanitized.gsub(/\.\.\./, '')
+      list = sanitized.include?(',') || core.include?('...') || core.include?('[,')
+      token = sanitized.split(',').first.to_s.strip
+      token = token.gsub(/[^A-Za-z0-9_]/, '')
+      token = nil if token.empty?
+
+      { optional: optional, list: list, base: token }
+    end
+
+    def infer_types_from_placeholder(types, placeholder_info, include_optional_boolean: true)
+      working = types.dup
+
+      if working.empty?
+        if placeholder_info[:optional]
+          inferred = if placeholder_info[:list]
+                       include_optional_boolean ? ['Boolean', 'String[]'] : ['String[]']
+                     else
+                       include_optional_boolean ? ['Boolean', 'String'] : ['String']
+                     end
+          working.concat(inferred)
+        elsif placeholder_info[:list]
+          working << 'String[]'
+        elsif placeholder_info[:base]
+          working << 'String'
+        end
+      elsif placeholder_info[:optional] && include_optional_boolean
+        working.unshift('Boolean') unless working.any? { |type| boolean_type?(type) }
+      end
+
+      working.uniq
+    end
+
+    def determine_requires_value(value_placeholder:, types:, boolean_flag:, optional_value:)
+      return nil if optional_value
+      return false if boolean_flag
+
+      value_present = !value_placeholder.nil?
+      non_boolean_types = types.reject { |type| boolean_type?(type) || nil_type?(type) }
+
+      if value_present
+        true
+      elsif non_boolean_types.any?
+        true
+      else
+        false
+      end
+    end
+
+    def normalize_long_option(option)
+      return nil unless option
+      option.start_with?('--') ? option : "--#{option.delete_prefix('-')}"
+    end
+
+    def normalize_short_option(option)
+      return nil unless option
+      option.start_with?('-') ? option : "-#{option}"
+    end
+
+    def default_placeholder_for(keyword)
+      keyword.to_s.upcase
+    end
+
+    def parse_list(value)
+      return [] if value.nil?
+
+      value.to_s.split(',').map(&:strip).reject(&:empty?)
+    end
+
+    def convert_boolean(value)
+      return value if [true, false].include?(value)
+
+      str = value.to_s.strip.downcase
+      case str
+      when 'true', 't', 'yes', 'y', '1'
+        true
+      when 'false', 'f', 'no', 'n', '0'
+        false
+      else
+        raise ArgumentError, "Cannot convert to boolean: #{value}"
+      end
+    end
+
+    def boolean_string?(value)
+      return false if value.nil?
+
+      %w[true false t f yes no y n 1 0].include?(value.to_s.strip.downcase)
+    end
+  end
+end

data/lib/rubycli/types.rb

@@ -0,0 +1,16 @@
+module Rubycli
+  OptionDefinition = Struct.new(
+    :keyword, :long, :short, :value_name, :types, :description, :requires_value,
+    :boolean_flag, :optional_value, :default_value, :inline_type_annotation,
+    :inline_type_text, :doc_format,
+    keyword_init: true
+  )
+
+  PositionalDefinition = Struct.new(
+    :placeholder, :label, :types, :description, :param_name, :default_value,
+    :inline_type_annotation, :inline_type_text, :doc_format,
+    keyword_init: true
+  )
+
+  ReturnDefinition = Struct.new(:types, :description, keyword_init: true)
+end

data/lib/rubycli/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Rubycli
+  VERSION = '0.1.1'
+end