rubycli 0.1.4 → 0.1.5

data/lib/rubycli/arguments/value_converter.rb

@@ -15,6 +15,11 @@ module Rubycli
         trimmed = value.strip
         return value if trimmed.empty?
 
+        if symbol_literal?(trimmed)
+          symbol_value = trimmed.delete_prefix(':')
+          return symbol_value.to_sym unless symbol_value.empty?
+        end
+
         if literal_like?(trimmed)
           literal = try_literal_parse(value)
           return literal unless literal.equal?(LITERAL_PARSE_FAILURE)
@@ -33,6 +38,12 @@ module Rubycli
 
       private
 
+      def symbol_literal?(value)
+        return false unless value
+
+        value.start_with?(':') && value.length > 1 && value[1..].match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+      end
+
       def integer_string?(str)
         str =~ /\A-?\d+\z/
       end

data/lib/rubycli/cli.rb

@@ -48,6 +48,9 @@ module Rubycli
       else
         execute_method(entry.method, command, args, cli_mode)
       end
+    rescue Rubycli::ArgumentError => e
+      warn "[ERROR] #{e.message}"
+      1
     end
 
     def available_commands(target)
@@ -113,6 +116,7 @@ module Rubycli
       method = target.method(:call)
       pos_args, kw_args = @argument_parser.parse(args, method)
       Rubycli.apply_argument_coercions(pos_args, kw_args)
+      @argument_parser.validate_inputs(method, pos_args, kw_args)
       begin
         result = Rubycli.call_target(target, pos_args, kw_args)
         @result_emitter.emit(result)
@@ -151,11 +155,11 @@ module Rubycli
     def execute_method_with_params(method_obj, command, args, cli_mode)
       pos_args, kw_args = @argument_parser.parse(args, method_obj)
       Rubycli.apply_argument_coercions(pos_args, kw_args)
-
       if should_show_method_help?(pos_args, kw_args)
         puts usage_for_method(command, method_obj)
         return 0
       end
+      @argument_parser.validate_inputs(method_obj, pos_args, kw_args)
 
       begin
         result = Rubycli.call_target(method_obj, pos_args, kw_args)

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|-j | --eval-args|-e | --eval-lax|-E] <target-path> [<class-or-module>] [-- <cli-args>...]
+      Usage: rubycli [--new|-n] [--pre-script=<src>] [--json-args|-j | --eval-args|-e | --eval-lax|-E] [--strict] [--check|-c] <target-path> [<class-or-module>] [-- <cli-args>...]
 
       Examples:
         rubycli scripts/sample_runner.rb echo --message hello
@@ -17,6 +17,8 @@ module Rubycli
         --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
+        --strict             Enforce documented input types/choices (invalid values abort)
+        --check, -c          Validate documentation/comments without executing commands
         (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.)
 
@@ -42,6 +44,7 @@ module Rubycli
       eval_mode = false
       eval_lax_mode = false
       constant_mode = nil
+      check_mode = false
       pre_script_sources = []
 
       loop do
@@ -64,7 +67,7 @@ module Rubycli
           flag = args.shift
           src = args.shift
           unless src
-            warn "#{flag} requires a file path or inline Ruby code"
+            warn "[ERROR] #{flag} requires a file path or inline Ruby code"
             return 1
           end
           context = File.file?(src) ? File.expand_path(src) : "(inline #{flag})"
@@ -79,8 +82,19 @@ module Rubycli
           eval_mode = true
           eval_lax_mode = true
           args.shift
+        when '--strict'
+          Rubycli.environment.enable_strict_input!
+          args.shift
+        when '--check', '-c'
+          check_mode = true
+          Rubycli.environment.enable_doc_check!
+          args.shift
         when '--print-result'
-         args.shift
+          args.shift
+        when '--debug'
+          args.shift
+          warn "[ERROR] --debug flag has been removed; set RUBYCLI_DEBUG=true instead."
+          return 1
         when '--auto-target', '-a'
           constant_mode = :auto
           args.shift
