rubycli 0.1.4 → 0.1.6

data/lib/rubycli/eval_coercer.rb

@@ -47,7 +47,7 @@ module Rubycli
       EVAL_BINDING.eval(trimmed)
     rescue SyntaxError, NameError => e
       if eval_lax_mode?
-        warn "[rubycli] Failed to evaluate argument as Ruby (#{e.message.strip}). Passing it through because --eval-lax is enabled."
+        warn "[WARN] Failed to evaluate argument as Ruby (#{e.message.strip}). Passing it through because --eval-lax is enabled."
         expression
       else
         raise

data/lib/rubycli/help_renderer.rb

@@ -45,7 +45,6 @@ module Rubycli
 
       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)
@@ -152,10 +151,10 @@ module Rubycli
     end
 
     def render_positionals(positionals_in_order)
-      rows = positionals_in_order.map do |info|
+        rows = positionals_in_order.map do |info|
         definition = info[:definition]
         label = info[:label]
-        type = formatted_types(definition&.types)
+        type = type_display(definition)
         requirement = positional_requirement(info[:kind])
         description_parts = []
         description_parts << info[:description] if info[:description]
@@ -169,7 +168,7 @@ module Rubycli
     def render_options(options, required_keywords)
       rows = options.map do |opt|
         label = option_flag_with_placeholder(opt)
-        type = formatted_types(opt.types)
+        type = type_display(opt)
         requirement = required_keywords.include?(opt.keyword) ? 'required' : 'optional'
         description_parts = []
         description_parts << opt.description if opt.description
@@ -198,10 +197,53 @@ module Rubycli
     end
 
     def formatted_types(types)
-      type_list = Array(types).compact.map(&:to_s).reject(&:empty?).uniq
+      type_list = Array(types).compact.map { |token| token.to_s.strip }.reject(&:empty?)
+      type_list = type_list.each_with_object([]) do |token, acc|
+        acc << token unless acc.include?(token)
+      end
       return '' if type_list.empty?
 
-      "[#{type_list.join(', ')}]"
+      nil_tokens, rest = type_list.partition { |token| token.casecmp('nil').zero? }
+      ordered = rest + nil_tokens
+      "[#{ordered.join(', ')}]"
+    end
+
+    def type_display(definition)
+      return formatted_types(definition&.types) unless definition
+
+      literal_entries = Array(definition.allowed_values).map { |entry| format_allowed_value(entry[:value]) }
+      type_tokens = Array(definition.types).map { |token| token.to_s.strip }.reject(&:empty?)
+      type_tokens.reject! { |token| literal_token?(token) }
+
+      combined = (literal_entries + type_tokens).uniq
+      return formatted_types(definition.types) if combined.empty?
+
+      "[#{combined.join(', ')}]"
+    end
+
+    def format_allowed_value(value)
+      case value
+      when Symbol
+        ":#{value}"
+      when String
+        %("#{value}")
+      when Integer, Float
+        value.to_s
+      when TrueClass, FalseClass
+        value.to_s
+      when NilClass
+        'nil'
+      else
+        value.inspect
+      end
+    end
+
+    def literal_token?(token)
+      return true if token.start_with?('%')
+      return true if token.include?('[')
+      return true if token.start_with?(':')
+
+      false
     end
 
     def positional_requirement(kind)
@@ -268,19 +310,25 @@ module Rubycli
     end
 
     def required_placeholder(placeholder, definition, name)
-      return placeholder.strip unless placeholder.nil? || placeholder.strip.empty?
+      unless placeholder.nil? || placeholder.strip.empty? || auto_generated_placeholder?(placeholder, definition, name)
+        return placeholder.strip
+      end
 
       default_positional_label(definition, name, uppercase: true)
     end
 
     def optional_placeholder(placeholder, definition, name)
-      return placeholder.strip unless placeholder.nil? || placeholder.strip.empty?
+      unless placeholder.nil? || placeholder.strip.empty? || auto_generated_placeholder?(placeholder, definition, name)
+        return placeholder.strip
+      end
 
       "[#{default_positional_label(definition, name, uppercase: true)}]"
     end
 
     def rest_placeholder(placeholder, definition, name)
-      return placeholder.strip unless placeholder.nil? || placeholder.strip.empty?
+      unless placeholder.nil? || placeholder.strip.empty? || auto_generated_placeholder?(placeholder, definition, name)
+        return placeholder.strip
+      end
 
       base = default_positional_label(definition, name, uppercase: true)
       "[#{base}...]"
@@ -320,6 +368,13 @@ module Rubycli
       first_non_nil_type
     end
 
+    def auto_generated_placeholder?(placeholder, definition, name)
+      return false unless definition
+      return false unless definition.respond_to?(:doc_format) && definition.doc_format == :auto_generated
+
+      placeholder.strip.casecmp(name.to_s).zero?
+    end
+
     def ensure_angle_bracket_placeholder(placeholder)
       raw = placeholder.to_s.strip
       return raw if raw.empty?

data/lib/rubycli/types.rb

@@ -2,13 +2,13 @@ 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,
+    :inline_type_text, :doc_format, :allowed_values,
     keyword_init: true
   )
 
   PositionalDefinition = Struct.new(
     :placeholder, :label, :types, :description, :param_name, :default_value,
-    :inline_type_annotation, :inline_type_text, :doc_format,
+    :inline_type_annotation, :inline_type_text, :doc_format, :allowed_values,
     keyword_init: true
   )
 

data/lib/rubycli/version.rb

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

data/lib/rubycli.rb

@@ -216,37 +216,21 @@ module Rubycli
       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 cannot be combined with --eval-args or --eval-lax'
       end
 
-      full_path = find_target_path(target_path)
-      capture = Rubycli.constant_capture
-      capture.capture(full_path) { load full_path }
-      $PROGRAM_NAME = File.basename(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
-      runner_target = new ? instantiate_target(target) : target
-      runner_target = apply_pre_scripts(pre_scripts, target, runner_target)
+      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
+      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)
@@ -255,6 +239,53 @@ module Rubycli
       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)
@@ -342,6 +373,41 @@ module Rubycli
       end
     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
+
+      runner_target = new ? instantiate_target(target) : 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|
@@ -465,19 +531,24 @@ module Rubycli
 
     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
+      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}"
+        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."
+        lines << 'Rubycli could not detect any publicly exposable constants in this file.'
       end
 
-      lines << "  #{details}" if details
+      if details
+        lines << ''
+        lines << details
+      end
 
-      lines << "  Ensure the CLASS_OR_MODULE argument is correct when invoking the CLI."
+      lines << ''
+      lines << 'Hint: Ensure the CLASS_OR_MODULE argument is correct when invoking the CLI.'
       lines.join("\n")
     end
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rubycli
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - inakaegg
 bindir: exe
 cert_chain: []
-date: 2025-11-07 00:00:00.000000000 Z
+date: 2025-11-11 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