sord 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9a2d105021ccde04330fef38f0a2d3fb270fbd3d2e2c43a258c3bc3f6e0b9f1
-  data.tar.gz: 7d4ff5718684cfd2505595c77ef0bbc6e7f79c6981b0210f28912a66cb6725eb
+  metadata.gz: f23de5349a9a01e6a4f4f4282b30197bb2bfa41714350da2223019ad7760f375
+  data.tar.gz: d99869924be64e52ac543c8a376c906aef074932c912a403992d79728cf638de
 SHA512:
-  metadata.gz: 8681c3b8c07c397f2f454f0e71546ba33ead6b66efdee7c98ecb57ccfea4908a9fe7f03c43d206d46409d4cf7bcdf3116dbb89b628feaf23bfdb52d9f2168c6a
-  data.tar.gz: 552beb2ce3b13800f16687967a3d6bc80b6ab7398f54c16e998612241a37b7bb4a6f490e25d17fa427960ccaecd3a4c0964ac224728dc3e13eb8abc0bb6de970
+  metadata.gz: 9db224cd69010f54a30282612e5e0e37eada990376c8016abacd36d9ce4c7a6e6d8154b50d1aabc226700acde74dc342b152d8085d15943700954df24e0bc024
+  data.tar.gz: 0a3ea8a0215c79a975e792291446422f65646ec8153340e045639ea0d166a2fd91febf806e9315168166915c800e0e832477c49d78021728ead6c6bc44e2b734

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/README.md

@@ -15,10 +15,12 @@ Sord has the following features:
   - Gracefully handles missing YARD types (`T.untyped`)
   - Can infer setter parameter type from the corresponding getter's return type
   - Recognises mixins (`include` and `extend`)
-  - Support for single-argument generic types such as `Array` (no hashes yet)
+  - Support for generic types such as `Array<T>` and `Hash<K, V>`
 
 ## Usage
 
+Install Sord with `gem install sord`.
+
 Sord is a command line tool. To use it, open a terminal in the root directory
 of your project, and run `yard` to generate a YARD registry if you haven't
 already. Then, invoke `sord`, passing a path of where you'd like to save your
@@ -34,6 +36,80 @@ RBI file will be replaced if you re-run Sord.
 
 ## Example
 
+Say we have this file, called `test.rb`:
+
+```ruby
+module Example
+  class Person
+    # @param [String] name
+    # @param [Integer] age
+    # @return [Example::Person]
+    def initialize(name, age)
+      @name = name
+      @age = age
+    end
+
+    # @return [String] name
+    attr_accessor :name
+
+    # @return [Integer] age
+    attr_accessor :age
+
+    # @param [Array<String>] possible_names
+    # @param [Array<Integer>] possible_ages
+    # @return [Example::Person]
+    def self.construct_randomly(possible_names, possible_ages)
+      Person.new(possible_names.sample, possible_ages.sample)
+    end
+  end
+end
+```
+
+First, generate a YARD registry by running `yardoc test.rb`. Then, we can run
+`sord test.rbi` to generate the RBI file. (Careful not to overwrite your code
+files! Note the `.rbi` file extension.) In doing this, Sord prints:
+
+```
+[INFER] (Example::Person#name=) inferred type of parameter "value" as String using getter's return type
+[INFER] (Example::Person#age=) inferred type of parameter "value" as Integer using getter's return type
+[DONE ] Processed 8 objects
+```
+
+The `test.rbi` file then contains a complete RBI file for `test.rb`:
+
+```ruby
+# typed: true
+module Example
+end
+class Example::Person 
+  sig { params(name: String, age: Integer).returns(Example::Person) }
+  def initialize(name, age) end
+  sig { params().returns(String) }
+  def name() end
+  # sord infer - inferred type of parameter "value" as String using getter's return type
+  sig { params(value: String).returns(String) }
+  def name=(value) end
+  sig { params().returns(Integer) }
+  def age() end
+  # sord infer - inferred type of parameter "value" as Integer using getter's return type
+  sig { params(value: Integer).returns(Integer) }
+  def age=(value) end
+  sig { params(possible_names: T::Array[String], possible_ages: T::Array[Integer]).returns(Example::Person) }
+  def self.construct_randomly(possible_names, possible_ages) end
+end
+```
+
+## Things to work on
+
+  - I'm not 100% sure how this handles undocumented methods and classes.
+  - More inference systems would be nice.
+  - This won't generate type parameter definitions for things which mix-in
+    `Enumerable`.
+  - Module scoping is an issue - if `Example::Person` is replaced with `Person`
+    in the YARD comments in the above example, Sorbet won't be able to resolve
+    it.
+  - Tests!!
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/sord. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

data/lib/sord/logging.rb

@@ -1,45 +1,115 @@
 require 'colorize'
 
 module Sord
+  # Handles writing logs to stdout and any other classes which request them.
   module Logging
+    # This is an Array of callables which are all executed upon a log message.
+    # The callables should take three parameters: (kind, msg, item).
     @@hooks = []
 
