sord 0.8.0 → 3.0.0.beta.1

data/lib/sord/logging.rb

@@ -1,4 +1,5 @@
-require 'colorize'
+# typed: true
+require 'rainbow'
 
 module Sord
   # Handles writing logs to stdout and any other classes which request them.
@@ -68,18 +69,17 @@ module Sord
     # @param [YARD::CodeObjects::Base] item The CodeObject which this log 
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
-    # @param [Integer] indent_level The level at which to indent the code.
     # @return [void]
-    def self.generic(kind, header, msg, item, indent_level = 0)
+    def self.generic(kind, header, msg, item)
       return unless enabled_types.include?(kind)
 
       if item
-        puts "#{header} (#{item.path.bold}) #{msg}" unless silent?
+        puts "#{header} (#{Rainbow(item.path).bold}) #{msg}" unless silent?
       else
         puts "#{header} #{msg}" unless silent?
       end
 
-      invoke_hooks(kind, msg, item, indent_level)
+      invoke_hooks(kind, msg, item)
     end
 
     # Print a warning message. This should be used for things which require the
@@ -88,10 +88,9 @@ module Sord
     # @param [YARD::CodeObjects::Base] item The CodeObject which this log 
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
-    # @param [Integer] indent_level The level at which to indent the code.
     # @return [void]
-    def self.warn(msg, item = nil, indent_level = 0)
-      generic(:warn, '[WARN ]'.yellow, msg, item, indent_level)
+    def self.warn(msg, item = nil)
+      generic(:warn, Rainbow('[WARN ]').yellow, msg, item)
     end
 
     # Print an info message. This should be used for generic informational
@@ -100,10 +99,9 @@ module Sord
     # @param [YARD::CodeObjects::Base] item The CodeObject which this log 
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
-    # @param [Integer] indent_level The level at which to indent the code.
     # @return [void]
-    def self.info(msg, item = nil, indent_level = 0)
-      generic(:info, '[INFO ]', msg, item, indent_level)
+    def self.info(msg, item = nil)
+      generic(:info, '[INFO ]', msg, item)
     end
 
     # Print a duck-typing message. This should be used when the YARD 
@@ -113,10 +111,9 @@ module Sord
     # @param [YARD::CodeObjects::Base] item The CodeObject which this log 
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
-    # @param [Integer] indent_level The level at which to indent the code.
     # @return [void]
-    def self.duck(msg, item = nil, indent_level = 0)
-      generic(:duck, '[DUCK ]'.cyan, msg, item, indent_level)
+    def self.duck(msg, item = nil)
+      generic(:duck, Rainbow('[DUCK ]').cyan, msg, item)
     end
 
     # Print an error message. This should be used for things which require the
@@ -125,10 +122,9 @@ module Sord
     # @param [YARD::CodeObjects::Base] item The CodeObject which this log 
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
-    # @param [Integer] indent_level The level at which to indent the code.
     # @return [void]
-    def self.error(msg, item = nil, indent_level = 0)
-      generic(:error, '[ERROR]'.red, msg, item, indent_level)
+    def self.error(msg, item = nil)
+      generic(:error, Rainbow('[ERROR]').red, msg, item)
     end
 
     # Print an infer message. This should be used when the user should be told
@@ -138,10 +134,9 @@ module Sord
     # @param [YARD::CodeObjects::Base] item The CodeObject which this log 
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
-    # @param [Integer] indent_level The level at which to indent the code.
     # @return [void]
-    def self.infer(msg, item = nil, indent_level = 0)
-      generic(:infer, '[INFER]'.light_blue, msg, item, indent_level)
+    def self.infer(msg, item = nil)
+      generic(:infer, Rainbow('[INFER]').blue, msg, item)
     end
 
     # Print an omit message. This should be used as a special type of warning
@@ -151,10 +146,9 @@ module Sord
     # @param [YARD::CodeObjects::Base] item The CodeObject which this log 
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
-    # @param [Integer] indent_level The level at which to indent the code.
     # @return [void]
-    def self.omit(msg, item = nil, indent_level = 0)
-      generic(:omit, '[OMIT ]'.magenta, msg, item, indent_level)
+    def self.omit(msg, item = nil)
+      generic(:omit, Rainbow('[OMIT ]').magenta, msg, item)
     end
 
     # Print a done message. This should be used when a process completes
@@ -163,10 +157,9 @@ module Sord
     # @param [YARD::CodeObjects::Base] item The CodeObject which this log 
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
-    # @param [Integer] indent_level The level at which to indent the code.
     # @return [void]
-    def self.done(msg, item = nil, indent_level = 0)
-      generic(:done, '[DONE ]'.green, msg, item)
+    def self.done(msg, item = nil)
+      generic(:done, Rainbow('[DONE ]').green, msg, item)
     end
 
     # Invokes all registered hooks on the logger.