@@ -106,10 +120,32 @@ module Rubycli
       args.shift if args.first == '--'
 
       if json_mode && eval_mode
-        warn '--json-args cannot be combined with --eval-args or --eval-lax'
+        warn '[ERROR] --json-args cannot be combined with --eval-args or --eval-lax'
+        return 1
+      end
+
+      if check_mode && (json_mode || eval_mode)
+        warn '[ERROR] --check cannot be combined with --json-args or --eval-args'
         return 1
       end
 
+      if check_mode && !args.empty?
+        warn '[ERROR] --check does not accept command arguments'
+        return 1
+      end
+
+      Rubycli.environment.clear_documentation_issues!
+
+      if check_mode
+        return Rubycli::Runner.check(
+          target_path,
+          class_or_module,
+          new: new_flag,
+          pre_scripts: pre_script_sources,
+          constant_mode: constant_mode
+        )
+      end
+
       Rubycli::Runner.execute(
         target_path,
         class_or_module,
@@ -124,10 +160,10 @@ module Rubycli
 
       0
     rescue Rubycli::Runner::PreScriptError => e
-      warn e.message
+      warn "[ERROR] #{e.message}"
       1
     rescue Rubycli::Runner::Error => e
-      warn e.message
+      warn "[ERROR] #{e.message}"
       1
     end
   end

data/lib/rubycli/documentation/metadata_parser.rb

@@ -122,7 +122,7 @@ module Rubycli
             file: source_file,
             line: line_number
           )
-          return nil if @environment.strict_mode?
+          return nil if @environment.doc_check_mode?
         end
 
         pattern = /\A@param\s+([a-zA-Z0-9_]+)(?:\s+\[([^\]]+)\])?(?:\s+\(([^)]+)\))?(?:\s+(.*))?\z/
@@ -130,12 +130,14 @@ module Rubycli
         return nil unless match
 
         param_name = match[1]
+        param_symbol = param_name.to_sym
         type_str = match[2]
         option_tokens = combine_bracketed_tokens(match[3]&.split(/\s+/) || [])
         description = match[4]&.strip
         description = nil if description&.empty?
 
-        types = parse_type_annotation(type_str)
+        raw_types = parse_type_annotation(type_str)
+        types, allowed_values = partition_type_tokens(raw_types)
 
         long_option = nil
         short_option = nil
@@ -179,23 +181,36 @@ module Rubycli
         end
 
         long_option ||= "--#{param_name.tr('_', '-')}"
+        role = parameter_role(method_obj, param_symbol)
+        if value_name.nil?
+          if role == :positional
+            value_name = default_placeholder_for(param_symbol)
+          elsif !types&.any? { |entry| boolean_type?(entry) }
+            # Most keywords expect a value; boolean flags should be documented with [Boolean].
+            value_name = default_placeholder_for(param_symbol)
+          end
+        end
 
-        types = parse_type_annotation(type_token) if (types.nil? || types.empty?) && type_token
+        if (types.nil? || types.empty?) && type_token
+          inline_raw_types = parse_type_annotation(type_token)
+          inline_types, inline_allowed = partition_type_tokens(inline_raw_types)
+          types = inline_types
+          allowed_values = merge_allowed_values(allowed_values, inline_allowed)
+        end
 
+        # TODO: Derive primitive types from Ruby default values when explicit hints are absent.
         option_def = build_option_definition(
-          param_name.to_sym,
+          param_symbol,
           long_option,
           short_option,
           value_name,
           types,
           description,
           inline_type_annotation: !type_token.nil?,
-          doc_format: :tagged_param
+          doc_format: :tagged_param,
+          allowed_values: allowed_values
         )
 
