docscribe 1.5.1 → 1.6.0

data/lib/docscribe/infer/behavior.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Infer
+    # Analyzes method behavior (predicates, side effects, mutating calls).
+    module Behavior
+      MUTATING_METHODS = %i[<< push pop delete merge update write save create destroy
+                            insert update_all delete_all].freeze
+
+      class << self
+        # @param [Object] body
+        # @param [Object] method_name
+        # @return [Hash<Symbol, Object>]
+        def analyze(body, method_name)
+          result = default_result(method_name)
+
+          return result unless body.is_a?(Parser::AST::Node)
+
+          analyze_body(body, result)
+          result
+        end
+
+        # @param [Object] method_name
+        # @return [Hash<Symbol, Object>]
+        def default_result(method_name)
+          {
+            predicate: method_name&.to_s&.end_with?('?') || false,
+            bang: method_name&.to_s&.end_with?('!') || false,
+            has_side_effects: false,
+            delegates: nil,
+            returns_self: false,
+            returns_boolean: false
+          }
+        end
+
+        # @param [Hash<Symbol, Object>] analysis
+        # @param [Object] _method_name
+        # @return [String?]
+        def infer_description(analysis, _method_name)
+          return nil unless analysis[:has_side_effects] || analysis[:predicate]
+
+          if analysis[:predicate]
+            'Returns true if the condition is met, false otherwise'
+          elsif analysis[:returns_self]
+            'Returns self to allow method chaining'
+          elsif analysis[:has_side_effects]
+            nil
+          end
+        end
+
+        private
+
+        # @private
+        # @param [Object] node
+        # @param [Hash<Symbol, Object>] result
+        # @return [void]
+        def analyze_body(node, result)
+          case node.type
+          when :ivasgn, :ivar
+            result[:has_side_effects] = true
+          when :send
+            analyze_send(node, result)
+          when :self
+            result[:returns_self] = true if result[:returns_self]
+          end
+
+          recurse_children(node, result)
+        end
+
+        # @private
+        # @param [Object] node
+        # @param [Hash<Symbol, Object>] result
+        # @return [void]
+        def recurse_children(node, result)
+          node.children.each do |child|
+            analyze_body(child, result) if child.is_a?(Parser::AST::Node)
+          end
+        end
+
+        # @private
+        # @param [Object] node
+        # @param [Hash<Symbol, Object>] result
+        # @return [void]
+        def analyze_send(node, result)
+          _receiver, method_name = *node
+          method_sym = method_name.is_a?(Symbol) ? method_name : nil
+          return unless method_sym
+
+          return unless MUTATING_METHODS.include?(method_sym)
+
+          result[:has_side_effects] = true
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/infer/params.rb

@@ -48,9 +48,7 @@ module Docscribe
       # @param [Boolean] treat_options_keyword_as_hash whether to treat 'options:' as Hash
       # @return [String]
       def inferred_param_type(name, default_str, fallback_type, treat_options_keyword_as_hash:)
-        if name.end_with?(':') && default_str.nil?
-          return options_keyword_type(name, treat_options_keyword_as_hash, fallback_type)
-        end
+        return options_keyword_type(name, treat_options_keyword_as_hash, fallback_type) if name.end_with?(':') && default_str.nil?
 
         node = parse_expr(default_str)
         ty = Literals.type_from_literal(node, fallback_type: fallback_type)
@@ -98,7 +96,7 @@ module Docscribe
         buffer = Parser::Source::Buffer.new('(param)')
         buffer.source = src
         Docscribe::Parsing.parse_buffer(buffer)
-      rescue Parser::SyntaxError # steep:ignore
+      rescue Parser::SyntaxError
         nil
       end
     end

data/lib/docscribe/infer/returns.rb

@@ -26,7 +26,7 @@ module Docscribe
         local_var_types = build_local_variable_types(body)
         run_last_expr_type(body, fallback_type: FALLBACK_TYPE, nil_as_optional: true,
                                  local_var_types: local_var_types) || FALLBACK_TYPE