+    # @return [Boolean] Whether log messages should be printed or not. This is
+    #   used for testing.
+    def self.silent?
+      @@silent || false
+    end
+
+    # Sets whether log messages should be printed or not.
+    # @param [Boolean] value
+    # @return [void]
+    def self.silent=(value)
+      @@silent = value
+    end
+
+    # A generic log message writer which is called by all other specific logging
+    # methods. This shouldn't be called outside of the Logging class itself.
+    # @param [Symbol] kind The kind of log message this is.
+    # @param [String] header The prefix for this log message. For consistency,
+    #   it should be up to five uppercase characters wrapped in square brackets,
+    #   with some unique colour applied.
+    # @param [String] msg The log message to write.
+    # @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.
     def self.generic(kind, header, msg, item)
       if item
-        puts "#{header} (#{item.path.light_white}) #{msg}"
+        puts "#{header} (#{item.path.light_white}) #{msg}" unless silent?
       else
-        puts "#{header} #{msg}"
+        puts "#{header} #{msg}" unless silent?
       end
 
       invoke_hooks(kind, msg, item)
     end
 
+    # Print a warning message. This should be used for things which require the
+    # user's attention but do not prevent the process from stopping.
+    # @param [String] msg The log message to write.
+    # @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.
     def self.warn(msg, item=nil)
       generic(:warn, '[WARN ]'.yellow, msg, item)
     end
 
+    # Print an error message. This should be used for things which require the
+    # current process to stop.
+    # @param [String] msg The log message to write.
+    # @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.
     def self.error(msg, item=nil)
       generic(:error, '[ERROR]'.red, msg, item)
     end
 
+    # Print an infer message. This should be used when the user should be told
+    # that some information has been filled in or guessed for them, and that 
+    # information is likely correct.
+    # @param [String] msg The log message to write.
+    # @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.
     def self.infer(msg, item=nil)
       generic(:infer, '[INFER]'.light_blue, msg, item)
     end
 
+    # Print an omit message. This should be used as a special type of warning
+    # to alert the user that there is some information missing, but this
+    # information is not critical to the completion of the process.
+    # @param [String] msg The log message to write.
+    # @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.
     def self.omit(msg, item=nil)
       generic(:omit, '[OMIT ]'.magenta, msg, item)
     end
 
+    # Print a done message. This should be used when a process completes
+    # successfully.
+    # @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.
     def self.done(msg, item=nil)
       generic(:done, '[DONE ]'.green, msg, item)
     end
 
-    def self.invoke_hooks(type, msg, item)
+    # Invokes all registered hooks on the logger.
+    # @param [Symbol] kind The kind of log message this is.
+    # @param [String] msg The log message to write.
+    # @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.
+    def self.invoke_hooks(kind, msg, item)
       @@hooks.each do |hook|
-        hook.(type, msg, item) rescue nil
+        hook.(kind, msg, item) rescue nil
       end
     end
 
+    # Adds a hook to the logger.
+    # @yieldparam [Symbol] kind The kind of log message this is.
+    # @yieldparam [String] msg The log message to write.
+    # @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.
+    # @yieldreturn [void]
     def self.add_hook(&blk)
       @@hooks << blk
     end

data/lib/sord/rbi_generator.rb

@@ -5,22 +5,37 @@ require 'colorize'
 require 'sord/logging'
 
 module Sord
+  # Converts the current working directory's YARD registry into an RBI file.
   class RbiGenerator
-    attr_reader :rbi_contents, :object_count
-
+    # @return [Array<String>] The lines of the generated RBI file so far.
+    attr_reader :rbi_contents
+    
+    # @return [Integer] The number of objects this generator has processed so 
+    #   far.
+    attr_reader :object_count
+
+    # Create a new RBI generator.
+    # @return [RbiGenerator]
     def initialize
-      @rbi_contents = ['# typed: true']
+      @rbi_contents = ['# typed: strong']
       @object_count = 0
 
+      # Hook the logger so that messages are added as comments to the RBI file
       Logging.add_hook do |type, msg, item|
         rbi_contents << "  # sord #{type} - #{msg}"
       end
     end
 
+    # Increment the object counter.
+    # @return [void]
     def count_object
       @object_count += 1
     end
 
+    # Given a YARD CodeObject, add lines defining its mixins (that is, extends
+    # and includes) to the current RBI file.
+    # @param [YARD::CodeObjects::Base] item
+    # @return [void]
     def add_mixins(item)
       extends = item.instance_mixins
       includes = item.class_mixins
@@ -33,8 +48,13 @@ module Sord
       end
     end
 
+    # Given a YARD NamespaceObject, add lines defining its methods and their
+    # signatures to the current RBI file.
+    # @param [YARD::CodeObjects::NamespaceObject] item
+    # @return [void]
     def add_methods(item)
       # TODO: block documentation
+
       item.meths.each do |meth|
         count_object
 
@@ -42,11 +62,12 @@ module Sord
           "#{name}#{default && " = #{default}"}"
         end.join(", ")
 
+        # This is better than iterating over YARD's "@param" tags directly 
+        # because it includes parameters without documentation
         parameter_names_to_tags = meth.parameters.map do |name, _|
           [name, meth.tags('param').find { |p| p.name == name }]
         end.to_h
 
