rubycli 0.1.6 → 0.2.0

data/lib/rubycli/documentation/metadata_parser.rb

@@ -32,11 +32,12 @@ module Rubycli
         summary_display_lines = []
         detail_lines = []
         summary_phase = true
+        deferred_positional = nil
 
         comment_lines.each do |content|
           stripped = content.strip
           if summary_phase && stripped.empty?
-            summary_display_lines << ""
+            summary_display_lines << ''
             next
           end
 
@@ -69,7 +70,14 @@ module Rubycli
           end
 
           if (positional = parse_positional_line(stripped, method_obj))
-            metadata[:positionals] << positional
+            # An untyped uppercase line opening a doc block ("JSON output
+            # formatter for reports.") reads exactly like a placeholder. Hold on
+            # to it and decide once the whole block is known.
+            if summary_phase && deferred_positional.nil? && !positional.inline_type_annotation
+              deferred_positional = { content: content, stripped: stripped, definition: positional }
+            else
+              metadata[:positionals] << positional
+            end
             summary_phase = false
             next
           end
@@ -81,6 +89,15 @@ module Rubycli
           end
         end
 
+        if deferred_positional
+          if positional_documentation_needed?(method_obj, metadata[:positionals].size)
+            metadata[:positionals].unshift(deferred_positional[:definition])
+          else
+            summary_display_lines << deferred_positional[:content].rstrip
+            summary_compact_lines << deferred_positional[:stripped]
+          end
+        end
+
         summary_text = summary_compact_lines.join(' ')
         summary_text = nil if summary_text.empty?
         metadata[:summary] = summary_text
@@ -93,6 +110,15 @@ module Rubycli
         metadata
       end
 
+      # True while the documented placeholders do not yet cover every positional
+      # parameter, which is what tells a real placeholder line from prose.
+      def positional_documentation_needed?(method_obj, documented_count)
+        return true unless method_obj.respond_to?(:parameters)
+
+        positional_count = method_obj.parameters.count { |type, _| %i[req opt rest].include?(type) }
+        documented_count < positional_count
+      end
+
       def trim_blank_edges(lines)
         return [] if lines.nil? || lines.empty?
 
@@ -108,15 +134,13 @@ module Rubycli
       def parse_tagged_param_line(line, method_obj)
         return nil unless line.start_with?('@param')
 
-        source_file = nil
+        nil
         source_line = nil
-        if method_obj.respond_to?(:source_location)
-          source_file, source_line = method_obj.source_location
-        end
+        _, source_line = method_obj.source_location if method_obj.respond_to?(:source_location)
         line_number = source_line ? [source_line - 1, 1].max : nil
 
         unless @environment.allow_param_comments?
