docscribe 1.0.0

data/lib/docscribe/config.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+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
+
+    attr_reader :raw
+
+    # +Docscribe::Config#initialize+ -> Object
+    #
+    # Method documentation.
+    #
+    # @param [Hash] raw Param documentation.
+    # @return [Object]
+    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

data/lib/docscribe/infer.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+require 'parser/current'
+
+module Docscribe
+  module Infer
+    class << self
+      # +Docscribe::Infer.infer_raises_from_node+ -> Object
+      #
+      # Method documentation.
+      #
+      # @param [Object] node Param documentation.
+      # @return [Object]
+      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
+      end
+
+      # +Docscribe::Infer.infer_param_type+ -> Object
+      #
+      # Method documentation.
+      #
+      # @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
+      end
+
+      # +Docscribe::Infer.parse_expr+ -> Object
+      #
+      # Method documentation.
+      #
+      # @param [Object] src Param documentation.
+      # @raise [Parser::SyntaxError]
+      # @return [Object]
+      # @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
+        Parser::CurrentRuby.new.parse(buffer)
+      rescue Parser::SyntaxError
+        nil
+      end
+
+      # +Docscribe::Infer.infer_return_type+ -> Object
+      #
+      # Method documentation.
+      #
+      # @param [Object] method_source Param documentation.
+      # @raise [Parser::SyntaxError]
+      # @return [Object]
+      # @return [String] if Parser::SyntaxError
+      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 = Parser::CurrentRuby.new.parse(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'
+      end
+
+      # +Docscribe::Infer.infer_return_type_from_node+ -> Object
+      #
+      # Method documentation.
+      #
+      # @param [Object] node Param documentation.
+      # @return [Object]
+      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'
+      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
+      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
+      end
+
+      # +Docscribe::Infer.const_full_name+ -> Object
+      #
+      # Method documentation.
+      #
+      # @param [Object] n Param documentation.
+      # @return [Object]
+      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
+
+      # +Docscribe::Infer.type_from_literal+ -> Object
+      #
+      # Method documentation.
+      #
+      # @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
+      end
+
+      # +Docscribe::Infer.unify_types+ -> String
+      #
+      # Method documentation.
+      #
+      # @param [Object] a Param documentation.
+      # @param [Object] b Param documentation.
+      # @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'
+      end
+    end
+  end
+end