-        # TODO: if it's a _= method, infer from the _ method
         sig_params_list = parameter_names_to_tags.map do |name, tag|
           if tag
             "#{name}: #{TypeConverter.yard_to_sorbet(tag.types, meth)}"
@@ -91,6 +112,9 @@ module Sord
       end
     end
 
+    # Generates the RBI file and writes it to the given file path.
+    # @param [String] filename
+    # @return [void]
     def run(filename)
       # Get YARD ready
       YARD::Registry.load!

data/lib/sord/type_converter.rb

@@ -1,18 +1,62 @@
 require 'sord/logging'
 
 module Sord
+  # Contains methods to convert YARD types to Sorbet types.
   module TypeConverter
+    # A regular expression which matches Ruby namespaces and identifiers. 
+    # "Foo", "Foo::Bar", and "::Foo::Bar" are all matches, whereas "Foo.Bar"
+    # or "Foo#bar" are not.
     SIMPLE_TYPE_REGEX =
       /(?:\:\:)?[a-zA-Z_][a-zA-Z_0-9]*(?:\:\:[a-zA-Z_][a-zA-Z_0-9]*)*/
 
-    # TODO: does not support mulitple type arguments (e.g. Hash<A, B>)
+    # A regular expression which matches a Ruby namespace immediately followed
+    # by another Ruby namespace in angle brackets. This is the format usually
+    # used in YARD to model generic types, such as "Array<String>".
     GENERIC_TYPE_REGEX =
-      /(#{SIMPLE_TYPE_REGEX})<(#{SIMPLE_TYPE_REGEX})>/
+      /(#{SIMPLE_TYPE_REGEX})\s*<\s*(.*)\s*>/
 
-    # TODO: Hash
-    SORBET_SUPPORTED_GENERIC_TYPES = %w{Array Set Enumerable Enumerator Range}
+    # An array of built-in generic types supported by Sorbet.
+    SORBET_SUPPORTED_GENERIC_TYPES = %w{Array Set Enumerable Enumerator Range Hash}
 
-    def self.yard_to_sorbet(yard, item=nil, &blk)
+    # Given a string of YARD type parameters (without angle brackets), splits
+    # the string into an array of each type parameter.
+    # @param [String] params The type parameters.
+    # @return [Array<String>] The split type parameters.
+    def self.split_type_parameters(params)
+      result = []
+      buffer = ""
+      current_bracketing_level = 0
+      character_pointer = 0
+      
+      while character_pointer < params.length
+        should_buffer = true
+
+        current_bracketing_level += 1 if params[character_pointer] == ?<
+        current_bracketing_level -= 1 if params[character_pointer] == ?>
+
+        if params[character_pointer] == ?,
+          if current_bracketing_level == 0
+            result << buffer.strip
+            buffer = ""
+            should_buffer = false
+          end
+        end
+
+        buffer += params[character_pointer] if should_buffer
+        character_pointer += 1
+      end
+
+      result << buffer.strip
+
+      result
+    end
+
+    # Converts a YARD type into a Sorbet 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.
+    def self.yard_to_sorbet(yard, item=nil)
       case yard
       when nil
         "T.untyped"
@@ -22,23 +66,21 @@ module Sord
         # If there's only one element, unwrap it, otherwise allow for a
         # selection of any of the types
         yard.length == 1 \
-          ? yard_to_sorbet(yard.first, item, &blk)
-          : "T.any(#{yard.map { |x| yard_to_sorbet(x, item, &blk) }.join(', ')})"
+          ? yard_to_sorbet(yard.first, item)
+          : "T.any(#{yard.map { |x| yard_to_sorbet(x, item) }.join(', ')})"
       when /^#{SIMPLE_TYPE_REGEX}$/
+        # 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)
         end
         yard
       when /^#{GENERIC_TYPE_REGEX}$/
         generic_type = $1
-        type_parameter = $2
+        type_parameters = $2
 
         if SORBET_SUPPORTED_GENERIC_TYPES.include?(generic_type)
-          if /^[_a-z]/ === type_parameter
-            Logging.warn("#{type_parameter} is probably not a type, but using anyway", item)
-          end  
-
-          "T::#{generic_type}[#{yard_to_sorbet(type_parameter, item, &blk)}]"
+          "T::#{generic_type}[#{
+            split_type_parameters(type_parameters).map { |x| yard_to_sorbet(x, item) }.join(', ')}]"
         else
           Logging.warn("unsupported generic type #{generic_type.inspect} in #{yard.inspect}", item)
           "SORD_ERROR_#{generic_type.gsub(/[^0-9A-Za-z_]/i, '')}"

data/lib/sord/version.rb

@@ -1,4 +1,4 @@
 # typed: strong
 module Sord
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/sord.gemspec

@@ -30,4 +30,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency 'sorbet'
+  spec.add_development_dependency 'simplecov'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sord
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Aaron Christiansen
@@ -108,6 +108,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  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'
 description: 
 email:
 - aaronc20000@gmail.com
@@ -117,6 +131,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rspec"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock