docscribe 1.1.0 → 1.2.0

data/lib/docscribe/config.rb

@@ -1,245 +1,35 @@
 # frozen_string_literal: true
 
 require 'yaml'
+require 'pathname'
+require 'psych'
 
 module Docscribe
   class Config
-    DEFAULT = {
-      'emit' => {
-        'header' => true,
-        'param_tags' => true,
-        'return_tag' => true,
-        'visibility_tags' => true,
-        'raise_tags' => true,
-        'rescue_conditional_returns' => true
-      },
-      'doc' => {
-        'default_message' => 'Method documentation.'
-      },
-      'methods' => {
-        'instance' => {
-          'public' => {},
-          'protected' => {},
-          'private' => {}
-        },
-        'class' => {
-          'public' => {},
-          'protected' => {},
-          'private' => {}
-        }
-      },
-      'inference' => {
-        'fallback_type' => 'Object',
-        'nil_as_optional' => true,
-        'treat_options_keyword_as_hash' => true
-      },
-      'filter' => {
-        'visibilities' => %w[public protected private],
-        'scopes' => %w[instance class],
-        'include' => [],
-        'exclude' => []
-      }
-    }.freeze
-
+    # Raw config hash after deep-merging user config with defaults.
+    #
+    # @!attribute [r] raw
+    #   @return [Hash]
     attr_reader :raw
 
-    # +Docscribe::Config#initialize+ -> Object
+    # Create a configuration object from a raw config hash.
     #
-    # Method documentation.
+    # Missing keys are filled from {DEFAULT} via deep merge.
     #
-    # @param [Hash] raw Param documentation.
-    # @return [Object]
+    # @param [Hash, nil] raw user-provided config hash
+    # @return [void]
     def initialize(raw = {})
       @raw = deep_merge(DEFAULT, raw || {})
     end