-      rescue Parser::SyntaxError # steep:ignore
+      rescue Parser::SyntaxError
         FALLBACK_TYPE
       end
 

data/lib/docscribe/infer.rb

@@ -16,6 +16,7 @@ require_relative 'infer/literals'
 require_relative 'infer/params'
 require_relative 'infer/returns'
 require_relative 'infer/raises'
+require_relative 'infer/behavior'
 
 module Docscribe
   # Best-effort inference utilities used to generate YARD tags.
@@ -37,6 +38,40 @@ module Docscribe
         Raises.infer_raises_from_node(node)
       end
 
+      # Analyze method behavior from AST node and method name.
+      #
+      # @param [Object] node def or defs node
+      # @param [Object] method_name
+      # @return [Hash<Symbol, Object>]
+      def analyze_behavior(node, method_name)
+        body = extract_body(node)
+        Behavior.analyze(body, method_name)
+      end
+
+      # Get behavioral description for a method.
+      #
+      # @param [Object] node def or defs node
+      # @param [Object] method_name
+      # @return [String?]
+      def infer_behavior_description(node, method_name)
+        body = extract_body(node)
+        return nil unless body
+
+        analysis = Behavior.analyze(body, method_name)
+        Behavior.infer_description(analysis, method_name)
+      end
+
+      # Extract method body from def/defs node.
+      #
+      # @param [Object] node def or defs node
+      # @return [Object?]
+      def extract_body(node)
+        return nil unless node.is_a?(Parser::AST::Node)
+
+        body_idx = node.type == :def ? 2 : 3
+        node.children[body_idx]
+      end
+
       # Infer a parameter type from its internal name form and optional default
       # expression.
       #

data/lib/docscribe/inline_rewriter/doc_builder.rb

@@ -186,7 +186,7 @@ module Docscribe
       # @param [Hash<Symbol, Object>] opts additional options including
       # @return [Hash<Symbol, Object>]
       def resolve_doc_setup!(setup, node, name, config, opts)
-        external_sig = resolve_external_sig(setup[:container], setup[:scope], name, opts[:signature_provider])
+        external_sig = resolve_external_sig(setup[:container], setup[:scope], name, opts[:signature_provider], node)
         returns_spec = compute_returns_spec(node, config, opts[:param_types], opts[:core_rbs_provider],
                                             signature_provider: opts[:signature_provider],
                                             container: setup[:container])
@@ -219,9 +219,26 @@ module Docscribe
       # @param [Symbol] scope method scope symbol
       # @param [Symbol] name the method name string
       # @param [Docscribe::Types::ProviderChain, nil] signature_provider external sig provider
+      # @param [Parser::AST::Node] node
       # @return [Docscribe::Types::MethodSignature, nil]
-      def resolve_external_sig(container, scope, name, signature_provider)
-        signature_provider&.signature_for(container: container, scope: scope, name: name)
+      def resolve_external_sig(container, scope, name, signature_provider, node = nil)
+        param_count, param_names = extract_sig_param_info(node)
+        signature_provider&.signature_for(container: container, scope: scope, name: name,
+                                          param_count: param_count, param_names: param_names)
+      end
+
+      # @note module_function: defines #extract_sig_param_info (visibility: private)
+      # @param [Parser::AST::Node?] node
+      # @return [(Integer?, Array<String>)]
+      def extract_sig_param_info(node)
+        empty = [] #: Array[String]
+        return [nil, empty] unless node
+
+        args = extract_args_from_node(node)
+        empty = [] #: Array[String]
+        return [nil, empty] unless args
+
+        [args.children.length, args.children.map { |a| a.children.first.to_s if a.respond_to?(:children) }.compact]
       end
 
       # Compute returns spec
@@ -594,7 +611,7 @@ module Docscribe
 
         return_type = rest[1...type_end] #: String
         desc = rest[(type_end + 1)..]&.strip
-        [return_type, desc&.empty? ? nil : desc]
+        [return_type, desc && desc.empty? ? nil : desc]
       end
 
       # Extract all comment tags from line