-        param_symbol = param_name.to_sym
-        role = parameter_role(method_obj, param_symbol)
-
         if role == :positional
           placeholder = option_def.value_name || default_placeholder_for(option_def.keyword)
           return PositionalDefinition.new(
@@ -204,7 +219,8 @@ module Rubycli
             types: option_def.types,
             description: option_def.description,
             param_name: param_symbol,
-            doc_format: option_def.doc_format
+            doc_format: option_def.doc_format,
+            allowed_values: option_def.allowed_values
           )
         elsif role == :keyword
           return option_def
@@ -218,7 +234,8 @@ module Rubycli
             types: option_def.types,
             description: option_def.description,
             param_name: param_symbol,
-            doc_format: option_def.doc_format
+            doc_format: option_def.doc_format,
+            allowed_values: option_def.allowed_values
           )
         end
 
@@ -291,7 +308,8 @@ module Rubycli
 
         description = description_tokens.join(' ').strip
         description = nil if description.empty?
-        types = parse_type_annotation(type_token)
+        raw_types = parse_type_annotation(type_token)
+        types, allowed_values = partition_type_tokens(raw_types)
 
         keyword = long_option.delete_prefix('--').tr('-', '_').to_sym
         return nil unless method_accepts_keyword?(method_obj, keyword)
@@ -304,7 +322,8 @@ module Rubycli
           types,
           description,
           inline_type_annotation: !type_token.nil?,
-          doc_format: :rubycli
+          doc_format: :rubycli,
+          allowed_values: allowed_values
         )
       end
 
@@ -326,7 +345,8 @@ module Rubycli
         description = tokens.join(' ').strip
         description = nil if description.empty?
 
-        types = parse_type_annotation(type_token)
+        raw_types = parse_type_annotation(type_token)
+        types, allowed_values = partition_type_tokens(raw_types)
         placeholder_info = analyze_placeholder(placeholder)
         inferred_types = infer_types_from_placeholder(
           normalize_type_list(types),
@@ -346,7 +366,8 @@ module Rubycli
           description: description,
           inline_type_annotation: inline_annotation,
           inline_type_text: inline_text,
-          doc_format: :rubycli
+          doc_format: :rubycli,
+          allowed_values: allowed_values
         )
       end
 
@@ -493,16 +514,18 @@ module Rubycli
                 file: source_file,
                 line: line_for_comment
               )
-              unless @environment.strict_mode?
+              unless @environment.doc_check_mode?
                 fallback = PositionalDefinition.new(
                   placeholder: name.to_s,
                   label: name.to_s.upcase,
-                  types: [],
+                  types: ['String'],
                   description: nil,
                   param_name: name,
                   default_value: defaults[name],
                   inline_type_annotation: false,
-                  inline_type_text: nil
+                  inline_type_text: nil,
+                  doc_format: :auto_generated,
+                  allowed_values: []
                 )
                 metadata[:positionals] << fallback
                 positional_map[name] = fallback
@@ -517,7 +540,7 @@ module Rubycli
                 file: source_file,
                 line: line_for_comment
               )
-              unless @environment.strict_mode?
+              unless @environment.doc_check_mode?
                 fallback_option = build_auto_option_definition(name)
                 ordered_options << fallback_option if fallback_option
               end
@@ -558,6 +581,11 @@ module Rubycli
                 opt.value_name = nil
                 opt.types = ['Boolean']
               end
+            elsif opt.boolean_flag
+              opt.boolean_flag = false
+              opt.requires_value = true
+              opt.value_name ||= default_placeholder_for(opt.keyword)
+              opt.types = ['String'] if opt.types.nil? || opt.types.empty?
             end
           end
         end
@@ -616,6 +644,98 @@ module Rubycli
         cleaned.split(/[,|]/).map { |token| normalize_type_token(token) }.reject(&:empty?)
       end
 