-
-    # +Docscribe::Config.load+ -> Object
-    #
-    # Method documentation.
-    #
-    # @param [nil] path Param documentation.
-    # @return [Object]
-    def self.load(path = nil)
-      raw = {}
-      if path && File.file?(path)
-        raw = YAML.safe_load_file(path, permitted_classes: [], aliases: true) || {}
-      elsif File.file?('docscribe.yml')
-        raw = YAML.safe_load_file('docscribe.yml', permitted_classes: [], aliases: true) || {}
-      end
-      new(raw)
-    end
-
-    # +Docscribe::Config#emit_header?+ -> Object
-    #
-    # Method documentation.
-    #
-    # @return [Object]
-    def emit_header?
-      fetch_bool(%w[emit header], true)
-    end
-
-    # +Docscribe::Config#emit_param_tags?+ -> Object
-    #
-    # Method documentation.
-    #
-    # @return [Object]
-    def emit_param_tags?
-      fetch_bool(%w[emit param_tags], true)
-    end
-
-    # +Docscribe::Config#emit_visibility_tags?+ -> Object
-    #
-    # Method documentation.
-    #
-    # @return [Object]
-    def emit_visibility_tags?
-      fetch_bool(%w[emit visibility_tags], true)
-    end
-
-    # +Docscribe::Config#emit_raise_tags?+ -> Object
-    #
-    # Method documentation.
-    #
-    # @return [Object]
-    def emit_raise_tags?
-      fetch_bool(%w[emit raise_tags], true)
-    end
-
-    # +Docscribe::Config#emit_rescue_conditional_returns?+ -> Object
-    #
-    # Method documentation.
-    #
-    # @return [Object]
-    def emit_rescue_conditional_returns?
-      fetch_bool(%w[emit rescue_conditional_returns], true)
-    end
-
-    # +Docscribe::Config#emit_return_tag?+ -> Object
-    #
-    # Method documentation.
-    #
-    # @param [Object] scope Param documentation.
-    # @param [Object] visibility Param documentation.
-    # @return [Object]
-    def emit_return_tag?(scope, visibility)
-      method_override_bool(scope, visibility, 'return_tag',
-                           default: fetch_bool(%w[emit return_tag], true))
-    end
-
-    # +Docscribe::Config#default_message+ -> Object
-    #
-    # Method documentation.
-    #
-    # @param [Object] scope Param documentation.
-    # @param [Object] visibility Param documentation.
-    # @return [Object]
-    def default_message(scope, visibility)
-      method_override_str(scope, visibility, 'default_message',
-                          default: raw.dig('doc', 'default_message') || 'Method documentation.')
-    end
-
-    # +Docscribe::Config#fallback_type+ -> Object
-    #
-    # Method documentation.
-    #
-    # @return [Object]
-    def fallback_type
-      raw.dig('inference', 'fallback_type') || 'Object'
-    end
-
-    # +Docscribe::Config#nil_as_optional?+ -> Object
-    #
-    # Method documentation.
-    #
-    # @return [Object]
-    def nil_as_optional?
-      fetch_bool(%w[inference nil_as_optional], true)
-    end
-
-    # +Docscribe::Config#treat_options_keyword_as_hash?+ -> Object
-    #
-    # Method documentation.
-    #
-    # @return [Object]
-    def treat_options_keyword_as_hash?
-      fetch_bool(%w[inference treat_options_keyword_as_hash], true)
-    end
-
-    private
-
-    # +Docscribe::Config#method_override_bool+ -> Object
-    #
-    # Method documentation.
-    #
-    # @private
-    # @param [Object] scope Param documentation.
-    # @param [Object] vis Param documentation.
-    # @param [Object] key Param documentation.
-    # @param [Object] default Param documentation.
-    # @return [Object]
-    def method_override_bool(scope, vis, key, default:)
-      node = raw.dig('methods', scope_to_key(scope), vis.to_s, key)
-      node.nil? ? default : !!node
-    end
-
-    # +Docscribe::Config#fetch_bool+ -> Object
-    #
-    # Method documentation.
-    #
-    # @private
-    # @param [Object] path Param documentation.
-    # @param [Object] default Param documentation.
-    # @return [Object]
-    def fetch_bool(path, default)
-      node = raw
-      path.each { |k| node = node[k] if node }
-      node.nil? ? default : !!node
-    end
-
-    # +Docscribe::Config#method_override_str+ -> Object
-    #
-    # Method documentation.
-    #
-    # @private
-    # @param [Object] scope Param documentation.
-    # @param [Object] vis Param documentation.
-    # @param [Object] key Param documentation.
-    # @param [Object] default Param documentation.
-    # @return [Object]
-    def method_override_str(scope, vis, key, default:)
-      node = raw.dig('methods', scope_to_key(scope), vis.to_s, key)
-      node.nil? ? default : node.to_s
-    end
-
-    # +Docscribe::Config#scope_to_key+ -> String
-    #
-    # Method documentation.
-    #
-    # @private
-    # @param [Object] scope Param documentation.
-    # @return [String]
-    def scope_to_key(scope)
-      scope == :class ? 'class' : 'instance'
-    end
-
-    # +Docscribe::Config#deep_merge+ -> Object
-    #
-    # Method documentation.
-    #
-    # @private
-    # @param [Object] hash1 Param documentation.
-    # @param [Object] hash2 Param documentation.
-    # @return [Object]
-    def deep_merge(hash1, hash2)
-      return hash1 unless hash2
-
-      hash1.merge(hash2) do |_, v1, v2|
-        if v1.is_a?(Hash) && v2.is_a?(Hash)
-          deep_merge(v1, v2)
-        else
-          v2
-        end
-      end
-    end
   end
 end
+
+require_relative 'config/defaults'
+require_relative 'config/utils'
+require_relative 'config/loader'
+require_relative 'config/template'
+require_relative 'config/emit'
+require_relative 'config/filtering'
+require_relative 'config/rbs'
+require_relative 'config/sorting'
+require_relative 'config/sorbet'

data/lib/docscribe/infer/ast_walk.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Infer
+    # AST traversal helpers for parser AST nodes.
+    module ASTWalk
+      module_function
+
+      # Depth-first walk over a parser AST.
+      #
+      # Yields each node exactly once, descending recursively through child nodes.
+      # Non-AST values are ignored.
+      #
+      # @note module_function: when included, also defines #walk (instance visibility: private)
+      # @param [Parser::AST::Node, nil] node root AST node
+      # @param [Proc] block visitor block
+      # @return [void]
+      def walk(node, &block)
+        return unless node.is_a?(Parser::AST::Node)
+
+        yield node
+        node.children.each do |ch|
+          walk(ch, &block) if ch.is_a?(Parser::AST::Node)
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/infer/constants.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Infer
+    # Default fallback type used when inference cannot be certain.
+    FALLBACK_TYPE = 'Object'
+
+    # Ruby's implicit rescue target for bare `rescue`.
+    DEFAULT_ERROR = 'StandardError'
+  end
+end