@@ -832,9 +849,7 @@ module Docscribe
       # @param [Hash<Symbol, Object>] info parse info hash to update with visibility flags
       # @return [Array<String>]
       def merge_module_function_note_lines(indent, insertion, name, info)
-        unless insertion.respond_to?(:module_function) && insertion.module_function && !info[:has_module_function_note]
-          return []
-        end
+        return [] unless insertion.respond_to?(:module_function) && insertion.module_function && !info[:has_module_function_note]
 
         included_vis = insertion.included_instance_visibility || :private
         ["#{indent}# @note module_function: defines ##{name} (visibility: #{included_vis})"]
@@ -1228,9 +1243,7 @@ module Docscribe
         end
 
         method_name = :"build_#{arg_node.type}_lines"
-        if respond_to?(method_name, true)
-          return send(method_name, arg_node, indent, external_sig, param_types_override, **opts)
-        end
+        return send(method_name, arg_node, indent, external_sig, param_types_override, **opts) if respond_to?(method_name, true)
 
         []
       end

data/lib/docscribe/inline_rewriter.rb

@@ -158,7 +158,8 @@ module Docscribe
       # @param [String] code the Ruby source code string to parse and rewrite
       # @param [Hash<Symbol, Object>] options hash containing :config, :file, and :core_rbs_provider
       # @raise [Docscribe::ParseError]
-      # @return [Hash<Symbol, Docscribe::Config, String, Parser::Source::Buffer, Parser::AST::Node, Docscribe::Types::ProviderChain, nil, Object, nil>]
+      # @return [Hash<Symbol, Docscribe::Config, String, Parser::Source::Buffer, Parser::AST::Node, Docscribe::Types::ProviderChain, nil, Object, nil>] rewrite environment with keys
+      #   :config, :file, :buffer, :ast, :core_rbs_provider
       def setup_rewrite_env(code, options)
         config = options[:config] || Docscribe::Config.load
         file = (options[:file] || '(inline)').to_s
@@ -454,7 +455,8 @@ module Docscribe
       # Plugin insertion priority
       #
       # @private
-      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected method insertion
+      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
+      #   method insertion (plugin hash or collected insertion object)
       # @raise [StandardError]
       # @return [Integer]
       # @return [Integer] if StandardError
@@ -469,7 +471,8 @@ module Docscribe
       # Plugin insertion label
       #
       # @private
-      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected method insertion
+      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
+      #   method insertion (plugin hash or collected insertion object)
       # @raise [StandardError]
       # @return [String]
       # @return [String] if StandardError
@@ -485,7 +488,8 @@ module Docscribe
       # Plugin insertion line
       #
       # @private
-      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected method insertion
+      # @param [Hash<Symbol, Object>, Docscribe::InlineRewriter::Collector::Insertion, Docscribe::InlineRewriter::Collector::AttrInsertion] insertion the collected
+      #   method insertion (plugin hash or collected insertion object)
       # @raise [StandardError]
       # @return [Integer, nil]
       # @return [nil] if StandardError
@@ -630,9 +634,7 @@ module Docscribe
       def normalize_plugin_doc(doc, indent, config:, anchor_node:)
         doc = normalize_plugin_doc_indent(doc, indent)
         doc = trim_trailing_blank_lines(doc)
-        if anchor_node && %i[def defs].include?(anchor_node.type) && config.include_default_message?
-          doc = prepend_default_message_if_no_prose(doc, anchor_node, indent, config)
-        end
+        doc = prepend_default_message_if_no_prose(doc, anchor_node, indent, config) if anchor_node && %i[def defs].include?(anchor_node.type) && config.include_default_message?
         doc
       end
 
@@ -794,9 +796,7 @@ module Docscribe
       # @return [void]
       def merge_existing_descriptions!(params, parsed)
         params[:param_descriptions] = parsed[:param_descriptions] if parsed[:param_descriptions].any?