+      def partition_type_tokens(tokens)
+        normalized = Array(tokens).dup
+        allowed = []
+
+        normalized.each do |token|
+          expand_annotation_token(token).each do |expanded|
+            literal_entry = literal_entry_from_token(expanded)
+            allowed << literal_entry if literal_entry
+          end
+        end
+
+        [normalized, allowed.compact.uniq]
+      end
+
+      def merge_allowed_values(primary, additional)
+        return Array(additional) if primary.nil? || primary.empty?
+        return Array(primary) if additional.nil? || additional.empty?
+
+        (primary + additional).uniq
+      end
+
+      def expand_annotation_token(token)
+        return [] unless token
+
+        stripped = token.strip
+        return [] if stripped.empty?
+
+        if stripped.start_with?('%i[') && stripped.end_with?(']')
+          inner = stripped[3..-2]
+          inner.split(/\s+/).map { |entry| ":#{entry}" }
+        elsif stripped.start_with?('%I[') && stripped.end_with?(']')
+          inner = stripped[3..-2]
+          inner.split(/\s+/).map { |entry| ":#{entry}" }
+        elsif stripped.start_with?('%w[') && stripped.end_with?(']')
+          inner = stripped[3..-2]
+          inner.split(/\s+/)
+        elsif stripped.start_with?('%W[') && stripped.end_with?(']')
+          inner = stripped[3..-2]
+          inner.split(/\s+/)
+        else
+          [stripped]
+        end
+      end
+
+      def literal_entry_from_token(token)
+        return nil unless token
+
+        stripped = token.strip
+        return nil if stripped.empty?
+        stripped = stripped[1..] if stripped.start_with?('[') && !stripped.end_with?(']')
+        if stripped.end_with?(']') && !stripped.include?('[')
+          stripped = stripped[0...-1]
+        end
+
+        lowered = stripped.downcase
+        return { kind: :literal, value: nil } if %w[nil null ~].include?(lowered)
+        return { kind: :literal, value: true } if lowered == 'true'
+        return { kind: :literal, value: false } if lowered == 'false'
+
+        if stripped.start_with?(':')
+          sym_name = stripped[1..]
+          return nil if sym_name.nil? || sym_name.empty?
+
+          return { kind: :literal, value: sym_name.to_sym }
+        end
+
+        if stripped.start_with?('"') && stripped.end_with?('"') && stripped.length >= 2
+          return { kind: :literal, value: stripped[1..-2] }
+        end
+
+        if stripped.start_with?("'") && stripped.end_with?("'") && stripped.length >= 2
+          return { kind: :literal, value: stripped[1..-2] }
+        end
+
+        if stripped.match?(/\A-?\d+\z/)
+          return { kind: :literal, value: Integer(stripped) }
+        end
+
+        if stripped.match?(/\A-?\d+\.\d+\z/)
+          return { kind: :literal, value: Float(stripped) }
+        end
+
+        if stripped.match?(/\A[a-z0-9._-]+\z/)
+          return { kind: :literal, value: stripped }
+        end
+
+        nil
+      rescue ArgumentError
+        nil
+      end
+
+
       def placeholder_token?(token)
         return false unless token
 
@@ -652,11 +772,15 @@ module Rubycli
         return false if stripped.empty?
 
         return true if stripped.start_with?('@')
+        return true if stripped.start_with?('%')
+        return true if stripped.include?('::')
+        return true if stripped.start_with?('(') && stripped.end_with?(')')
+        return true if stripped.include?('[') && stripped.include?(']')
 
-        parsed = parse_type_annotation(stripped)
-        return false if parsed.empty?
+        normalized = normalize_type_token(stripped)
+        return false if normalized.empty?
 
-        parsed.all? { |entry| inline_type_hint?(entry) }
+        INLINE_TYPE_HINTS.include?(normalized)
       end
 
       def known_type_token?(token)
@@ -723,6 +847,9 @@ module Rubycli
           elsif token.start_with?('(') && !token.include?(')')
             buffer = token.dup
             closing = ')'
+          elsif token.start_with?('%') && token.include?('[') && !token.include?(']')
+            buffer = token.dup
+            closing = ']'
           else
             combined << token
           end
@@ -755,7 +882,8 @@ module Rubycli
         types,
         description,
         inline_type_annotation: false,
