docscribe 1.1.0 → 1.2.1

data/lib/docscribe/infer/returns.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Infer
+    # Return type inference and rescue-conditional return extraction.
+    module Returns
+      module_function
+
+      # Infer a return type from a full method definition source string.
+      #
+      # The source must parse to a `:def` or `:defs` node. If parsing fails or inference
+      # is uncertain, the fallback type is returned.
+      #
+      # @note module_function: when included, also defines #infer_return_type (instance visibility: private)
+      # @param [String, nil] method_source full method definition source
+      # @raise [Parser::SyntaxError]
+      # @return [String]
+      def infer_return_type(method_source)
+        return FALLBACK_TYPE if method_source.nil? || method_source.strip.empty?
+
+        buffer = Parser::Source::Buffer.new('(method)')
+        buffer.source = method_source
+        root = Docscribe::Parsing.parse_buffer(buffer)
+        return FALLBACK_TYPE unless root && %i[def defs].include?(root.type)
+
+        body = root.children.last
+        last_expr_type(body, fallback_type: FALLBACK_TYPE, nil_as_optional: true) || FALLBACK_TYPE
+      rescue Parser::SyntaxError
+        FALLBACK_TYPE
+      end
+
+      # Infer a method's normal return type from an already parsed def/defs node.
+      #
+      # @note module_function: when included, also defines #infer_return_type_from_node (instance visibility: private)
+      # @param [Parser::AST::Node] node `:def` or `:defs` node
+      # @return [String]
+      def infer_return_type_from_node(node)
+        body =
+          case node.type
+          when :def then node.children[2]
+          when :defs then node.children[3]
+          end
+
+        return FALLBACK_TYPE unless body
+
+        last_expr_type(body, fallback_type: FALLBACK_TYPE, nil_as_optional: true) || FALLBACK_TYPE
+      end
+
+      # Return a structured return-type spec for a method node.
+      #
+      # The result includes:
+      # - `:normal`  => normal/happy-path return type
+      # - `:rescues` => array of `[exception_names, return_type]` pairs for rescue branches
+      #
+      # @note module_function: when included, also defines #returns_spec_from_node (instance visibility: private)
+      # @param [Parser::AST::Node] node `:def` or `:defs` node
+      # @param [String] fallback_type type used when inference is uncertain
+      # @param [Boolean] nil_as_optional whether `nil` unions should be rendered as optional types
+      # @return [Hash]
+      def returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true)
+        body =
+          case node.type
+          when :def then node.children[2]
+          when :defs then node.children[3]
+          end
+
+        spec = { normal: FALLBACK_TYPE, rescues: [] }
+        return spec unless body
+
+        if body.type == :rescue
+          main_body = body.children[0]
+          spec[:normal] =
+            last_expr_type(main_body, fallback_type: fallback_type, nil_as_optional: nil_as_optional) || FALLBACK_TYPE
+
+          body.children.each do |ch|
+            next unless ch.is_a?(Parser::AST::Node) && ch.type == :resbody
+
+            exc_list, _asgn, rescue_body = *ch
+            exc_names = Raises.exception_names_from_rescue_list(exc_list)
+            rtype =
+              last_expr_type(rescue_body, fallback_type: fallback_type, nil_as_optional: nil_as_optional) ||
+              fallback_type
+            spec[:rescues] << [exc_names, rtype]
+          end
+        else
+          spec[:normal] =
+            last_expr_type(body, fallback_type: fallback_type, nil_as_optional: nil_as_optional) || FALLBACK_TYPE
+        end
+
+        spec
+      end
+
+      # Infer the type of the last expression in a node.
+      #
+      # Supports:
+      # - `begin` groups
+      # - `if` branches
+      # - `case` expressions
+      # - explicit `return`
+      # - literal-like expressions via {Literals.type_from_literal}
+      #
+      # @note module_function: when included, also defines #last_expr_type (instance visibility: private)
+      # @param [Parser::AST::Node, nil] node expression node
+      # @param [String] fallback_type type used when inference is uncertain
+      # @param [Boolean] nil_as_optional whether `nil` unions should be rendered as optional types
+      # @return [String, nil]
+      def last_expr_type(node, fallback_type:, nil_as_optional:)
+        return nil unless node
+
+        case node.type
+        when :begin
+          last_expr_type(node.children.last, fallback_type: fallback_type, nil_as_optional: nil_as_optional)
+
+        when :if
+          t = last_expr_type(node.children[1], fallback_type: fallback_type, nil_as_optional: nil_as_optional)
+          e = last_expr_type(node.children[2], fallback_type: fallback_type, nil_as_optional: nil_as_optional)
+          unify_types(t, e, fallback_type: fallback_type, nil_as_optional: nil_as_optional)
+
+        when :case
+          branches = node.children[1..].compact.flat_map do |child|
+            if child.type == :when
+              last_expr_type(child.children.last, fallback_type: fallback_type, nil_as_optional: nil_as_optional)
+            else
+              last_expr_type(child, fallback_type: fallback_type, nil_as_optional: nil_as_optional)
+            end
+          end.compact
+
+          if branches.empty?
+            fallback_type
+          else
+            branches.reduce do |a, b|
+              unify_types(a, b, fallback_type: fallback_type, nil_as_optional: nil_as_optional)
+            end
+          end
+
+        when :return
+          Literals.type_from_literal(node.children.first, fallback_type: fallback_type)
+
+        else
+          Literals.type_from_literal(node, fallback_type: fallback_type)
+        end
+      end
+
+      # Unify two inferred types into a single type string.
+      #
+      # Rules:
+      # - identical types remain unchanged
+      # - `nil` unions may become optional types if enabled
+      # - otherwise falls back conservatively to `fallback_type`
+      #
+      # @note module_function: when included, also defines #unify_types (instance visibility: private)
+      # @param [String, nil] a
+      # @param [String, nil] b
+      # @param [String] fallback_type
+      # @param [Boolean] nil_as_optional
+      # @return [String, nil]
+      def unify_types(a, b, fallback_type:, nil_as_optional:)
+        a ||= fallback_type
+        b ||= fallback_type
+        return a if a == b
+
+        if a == 'nil' || b == 'nil'
+          non_nil = (a == 'nil' ? b : a)
+          return nil_as_optional ? "#{non_nil}?" : "#{non_nil}, nil"
+        end
+
+        fallback_type
+      end
+    end
+  end
+end

