sord 3.0.0.beta.2 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a96fafb7c0a8a07c5462a5138b836837e65e2dd14f68d9f51ebd502170c84f9
-  data.tar.gz: 8d82f8e1848f0422cdd4729933f867f78daffeeb226a54b826d5fd75660e73ac
+  metadata.gz: dc4c58d9ccea9406b38e20c3d6d92357a962e49aa91884b421a496d9302566d2
+  data.tar.gz: cdcc1158ce99895796423ba6b833f68e261e09d6a61b6892104d5948a3c64625
 SHA512:
-  metadata.gz: f885ba62dd5b528f63e644d6cc6d000b33f372ea07ec7f372b1231464f5989e5353db508d553d997cdb772dc5ad075cf8fc3d37ede901f16efaa031438b59474
-  data.tar.gz: 859a054fdf1e1609035862c4f95d3b03622dcf7fe97c97afae120e80168102af0806dd8463aa00815f2e294cb0c895f511a9387b4f22e8464dc8aa9dc4f9a333
+  metadata.gz: 984cf951dc9a0ee9ea6180402e60817c866d171f313c102a34f4d8d20cc36ca95d11c24082b46810b70eb35fa6e67643bd4b9e3007889ec7a87f25fa0db3c44d
+  data.tar.gz: b9f25ab1affc00c9c2a25b90db7735c1ee8c89e53cd98ef1a04087b58d9efe2f8878e54f6a1cbdc913c38142507aaff74a9e437151cd74fd5f7b612cbab4f38f

data/.github/workflows/ruby.yml

@@ -0,0 +1,22 @@
+name: Run tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        ruby: [2.4, 2.5, 2.6, 2.7, 3.0]
+    continue-on-error: false
+      
+    runs-on: ubuntu-latest    
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+    - name: Install dependencies
+      run: bundle install
+    - name: Run tests
+      run: bundle exec rake

data/CHANGELOG.md

@@ -3,12 +3,30 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
-## [3.0.0.beta.2] - 2020-10-05
+## [4.0.0] - 2022-07-19
 ### Added
-- Sord is no longer limited to a known set of generics, and will instead
-  generate `Parlour::Types::Generic` types for user-defined generics.
+- Constants are now assigned types when generating RBS, using `@return`.
+- Class-level `attr_accessor`s are converted to methods when generating RBS.
+- Added the `--exclude-untyped` flag, which skips generating type signatures for methods with
+  `untyped` return values.
 
