sord 3.0.1 → 5.0.0

data/lib/sord/parlour_plugin.rb

@@ -1,5 +1,6 @@
 # typed: true
 require 'parlour'
+require 'yard/tags/library'
 
 module Sord
   class ParlourPlugin < Parlour::Plugin
@@ -42,17 +43,21 @@ module Sord
         Sord::Logging.error('No output format given; please specify --rbi or --rbs')
         exit 1
       end
-  
+
       if (options[:rbi] && options[:rbs])
         Sord::Logging.error('You cannot specify both --rbi and --rbs; please use only one')
         exit 1
       end
-  
+
       if options[:regenerate]
         begin
           Sord::Logging.info('Running YARD...')
           Sord::ParlourPlugin.with_clean_env do
-            system('bundle exec yard')
+            tag_param = ''
+            options[:tags]&.each do |tag|
+              tag_param += "--tag #{tag} "
+            end
+            system("bundle exec yard #{tag_param} --no-output")
           end
         rescue Errno::ENOENT
           Sord::Logging.error('The YARD tool could not be found on your PATH.')
@@ -63,15 +68,26 @@ module Sord
       end
 
       options[:mode] = \
-        if options[:rbi] then :rbi elsif options[:rbs] then :rbs end 
+        if options[:rbi] then :rbi elsif options[:rbs] then :rbs end
       options[:parlour] = @parlour
       options[:root] = root
 
+      add_custom_tags
+
       Sord::Generator.new(options).run
 
       true
     end
 
+    def add_custom_tags
+      return if options[:tags].empty?
+
+      options[:tags].each do |tag|
+        name, description = tag.split(':')
+        YARD::Tags::Library.define_tag(description, name)
+      end
+    end
+
     def self.with_clean_env &block
       meth = if Bundler.respond_to?(:with_unbundled_env)
                :with_unbundled_env
@@ -81,4 +97,4 @@ module Sord
       Bundler.send meth, &block
     end
   end
-end
+end

data/lib/sord/resolver.rb

@@ -1,30 +1,91 @@
 # typed: false
 require 'stringio'
+require 'rbs'
+require 'rbs/cli'
 
 module Sord
   module Resolver
     # @return [void]
     def self.prepare
+      return @names_to_paths if @names_to_paths
+
+      gem_objects = {}
+      load_gem_objects(gem_objects)
+
       # Construct a hash of class names to full paths
-      @@names_to_paths ||= YARD::Registry.all(:class)
+      @names_to_paths = YARD::Registry.all(:class)
         .group_by(&:name)
-        .map { |k, v| [k.to_s, v.map(&:path)] }
+        .map { |k, v| [k.to_s, v.map(&:path).to_set] }
         .to_h
-        .merge(builtin_classes.map { |x| [x, [x]] }.to_h) do |k, a, b|
-          a | b
+        .merge(builtin_classes.map { |x| [x, Set.new([x])] }.to_h) { |_k, a, b| a.union(b) }
+        .merge(gem_objects) { |_k, a, b| a.union(b) }
+    end
+
+    def self.load_gem_objects(hash)
+      all_decls = []
+      begin
+        RBS::CLI::LibraryOptions.new.loader.load(env: all_decls)
+      rescue RBS::Collection::Config::CollectionNotAvailable
+        Sord::Logging.warn("Could not load RBS collection - run rbs collection install for dependencies")
+      end
+      add_rbs_objects_to_paths(all_decls, hash)
+
+      gem_paths = Bundler.load.specs.map(&:full_gem_path)
+      gem_paths.each do |path|
+        if File.exists?("#{path}/rbi")
+          Dir["#{path}/rbi/**/*.rbi"].each do |sigfile|
+            tree = Parlour::TypeLoader.load_file(sigfile)
+            add_rbi_objects_to_paths(tree.children, hash)
+          end
         end