data/lib/docscribe/infer.rb

@@ -1,306 +1,152 @@
 # frozen_string_literal: true
 
+# NOTE: parser/base references Racc::Parser in some environments, so require runtime first.
 require 'racc/parser'
 require 'ast'
 require 'parser/ast/node'
 require 'parser/source/buffer'
 require 'parser/base'
+
 require 'docscribe/parsing'
 
+require_relative 'infer/constants'
+require_relative 'infer/ast_walk'
+require_relative 'infer/names'
+require_relative 'infer/literals'
+require_relative 'infer/params'
+require_relative 'infer/returns'
+require_relative 'infer/raises'
+
 module Docscribe
+  # Best-effort inference utilities used to generate YARD tags.
+  #
+  # This module is intentionally heuristic:
+  # - it aims to be useful for common Ruby patterns
+  # - it prefers safe fallback behavior when uncertain
+  # - when inference cannot be specific, it falls back to `Object`
+  #
+  # External signature sources such as RBS and Sorbet are applied later in the
+  # doc builder and can override these inferred types.
   module Infer
     class << self
-      # +Docscribe::Infer.infer_raises_from_node+ -> Object
-      #
-      # Method documentation.
+      # Infer exception classes raised or rescued within an AST node.
       #
-      # @param [Object] node Param documentation.
-      # @return [Object]
+      # @param [Parser::AST::Node] node
+      # @return [Array<String>]
       def infer_raises_from_node(node)
