docscribe 1.4.1 → 1.5.0

data/lib/docscribe/types/sorbet/source_provider.rb

@@ -10,11 +10,12 @@ module Docscribe
       # This provider parses the source being rewritten and indexes any leading
       # `sig` declarations it can resolve through the RBS RBI prototype bridge.
       class SourceProvider < BaseProvider
+        # Initialize
+        #
         # @param [String] source Ruby source containing inline `sig` declarations
         # @param [String] file source label used in diagnostics/debug warnings
         # @param [Boolean] collapse_generics whether generic container types
-        #   should be simplified during formatting
-        # @return [Object]
+        # @return [void]
         def initialize(source:, file:, collapse_generics: false)
           super(collapse_generics: collapse_generics)
           load_from_string(source, label: file)

data/lib/docscribe/types/yard/formatter.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative 'types'
+
+module Docscribe
+  module Types
+    module Yard
+      # Converts YARD type AST to RBS type strings
+      module Formatter
+        class << self
+          # @param [Docscribe::Types::Yard::node?] node
+          # @return [String]
+          def to_rbs(node) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+            return 'untyped' if node.nil?
+
+            case node
+            when Named then format_named(node)
+            when Generic then format_generic(node)
+            when Union then format_union(node)
+            when Intersection then format_intersection(node)
+            when Optional then format_optional(node)
+            when Tuple then format_tuple(node)
+            when HashMap then format_hash_map(node)
+            when Literal then format_literal(node)
+            else 'untyped'
+            end
+          end
+
+          private
+
+          # @private
+          # @param [Docscribe::Types::Yard::Named] node
+          # @return [String]
+          def format_named(node)
+            case node.name
+            when 'Boolean' then 'bool'
+            when 'Object' then 'untyped'
+            else node.name
+            end
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::Generic] node
+          # @return [String]
+          def format_generic(node)
+            "#{node.base}[#{node.args.map { |a| to_rbs(a) }.join(', ')}]"
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::Union] node
+          # @return [String]
+          def format_union(node)
+            node.types.map { |t| to_rbs(t) }.join(' | ')
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::Intersection] node
+          # @return [String]
+          def format_intersection(node)
+            node.types.map { |t| to_rbs(t) }.join(' & ')
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::Optional] node
+          # @return [String]
+          def format_optional(node)
+            "#{to_rbs(node.type)}?"
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::Tuple] node
+          # @return [String]
+          def format_tuple(node)
+            "[#{node.types.map { |t| to_rbs(t) }.join(', ')}]"
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::HashMap] node
+          # @return [String]
+          def format_hash_map(node)
+            "Hash[#{to_rbs(node.key_type)}, #{to_rbs(node.value_type)}]"
+          end
+
+          # @private
+          # @param [Docscribe::Types::Yard::Literal] node
+          # @return [String]
+          def format_literal(node)
+            case node.value
+            when 'void' then 'void'
+            when 'nil' then 'nil'
+            when 'self' then 'self'
+            when 'true', 'false' then 'bool'
+            else 'untyped'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/types/yard/parser.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require_relative 'types'
+
+module Docscribe
+  module Types
+    # YARD type parser
+    module Yard
+      class << self
+        # @param [String?] string
+        # @return [Docscribe::Types::Yard::node?]
+        def parse(string)
+          return nil if string.nil? || string.strip.empty?
+
+          Parser.new(string).parse
+        end
+      end
+
+      # Parses YARD type strings into an AST
+      class Parser
+        # @param [String] string
+        # @return [void]
+        def initialize(string)
+          @s = string.strip
+          @i = 0
+        end
+
+        # @return [Docscribe::Types::Yard::node]
+        def parse
+          skip_space
+          node = parse_union
+          skip_space
+          node
+        end
+
+        private
+
+        # @private
+        # @return [Docscribe::Types::Yard::node]
+        def parse_union
+          types = [parse_intersection]
+          skip_space
+          while @i < @s.length && @s[@i] == ','
+            @i += 1
+            skip_space
+            types << parse_intersection
+            skip_space
+          end
+          types.size == 1 ? types.first : Union.new(types: types)
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::node]
+        def parse_intersection
+          types = [parse_optional]
+          skip_space
+          while @i < @s.length && @s[@i] == '&'
+            @i += 1
+            skip_space
+            types << parse_optional
+            skip_space
+          end
+          types.size == 1 ? types.first : Intersection.new(types: types)
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::node]
+        def parse_optional
+          type = parse_primary
+          skip_space
+          if @i < @s.length && @s[@i] == '?'
+            @i += 1
+            Optional.new(type: type)
+          else
+            type
+          end
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::node]
+        def parse_primary
+          skip_space
+          case peek
+          when '(' then parse_tuple
+          when '{' then parse_hash_map
+          when '#' then parse_duck_type
+          else
+            parse_named_type
+          end
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::Named, Docscribe::Types::Yard::Literal, Docscribe::Types::Yard::Generic, Docscribe::Types::Yard::HashMap]
+        def parse_named_type
+          name = scan_name
+          return Literal.new(value: name) if literal?(name)
+
+          skip_space
+          if @i < @s.length && @s[@i] == '<'
+            parse_generic(Named.new(name: name))
+          elsif @i < @s.length && @s[@i] == '{'
+            parse_named_hash_map
+          else
+            Named.new(name: name)
+          end
+        end
+
+        # @private
+        # @param [Docscribe::Types::Yard::Named] base
+        # @return [Docscribe::Types::Yard::Generic]
+        def parse_generic(base)
+          @i += 1
+          args = parse_generic_args
+          @i += 1 if @i < @s.length && @s[@i] == '>'
+          Generic.new(base: base.name, args: args)
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::node]
+        def parse_generic_arg
+          types = [parse_intersection]
+          skip_space
+          while @i < @s.length && @s[@i] == '|'
+            @i += 1
+            skip_space
+            types << parse_intersection
+            skip_space
+          end
+          types.size == 1 ? types.first : Union.new(types: types)
+        end
+
+        # @private
+        # @return [Array<Docscribe::Types::Yard::node>]
+        def parse_generic_args
+          args = [] #: Array[untyped]
+          skip_space
+          while @i < @s.length && @s[@i] != '>'
+            args << parse_generic_arg
+            skip_space
+            next unless @i < @s.length && @s[@i] == ','
+
+            @i += 1
+            skip_space
+          end
+          args
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::Tuple]
+        def parse_tuple
+          @i += 1
+          types = [] #: Array[untyped]
+          while @i < @s.length && @s[@i] != ')'
+            types << parse_tuple_element
+            @i += 1 and skip_space if @s[@i] == ','
+          end
+          @i += 1 if @s[@i] == ')'
+          Tuple.new(types: types)
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::node]
+        def parse_tuple_element
+          type = parse_intersection
+          skip_space
+          if @i < @s.length && @s[@i] == '?'
+            @i += 1
+            Optional.new(type: type)
+          else
+            type
+          end
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::HashMap]
+        def parse_hash_map
+          @i += 1
+          key = parse_union
+          @i += 2 if @s[@i..(@i + 1)] == '=>'
+          value = parse_union
+          @i += 1 if @s[@i] == '}'
+          HashMap.new(key_type: key, value_type: value)
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::HashMap]
+        def parse_named_hash_map
+          parse_hash_map
+        end
+
+        # @private
+        # @return [Docscribe::Types::Yard::Duck]
+        def parse_duck_type
+          methods = [] #: Array[String]
+          while @i < @s.length && @s[@i] == '#'
+            @i += 1
+            name = scan_name
+            methods << name
+            skip_space
+          end
+          Duck.new(method_names: methods)
+        end
+
+        # @private
+        # @return [String]
+        def scan_name
+          start = @i
+          @i += 1 while @i < @s.length && name_char?(@s[@i])
+          @s[start...@i]
+        end
+
+        # @private
+        # @param [String] char
+        # @return [Boolean]
+        def name_char?(char)
+          char.match?(/[a-zA-Z0-9_:]/)
+        end
+
+        # @private
+        # @param [String] name
+        # @return [Boolean]
+        def literal?(name)
+          %w[void nil self true false].include?(name)
+        end
+
+        # @private
+        # @return [void]
+        def skip_space
+          @i += 1 while @i < @s.length && @s[@i].match?(/\s/)
+        end
+
+        # @private
+        # @return [String?]
+        def peek
+          @i < @s.length ? @s[@i] : nil
+        end
+      end
+    end
+  end
+end