+      end
+    end
+
+    def self.add_rbs_objects_to_paths(all_decls, names_to_paths, path=[])
+      klasses = [
+        RBS::AST::Declarations::Module,
+        RBS::AST::Declarations::Class,
+        RBS::AST::Declarations::Constant
+      ]
+      all_decls.each do |decl|
+        next unless klasses.include?(decl.class)
+        name = decl.name.to_s
+        new_path = path + [name]
+        names_to_paths[name] ||= Set.new
+        names_to_paths[name] << new_path.join('::')
+        add_rbs_objects_to_paths(decl.members, names_to_paths, new_path) if decl.respond_to?(:members)
+      end
+    end
+
+    def self.add_rbi_objects_to_paths(nodes, names_to_paths, path=[])
+      klasses = [
+        Parlour::RbiGenerator::Constant,
+        Parlour::RbiGenerator::ModuleNamespace,
+        Parlour::RbiGenerator::ClassNamespace
+      ]
+      nodes.each do |node|
+        next unless klasses.include?(node.class)
+        new_path = path + [node.name]
+        names_to_paths[node.name] ||= Set.new
+        names_to_paths[node.name] << new_path.join('::')
+        add_rbi_objects_to_paths(node.children, names_to_paths, new_path) if node.respond_to?(:children)
+      end
     end
 
     # @return [void]
     def self.clear
-      @@names_to_paths = nil
+      @names_to_paths = nil
     end
 
     # @param [String] name
     # @return [Array<String>]
     def self.paths_for(name)
       prepare
-      (@@names_to_paths[name.split('::').last] || [])
+
+      # 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,9 +100,9 @@ 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 
+      sorted_set_removed = major >= 3
 
       Object.constants
         .reject { |x| sorted_set_removed && x == :SortedSet }

data/lib/sord/type_converter.rb