-        doc_format: nil
+        doc_format: nil,
+        allowed_values: nil
       )
         normalized_long = normalize_long_option(long_option)
         normalized_short = normalize_short_option(short_option)
@@ -800,10 +928,15 @@ module Rubycli
           optional_value: optional_value,
           inline_type_annotation: inline_type_annotation,
           inline_type_text: inline_type_text,
-          doc_format: doc_format
+          doc_format: doc_format,
+          allowed_values: normalize_allowed_values(allowed_values)
         )
       end
 
+      def normalize_allowed_values(values)
+        Array(values).compact.uniq
+      end
+
       def build_auto_option_definition(keyword)
         long_option = "--#{keyword.to_s.tr('_', '-')}"
         placeholder = default_placeholder_for(keyword)
@@ -815,7 +948,8 @@ module Rubycli
           [],
           nil,
           inline_type_annotation: false,
-          doc_format: :auto_generated
+          doc_format: :auto_generated,
+          allowed_values: []
         )
       end
 
@@ -830,7 +964,8 @@ module Rubycli
           default_value: option.default_value,
           inline_type_annotation: option.inline_type_annotation,
           inline_type_text: option.inline_type_text,
-          doc_format: option.doc_format
+          doc_format: option.doc_format,
+          allowed_values: option.allowed_values
         )
       end
     end

data/lib/rubycli/documentation_registry.rb

@@ -20,7 +20,7 @@ module Rubycli
       location = method_obj.source_location
       return empty_metadata unless location
 
-      cache_key = [location[0], location[1], @environment.strict_mode?, @environment.allow_param_comments?]
+      cache_key = [location[0], location[1], @environment.doc_check_mode?, @environment.allow_param_comments?]
       return deep_dup(@metadata_cache[cache_key]) if @metadata_cache.key?(cache_key)
 
       comment_lines = @comment_extractor.extract(location[0], location[1])

data/lib/rubycli/environment.rb

@@ -6,6 +6,9 @@ module Rubycli
       @argv = argv
       @debug = env['RUBYCLI_DEBUG'] == 'true'
       @print_result = env['RUBYCLI_PRINT_RESULT'] == 'true'
+      @doc_check_mode = false
+      @strict_input = false
+      @documentation_issues = []
       scrub_argv_flags!
     end
 
@@ -17,16 +20,39 @@ module Rubycli
       @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)
     end
 
+    def enable_doc_check!
+      @doc_check_mode = true
+    end
+
+    def doc_check_mode?
+      @doc_check_mode
+    end
+
+    def disable_doc_check!
+      @doc_check_mode = false
+    end
+
+    def enable_strict_input!
+      @strict_input = true
+    end
+
+    def strict_input?
+      @strict_input
+    end
+
+    def documentation_issues
+      @documentation_issues.dup
+    end
+
+    def clear_documentation_issues!
+      @documentation_issues.clear
+    end
+
     def constant_resolution_mode
       value = fetch_env_value('RUBYCLI_AUTO_TARGET', 'strict')
       return :auto if %w[auto on true yes 1].include?(value)
@@ -49,7 +75,17 @@ module Rubycli
         message
       end
 
-      warn "[WARN] Rubycli documentation mismatch: #{formatted_message}" if strict_mode?
+      entry = { message: formatted_message, location: location }
+      @documentation_issues << entry
+      warn "[WARN] Rubycli documentation mismatch: #{formatted_message}" if doc_check_mode?
+    end
+
+    def handle_input_violation(message)
+      if strict_input?
+        raise Rubycli::ArgumentError, message
+      else
+        warn "[WARN] #{message} (use --strict to abort on invalid input)"
+      end
     end
 
     def enable_print_result!
@@ -65,7 +101,6 @@ module Rubycli
     def scrub_argv_flags!
       return unless @argv
 
-      remove_all_flags!(@argv, '--debug') { @debug = true }
       remove_all_flags!(@argv, '--print-result') { @print_result = true }
     end
 

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