data/lib/docscribe/types/yard/types.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Docscribe
+  module Types
+    module Yard
+      # @!attribute [rw] name
+      #   @return [String]
+      #   @param [String] value
+      Named = Struct.new(:name, keyword_init: true)
+      # @!attribute [rw] base
+      #   @return [String]
+      #   @param [String] value
+      #
+      # @!attribute [rw] args
+      #   @return [Array<Docscribe::Types::Yard::node>]
+      #   @param [Array<Docscribe::Types::Yard::node>] value
+      Generic = Struct.new(:base, :args, keyword_init: true)
+      # @!attribute [rw] types
+      #   @return [Array<Docscribe::Types::Yard::node>]
+      #   @param [Array<Docscribe::Types::Yard::node>] value
+      Union = Struct.new(:types, keyword_init: true)
+      # @!attribute [rw] types
+      #   @return [Array<Docscribe::Types::Yard::node>]
+      #   @param [Array<Docscribe::Types::Yard::node>] value
+      Intersection = Struct.new(:types, keyword_init: true)
+      # @!attribute [rw] type
+      #   @return [Docscribe::Types::Yard::node]
+      #   @param [Docscribe::Types::Yard::node] value
+      Optional = Struct.new(:type, keyword_init: true)
+      # @!attribute [rw] types
+      #   @return [Array<Docscribe::Types::Yard::node>]
+      #   @param [Array<Docscribe::Types::Yard::node>] value
+      Tuple = Struct.new(:types, keyword_init: true)
+      # @!attribute [rw] key_type
+      #   @return [Docscribe::Types::Yard::node]
+      #   @param [Docscribe::Types::Yard::node] value
+      #
+      # @!attribute [rw] value_type
+      #   @return [Docscribe::Types::Yard::node]
+      #   @param [Docscribe::Types::Yard::node] value
+      HashMap = Struct.new(:key_type, :value_type, keyword_init: true)
+      # @!attribute [rw] method_names
+      #   @return [Array<String>]
+      #   @param [Array<String>] value
+      Duck = Struct.new(:method_names, keyword_init: true)
+      # @!attribute [rw] value
+      #   @return [String]
+      #   @param [String] value
+      Literal = Struct.new(:value, keyword_init: true)
+    end
+  end
+end