@@ -175,11 +168,10 @@ module Sord
     # @param [YARD::CodeObjects::Base] item The CodeObject which this log 
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
-    # @param [Integer] indent_level The level at which to indent the code.
     # @return [void]
-    def self.invoke_hooks(kind, msg, item, indent_level = 0)
+    def self.invoke_hooks(kind, msg, item)
       @@hooks.each do |hook|
-        hook.(kind, msg, item, indent_level) rescue nil
+        hook.(kind, msg, item) rescue nil
       end
     end
 
@@ -189,7 +181,6 @@ module Sord
     # @yieldparam [YARD::CodeObjects::Base] item The CodeObject which this log 
     #  is associated with, if any. This is shown before the log message if it is
     #  specified.
-    # @yieldparam [Integer] indent_level The level at which to indent the code.
     # @yieldreturn [void]
     # @return [void]
     def self.add_hook(&blk)

data/lib/sord/parlour_plugin.rb

@@ -0,0 +1,84 @@
+# typed: true
+require 'parlour'
+
+module Sord
+  class ParlourPlugin < Parlour::Plugin
+    attr_reader :options
+    attr_accessor :parlour
+
+    def initialize(options)
+      @parlour = nil
+      @options = options
+
+      options[:sord_comments] = true if options[:sord_comments].nil?
+      options[:regenerate] = true if options[:regenerate].nil?
+      options[:replace_errors_with_untyped] ||= false
+      options[:replace_unresolved_with_untyped] ||= false
+    end
+
+    def generate(root)
+      if options[:include_messages] && options[:exclude_messages]
+        Sord::Logging.error('Please specify only one of --include-messages and --exclude-messages.')
+        return false
+      elsif options[:include_messages]
+        whitelist = options[:include_messages].map { |x| x.downcase.to_sym }
+        unless Sord::Logging.valid_types?(whitelist)
+          Sord::Logging.error('Not all types on your --include-messages list are valid.')
+          Sord::Logging.error("Valid options are: #{Sord::Logging::AVAILABLE_TYPES.map(&:to_s).join(', ')}")
+          return false
+        end
+        Sord::Logging.enabled_types = whitelist | [:done]
+      elsif options[:exclude_messages]
+        blacklist = options[:exclude_messages].map { |x| x.downcase.to_sym }
+        unless Sord::Logging.valid_types?(blacklist)
+          Sord::Logging.error('Not all types on your --include-messages list are valid.')
+          Sord::Logging.error("Valid options are: #{Sord::Logging::AVAILABLE_TYPES.map(&:to_s).join(', ')}")
+          return false
+        end
+        Sord::Logging.enabled_types = Sord::Logging::AVAILABLE_TYPES - blacklist
+      end
+
+      if !(options[:rbi] || options[:rbs])
+        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')
+          end
+        rescue Errno::ENOENT
+          Sord::Logging.error('The YARD tool could not be found on your PATH.')
+          Sord::Logging.error('You may need to run \'gem install yard\'.')
+          Sord::Logging.error('If documentation has already been generated, pass --no-regenerate to Sord.')
+          return false
+        end
+      end
+
+      options[:mode] = \
+        if options[:rbi] then :rbi elsif options[:rbs] then :rbs end 
+      options[:parlour] = @parlour
+      options[:root] = root
+
+      Sord::Generator.new(options).run
+
+      true
+    end
+
+    def self.with_clean_env &block
+      meth = if Bundler.respond_to?(:with_unbundled_env)
+               :with_unbundled_env
+             else
+               :with_clean_env
+            end
+      Bundler.send meth, &block
+    end
+  end
+end

data/lib/sord/resolver.rb

@@ -1,3 +1,4 @@
+# typed: false
 require 'stringio'
 
 module Sord
@@ -50,12 +51,18 @@ module Sord
     # @param [Object] item
     # @return [Boolean]
     def self.resolvable?(name, item)
-      name_parts = name.split('::')
-
       current_context = item
       current_context = current_context.parent \
         until current_context.is_a?(YARD::CodeObjects::NamespaceObject)
 
+      # If there is any matching object directly in the heirarchy, this is
+      # always true. Ruby can do the resolution.
+      unless name.include?('::')
+        return true if current_context.path.split('::').include?(name)
+      end
+
+      name_parts = name.split('::')
+
       matching_paths = []
 
       loop do

data/lib/sord/type_converter.rb

@@ -1,9 +1,11 @@
+# typed: true
 require 'yaml'
 require 'sord/logging'
 require 'sord/resolver'
+require 'parlour'
 
 module Sord
