docscribe 1.4.1 → 1.5.0

data/lib/docscribe/infer/literals.rb

@@ -17,38 +17,51 @@ module Docscribe
       #
       # If the node does not match a supported pattern, the fallback type is returned.
       #
-      # @note module_function: when included, also defines #type_from_literal (instance visibility: private)
+      # @note module_function: defines #type_from_literal (visibility: private)
       # @param [Parser::AST::Node, nil] node literal/value node
       # @param [String] fallback_type type returned when inference is uncertain
       # @return [String]
       def type_from_literal(node, fallback_type: FALLBACK_TYPE)
         return fallback_type 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
-            fallback_type
-          end
-
-        else
-          fallback_type
-        end
+        literal_type_for(node.type) || const_type_for(node, fallback_type) ||
+          send_new_type_for(node, fallback_type) || fallback_type
+      end
+
+      # Map a node type symbol to a known literal type name.
+      #
+      # @note module_function: defines #literal_type_for (visibility: private)
+      # @param [Symbol] type node type
+      # @return [String, nil]
+      def literal_type_for(type)
+        LITERAL_TYPE_MAP[type]
+      end
+
+      # Extract a constant name from a `:const` node.
+      #
+      # @note module_function: defines #const_type_for (visibility: private)
+      # @param [Parser::AST::Node] node literal/value node
+      # @param [String] _fallback_type fallback type string (unused here)
+      # @return [String, nil]
+      def const_type_for(node, _fallback_type)
+        return unless node.type == :const
+
+        node.children.last.to_s
+      end
+
+      # Extract a type from a `Foo.new` send node.
+      #
+      # @note module_function: defines #send_new_type_for (visibility: private)
+      # @param [Parser::AST::Node] node literal/value node
+      # @param [String] _fallback_type fallback type string (unused here)
+      # @return [String, nil]
+      def send_new_type_for(node, _fallback_type)
+        return unless node.type == :send
+
+        recv, meth, = node.children
+        return unless meth == :new && recv&.type == :const
+
+        recv.children.last.to_s
       end
     end
   end

data/lib/docscribe/infer/names.rb

@@ -15,27 +15,35 @@ module Docscribe
       #
       # Returns nil for unsupported nodes.
       #
-      # @note module_function: when included, also defines #const_full_name (instance visibility: private)
-      # @param [Parser::AST::Node, nil] n constant-like AST node
+      # @note module_function: defines #const_full_name (visibility: private)
+      # @param [Parser::AST::Node, nil] node constant-like AST node
       # @return [String, nil]
-      def const_full_name(n)
-        return nil unless n.is_a?(Parser::AST::Node)
+      def const_full_name(node)
+        return nil unless node.is_a?(Parser::AST::Node)
 
-        case n.type
+        case node.type
         when :const
-          scope, name = *n
-          scope_name = const_full_name(scope)
+          build_const_full_name(node)
+        when :cbase
+          ''
+        end
+      end
 
-          if scope_name && !scope_name.empty?
-            "#{scope_name}::#{name}"
-          elsif scope_name == '' # leading ::
-            "::#{name}"
-          else
-            name.to_s
-          end
+      # Build the fully qualified name from a `:const` node.
+      #
+      # @note module_function: defines #build_const_full_name (visibility: private)
+      # @param [Parser::AST::Node] node a `:const` node
+      # @return [String]
+      def build_const_full_name(node)
+        scope, name = *node
+        scope_name = const_full_name(scope)
 
-        when :cbase
-          '' # represents leading :: scope
+        if scope_name && !scope_name.empty?
+          "#{scope_name}::#{name}"
+        elsif scope_name == ''
+          "::#{name}"
+        else
+          name.to_s
         end
       end
     end

data/lib/docscribe/infer/params.rb

@@ -15,46 +15,90 @@ module Docscribe
       # - special-casing `options:` as `Hash` when enabled
       # - literal defaults via AST parsing
       #
-      # @note module_function: when included, also defines #infer_param_type (instance visibility: private)
+      # @note module_function: defines #infer_param_type (visibility: private)
       # @param [String] name parameter name as used internally (may include `*`, `**`, `&`, or trailing `:`)
-      # @param [String, nil] default_str source for the default value expression
+      # @param [String?] default_str source for the default value expression
       # @param [String] fallback_type type returned when inference is uncertain
       # @param [Boolean] treat_options_keyword_as_hash whether `options:` should
-      #   be treated specially as Hash
       # @return [String]
       def infer_param_type(name, default_str, fallback_type: FALLBACK_TYPE, treat_options_keyword_as_hash: true)
+        prefix_param_type(name) || inferred_param_type(name, default_str, fallback_type,
+                                                       treat_options_keyword_as_hash: treat_options_keyword_as_hash)
+      end
+
+      # Return type for special parameter prefixes.
+      #
+      # @note module_function: defines #prefix_param_type (visibility: private)
+      # @param [String] name parameter name
+      # @return [String, nil]
+      def prefix_param_type(name)
         return 'Array' if name.start_with?('*') && !name.start_with?('**')
         return 'Hash'  if name.start_with?('**')
         return 'Proc'  if name.start_with?('&')
 