-        if parsed[:return_description] && !parsed[:return_description].start_with?('if ')
-          params[:return_description] = parsed[:return_description]
-        end
+        params[:return_description] = parsed[:return_description] if parsed[:return_description] && !parsed[:return_description].start_with?('if ')
         params[:description] = parsed[:description] if parsed[:description].any?
       end
 
@@ -841,13 +841,27 @@ module Docscribe
       # @return [Docscribe::Types::MethodSignature, nil]
       def resolve_external_signature(insertion, signature_provider)
         node_name = SourceHelpers.node_name(insertion.node) #: Symbol
+        param_count, param_names = extract_param_info(insertion)
         signature_provider&.signature_for(
           container: insertion.container,
           scope: insertion.scope,
-          name: node_name
+          name: node_name,
+          param_count: param_count,
+          param_names: param_names
         )
       end
 
+      # @private
+      # @param [Object] insertion
+      # @return [(Integer?, Array<Object>)]
+      def extract_param_info(insertion)
+        args = DocBuilder.extract_args_from_node(insertion.node)
+        empty = [] #: Array[untyped]
+        return [nil, empty] unless args
+
+        [args.children.length, args.children.map { |a| a.children.first.to_s if a.respond_to?(:children) }.compact]
+      end
+
       # Resolve param types
       #
       # @private
@@ -1079,7 +1093,8 @@ module Docscribe
       # @param [Docscribe::Config] config the active Docscribe::Config
       # @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
       # @param [Parser::Source::Range] bol_range the beginning-of-line range for the attribute node