-        raises = []
-        walk = lambda do |n|
-          return unless n.is_a?(Parser::AST::Node)
-
-          case n.type
-          when :rescue
-            n.children.each { |ch| walk.call(ch) }
-          when :resbody
-            exc_list = n.children[0]
-            if exc_list.nil?
-              raises << 'StandardError'
-            elsif exc_list.type == :array
-              exc_list.children.each { |e| (c = const_full_name(e)) && (raises << c) }
-            else
-              (c = const_full_name(exc_list)) && (raises << c)
-            end
-            n.children.each { |ch| walk.call(ch) if ch.is_a?(Parser::AST::Node) }
-          when :send
-            recv, meth, *args = *n
-            if recv.nil? && %i[raise fail].include?(meth)
-              if args.empty?
-                raises << 'StandardError'
-              else
-                c = const_full_name(args[0])
-                raises << (c || 'StandardError')
-              end
-            end
-            n.children.each { |ch| walk.call(ch) if ch.is_a?(Parser::AST::Node) }
-          else
-            n.children.each { |ch| walk.call(ch) if ch.is_a?(Parser::AST::Node) }
-          end
-        end
-        walk.call(node)
-        raises.uniq
+        Raises.infer_raises_from_node(node)
       end
 
-      # +Docscribe::Infer.infer_param_type+ -> Object
+      # Infer a parameter type from its internal name form and optional default
+      # expression.
       #
-      # Method documentation.
+      # The internal parameter name may include:
+      # - `*` for rest args
+      # - `**` for keyword rest args
+      # - `&` for block args
+      # - trailing `:` for keyword args
       #
-      # @param [Object] name Param documentation.
-      # @param [Object] default_str Param documentation.
-      # @return [Object]
-      def infer_param_type(name, default_str)
-        # splats and kwargs are driven by name shape
-        return 'Array' if name.start_with?('*') && !name.start_with?('**')
-        return 'Hash'  if name.start_with?('**')
-        return 'Proc'  if name.start_with?('&')
-
-        # keyword arg e.g. "verbose:" — default_str might be nil or something
-        is_kw = name.end_with?(':')
-
-        node = parse_expr(default_str)
-        ty = type_from_literal(node)
-
-        # If kw with no default, still show Object (or Hash for options:)
-        if is_kw && default_str.nil?
-          return (name == 'options:' ? 'Hash' : 'Object')
-        end
-
-        # If param named options and default is {}, call it Hash
-        return 'Hash' if name == 'options:' && (default_str == '{}' || ty == 'Hash')
-
-        ty
+      # @param [String] name internal parameter name representation
+      # @param [String, nil] default_str source for the default expression
+      # @param [String] fallback_type
+      # @param [Boolean] treat_options_keyword_as_hash
+      # @return [String]
+      def infer_param_type(name, default_str, fallback_type: FALLBACK_TYPE, treat_options_keyword_as_hash: true)
+        Params.infer_param_type(
+          name,
+          default_str,
+          fallback_type: fallback_type,
+          treat_options_keyword_as_hash: treat_options_keyword_as_hash
+        )
       end
 
-      # +Docscribe::Infer.parse_expr+ -> Object
+      # Parse a standalone expression source string for inference helpers.
       #
-      # Method documentation.
-      #
-      # @param [Object] src Param documentation.
-      # @raise [Parser::SyntaxError]
-      # @return [Object]
-      # @return [nil] if Parser::SyntaxError
+      # @param [String, nil] src
+      # @return [Parser::AST::Node, nil]
       def parse_expr(src)
-        return nil if src.nil? || src.strip.empty?
-
-        buffer = Parser::Source::Buffer.new('(param)')
-        buffer.source = src
-        Docscribe::Parsing.parse_buffer(buffer)
-      rescue Parser::SyntaxError
-        nil
+        Params.parse_expr(src)
       end
 
-      # +Docscribe::Infer.infer_return_type+ -> Object
-      #
-      # Method documentation.
+      # Infer a return type from full method source.
       #