data/lib/docscribe/infer/literals.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Infer
+    # Literal inference: map simple AST literals to type names.
+    module Literals
+      module_function
+
+      # Infer a type name from a literal-like AST node.
+      #
+      # Supports common literal/value node types such as:
+      # - integers, floats, strings, symbols
+      # - booleans and nil
+      # - arrays, hashes, regexps
+      # - constants
+      # - `Foo.new` constructor calls
+      #
+      # 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)
+      # @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
+      end
+    end
+  end
+end

data/lib/docscribe/infer/names.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Infer
+    # Constant-name helpers for turning AST nodes into fully qualified names.
+    module Names
+      module_function
+
+      # Convert a `:const` / `:cbase` AST node into a fully qualified constant name.
+      #
+      # Examples:
+      # - `Foo` => `"Foo"`
+      # - `Foo::Bar` => `"Foo::Bar"`
+      # - `::Foo::Bar` => `"::Foo::Bar"`
+      #
+      # 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
+      # @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
+      end
+    end
+  end
+end

data/lib/docscribe/infer/params.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Infer
+    # Parameter type inference.
+    module Params
+      module_function
+
+      # Infer a parameter type from an internal parameter name representation and
+      # an optional default expression.
+      #
+      # Handles:
+      # - positional/rest/block parameter prefixes (`*`, `**`, `&`)
+      # - keyword params with and without defaults
+      # - 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)
+      # @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] 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)
+        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)
+
+        if is_kw && default_str.nil?
+          return (treat_options_keyword_as_hash && name == 'options:' ? 'Hash' : fallback_type)
+        end
+
+        return 'Hash' if treat_options_keyword_as_hash && name == 'options:' && (default_str == '{}' || ty == 'Hash')
+
+        ty
+      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
+      # @raise [Parser::SyntaxError]
+      # @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
+      end
+    end
+  end
+end

data/lib/docscribe/infer/raises.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Infer
+    # Exception inference from AST (`raise`/`fail` calls and `rescue` clauses).
+    module Raises
+      module_function
+
+      # Infer exception class names raised or rescued within a node.
+      #
+      # Sources considered:
+      # - `rescue Foo, Bar`
+      # - bare `rescue` (=> StandardError)
+      # - `raise Foo`
+      # - bare `raise` / `fail` (=> StandardError)
+      #
+      # Returns unique exception names in discovery order.
+      #
+      # @note module_function: when included, also defines #infer_raises_from_node (instance visibility: private)
+      # @param [Parser::AST::Node] node method or expression node to inspect
+      # @return [Array<String>]
+      def infer_raises_from_node(node)
+        raises = []
+
+        ASTWalk.walk(node) do |n|
+          case n.type
+          when :resbody
+            exc_list = n.children[0]
+            raises.concat(exception_names_from_rescue_list(exc_list))
+
+          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
+          end
+        end
+
+        raises.uniq
+      end
+
+      # Extract exception class names from a rescue exception list.
+      #
+      # Examples:
+      # - nil => `[StandardError]`
+      # - `Foo` => `["Foo"]`
+      # - `[Foo, Bar]` => `["Foo", "Bar"]`
+      #
+      # @note module_function: when included, also defines #exception_names_from_rescue_list (instance visibility: private)
+      # @param [Parser::AST::Node, nil] exc_list rescue exception list node
+      # @return [Array<String>]
+      def exception_names_from_rescue_list(exc_list)
+        if exc_list.nil?
+          [DEFAULT_ERROR]
+        elsif exc_list.type == :array
+          exc_list.children.map { |e| Names.const_full_name(e) || DEFAULT_ERROR }
+        else
+          [Names.const_full_name(exc_list) || DEFAULT_ERROR]
+        end
+      end
+    end
+  end
+end