-  # Contains methods to convert YARD types to Sorbet types.
+  # Contains methods to convert YARD types to Parlour types.
   module TypeConverter
     # A regular expression which matches Ruby namespaces and identifiers. 
     # "Foo", "Foo::Bar", and "::Foo::Bar" are all matches, whereas "Foo.Bar"
@@ -36,9 +38,9 @@ module Sord
     # "<String>".
     SHORTHAND_ARRAY_SYNTAX = /^<\s*(.*)\s*>$/
 
-    # An array of built-in generic types supported by Sorbet.
-    SORBET_SUPPORTED_GENERIC_TYPES = %w{Array Set Enumerable Enumerator Range Hash Class}
-    SORBET_SINGLE_ARG_GENERIC_TYPES = %w{Array Set Enumerable Enumerator Range}
+    # An array of built-in types supported by Parlour.
+    SUPPORTED_GENERIC_TYPES = %w{Array Set Enumerable Enumerator Range Hash Class}
+    SINGLE_ARG_GENERIC_TYPES = %w{Array Set Enumerable Enumerator Range}
 
     # Given a string of YARD type parameters (without angle brackets), splits
     # the string into an array of each type parameter.
@@ -89,37 +91,47 @@ module Sord
       result
     end
 
-    # Converts a YARD type into a Sorbet type.
+    # 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 [Integer] indent_level 
     # @param [Boolean] replace_errors_with_untyped If true, T.untyped is used
     #   instead of SORD_ERROR_ constants for unknown types.
-    # @return [String]
-    def self.yard_to_sorbet(yard, item = nil, indent_level = 0, replace_errors_with_untyped = false)
+    # @param [Boolean] replace_unresolved_with_untyped If true, T.untyped is used
+    #   when Sord is unable to resolve a constant.
+    # @return [Parlour::Types::Type]
+    def self.yard_to_parlour(yard, item = nil, replace_errors_with_untyped = false, replace_unresolved_with_untyped = false)
       case yard
       when nil # Type not specified
-        "T.untyped"
+        Parlour::Types::Untyped.new
       when  "bool", "Bool", "boolean", "Boolean", "true", "false"
-        "T::Boolean"
+        Parlour::Types::Boolean.new
       when 'self'
-        item.parent.path
+        Parlour::Types::Self.new
       when Array
         # If there's only one element, unwrap it, otherwise allow for a
         # selection of any of the types
         types = yard
           .reject { |x| x == 'nil' }
-          .map { |x| yard_to_sorbet(x, item, indent_level, replace_errors_with_untyped) }
-          .uniq
-        result = types.length == 1 ? types.first : "T.any(#{types.join(', ')})"
-        result = "T.nilable(#{result})" if yard.include?('nil')
+          .map { |x| yard_to_parlour(x, item, replace_errors_with_untyped, replace_unresolved_with_untyped) }
+          .uniq(&:hash)
+        result = types.length == 1 \
+          ? types.first
+          : Parlour::Types::Union.new(types)
+        result = Parlour::Types::Nilable.new(result) if yard.include?('nil')
         result
       when /^#{SIMPLE_TYPE_REGEX}$/
+        if SINGLE_ARG_GENERIC_TYPES.include?(yard)
+          return Parlour::Types.const_get(yard).new(Parlour::Types::Untyped.new)
+        elsif yard == "Hash"
+          return Parlour::Types::Hash.new(
+            Parlour::Types::Untyped.new, Parlour::Types::Untyped.new
+          )
+        end
         # If this doesn't begin with an uppercase letter, warn
         if /^[_a-z]/ === yard
-          Logging.warn("#{yard} is probably not a type, but using anyway", item, indent_level)
+          Logging.warn("#{yard} is probably not a type, but using anyway", item)
         end
 
         # Check if whatever has been specified is actually resolvable; if not,
@@ -127,65 +139,99 @@ module Sord
         if item && !Resolver.resolvable?(yard, item)
           if Resolver.path_for(yard)
             new_path = Resolver.path_for(yard)
-            Logging.infer("#{yard} was resolved to #{new_path}", item, indent_level) \
+            Logging.infer("#{yard} was resolved to #{new_path}", item) \
               unless yard == new_path
-            new_path
+            Parlour::Types::Raw.new(new_path)
           else
-            Logging.warn("#{yard} wasn't able to be resolved to a constant in this project", item, indent_level)
-            yard
+            if 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
+              Logging.warn("#{yard} wasn't able to be resolved to a constant in this project", item)
+              Parlour::Types::Raw.new(yard)
+            end
           end
         else
-          yard
+          Parlour::Types::Raw.new(yard)
         end
       when DUCK_TYPE_REGEX