-## [3.0.0.beta.1] - 2020-09-16
+### Changed
+- If YARD tags are present for a block, but there is no block param (such as when using `yield`),
+  the type signature now includes the documented block. This could be a **breaking change** leading
+  to type errors in existing code where such methods are called.
+
+### Fixed
+- Added workaround for YARD syntax error when a default parameter value begins with a unary minus
+- Name resolutions from the root (e.g. `::X`) now behave correctly; previously they may have
+  selected a class named `X` nested within another namespace. This may be a **breaking change** if
+  any part of your generated type signatures was relying on the old, buggy behaviour.
+
+## [3.0.1] - 2020-12-28
+### Fixed
+- Fixed `SortedSet` crash on Ruby 3
+- Fixed incorrect `extend` order on YARD 0.9.26
+
+## [3.0.0] - 2020-12-26
 ### Added
 - Sord now uses the Parlour 5 beta's RBS generation to generate RBS files!
 - Added `--rbi` and `--rbs` to select an output format to use (if neither given,
@@ -23,6 +41,32 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `#return [nil]` no longer produces a union of zero types, instead becoming
   `void` for method returns or `untyped` for attributes.
 
+
+<details>
+  <summary>3.0.0 pre-releases</summary>
+
+  ## [3.0.0.beta.2] - 2020-10-05
+  ### Added
+  - Sord is no longer limited to a known set of generics, and will instead
+    generate `Parlour::Types::Generic` types for user-defined generics.
+
+  ## [3.0.0.beta.1] - 2020-09-16
+  ### Added
+  - Sord now uses the Parlour 5 beta's RBS generation to generate RBS files!
+  - Added `--rbi` and `--rbs` to select an output format to use (if neither given,
+    tries to infer from file extension).
+
+  ### Changed
+  - `RbiGenerator` has been renamed to `Generator`.
+  - `TypeConverter#yard_to_sorbet` is now `TypeConverter#yard_to_parlour`, and
+    returns `Parlour::Types::Type` instances rather than strings.
+
+  ### Fixed
+  - `#return [nil]` no longer produces a union of zero types, instead becoming
+    `void` for method returns or `untyped` for attributes.
+
+</details>
+
 ## [2.0.0] - 2020-03-16
 ### Added
 - Sord now supports generating `attr_accessor`, `attr_reader` and `attr_writer`

data/README.md

@@ -12,6 +12,8 @@ type signatures you need!
 Sord is the perfect way to jump-start the adoption of types in your project,
 whether you plan to use Sorbet's RBI format or Ruby 3/Steep's RBS format.
 
+**Try Sord online at: [sord.aaronc.cc](https://sord.aaronc.cc)**
+
 Sord has the following features:
   - Automatically generates signatures for modules, classes and methods
   - Support for multiple parameter or return types (`T.any`/`|`)
@@ -81,6 +83,8 @@ Sord also takes some flags to alter the generated file:
     take a comma-separated list of logging kinds, for example `omit,infer`.
     When using `--include-messages`, the `done` kind is included by default.
     (You cannot specify both `--include-messages` and `--exclude-messages`.)
+  - `--exclude-untyped`: Exclude methods and attributes with untyped return
+    values.
 
 ## Example
 

data/exe/sord

@@ -23,6 +23,7 @@ command :gen do |c|
   c.option '--keep-original-comments', 'Retains original YARD comments rather than converting them to Markdown'
   c.option '--skip-constants', 'Excludes constants from generated file'
   c.option '--use-original-initialize-return', 'Uses the specified return type for #initialize rather than void'
+  c.option '--exclude-untyped', 'Exclude methods and attributes with untyped return values'
 
   c.action do |args, options|
     options.default(
@@ -38,16 +39,17 @@ command :gen do |c|
       keep_original_comments: false,
       skip_constants: false,
       use_original_initialize_return: false,
+      exclude_untyped: false,
     )
 
     if args.length != 1
       Sord::Logging.error('Must specify filename')
       exit 1
     end
-    
+
     plugin_options = options.__hash__
-    plugin_options[:exclude_options] = plugin_options[:exclude_options]&.split(',')
-    plugin_options[:include_options] = plugin_options[:include_options]&.split(',')
+    plugin_options[:exclude_messages] = plugin_options[:exclude_messages]&.split(',')
+    plugin_options[:include_messages] = plugin_options[:include_messages]&.split(',')
 
     if !(plugin_options[:rbi] || plugin_options[:rbs])
       if args.first

data/lib/sord/generator.rb

@@ -8,16 +8,16 @@ require 'rainbow'
 module Sord
   # Converts the current working directory's YARD registry into an type
   # signature file.
-  class Generator    
+  class Generator
     VALID_MODES = [:rbi, :rbs]
 
-    # @return [Integer] The number of objects this generator has processed so 
+    # @return [Integer] The number of objects this generator has processed so
     #   far.
     def object_count
       @namespace_count + @method_count
     end
 
-    # @return [Array<Array(String, YARD::CodeObjects::Base, Integer)>] The 
+    # @return [Array<Array(String, YARD::CodeObjects::Base, Integer)>] The
     #   errors encountered by by the generator. Each element is of the form
     #   [message, item, line].
     attr_reader :warnings
@@ -55,10 +55,19 @@ module Sord
       @keep_original_comments = options[:keep_original_comments]
       @skip_constants = options[:skip_constants]
       @use_original_initialize_return = options[:use_original_initialize_return]
+      @exclude_untyped = options[:exclude_untyped]
 
       # Hook the logger so that messages are added as comments
-      Logging.add_hook do |type, msg, item|
-        @current_object.add_comment_to_next_child("sord #{type} - #{msg}")
+      Logging.add_hook do |type, msg, item, **opts|
+        # Hack: the "exclude untyped" log message needs to print somewhere, but
+        # if there's no future object for that comment to associate with, it'll
+        # never be printed!
+        # Instead, add an arbitrary containing the comment 
+        if opts[:immediate]
+          @current_object.create_arbitrary(code: "# sord #{type} - #{msg}") 
+        else
+          @current_object.add_comment_to_next_child("sord #{type} - #{msg}")
+        end
       end if options[:sord_comments]
 
       # Hook the logger so that warnings are collected
@@ -88,8 +97,17 @@ module Sord
       item.instance_mixins.reverse_each do |i|
         @current_object.create_include(i.path.to_s)
       end
-      item.class_mixins.reverse_each do |e|
-        @current_object.create_extend(e.path.to_s)
+
+      # YARD 0.9.26 makes extends appear in the same order as code
+      # (includes are still reversed)
+      if Gem::Version.new(YARD::VERSION) >= Gem::Version.new("0.9.26")
+        item.class_mixins.each do |e|
+          @current_object.create_extend(e.path.to_s)
+        end
+      else
+        item.class_mixins.reverse_each do |e|
+          @current_object.create_extend(e.path.to_s)
+        end
       end
 
       item.instance_mixins.length + item.class_mixins.length
@@ -101,7 +119,7 @@ module Sord
     def add_constants(item)
       inserted_constant_names = Set.new
 
-      item.constants(included: false).each do |constant|      
+      item.constants(included: false).each do |constant|
         # Take a constant (like "A::B::CONSTANT"), split it on each '::', and
         # set the constant name to the last string in the array.
         constant_name = constant.to_s.split('::').last
@@ -110,7 +128,7 @@ module Sord
           next
         end
         inserted_constant_names << constant_name
-        
+
         # Add the constant to the current object being generated.
         case @mode
         when :rbi
@@ -118,7 +136,19 @@ module Sord
             c.add_comments(constant.docstring.all.split("\n"))
           end
         when :rbs
-          @current_object.create_constant(constant_name, type: Parlour::Types::Untyped.new) do |c|
+          return_tags = constant.tags('return')
+          returns = if return_tags.empty?
+            Logging.omit("no YARD return type given, using untyped", constant)
+            Parlour::Types::Untyped.new
+          else
+            TypeConverter.yard_to_parlour(
+              return_tags.map(&:types).flatten,
+              constant,
+              @replace_errors_with_untyped,
+              @replace_unresolved_with_untyped
+            )
+          end
+          @current_object.create_constant(constant_name, type: returns) do |c|
             c.add_comments(constant.docstring.all.split("\n"))
           end
         end
@@ -234,17 +264,23 @@ module Sord
         if meth.is_attribute?
           next
         end
-      
+
         # Sort parameters
         meth.parameters.reverse.sort! { |pair1, pair2| sort_params(pair1, pair2) }
-        # This is better than iterating over YARD's "@param" tags directly 
+        # This is better than iterating over YARD's "@param" tags directly
         # because it includes parameters without documentation
         # (The gsubs allow for better splat-argument compatibility)
         parameter_names_and_defaults_to_tags = meth.parameters.map do |name, default|
-          [[name, default], meth.tags('param')
+          [[name, fix_default_if_unary_minus(default)], meth.tags('param')
             .find { |p| p.name&.gsub('*', '')&.gsub(':', '') == name.gsub('*', '').gsub(':', '') }]
         end.to_h
 
+        # Add block param if there is no named param but YARD tags are present
+        if !parameter_names_and_defaults_to_tags.any? { |((name, _), _)| name.start_with? '&' } \
+            && (meth.tags('yieldparam').any? || meth.tag('yieldreturn'))
+          parameter_names_and_defaults_to_tags[['&blk']] = nil
+        end
+
         parameter_types = parameter_names_and_defaults_to_tags.map do |name_and_default, tag|
           name = name_and_default.first
 
@@ -281,10 +317,10 @@ module Sord
               if parameter_names_and_defaults_to_tags.length == 1 \
                 && meth.tags('param').length == 1 \
                 && meth.tag('param').types
-  
+
                 Logging.infer("argument name in single @param inferred as #{parameter_names_and_defaults_to_tags.first.first.first.inspect}", meth)
                 next TypeConverter.yard_to_parlour(meth.tag('param').types, meth, @replace_errors_with_untyped, @replace_unresolved_with_untyped)
-              else  
+              else
                 Logging.omit("no YARD type given for #{name.inspect}, using untyped", meth)
                 next Parlour::Types::Untyped.new
               end
@@ -297,7 +333,7 @@ module Sord
             end
             inferred_type = TypeConverter.yard_to_parlour(
               return_types, meth, @replace_errors_with_untyped, @replace_unresolved_with_untyped)
-            
+
             Logging.infer("inferred type of parameter #{name.inspect} as #{inferred_type.describe} using getter's return type", meth)
             inferred_type
           else
@@ -332,7 +368,7 @@ module Sord
         parlour_params = parameter_names_and_defaults_to_tags
           .zip(parameter_types)
           .map do |((name, default), _), type|
-            # If the default is "nil" but the type is not nilable, then it 
+            # If the default is "nil" but the type is not nilable, then it
             # should become nilable
             # (T.untyped can include nil, so don't alter that)
             type = Parlour::Types::Nilable.new(type) \
@@ -360,10 +396,15 @@ module Sord
           end
           .compact
 
+        if @exclude_untyped && parlour_params.all? { |p| p.type.is_a?(Parlour::Types::Untyped) } && returns.is_a?(Parlour::Types::Untyped)
+          Logging.omit("excluding untyped", meth, immediate: true)
+          next
+        end
+
         case @mode
         when :rbi
           @current_object.create_method(
-            meth.name.to_s, 
+            meth.name.to_s,
             parameters: parlour_params,
             returns: returns,
             class_method: meth.scope == :class
@@ -382,7 +423,7 @@ module Sord
           ) do |m|
             add_comments(meth, m)
           end
-        end  
+        end
       end
     end
 
@@ -436,6 +477,11 @@ module Sord
             kind = :writer
           end
 
+          if @exclude_untyped && parlour_type.is_a?(Parlour::Types::Untyped)
+            Logging.omit("excluding untyped attribute", reader || writer, immediate: true)
+            next
+          end
+
           case @mode
           when :rbi
             @current_object.create_attribute(
@@ -448,7 +494,31 @@ module Sord
             end
           when :rbs
             if attr_loc == :class
-              Logging.warn("RBS doesn't support class attributes, dropping", reader || writer)
+              # RBS doesn't support class attr_accessors so create individual methods
+
+              if reader
+                @current_object.create_method(
+                  name.to_s,
+                  [Parlour::RbsGenerator::MethodSignature.new([], parlour_type)],
+                  class_method: true
+                ) do |m|
+                  add_comments(reader, m)
+                end
+              end
+
+              if writer
+                @current_object.create_method(
+                  "#{name}=",
+                  [Parlour::RbsGenerator::MethodSignature.new([Parlour::RbsGenerator::Parameter.new(
+                    "value",
+                    type: parlour_type,
+                    required: true
+                  )], parlour_type)],
+                  class_method: true
+                ) do |m|
+                  add_comments(writer, m)
+                end
+              end
             else
               @current_object.create_attribute(
                 name.to_s,
@@ -490,7 +560,7 @@ module Sord
       @current_object = parent
     end
 
-    # Populates the generator with the contents of the YARD registry. You 
+    # Populates the generator with the contents of the YARD registry. You
     # must load the YARD registry first!
     # @return [void]
     def populate
@@ -588,5 +658,20 @@ module Sord
 
       return pair_type_order[pair1_type] <=> pair_type_order[pair2_type]
     end
+
+    # Removes the last character of a default parameter value if it begins with
+    # '-', working around a bug in YARD. (See lsegal/yard #894)
+    #
+    # @param [String] default
+    # @return [String, nil]
+    def fix_default_if_unary_minus(default)
+      if default.nil?
+        nil
+      elsif default[0] == '-' && !default.start_with?('->')
+        default[0..-2]
+      else
+        default
+      end
+    end
   end
 end

data/lib/sord/logging.rb

@@ -70,16 +70,17 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.generic(kind, header, msg, item)
+    def self.generic(kind, header, msg, item, **opts)
       return unless enabled_types.include?(kind)
 
-      if item
-        puts "#{header} (#{Rainbow(item.path).bold}) #{msg}" unless silent?
+      message = if item
+        "#{header} (#{Rainbow(item.path).bold}) #{msg}"
       else
-        puts "#{header} #{msg}" unless silent?
+        "#{header} #{msg}"
       end
+      puts message unless silent?
 
-      invoke_hooks(kind, msg, item)
+      invoke_hooks(kind, msg, item, **opts)
     end
 
     # Print a warning message. This should be used for things which require the
@@ -89,8 +90,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.warn(msg, item = nil)
-      generic(:warn, Rainbow('[WARN ]').yellow, msg, item)
+    def self.warn(msg, item = nil, **opts)
+      generic(:warn, Rainbow('[WARN ]').yellow, msg, item, **opts)
     end
 
     # Print an info message. This should be used for generic informational
@@ -100,8 +101,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.info(msg, item = nil)
-      generic(:info, '[INFO ]', msg, item)
+    def self.info(msg, item = nil, **opts)
+      generic(:info, '[INFO ]', msg, item, **opts)
     end
 
     # Print a duck-typing message. This should be used when the YARD 
@@ -112,8 +113,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.duck(msg, item = nil)
-      generic(:duck, Rainbow('[DUCK ]').cyan, msg, item)
+    def self.duck(msg, item = nil, **opts)
+      generic(:duck, Rainbow('[DUCK ]').cyan, msg, item, **opts)
     end
 
     # Print an error message. This should be used for things which require the
@@ -123,8 +124,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.error(msg, item = nil)
-      generic(:error, Rainbow('[ERROR]').red, msg, item)
+    def self.error(msg, item = nil, **opts)
+      generic(:error, Rainbow('[ERROR]').red, msg, item, **opts)
     end
 
     # Print an infer message. This should be used when the user should be told
@@ -135,8 +136,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.infer(msg, item = nil)
-      generic(:infer, Rainbow('[INFER]').blue, msg, item)
+    def self.infer(msg, item = nil, **opts)
+      generic(:infer, Rainbow('[INFER]').blue, msg, item, **opts)
     end
 
     # Print an omit message. This should be used as a special type of warning
@@ -147,8 +148,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.omit(msg, item = nil)
-      generic(:omit, Rainbow('[OMIT ]').magenta, msg, item)
+    def self.omit(msg, item = nil, **opts)
+      generic(:omit, Rainbow('[OMIT ]').magenta, msg, item, **opts)
     end
 
     # Print a done message. This should be used when a process completes
@@ -158,8 +159,8 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.done(msg, item = nil)
-      generic(:done, Rainbow('[DONE ]').green, msg, item)
+    def self.done(msg, item = nil, **opts)
+      generic(:done, Rainbow('[DONE ]').green, msg, item, **opts)
     end
 
     # Invokes all registered hooks on the logger.
@@ -169,9 +170,9 @@ module Sord
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
     # @return [void]
-    def self.invoke_hooks(kind, msg, item)
+    def self.invoke_hooks(kind, msg, item, **opts)
       @@hooks.each do |hook|
-        hook.(kind, msg, item) rescue nil
+        hook.(kind, msg, item, **opts)
       end
     end
 

data/lib/sord/resolver.rb

@@ -24,6 +24,10 @@ module Sord
     # @return [Array<String>]
     def self.paths_for(name)
       prepare
+
+      # If the name starts with ::, then we've been given an explicit path from root - just use that
+      return [name] if name.start_with?('::')
+
       (@@names_to_paths[name.split('::').last] || [])
         .select { |x| x.end_with?(name) }
     end
@@ -39,8 +43,12 @@ module Sord
       # This prints some deprecation warnings, so suppress them
       prev_stderr = $stderr
       $stderr = StringIO.new
+      
+      major = RUBY_VERSION.split('.').first.to_i
+      sorted_set_removed = major >= 3 
 
       Object.constants
+        .reject { |x| sorted_set_removed && x == :SortedSet }
         .select { |x| Object.const_get(x).is_a?(Class) }
         .map(&:to_s)
     ensure

data/lib/sord/version.rb

@@ -1,4 +1,4 @@
 # typed: strong
 module Sord
-  VERSION = '3.0.0.beta.2'
+  VERSION = '4.0.0'
 end

data/rbi/sord.rbi

@@ -1,6 +1,7 @@
 # typed: strong
+
 module Sord
-  VERSION = T.let('3.0.0.beta.2', T.untyped)
+  VERSION = T.let('3.0.1', T.untyped)
 
   # Handles writing logs to stdout and any other classes which request them.
   module Logging

data/sord.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'yard'
   spec.add_dependency 'sorbet-runtime'
   spec.add_dependency 'commander', '~> 4.5'
-  spec.add_dependency 'parlour', '5.0.0.beta.6'
+  spec.add_dependency 'parlour', '~> 5.0'
 
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 10.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sord
 version: !ruby/object:Gem::Version
-  version: 3.0.0.beta.2
+  version: 4.0.0
 platform: ruby
 authors:
 - Aaron Christiansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-10-05 00:00:00.000000000 Z
+date: 2022-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -56,16 +56,16 @@ dependencies:
   name: parlour
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.0.0.beta.6
+        version: '5.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.0.0.beta.6
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -146,6 +146,7 @@ extra_rdoc_files: []
 files:
 - ".github/ISSUE_TEMPLATE/bug_report.md"
 - ".github/ISSUE_TEMPLATE/feature-request.md"
+- ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".parlour"
 - ".rspec"
@@ -181,11 +182,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.2.22
 signing_key:
 specification_version: 4
 summary: Generate Sorbet RBI files from YARD documentation