-        is_kw = name.end_with?(':')
-        node = parse_expr(default_str)
-        ty = Literals.type_from_literal(node, fallback_type: fallback_type)
+        nil
+      end
 
-        if is_kw && default_str.nil?
-          return (treat_options_keyword_as_hash && name == 'options:' ? 'Hash' : fallback_type)
+      # Infer type for a regular or keyword parameter with optional default.
+      #
+      # @note module_function: defines #inferred_param_type (visibility: private)
+      # @param [String] name parameter name
+      # @param [String?] default_str default expression source
+      # @param [String] fallback_type type returned when not special-cased
+      # @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 'Hash' if treat_options_keyword_as_hash && name == 'options:' && (default_str == '{}' || ty == 'Hash')
+        node = parse_expr(default_str)
+        ty = Literals.type_from_literal(node, fallback_type: fallback_type)
+
+        return 'Hash' if options_hash_keyword?(name, default_str, ty, treat_options_keyword_as_hash)
 
         ty
       end
 
+      # Return 'Hash' for a keyword parameter named 'options:' when special-cased, else fallback.
+      #
+      # @note module_function: defines #options_keyword_type (visibility: private)
+      # @param [String] name parameter name
+      # @param [Boolean] treat_options_keyword_as_hash whether to treat 'options:' as Hash
+      # @param [String] fallback_type type returned when not special-cased
+      # @return [String]
+      def options_keyword_type(name, treat_options_keyword_as_hash, fallback_type)
+        treat_options_keyword_as_hash && name == 'options:' ? 'Hash' : fallback_type
+      end
+
+      # Whether a keyword parameter named 'options:' with a hash default should be typed as Hash.
+      #
+      # @note module_function: defines #options_hash_keyword? (visibility: private)
+      # @param [String] name parameter name
+      # @param [String?] default_str default expression source
+      # @param [String] type inferred type
+      # @param [Boolean] treat_options_keyword_as_hash whether to treat 'options:' as Hash
+      # @return [Boolean]
+      def options_hash_keyword?(name, default_str, type, treat_options_keyword_as_hash)
+        treat_options_keyword_as_hash && name == 'options:' && (default_str == '{}' || type == 'Hash')
+      end
+
       # Parse a standalone expression for parameter-default inference.
       #
       # Returns nil if the expression is empty or cannot be parsed.
       #
-      # @note module_function: when included, also defines #parse_expr (instance visibility: private)
-      # @param [String, nil] src expression source
+      # @note module_function: defines #parse_expr (visibility: private)
+      # @param [String?] src expression source
       # @raise [Parser::SyntaxError]
-      # @return [Parser::AST::Node, nil]
+      # @return [Parser::AST::Node, nil] if Parser::SyntaxError
+      # @return [nil] if Parser::SyntaxError
       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
+      rescue Parser::SyntaxError # steep:ignore
         nil
       end
     end

data/lib/docscribe/infer/raises.rb

@@ -16,28 +16,18 @@ module Docscribe
       #
       # Returns unique exception names in discovery order.
       #
-      # @note module_function: when included, also defines #infer_raises_from_node (instance visibility: private)
+      # @note module_function: defines #infer_raises_from_node (visibility: private)
       # @param [Parser::AST::Node] node method or expression node to inspect
       # @return [Array<String>]
       def infer_raises_from_node(node)
-        raises = []
+        raises = [] #: Array[String]
 
         ASTWalk.walk(node) do |n|
           case n.type
           when :resbody
-            exc_list = n.children[0]
-            raises.concat(exception_names_from_rescue_list(exc_list))
-
+            raises.concat(exception_names_from_rescue_list(n.children[0]))
           when :send
-            recv, meth, *args = *n
-            next unless recv.nil? && %i[raise fail].include?(meth)
-
-            if args.empty?
-              raises << DEFAULT_ERROR
-            else
-              c = Names.const_full_name(args[0])
-              raises << (c || DEFAULT_ERROR)
-            end
+            collect_send_raise(raises, n)
           end
         end
 
@@ -51,7 +41,7 @@ module Docscribe
       # - `Foo` => `["Foo"]`
       # - `[Foo, Bar]` => `["Foo", "Bar"]`
       #
-      # @note module_function: when included, also defines #exception_names_from_rescue_list (instance visibility: private)
+      # @note module_function: defines #exception_names_from_rescue_list (visibility: private)
       # @param [Parser::AST::Node, nil] exc_list rescue exception list node
       # @return [Array<String>]
       def exception_names_from_rescue_list(exc_list)
@@ -63,6 +53,24 @@ module Docscribe
           [Names.const_full_name(exc_list) || DEFAULT_ERROR]
         end
       end
+
+      # Collect exception names from a `raise` or `fail` send node.
+      #
+      # @note module_function: defines #collect_send_raise (visibility: private)
+      # @param [Array<String>] raises accumulator
+      # @param [Parser::AST::Node] node send node
+      # @return [void]
+      def collect_send_raise(raises, node)
+        recv, meth, *args = *node
+        return unless recv.nil? && %i[raise fail].include?(meth)
+
+        if args.empty?
+          raises << DEFAULT_ERROR
+        else
+          c = Names.const_full_name(args[0])
+          raises << (c || DEFAULT_ERROR)
+        end
+      end
     end
   end
 end