sord 3.0.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c04d27e18791a912df49bf20c04c3d8555c04ce7f4e9d97d566398c705b4d826
-  data.tar.gz: c9868a430d1cace15d5c11463c7718aa768e2f4b195c9877ba0cb9a995bb8d7e
+  metadata.gz: dc4c58d9ccea9406b38e20c3d6d92357a962e49aa91884b421a496d9302566d2
+  data.tar.gz: cdcc1158ce99895796423ba6b833f68e261e09d6a61b6892104d5948a3c64625
 SHA512:
-  metadata.gz: 2e1266f3b0950874993fb09814431d6ccc7e379128b7146bd46865571d422676df3103ec602534d2cd2e517e1b24b098d8e1edb09cb7002226369fa41d65c127
-  data.tar.gz: c358bd3954399bc55db8883720a40bf1452131771367eb0613637899f5c4d319af6ee3c4d261cb70cb355d83cc21339489562ec1847c47f2893cb40a9c192818
+  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,6 +3,24 @@ 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/).
 
+## [4.0.0] - 2022-07-19
+### Added
+- 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.
+
+### 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

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
@@ -110,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
@@ -119,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
@@ -127,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
@@ -243,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
 
@@ -290,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
@@ -306,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
@@ -341,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) \
@@ -369,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
@@ -391,7 +423,7 @@ module Sord
           ) do |m|
             add_comments(meth, m)
           end
-        end  
+        end
       end
     end
 
@@ -445,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(
@@ -457,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,
@@ -499,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
@@ -597,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

data/lib/sord/version.rb

@@ -1,4 +1,4 @@
 # typed: strong
 module Sord
-  VERSION = '3.0.1'
+  VERSION = '4.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sord
 version: !ruby/object:Gem::Version
-  version: 3.0.1
+  version: 4.0.0
 platform: ruby
 authors:
 - Aaron Christiansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-12-28 00:00:00.000000000 Z
+date: 2022-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -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"
@@ -185,7 +186,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       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