-      # @param [Object] method_source Param documentation.
-      # @raise [Parser::SyntaxError]
-      # @return [Object]
-      # @return [String] if Parser::SyntaxError
+      # @param [String, nil] method_source
+      # @return [String]
       def infer_return_type(method_source)
-        return 'Object' if method_source.nil? || method_source.strip.empty?
-
-        buffer = Parser::Source::Buffer.new('(method)')
-        buffer.source = method_source
-        root = Docscribe::Parsing.parse_buffer(buffer)
-        return 'Object' unless root && %i[def defs].include?(root.type)
-
-        body = root.children.last # method body node
-        ty = last_expr_type(body)
-        ty || 'Object'
-      rescue Parser::SyntaxError
-        'Object'
+        Returns.infer_return_type(method_source)
       end
 
-      # +Docscribe::Infer.infer_return_type_from_node+ -> Object
-      #
-      # Method documentation.
+      # Infer a return type from an already parsed `:def` / `:defs` node.
       #
-      # @param [Object] node Param documentation.
-      # @return [Object]
+      # @param [Parser::AST::Node] node
+      # @return [String]
       def infer_return_type_from_node(node)
-        body =
-          case node.type
-          when :def then node.children[2] # [name, args, body]
-          when :defs then node.children[3] # [recv, name, args, body]
-          end
-        return 'Object' unless body
-
-        ty = last_expr_type(body)
-        ty || 'Object'
+        Returns.infer_return_type_from_node(node)
       end
 
-      # +Docscribe::Infer.returns_spec_from_node+ -> Object
-      #
-      # Method documentation.
-      #
-      # @param [Object] node Param documentation.
-      # @return [Object]
-      def returns_spec_from_node(node)
-        # Returns a Hash like: { normal: 'Type', rescues: [[['Foo','Bar'], 'Type'], ...] }
-        body =
-          case node.type
-          when :def then node.children[2] # [name, args, body]
-          when :defs then node.children[3] # [recv, name, args, body]
-          end
-
-        spec = { normal: 'Object', rescues: [] }
-        return spec unless body
-
-        if body.type == :rescue
-          # child[0] is the main body (before rescue)
-          main_body = body.children[0]
-          spec[:normal] = last_expr_type(main_body) || 'Object'
-
-          # :resbody nodes hold exception list, optional var, and rescue body
-          body.children.each do |ch|
-            next unless ch.is_a?(Parser::AST::Node) && ch.type == :resbody
-
-            exc_list, _asgn, rescue_body = *ch
-
-            exc_names = []
-            if exc_list.nil?
-              exc_names << 'StandardError'
-            elsif exc_list.type == :array
-              exc_list.children.each do |e|
-                name = const_full_name(e)
-                exc_names << (name || 'StandardError')
-              end
-            else
-              name = const_full_name(exc_list)
-              exc_names << (name || 'StandardError')
-            end
-
-            rtype = last_expr_type(rescue_body) || 'Object'
-            spec[:rescues] << [exc_names, rtype]
-          end
-        else
-          spec[:normal] = last_expr_type(body) || 'Object'
-        end
-
-        spec
+      # Return structured normal/rescue return information for a method node.
+      #
+      # Result shape:
+      # - `:normal` => the normal return type
+      # - `:rescues` => rescue-branch conditional return info
+      #
+      # @param [Parser::AST::Node] node
+      # @param [String] fallback_type
+      # @param [Boolean] nil_as_optional
+      # @return [Hash]
+      def returns_spec_from_node(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true)
+        Returns.returns_spec_from_node(
+          node,
+          fallback_type: fallback_type,
+          nil_as_optional: nil_as_optional
+        )
       end
 