-      # @return [Hash<Symbol, Docscribe::InlineRewriter::Collector::AttrInsertion, Docscribe::Config, Docscribe::Types::ProviderChain, nil, Parser::Source::Range>]
+      # @return [Hash<Symbol, Docscribe::InlineRewriter::Collector::AttrInsertion, Docscribe::Config, Docscribe::Types::ProviderChain, nil, Parser::Source::Range>] attr insertion params with keys
+      #   :insertion, :config, :signature_provider, :bol_range
       def attr_insertion_params(insertion, config, signature_provider, bol_range)
         {
           insertion: insertion, config: config,
@@ -1237,19 +1252,52 @@ module Docscribe
       # @return [String, nil]
       # @return [nil] if StandardError
       def build_attr_merge_additions(ins:, existing_lines:, config:, signature_provider:)
-        missing = missing_attr_names(ins, existing_lines)
-        return '' if missing.empty?
-
         indent = SourceHelpers.line_indent(ins.node)
-        lines = [] #: Array[String]
-        lines << "#{indent}#" if existing_lines.any? && existing_lines.last.strip != '#'
-        lines.concat(build_attr_doc_lines(ins, indent: indent, config: config,
-                                               signature_provider: signature_provider, names: missing))
-        lines.map { |l| "#{l}\n" }.join
+        lines = build_attr_merge_missing_lines(ins, existing_lines, indent, config, signature_provider)
+        lines.concat(build_attr_merge_tag_lines(ins, existing_lines, indent, config, signature_provider))
+
+        lines.empty? ? '' : lines.map { |l| "#{l}\n" }.join
       rescue StandardError
         nil
       end
 
+      # @private
+      # @param [Object] ins
+      # @param [Array<String>] existing_lines
+      # @param [String] indent
+      # @param [Docscribe::Config] config
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider
+      # @return [Array<String>]
+      def build_attr_merge_missing_lines(ins, existing_lines, indent, config, signature_provider)
+        missing = missing_attr_names(ins, existing_lines)
+        lines = [] #: Array[String]
+
+        unless missing.empty?
+          lines << "#{indent}#" if existing_lines.any? && existing_lines.last.strip != '#'
+          lines.concat(build_attr_doc_lines(ins, indent: indent, config: config,
+                                                 signature_provider: signature_provider, names: missing))
+        end
+
+        lines
+      end
+
+      # @private
+      # @param [Object] ins
+      # @param [Array<String>] existing_lines
+      # @param [String] indent
+      # @param [Docscribe::Config] config
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider
+      # @return [Array<String>]
+      def build_attr_merge_tag_lines(ins, existing_lines, indent, config, signature_provider)
+        tag_additions = build_missing_tag_additions(ins, existing_lines, indent, config, signature_provider)
+        return [] if tag_additions.empty?
+
+        result = [] #: Array[String]
+        result << "#{indent}#" if existing_lines.any? && existing_lines.last.strip != '#'
+        result.concat(tag_additions)
+        result
+      end
+
       # Missing attr names
       #
       # @private
@@ -1278,6 +1326,80 @@ module Docscribe
         names
       end
 
+      # Build missing tag additions for existing @!attribute lines
+      #
+      # @private
+      # @param [Docscribe::InlineRewriter::Collector::AttrInsertion] ins the attribute insertion object
+      # @param [Array<String>] existing_lines array of existing doc comment lines
+      # @param [String] indent whitespace indentation prefix
+      # @param [Docscribe::Config] config the active Docscribe::Config
+      # @param [Docscribe::Types::ProviderChain, nil] signature_provider external RBS signature provider
+      # @return [Array<String>]
+      def build_missing_tag_additions(ins, existing_lines, indent, config, signature_provider)
+        ins.names.each_with_object([]) do |name_sym, additions|
+          idx = existing_attr_line_index(existing_lines, name_sym.to_s)
+          next unless idx
+
+          attr_type = attribute_type(ins, name_sym, config, signature_provider: signature_provider)
+          additions << "#{indent}#   @return [#{attr_type}]" if attr_return_missing?(ins.access, existing_lines, idx)
+          additions << format_attribute_param_tag(indent, 'value', attr_type, style: config.param_tag_style) if attr_param_missing?(ins.access, existing_lines, idx)
+        end
+      end
+
+      # @private
+      # @param [Symbol] access
+      # @param [Array<String>] existing_lines
+      # @param [Integer] idx
+      # @return [Boolean]
+      def attr_return_missing?(access, existing_lines, idx)
+        %i[r rw].include?(access) && !existing_lines_contain_tag?(existing_lines, idx, 'return')
+      end
+
+      # @private
+      # @param [Symbol] access
+      # @param [Array<String>] existing_lines
+      # @param [Integer] idx
+      # @return [Boolean]
+      def attr_param_missing?(access, existing_lines, idx)
+        %i[w rw].include?(access) && !existing_lines_contain_tag?(existing_lines, idx, 'param')
+      end
+
+      # Find index of line containing @!attribute for a specific name
+      #
+      # @private
+      # @param [Array<String>] lines array of existing doc comment lines
+      # @param [String] name the attribute name to search for
+      # @return [Integer?]
+      def existing_attr_line_index(lines, name)
+        Array(lines).each_with_index do |line, idx|
+          return idx if line.match?(/\A\s*#\s*@!attribute\b(?:\s+\[[^\]]+\])?\s+#{Regexp.escape(name)}\b/)
+        end
+        nil
+      end
+
+      # Check if lines after an @!attribute line contain a specific tag
+      #
+      # Walks forward from attr_line_idx + 1, stopping at the next top-level
+      # directive or non-comment line.
+      #
+      # @private
+      # @param [Array<String>] lines array of existing doc comment lines
+      # @param [Integer] attr_line_idx index of the @!attribute line
+      # @param [String] tag_name the tag name to search for (e.g. "return", "param")
+      # @return [Boolean]
+      def existing_lines_contain_tag?(lines, attr_line_idx, tag_name)
+        i = attr_line_idx + 1
+        while i < lines.length
+          line = lines[i]
+          break unless line.match?(/\A\s*#/) # not a comment line
+          break if line.match?(/\A\s*# @(?!@)/) # next top-level directive (single space)
+          return true if line.match?(/\A\s*#\s{2,}@#{tag_name}\b/)
+
+          i += 1
+        end
+        false
+      end
+
       # Attribute allowed
       #
       # @private