data/lib/docscribe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docscribe
-  VERSION = '1.4.1'
+  VERSION = '1.5.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docscribe
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.5.0
 platform: ruby
 authors:
 - unurgunite
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: irb-autosuggestions
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -145,11 +159,19 @@ files:
 - exe/docscribe
 - lib/docscribe.rb
 - lib/docscribe/cli.rb
+- lib/docscribe/cli/check_for_comments.rb
 - lib/docscribe/cli/config_builder.rb
+- lib/docscribe/cli/formatters.rb
+- lib/docscribe/cli/formatters/json.rb
+- lib/docscribe/cli/formatters/sarif.rb
+- lib/docscribe/cli/formatters/text.rb
 - lib/docscribe/cli/generate.rb
 - lib/docscribe/cli/init.rb
 - lib/docscribe/cli/options.rb
+- lib/docscribe/cli/rbs_gen.rb
 - lib/docscribe/cli/run.rb
+- lib/docscribe/cli/sigs.rb
+- lib/docscribe/cli/update_types.rb
 - lib/docscribe/config.rb
 - lib/docscribe/config/defaults.rb
 - lib/docscribe/config/emit.rb
@@ -190,6 +212,9 @@ files:
 - lib/docscribe/types/sorbet/base_provider.rb
 - lib/docscribe/types/sorbet/rbi_provider.rb
 - lib/docscribe/types/sorbet/source_provider.rb
+- lib/docscribe/types/yard/formatter.rb
+- lib/docscribe/types/yard/parser.rb
+- lib/docscribe/types/yard/types.rb
 - lib/docscribe/version.rb
 homepage: https://github.com/unurgunite/docscribe
 licenses:
@@ -199,6 +224,13 @@ metadata:
   source_code_uri: https://github.com/unurgunite/docscribe
   changelog_uri: https://github.com/unurgunite/docscribe/blob/master/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message: |
+  You installed docscribe 1.5.0. Your future self (and your team) thank you.
+
+    $ docscribe --help
+
+  Happy documenting!
+  https://github.com/unurgunite/docscribe
 rdoc_options: []
 require_paths:
 - lib
@@ -213,7 +245,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.12
+rubygems_version: 4.0.13
 specification_version: 4
 summary: Auto-generate inline YARD documentation for Ruby by analyzing code AST. Supports
   RBS and Sorbet type signatures.