-          source_file, source_line = method_obj.source_location
+          source_file, = method_obj.source_location
           @environment.handle_documentation_issue(
             '@param notation is disabled. Enable it via ENV RUBYCLI_ALLOW_PARAM_COMMENT=ON.',
             file: source_file,
@@ -134,7 +158,7 @@ module Rubycli
         type_str = match[2]
         option_tokens = combine_bracketed_tokens(match[3]&.split(/\s+/) || [])
         description = match[4]&.strip
-        description = nil if description&.empty?
+        description = nil if description && description.empty?
 
         raw_types = parse_type_annotation(type_str)
         audit_type_annotation_tokens(raw_types, method_obj)
@@ -248,13 +272,13 @@ module Rubycli
         return nil unless line.start_with?('--') || line.start_with?('-')
 
         raw_tokens = combine_bracketed_tokens(line.split(/\s+/))
-        tokens = raw_tokens.flat_map { |token|
+        tokens = raw_tokens.flat_map do |token|
           if token.include?('/') && !token.start_with?('[')
             token.split('/')
           else
             [token]
           end
-        }
+        end
 
         long_option = nil
         short_option = nil
@@ -341,9 +365,13 @@ module Rubycli
         return nil unless placeholder_token?(clean_placeholder)
 
         type_token = nil
-        if tokens.first && type_token_candidate?(tokens.first)
-          type_token = tokens.shift
-        end
+        type_token = tokens.shift if tokens.first && type_token_candidate?(tokens.first)
+
+        # Summaries such as "A command that ..." or "I keep ..." start with an
+        # all-uppercase single letter and would otherwise take over the first
+        # positional argument. Require a type annotation to use one as a
+        # placeholder; "A [String] ..." keeps working.
+        return nil if type_token.nil? && clean_placeholder.match?(/\A[A-Z]\z/)
 
         description = tokens.join(' ').strip
         description = nil if description.empty?
@@ -392,14 +420,14 @@ module Rubycli
           return ReturnDefinition.new(types: types, description: description)
         end
 
-        if line.start_with?('return ')
-          stripped = line.sub(/\Areturn\s+/, '')
-          type_token, description = stripped.split(/\s+/, 2)
-          types = parse_type_annotation(type_token)
-          audit_type_annotation_tokens(types, method_obj)
-          description = description&.strip
-          return ReturnDefinition.new(types: types, description: description)
-        end
+        return unless line.start_with?('return ')
+
+        stripped = line.sub(/\Areturn\s+/, '')
+        type_token, description = stripped.split(/\s+/, 2)
+        types = parse_type_annotation(type_token)
+        audit_type_annotation_tokens(types, method_obj)
+        description = description&.strip
+        ReturnDefinition.new(types: types, description: description)
       end
 
       def doc_issue_location(method_obj)
@@ -437,11 +465,10 @@ module Rubycli
         end
 
         literal_entry = literal_entry_from_token(normalized)
-        if literal_entry
-          return
-        end
+        return if literal_entry
 
-        if literal_context && literal_token_candidate?(normalized, include_uppercase: true) && !known_type_token?(normalized)
+        if literal_context && literal_token_candidate?(normalized,
+                                                       include_uppercase: true) && !known_type_token?(normalized)
           warn_unknown_allowed_value(normalized, source_file, line_number)
           return
         end
@@ -478,6 +505,7 @@ module Rubycli
           line = lines[index]
           signature << line
           break if balanced_signature?(signature)
+
           index += 1
         end
 
@@ -520,12 +548,13 @@ module Rubycli
 
       def extract_params_from_signature(signature)
         return nil unless (def_match = signature.match(/\bdef\b\s+[^(\s]+\s*(\((.*)\))?/m))
+
         if def_match[1]
-          inner = def_match[1][1..-2]
-          inner
+          def_match[1][1..-2]
+
         else
           signature_after_def = signature.sub(/.*\bdef\b\s+[^(\s]+\s*/m, '')
-          signature_after_def.split(/\n/).first&.strip
+          signature_after_def.split("\n").first&.strip
         end
       end
 
@@ -564,18 +593,16 @@ module Rubycli
 
         source_file = nil
         source_line = nil
-        if method_obj.respond_to?(:source_location)
-          source_file, source_line = method_obj.source_location
-        end
+        source_file, source_line = method_obj.source_location if method_obj.respond_to?(:source_location)
         line_for_comment = source_line ? [source_line - 1, 1].max : nil
 
         method_obj.parameters.each do |type, name|
           case type
-          when :req, :opt
-            doc = positional_defs.shift
+          when :req, :opt, :rest
+            doc = take_positional_definition(positional_defs, name)
             if doc
               doc.param_name = name
-              doc.default_value = defaults[name]
+              doc.default_value = type == :rest ? [] : defaults[name]
               positional_map[name] = doc
             else
               @environment.handle_documentation_issue(
@@ -587,10 +614,10 @@ module Rubycli
                 fallback = PositionalDefinition.new(
                   placeholder: name.to_s,
                   label: name.to_s.upcase,
-                  types: ['String'],
+                  types: [type == :rest ? 'String[]' : 'String'],
                   description: nil,
                   param_name: name,
-                  default_value: defaults[name],
+                  default_value: type == :rest ? [] : defaults[name],
                   inline_type_annotation: false,
                   inline_type_text: nil,
                   doc_format: :auto_generated,
@@ -641,25 +668,46 @@ module Rubycli
         metadata[:positionals_map] = positional_map
 
         metadata[:options].each do |opt|
-          if defaults.key?(opt.keyword)
-            opt.default_value = defaults[opt.keyword]
-            if TypeUtils.boolean_string?(opt.default_value)
-              opt.boolean_flag = true
-              opt.requires_value = false
-              if opt.doc_format == :auto_generated
-                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?
+          next unless defaults.key?(opt.keyword)
+
+          opt.default_value = defaults[opt.keyword]
+          if boolean_default?(opt.default_value)
+            opt.boolean_flag = true
+            opt.requires_value = false
+            if opt.doc_format == :auto_generated
+              opt.value_name = nil
+              opt.types = ['Boolean']
             end
+          elsif opt.boolean_flag && !TypeUtils.boolean_string?(opt.default_value)
+            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
 
+      # Only a literal true/false default turns an option into a boolean flag.
+      # Values such as 0/1 are truthy for TypeUtils.boolean_string?, but they are
+      # ordinary defaults for numeric options, so they must keep accepting a value.
+      def boolean_default?(default_value)
+        return true if [true, false].include?(default_value)
+
+        %w[true false].include?(default_value.to_s.strip.downcase)
+      end
+
+      def take_positional_definition(positional_defs, parameter_name)
+        tagged_index = positional_defs.index do |definition|
+          definition.doc_format == :tagged_param && definition.param_name == parameter_name
+        end
+        return positional_defs.delete_at(tagged_index) if tagged_index
+
+        tagless_index = positional_defs.index { |definition| definition.doc_format != :tagged_param }
+        return positional_defs.delete_at(tagless_index) if tagless_index
+
+        nil
+      end
+
       def detail_line_for_extra_positional(doc)
         return nil unless doc
 
@@ -669,9 +717,7 @@ module Rubycli
         parts << placeholder unless placeholder.empty?
 
         type_text = doc.inline_type_text
-        if (!type_text || type_text.empty?) && doc.types && !doc.types.empty?
-          type_text = "[#{doc.types.join(', ')}]"
-        end
+        type_text = "[#{doc.types.join(', ')}]" if (!type_text || type_text.empty?) && doc.types && !doc.types.empty?
         parts << type_text if type_text && !type_text.empty?
 
         description = doc.description.to_s.strip
@@ -762,10 +808,9 @@ module Rubycli
 
         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
+        stripped = stripped[0...-1] if stripped.end_with?(']') && !stripped.include?('[')
 
         lowered = stripped.downcase
         return { kind: :literal, value: nil } if %w[nil null ~].include?(lowered)
@@ -787,17 +832,11 @@ module Rubycli
           return { kind: :literal, value: stripped[1..-2] }
         end
 
-        if stripped.match?(/\A-?\d+\z/)
-          return { kind: :literal, value: Integer(stripped) }
-        end
+        return { kind: :literal, value: Integer(stripped) } if stripped.match?(/\A-?\d+\z/)
 
-        if stripped.match?(/\A-?\d+\.\d+\z/)
-          return { kind: :literal, value: Float(stripped) }
-        end
+        return { kind: :literal, value: Float(stripped) } if stripped.match?(/\A-?\d+\.\d+\z/)
 
-        if stripped.match?(/\A[a-z0-9._-]+\z/)
-          return { kind: :literal, value: stripped }
-        end
+        return { kind: :literal, value: stripped } if stripped.match?(/\A[a-z0-9._-]+\z/)
 
         nil
       rescue ArgumentError
@@ -873,6 +912,8 @@ module Rubycli
       end
 
       def type_dictionary
+        return @type_dictionary if defined?(@type_dictionary) && @type_dictionary
+
         builtins = (INLINE_TYPE_HINTS + %w[NilClass Fixnum Decimal Struct]).uniq
         constant_names = []
         begin
@@ -888,9 +929,12 @@ module Rubycli
           constant_names = Object.constants.map(&:to_s)
         end
 
-        (builtins + constant_names).map(&:to_s).map(&:strip).reject(&:empty?).uniq
+        @type_dictionary = (builtins + constant_names).map(&:to_s).map(&:strip).reject(&:empty?).uniq
       end
 
+      def reset_type_dictionary_cache!
+        @type_dictionary = nil
+      end
 
       def placeholder_token?(token)
         return false unless token
@@ -902,7 +946,7 @@ module Rubycli
         candidate = candidate[1..-2].strip if optional
         return false if candidate.empty?
 
-        candidate = candidate.gsub(/[,\|]/, '')
+        candidate = candidate.gsub(/[,|]/, '')
         return false if candidate.empty?
 
         ellipsis = candidate.end_with?('...')
@@ -984,8 +1028,6 @@ module Rubycli
           stripped[0..-3]
         elsif stripped.start_with?('Array<') && stripped.end_with?('>')
           stripped[6..-2].strip
-        else
-          nil
         end
       end
 
@@ -1099,16 +1141,14 @@ module Rubycli
         normalized_long = normalize_long_option(long_option)
         normalized_short = normalize_short_option(short_option)
         value_placeholder = value_name&.strip
-        value_placeholder = nil if value_placeholder&.empty?
+        value_placeholder = nil if value_placeholder && value_placeholder.empty?
         description_text = description&.strip
-        description_text = nil if description_text&.empty?
+        description_text = nil if description_text && description_text.empty?
 
         placeholder_info = analyze_placeholder(value_placeholder)
         normalized_types = normalize_type_list(types)
         inferred_types = infer_types_from_placeholder(normalized_types, placeholder_info)
-        if inferred_types.empty? && value_placeholder.nil?
-          inferred_types = ['Boolean']
-        end
+        inferred_types = ['Boolean'] if inferred_types.empty? && value_placeholder.nil?
 
         optional_value = placeholder_info[:optional]
         boolean_flag = !optional_value && inferred_types.any? { |type| boolean_type?(type) }

data/lib/rubycli/documentation_registry.rb

@@ -34,6 +34,7 @@ module Rubycli
     def reset!
       @metadata_cache.clear
       @comment_extractor.reset!
+      @parser.reset_type_dictionary_cache! if @parser.respond_to?(:reset_type_dictionary_cache!)
     end
 
     private

data/lib/rubycli/environment.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rubycli
   # Environment captures runtime flags and configuration derived from ENV / argv.
   class Environment
@@ -45,6 +47,10 @@ module Rubycli
       @strict_input
     end
 
+    def disable_strict_input!
+      @strict_input = false
+    end
+
     def documentation_issues
       @documentation_issues.dup
     end
@@ -70,10 +76,10 @@ module Rubycli
       end
 
       formatted_message = if location
-        "#{location} #{message}"
-      else
-        message
-      end
+                            "#{location} #{message}"
+                          else
+                            message
+                          end
 
       entry = { message: formatted_message, location: location }
       @documentation_issues << entry
@@ -81,17 +87,19 @@ module Rubycli
     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
+      raise Rubycli::ArgumentError, message if strict_input?
+
+      warn "[WARN] #{message} (use --strict to abort on invalid input)"
     end
 
     def enable_print_result!
       @print_result = true
     end
 
+    def disable_print_result!
+      @print_result = false
+    end
+
     private
 
     def fetch_env_value(key, default)

data/lib/rubycli/eval_coercer.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 module Rubycli
   class EvalCoercer
     THREAD_KEY = :rubycli_eval_mode
     LAX_THREAD_KEY = :rubycli_eval_lax_mode
-    EVAL_BINDING = Object.new.instance_eval { binding }
+    BINDING_THREAD_KEY = :rubycli_eval_binding
 
     def eval_mode?
       Thread.current[THREAD_KEY] == true
@@ -12,15 +14,28 @@ module Rubycli
       Thread.current[LAX_THREAD_KEY] == true
     end
 
-    def with_eval_mode(enabled = true, lax: false)
+    def with_eval_mode(enabled = true, lax: false, reuse_binding: false)
       previous = Thread.current[THREAD_KEY]
       previous_lax = Thread.current[LAX_THREAD_KEY]
+      previous_binding = Thread.current[BINDING_THREAD_KEY]
       Thread.current[THREAD_KEY] = enabled
       Thread.current[LAX_THREAD_KEY] = enabled && lax
+      if enabled
+        Thread.current[BINDING_THREAD_KEY] = reuse_binding && previous_binding ? previous_binding : isolated_binding
+      end
       yield
     ensure
       Thread.current[THREAD_KEY] = previous
       Thread.current[LAX_THREAD_KEY] = previous_lax
+      Thread.current[BINDING_THREAD_KEY] = previous_binding
+    end
+
+    def with_eval_binding
+      previous_binding = Thread.current[BINDING_THREAD_KEY]
+      Thread.current[BINDING_THREAD_KEY] = isolated_binding
+      yield
+    ensure
+      Thread.current[BINDING_THREAD_KEY] = previous_binding
     end
 
     def coerce_eval_value(value)
@@ -34,7 +49,7 @@ module Rubycli
       else
         value
       end
-    rescue StandardError => e
+    rescue SyntaxError, StandardError => e
       raise Rubycli::ArgumentError, "Failed to evaluate Ruby code: #{e.message}"
     end
 
@@ -44,14 +59,16 @@ module Rubycli
       trimmed = expression.strip
       return trimmed if trimmed.empty?
 
-      EVAL_BINDING.eval(trimmed)
+      (Thread.current[BINDING_THREAD_KEY] || isolated_binding).eval(trimmed)
     rescue SyntaxError, NameError => e
-      if eval_lax_mode?
-        warn "[WARN] Failed to evaluate argument as Ruby (#{e.message.strip}). Passing it through because --eval-lax is enabled."
-        expression
-      else
-        raise
-      end
+      raise unless eval_lax_mode?
+
+      warn "[WARN] Failed to evaluate argument as Ruby (#{e.message.strip}). Passing it through because --eval-lax is enabled."
+      expression
+    end
+
+    def isolated_binding
+      Object.new.instance_eval { binding }
     end
   end
 end