-      # +Docscribe::Infer.last_expr_type+ -> Object
-      #
-      # Method documentation.
-      #
-      # @param [Object] node Param documentation.
-      # @return [Object]
-      def last_expr_type(node)
-        return nil unless node
-
-        case node.type
-        when :begin
-          last = node.children.last
-          last_expr_type(last)
-        when :if
-          t = last_expr_type(node.children[1])
-          e = last_expr_type(node.children[2])
-          unify_types(t, e)
-        when :case
-          # check whens and else
-          branches = node.children[1..].compact.flat_map do |child|
-            if child && child.type == :when
-              last_expr_type(child.children.last)
-            else
-              last_expr_type(child)
-            end
-          end
-          branches.compact!
-          branches.empty? ? 'Object' : branches.reduce { |a, b| unify_types(a, b) }
-        when :return
-          type_from_literal(node.children.first)
-        else
-          type_from_literal(node)
-        end
+      # Infer the type of the last expression in an AST node.
+      #
+      # @param [Parser::AST::Node, nil] node
+      # @param [String] fallback_type
+      # @param [Boolean] nil_as_optional
+      # @return [String, nil]
+      def last_expr_type(node, fallback_type: FALLBACK_TYPE, nil_as_optional: true)
+        Returns.last_expr_type(
+          node,
+          fallback_type: fallback_type,
+          nil_as_optional: nil_as_optional
+        )
       end
 
-      # +Docscribe::Infer.const_full_name+ -> Object
-      #
-      # Method documentation.
+      # Convert a constant AST node into its fully qualified name.
       #
-      # @param [Object] n Param documentation.
-      # @return [Object]
+      # @param [Parser::AST::Node, nil] n
+      # @return [String, nil]
       def const_full_name(n)
-        return nil unless n.is_a?(Parser::AST::Node)
-
-        case n.type
-        when :const
-          scope, name = *n
-          scope_name = const_full_name(scope)
-          if scope_name && !scope_name.empty?
-            "#{scope_name}::#{name}"
-          elsif scope_name == '' # leading ::
-            "::#{name}"
-          else
-            name.to_s
-          end
-        when :cbase
-          '' # represents leading :: scope
-        end
+        Names.const_full_name(n)
       end
 
-      # +Docscribe::Infer.type_from_literal+ -> Object
-      #
-      # Method documentation.
+      # Infer a YARD-ish type string from a literal AST node.
       #
-      # @param [Object] node Param documentation.
-      # @return [Object]
-      def type_from_literal(node)
-        return 'Object' unless node
-
-        case node.type
-        when :int then 'Integer'
-        when :float then 'Float'
-        when :str, :dstr then 'String'
-        when :sym then 'Symbol'
-        when :true, :false then 'Boolean' # rubocop:disable Lint/BooleanSymbol
-        when :nil then 'nil'
-        when :array then 'Array'
-        when :hash then 'Hash'
-        when :regexp then 'Regexp'
-        when :const
-          node.children.last.to_s
-        when :send
-          recv, meth, = node.children
-          if meth == :new && recv && recv.type == :const
-            recv.children.last.to_s
-          else
-            'Object'
-          end
-        else
-          'Object'
-        end
+      # @param [Parser::AST::Node, nil] node
+      # @param [String] fallback_type
+      # @return [String]
+      def type_from_literal(node, fallback_type: FALLBACK_TYPE)
+        Literals.type_from_literal(node, fallback_type: fallback_type)
       end
 
-      # +Docscribe::Infer.unify_types+ -> String
+      # Unify two inferred type strings conservatively.
       #
-      # Method documentation.
-      #
-      # @param [Object] a Param documentation.
-      # @param [Object] b Param documentation.
+      # @param [String, nil] a
+      # @param [String, nil] b
+      # @param [String] fallback_type
+      # @param [Boolean] nil_as_optional
       # @return [String]
-      def unify_types(a, b)
-        a ||= 'Object'
-        b ||= 'Object'
-        return a if a == b
-        # nil-union => Optional
-        return "#{a == 'nil' ? b : a}?" if a == 'nil' || b == 'nil'
-
-        'Object'
+      def unify_types(a, b, fallback_type: FALLBACK_TYPE, nil_as_optional: true)
+        Returns.unify_types(
+          a,
+          b,
+          fallback_type: fallback_type,
+          nil_as_optional: nil_as_optional
+        )
       end
     end
   end