-        Logging.duck("#{yard} looks like a duck type, replacing with T.untyped", item, indent_level)
-        'T.untyped'
+        Logging.duck("#{yard} looks like a duck type, replacing with untyped", item)
+        Parlour::Types::Untyped.new
       when /^#{GENERIC_TYPE_REGEX}$/
         generic_type = $1
         type_parameters = $2
 
-        if SORBET_SUPPORTED_GENERIC_TYPES.include?(generic_type)
+        if SUPPORTED_GENERIC_TYPES.include?(generic_type)
           parameters = split_type_parameters(type_parameters)
-            .map { |x| yard_to_sorbet(x, item, indent_level, replace_errors_with_untyped) }
-          if SORBET_SINGLE_ARG_GENERIC_TYPES.include?(generic_type) && parameters.length > 1
-            "T::#{generic_type}[T.any(#{parameters.join(', ')})]"
+            .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
-            "T.class_of(#{parameters.first})"
+            Parlour::Types::Class.new(parameters.first)
+          elsif 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)
+            end
           else
-            "T::#{generic_type}[#{parameters.join(', ')}]"
+            Parlour::Types.const_get(generic_type).new(*parameters)
           end
         else
-          Logging.warn("unsupported generic type #{generic_type.inspect} in #{yard.inspect}", item, indent_level)
-          replace_errors_with_untyped ? "T.untyped" : "SORD_ERROR_#{generic_type.gsub(/[^0-9A-Za-z_]/i, '')}"
+          return handle_sord_error(
+            generic_type,
+            "unsupported generic type #{generic_type.inspect} in #{yard.inspect}",
+            item,
+            replace_errors_with_untyped
+          )
         end
       # Converts ordered lists like Array(Symbol, String) or (Symbol, String)
-      # into Sorbet Tuples like [Symbol, String].
+      # into tuples.
       when ORDERED_LIST_REGEX
         type_parameters = $1
         parameters = split_type_parameters(type_parameters)
-          .map { |x| yard_to_sorbet(x, item, indent_level, replace_errors_with_untyped) }
-        "[#{parameters.join(', ')}]"
+          .map { |x| yard_to_parlour(x, item, replace_errors_with_untyped, replace_unresolved_with_untyped) }
+        Parlour::Types::Tuple.new(parameters)
       when SHORTHAND_HASH_SYNTAX
         type_parameters = $1
         parameters = split_type_parameters(type_parameters)
-          .map { |x| yard_to_sorbet(x, item, indent_level, replace_errors_with_untyped) }
-        "T::Hash<#{parameters.join(', ')}>"
+          .map { |x| yard_to_parlour(x, item, replace_errors_with_untyped, replace_unresolved_with_untyped) }
+        # 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)
+        end
       when SHORTHAND_ARRAY_SYNTAX
         type_parameters = $1
         parameters = split_type_parameters(type_parameters)
-          .map { |x| yard_to_sorbet(x, item, indent_level, replace_errors_with_untyped) }
+          .map { |x| yard_to_parlour(x, item, replace_errors_with_untyped, replace_unresolved_with_untyped) }
         parameters.one? \
-          ? "T::Array<#{parameters.first}>"
-          : "T::Array<T.any(#{parameters.join(', ')})>"
+          ? Parlour::Types::Array.new(parameters.first)
+          : Parlour::Types::Array.new(Parlour::Types::Union.new(parameters))
       else
         # Check for literals
         from_yaml = YAML.load(yard) rescue nil
-        return from_yaml.class.to_s \
+        return Parlour::Types::Raw.new(from_yaml.class.to_s) \
           if [Symbol, Float, Integer].include?(from_yaml.class)
 
-        Logging.warn("#{yard.inspect} does not appear to be a type", item, indent_level)
-        replace_errors_with_untyped ? "T.untyped" : "SORD_ERROR_#{yard.gsub(/[^0-9A-Za-z_]/i, '')}"
+        return handle_sord_error(yard.to_s, "#{yard.inspect} does not appear to be a type", item, replace_errors_with_untyped)
       end
     end
+
+    # Handles SORD_ERRORs.
+    #
+    # @param [String, Parlour::Types::Type] name
+    # @param [String] log_warning
+    # @param [YARD::CodeObjects::Base] item
+    # @param [Boolean] replace_errors_with_untyped
+    # @return [Parlour::Types::Type]
+    def self.handle_sord_error(name, log_warning, item, replace_errors_with_untyped)
+      Logging.warn(log_warning, item)
+      str = name.is_a?(Parlour::Types::Type) ? name.describe : name
+      return replace_errors_with_untyped \
+        ? Parlour::Types::Untyped.new
+        : Parlour::Types::Raw.new("SORD_ERROR_#{name.gsub(/[^0-9A-Za-z_]/i, '')}")
+    end
   end
 end