@@ -21,10 +21,15 @@ module Sord
     GENERIC_TYPE_REGEX =
       /(#{SIMPLE_TYPE_REGEX})\s*[<{]\s*(.*)\s*[>}]/
 
+    # Matches valid method names.
+    # From: https://stackoverflow.com/a/4379197/2626000
+    METHOD_NAME_REGEX =
+      /(?:[a-z_]\w*[?!=]?|\[\]=?|<<|>>|\*\*|[!~+\*\/%&^|-]|[<>]=?|<=>|={2,3}|![=~]|=~)/i 
+
     # Match duck types which require the object implement one or more methods,
     # like '#foo', '#foo & #bar', '#foo&#bar&#baz', and '#foo&#bar&#baz&#foo_bar'.
     DUCK_TYPE_REGEX =
-      /^\#[a-zA-Z_][\w]*(?:[a-zA-Z_][\w=]*)*(?:( ?\& ?\#)*[a-zA-Z_][\w=]*)*$/
+      /^\##{METHOD_NAME_REGEX}(?:\s*\&\s*\##{METHOD_NAME_REGEX})*$/
 
     # A regular expression which matches ordered lists in the format of
     # either "Array(String, Symbol)" or "(String, Symbol)".
@@ -90,17 +95,35 @@ module Sord
       result
     end
 
+    # Configuration for how the type converter should work in particular cases.
+    class Configuration
+      def initialize(replace_errors_with_untyped:, replace_unresolved_with_untyped:, output_language:)
+        @output_language = output_language
+        @replace_errors_with_untyped = replace_errors_with_untyped
+        @replace_unresolved_with_untyped = replace_unresolved_with_untyped
+      end
+
+      # The language which the generated types will be converted to - one of
+      # `:rbi` or `:rbs`.
+      attr_accessor :output_language
+
+      # @return [Boolean] If true, T.untyped is used instead of SORD_ERROR_
+      #   constants for unknown types.
+      attr_accessor :replace_errors_with_untyped
+
+      # @param [Boolean] replace_unresolved_with_untyped If true, T.untyped is
+      #   used when Sord is unable to resolve a constant.
+      attr_accessor :replace_unresolved_with_untyped
+    end
+
     # Converts a YARD type into a Parlour type.
     # @param [Boolean, Array, String] yard The YARD type.
     # @param [YARD::CodeObjects::Base] item The CodeObject which the YARD type
     #   is associated with. This is used for logging and can be nil, but this
     #   will lead to less informative log messages.
-    # @param [Boolean] replace_errors_with_untyped If true, T.untyped is used
-    #   instead of SORD_ERROR_ constants for unknown types.
-    # @param [Boolean] replace_unresolved_with_untyped If true, T.untyped is used
-    #   when Sord is unable to resolve a constant.
+    # @param [Configuration] config The generation configuration.
     # @return [Parlour::Types::Type]
-    def self.yard_to_parlour(yard, item = nil, replace_errors_with_untyped = false, replace_unresolved_with_untyped = false)
+    def self.yard_to_parlour(yard, item, config)
       case yard
       when nil # Type not specified
         Parlour::Types::Untyped.new
@@ -113,7 +136,7 @@ module Sord
         # selection of any of the types
         types = yard
           .reject { |x| x == 'nil' }
-          .map { |x| yard_to_parlour(x, item, replace_errors_with_untyped, replace_unresolved_with_untyped) }
+          .map { |x| yard_to_parlour(x, item, config) }
           .uniq(&:hash)
         result = types.length == 1 \
           ? types.first
@@ -142,7 +165,7 @@ module Sord
               unless yard == new_path
             Parlour::Types::Raw.new(new_path)
           else
-            if replace_unresolved_with_untyped
+            if config.replace_unresolved_with_untyped
               Logging.warn("#{yard} wasn't able to be resolved to a constant in this project, replaced with untyped", item)
               Parlour::Types::Untyped.new
             else
@@ -154,33 +177,43 @@ module Sord
           Parlour::Types::Raw.new(yard)
         end
       when DUCK_TYPE_REGEX
-        Logging.duck("#{yard} looks like a duck type, replacing with untyped", item)
-        Parlour::Types::Untyped.new
+        if config.output_language == :rbs && (type = duck_type_to_rbs_type(yard))
+          Logging.duck("#{yard} looks like a duck type with an equivalent RBS interface, replacing with #{type.generate_rbs}", item)
+          type
+        else
+          Logging.duck("#{yard} looks like a duck type, replacing with untyped", item)
+          Parlour::Types::Untyped.new
+        end
       when /^#{GENERIC_TYPE_REGEX}$/
         generic_type = $1
         type_parameters = $2
 
+        # If we don't do this, `const_defined?` will resolve "::Array" as the actual Ruby `Array`
+        # type, not `Parlour::Types::Array`!
+        relative_generic_type = generic_type.start_with?('::') \
+          ? generic_type[2..-1] : generic_type
+
         parameters = split_type_parameters(type_parameters)
-          .map { |x| yard_to_parlour(x, item, replace_errors_with_untyped, replace_unresolved_with_untyped) }
-        if SINGLE_ARG_GENERIC_TYPES.include?(generic_type) && parameters.length > 1
-          Parlour::Types.const_get(generic_type).new(Parlour::Types::Union.new(parameters))
-        elsif generic_type == 'Class' && parameters.length == 1
+          .map { |x| yard_to_parlour(x, item, config) }
+        if SINGLE_ARG_GENERIC_TYPES.include?(relative_generic_type) && parameters.length > 1
+          Parlour::Types.const_get(relative_generic_type).new(Parlour::Types::Union.new(parameters))
+        elsif relative_generic_type == 'Class' && parameters.length == 1
           Parlour::Types::Class.new(parameters.first)
-        elsif generic_type == 'Hash'
+        elsif relative_generic_type == 'Hash'
           if parameters.length == 2
             Parlour::Types::Hash.new(*parameters)
           else
-            handle_sord_error(parameters.map(&:describe).join, "Invalid hash, must have exactly two types: #{yard.inspect}.", item, replace_errors_with_untyped)
+            handle_sord_error(parameters.map(&:describe).join, "Invalid hash, must have exactly two types: #{yard.inspect}.", item, config.replace_errors_with_untyped)
           end
         else
-          if Parlour::Types.const_defined?(generic_type)
+          if Parlour::Types.constants.include?(relative_generic_type.to_sym)
             # This generic is built in to parlour, but sord doesn't
             # explicitly know about it.
-            Parlour::Types.const_get(generic_type).new(*parameters)
+            Parlour::Types.const_get(relative_generic_type).new(*parameters)
           else
             # This is a user defined generic
             Parlour::Types::Generic.new(
-              yard_to_parlour(generic_type),
+              yard_to_parlour(generic_type, nil, config),
               parameters
             )
           end
@@ -190,22 +223,22 @@ module Sord
       when ORDERED_LIST_REGEX
         type_parameters = $1
         parameters = split_type_parameters(type_parameters)
-          .map { |x| yard_to_parlour(x, item, replace_errors_with_untyped, replace_unresolved_with_untyped) }
+          .map { |x| yard_to_parlour(x, item, config) }
         Parlour::Types::Tuple.new(parameters)
       when SHORTHAND_HASH_SYNTAX
         type_parameters = $1
         parameters = split_type_parameters(type_parameters)
-          .map { |x| yard_to_parlour(x, item, replace_errors_with_untyped, replace_unresolved_with_untyped) }
+          .map { |x| yard_to_parlour(x, item, config) }
         # Return a warning about an invalid hash when it has more or less than two elements.
         if parameters.length == 2
           Parlour::Types::Hash.new(*parameters)
         else
-          handle_sord_error(parameters.map(&:describe).join, "Invalid hash, must have exactly two types: #{yard.inspect}.", item, replace_errors_with_untyped)
+          handle_sord_error(parameters.map(&:describe).join, "Invalid hash, must have exactly two types: #{yard.inspect}.", item, config.replace_errors_with_untyped)
         end
       when SHORTHAND_ARRAY_SYNTAX
         type_parameters = $1
         parameters = split_type_parameters(type_parameters)
-          .map { |x| yard_to_parlour(x, item, replace_errors_with_untyped, replace_unresolved_with_untyped) }
+          .map { |x| yard_to_parlour(x, item, config) }
         parameters.one? \
           ? Parlour::Types::Array.new(parameters.first)
           : Parlour::Types::Array.new(Parlour::Types::Union.new(parameters))
@@ -215,7 +248,7 @@ module Sord
         return Parlour::Types::Raw.new(from_yaml.class.to_s) \
           if [Symbol, Float, Integer].include?(from_yaml.class)
 
-        return handle_sord_error(yard.to_s, "#{yard.inspect} does not appear to be a type", item, replace_errors_with_untyped)
+        return handle_sord_error(yard.to_s, "#{yard.inspect} does not appear to be a type", item, config.replace_errors_with_untyped)
       end
     end
 
@@ -233,5 +266,50 @@ module Sord
         ? Parlour::Types::Untyped.new
         : Parlour::Types::Raw.new("SORD_ERROR_#{name.gsub(/[^0-9A-Za-z_]/i, '')}")
     end
+
+    # Taken from: https://github.com/ruby/rbs/blob/master/core/builtin.rbs
+    # When the latest commit was: 6c847d1
+    #
+    # Interfaces which use generic arguments have those arguments as `untyped`, since I'm not aware
+    # of any standard way that these are specified.
+    DUCK_TYPES_TO_RBS_TYPE_NAMES = {
+      # Concrete
+      "#to_i" => "_ToI",
+      "#to_int" => "_ToInt",
+      "#to_r" => "_ToR",
+      "#to_s" => "_ToS",
+      "#to_str" => "_ToStr",
+      "#to_proc" => "_ToProc",
+      "#to_path" => "_ToPath",
+      "#read" => "_Reader",
+      "#readpartial" => "_ReaderPartial",
+      "#write" => "_Writer",
+      "#rewind" => "_Rewindable",
+      "#to_io" => "_ToIO",
+      "#exception" => "_Exception",
+
+      # Generic - these will be put in a `Types::Raw`, so writing RBS syntax is a little devious,
+      # but by their nature we know they'll only be used in an RBS file, so it's probably fine
+      "#to_hash" => "_ToHash[untyped, untyped]",
+      "#each" => "_Each[untyped]",
+    }
+
+    # Given a YARD duck type string, attempts to convert it to one of a list of pre-defined RBS
+    # built-in interfaces.
+    #
+    # For example, the common duck type `#to_s` has a built-in RBS equivalent `_ToS`.
+    #
+    # If no such interface exists, returns `nil`.
+    #
+    # @param [String] type
+    # @return [Parlour::Types::Type, nil]
+    def self.duck_type_to_rbs_type(type)
+      type_name = DUCK_TYPES_TO_RBS_TYPE_NAMES[type]
+      if !type_name.nil?
+        Parlour::Types::Raw.new(type_name)
+      else
+        nil
+      end
+    end
   end
 end

data/lib/sord/version.rb

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