sord 0.8.0 → 3.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4302b93ba07124b24e91c6db6a2757d2fe148c573f3b86a918c72155e83d0d5
-  data.tar.gz: 610ce8222970fb4da8f5d01368a21b1aef4067936f6883b2eb5522e567e8fcce
+  metadata.gz: 6cfc03da2fe9815159c9041a5afff2a0e1e089567cb92da25bcec87137f9e747
+  data.tar.gz: acd6551c560c205199ec494930f4628c5357a34263b0cce05757033014ba929b
 SHA512:
-  metadata.gz: 2a3798003e636dc6baba752bbae52718eefb3f43a5562d7fb3659e39d0a0245c39dd10d297433f05df12f60ac102b93a6ad1b71bc0e1fcb2bf3405233dfb834c
-  data.tar.gz: 0b9a87eea2db2c948006c89c0970175c98471f0e98358a190c17e6c8e064ff59c5849ea73b0081ef6cd09975488884e333b359a44f8d79a8dac78d6f7f461c3e
+  metadata.gz: a3ef67b5162e55af55f81fd056c0a1f232293c021b145fab2054cd482951c9cd22aa2e9f8874687131c65b209f2217488ce6808f9bd88da75a04928720452a34
+  data.tar.gz: 719461ac9a36dc5c636c4f1b79c22923da4e1decb25032ec8e0c6eef8df60454c3eba6d275c61f91fec9d637d200631d3c3003b1aff981d6bafac3c91323e323

data/.parlour

@@ -0,0 +1,11 @@
+parser: false
+
+output_file:
+  rbi: rbi/sord.rbi
+
+requires:
+  - sord
+
+plugins:
+  Sord::ParlourPlugin:
+    rbi: yes

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+dist: trusty
+before_install:
+  - gem install bundler
+rvm: 
+  - 2.6

data/CHANGELOG.md

@@ -3,6 +3,105 @@ 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.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.
+
+## [2.0.0] - 2020-03-16
+### Added
+- Sord now supports generating `attr_accessor`, `attr_reader` and `attr_writer`
+and will do so automatically when these are used in your code.
+  - Depending on what you're doing with Sord, this is **potentially breaking**,
+  as for example attributes which would previously generate two `foo` and `foo=`
+  methods in Sord will now just generate an `attr_accessor`.
+- `#initialize` is now always typed as returning `void`, which is
+**potentially breaking** if you directly call `#initialize` in code.
+  - The `--use-original-initialize-return` flag restores the old behaviour of
+  using whatever return type is provided, like any other method.
+
+## [1.0.0] - 2020-02-16
+### Added
+- Added the `--skip-constants` flag to avoid generating RBIs for constants.
+
+### Changed
+- Parlour 2.0.0 is now being used.
+
+### Fixed
+- Fixed a bug where blank parameters were sometimes treated like non-blank
+parameters.
+- Fixed parameter order sometimes being incorrect.
+- Fixed multiline parameter lists sometimes generating invalid RBIs.
+- Multiline comments are now generated correctly.
+- Fixed an incorrect README link.
+
+## [0.10.0] - 2019-09-14
+### Added
+- Comments in RBIs are now converted from YARD into Markdown format, making them
+look much better when viewed in an IDE. (To restore the old behaviour of copying
+the YARD comments verbatim, use the `--keep-original-comments` flag.)
+
+### Changed
+- Parlour 0.8.0 is now being used.
+- References to `self` as a type in YARD docs are now generated as
+`T.self_type`, rather than a fixed self type determined by Sord.
+
+## [0.9.0] - 2019-08-09
+### Added
+- Add the `--replace-constants-with-untyped` flag, which generates `T.untyped` instead of `SORD_ERROR` constants.
+- Added an option to clean the `sord_examples` directory when seeding or reseeding.
+- Added a Rake task to typecheck the `sord_examples` directory.
+- Added a `.parlour` file to the project for generating Sord's RBIs.
+- Added CI with Travis.
+
+### Changed
+- Code generation has been broken out into the Parlour gem, and Sord is now a Parlour plugin.
+- Rainbow is now used for coloured output instead of colorize.
+- Duplicate type signatures are no longer generated for inherited methods.
+- The Resolver can now resolve more objects.
+- If a parameter has `nil` as its default, it now has a nilable type.
+- Generation of constants has been improved.
+- Superclass names are now generated as fully-qualified identifiers.
+
+### Fixed
+- Fixed `T::Hash` and `T::Array` syntax being generated incorrectly.
+- Fix a bug where the `--no-comments` or `--no-generate` flags were ignored.
+- Collections of `T.untyped` now have signatures generated correctly.
+- Fix generation of hashes when they are given too few parameters.
+- YARD no longer prints irrelevant error messages when running rake.
+
+## [0.8.0] - 2019-07-07
+### Added
+- Block types can now be generated using `@yieldparam` and `@yieldreturn`.
+- Long lists of parameters (at least 4) are now broken onto multiple lines. The threshold can be altered with the `--break-params` option.
+- If a constant used is not found, Sord will now attempt to locate it and fully-qualify its name.
+- Add the `--replace-errors-with-untyped` flag; when present, `T.untyped` is used instead of `SORD_ERROR_` constants.
+- Add the `--include/exclude-messages` flags, which can be used to suppress certain log message kinds.
+- Add support for the `Class<...>` generic becoming `T.class_of(...)`. (#44)
+- Add YARD array (`<...>`) and hash (`{... => ...}`) shorthands. (#43)
+- Sord now has an `examples` set of Rake tasks to test Sord on a large number of repos.
+- Sord now bundles an RBI for itself.
+
+### Changed
+- Methods without any YARD documentation are now typed as `T.untyped` rather than `void`.
+
+### Fixed
+- Duck types in the form of setters (`#foo=`) are now interpreted properly.
+- Fix some cases where indentation was incorrect. (#30, #46)
+- Fix `include` and `extend` calls being swapped, and give them proper blank lines.
+- Fix incorrect blank lines inside empty namespaces.
+- Fix a crash when a `@param` has no name given.
+
 ## [0.7.1] - 2019-06-24
 ### Fixed
 - Fix bug where `--no-regenerate` flag was ignored.

data/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Sord is a [**So**rbet](https://sorbet.org) and [YA**RD**](https://sorbet.org)
+Sord is a [**So**rbet](https://sorbet.org) and [YA**RD**](https://yardoc.org/)
 crossover. It can automatically generate Sorbet type signatures files by
 looking at the types specified in YARD documentation comments.
 
@@ -52,14 +52,16 @@ where the maintainer is unwilling to ship type signatures with the gem itself.
 
 Sord also takes some flags to alter the generated `.rbi` file:
 
-  - `--no-comments`: Generates the `.rbi` file without any comments about
-    warnings/inferences/errors.
+  - `--no-sord-comments`: Generates the `.rbi` file without any Sord comments 
+    about warnings/inferences/errors. (The original file's comments will still
+    be included.)
   - `--no-regenerate`: By default, Sord will regenerate a repository's YARD
     docs for you. This option skips regenerating the YARD docs.
   - `--break-params`: Determines how many parameters are necessary before
     the signature is changed from a single-line to a multi-line block.
     (Default: 4)
   - `--replace-errors-with-untyped`: Uses `T.untyped` instead of `SORD_ERROR_*` constants.
+  - `--replace-unresolved-with-untyped`: Uses `T.untyped` when Sord is unable to resolve a constant.
   - `--include-messages` and `--exclude-messages`: Used to filter the logging
     messages given by Sord. `--include-messages` acts as a whitelist, printing
     only messages of the specified logging kinds, whereas `--exclude-messages`
@@ -75,22 +77,22 @@ Say we have this file, called `test.rb`:
 ```ruby
 module Example
   class Person
-    # @param [String] name
-    # @param [Integer] age
+    # @param name [String] The name of the Person to create.
+    # @param age [Integer] The age of the Person to create.
     # @return [Example::Person]
     def initialize(name, age)
       @name = name
       @age = age
     end
 
-    # @return [String] name
+    # @return name [String]
     attr_accessor :name
 
-    # @return [Integer] age
+    # @return age [Integer]
     attr_accessor :age
 
-    # @param [Array<String>] possible_names
-    # @param [Array<Integer>] possible_ages
+    # @param possible_names [Array<String>] An array of potential names to choose from.
+    # @param possible_ages [Array<Integer>] An array of potential ages to choose from.
     # @return [Example::Person]
     def self.construct_randomly(possible_names, possible_ages)
       Person.new(possible_names.sample, possible_ages.sample)
@@ -115,23 +117,27 @@ The `test.rbi` file then contains a complete RBI file for `test.rb`:
 # typed: strong
 module Example
   class Person
+    # @param `name` — The name of the Person to create.
+    # @param `age` — The age of the Person to create.
     sig { params(name: String, age: Integer).returns(Example::Person) }
     def initialize(name, age); end
 
     sig { returns(String) }
-    def name(); end
+    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 { returns(Integer) }
-    def age(); end
+    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
 
+    # @param `possible_names` — An array of potential names to choose from.
+    # @param `possible_ages` — An array of potential ages to choose from.
     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

data/Rakefile

@@ -10,6 +10,7 @@ REPOS = {
   bundler: 'https://github.com/bundler/bundler',
   discordrb: 'https://github.com/meew0/discordrb',
   gitlab: 'https://github.com/NARKOZ/gitlab',
+  'graphql-ruby': 'https://github.com/rmosolgo/graphql-ruby',
   haml: 'https://github.com/haml/haml',
   oga: 'https://gitlab.com/yorickpeterse/oga',
   rouge: 'https://github.com/rouge-ruby/rouge',
@@ -20,12 +21,21 @@ REPOS = {
 
 namespace :examples do
   require 'fileutils'
-  require 'colorize'
+  require 'rainbow'
 
   desc "Clone git repositories and run Sord on them as examples"
-  task :seed do
+  task :seed, [:mode, :clean] do |t, args|
     if File.directory?('sord_examples')
-      puts 'sord_examples directory already exists, please delete the directory or run a reseed!'.red
+      puts Rainbow('sord_examples directory already exists, please delete the directory or run a reseed!').red
+      exit
+    end
+
+    if args[:mode] == 'rbi'
+      mode_arg = '--rbi'
+    elsif args[:mode] == 'rbs'
+      mode_arg = '--rbs'
+    else
+      puts Rainbow('please specify \'rbi\' or \'rbs\'!').red
       exit
     end
 
@@ -44,35 +54,100 @@ namespace :examples do
         system('bundle install')
         # Generate sri
         puts "Generating rbi for #{name}..."
-        system("bundle exec sord ../#{name}.rbi")
-        puts "#{name}.rbi generated!"
+        if args[:clean]
+          system("bundle exec sord ../#{name}.#{args[:mode]} #{mode_arg} --no-sord-comments --replace-errors-with-untyped --replace-unresolved-with-untyped")
+        else
+          system("bundle exec sord ../#{name}.#{args[:mode]} #{mode_arg}")
+        end
+        puts "#{name}.#{args[:mode]} generated!"
         FileUtils.cd '..'
       end
     end
 
-    puts "Seeding complete!".green
+    puts Rainbow("Seeding complete!").green
   end
 
   desc 'Regenerate the rbi files in sord_examples.'
-  task :reseed do
-    FileUtils.cd 'sord_examples'
+  task :reseed, [:mode, :clean] do |t, args|
+    if Dir.exist?('sord_examples')
+      FileUtils.cd 'sord_examples'
+    else
+      raise Rainbow("The sord_examples directory does not exist. Have you run the seed task?").red.bold
+    end
+
+    if args[:mode] == 'rbi'
+      mode_arg = '--rbi'
+    elsif args[:mode] == 'rbs'
+      mode_arg = '--rbs'
+    else
+      puts Rainbow('please specify \'rbi\' or \'rbs\'!').red
+      exit
+    end
 
     REPOS.keys.each do |name|
       FileUtils.cd name.to_s
       puts "Regenerating rbi file for #{name}..."
       Bundler.with_clean_env do
-        system("bundle exec sord ../#{name}.rbi --no-regenerate")
+        if args[:clean]
+          system("bundle exec sord ../#{name}.#{args[:mode]} #{mode_arg} --no-regenerate --no-sord-comments --replace-errors-with-untyped --replace-unresolved-with-untyped")
+        else
+          system("bundle exec sord ../#{name}.#{args[:mode]} #{mode_arg} --no-regenerate")
+        end
       end
       FileUtils.cd '..'
     end
 
-    puts "Re-seeding complete!".green
+    puts Rainbow("Re-seeding complete!").green
   end
   
   desc 'Delete the sord_examples directory to allow the seeder to run again.'
   task :reset do
     FileUtils.rm_rf 'sord_examples' if File.directory?('sord_examples')
-    puts 'Reset complete.'.green
+    puts Rainbow('Reset complete.').green
   end
-end
 
+  desc 'Typecheck each of the sord_examples rbi files.'
+  task :typecheck, [:verbose] do |t, args|
+    results_hash = {}
+    REPOS.each do |name, url|
+      Bundler.with_clean_env do
+        puts "srb tc sord_examples/#{name}.rbi --ignore sord.rbi 2>&1"
+        if args[:verbose]
+          output = system("srb tc sord_examples/#{name}.rbi --ignore sord.rbi 2>&1")
+        else
+          output = `srb tc sord_examples/#{name}.rbi --ignore sord.rbi 2>&1`.split("\n").last
+          results_hash[:"#{name}"] = output
+        end
+      end
+    end
+    
+    unless args[:verbose]
+      puts Rainbow("Errors").bold
+      longest_name = results_hash.keys.map { |name| name.length }.max
+
+      # Replace all values in results_hash with integer by parsing it.
+      results_hash.each do |name, result|
+        result.scan(/Errors\: (\d+)/) { |match| result = match.first.to_i }
+        results_hash[name] = (result == "No errors! Great job.") ? 0 : result
+      end
+
+      # Print the right-aligned name and the number of errors, with different colors depending on the number of errors. 
+      results_hash.each do |name, result|
+        spaces_needed = longest_name - name.length
+        output = "#{' ' * spaces_needed}#{name}: #{result}"
+        case result
+        when 0..5
+          puts Rainbow(output).green.bright
+        when 6..25
+          puts Rainbow(output).green
+        when 26..50
+          puts Rainbow(output).red
+        else
+          puts Rainbow(output).red.bright
+        end
+      end
+      # Report the Total.
+      puts Rainbow("#{' ' * (longest_name - 'Total'.length)}Total: #{results_hash.values.inject(0, :+)}").bold
+    end
+  end
+end

data/exe/sord

@@ -10,64 +10,81 @@ program :description, 'Generate Sorbet RBIs from YARD documentation'
 default_command :gen
 command :gen do |c|
   c.syntax = 'sord gen <output-file> [options]'
-  c.description = 'Generates an RBI file from this directory\'s YARD docs'
-  c.option '--[no-]comments', 'Controls informational/warning comments in the RBI file'
+  c.description = 'Generates a type signature file from this directory\'s YARD docs'
+  c.option '--rbi', 'Use Sorbet\'s RBI format'
+  c.option '--rbs', 'Use Steep/Ruby 3\'s RBS format'
+  c.option '--[no-]sord-comments', 'Controls informational/warning comments in the file'
   c.option '--[no-]regenerate', 'Controls whether YARD is executed before Sord runs'
   c.option '--break-params INTEGER', Integer, 'Break params onto their own lines if there are this many'
   c.option '--replace-errors-with-untyped', 'Uses T.untyped rather than SORD_ERROR_ constants'
+  c.option '--replace-unresolved-with-untyped', 'Uses T.untyped when Sord is unable to resolve a constant'
   c.option '--exclude-messages STRING', String, 'Blacklists a comma-separated string of log message types'
   c.option '--include-messages STRING', String, 'Whitelists a comma-separated string of log message types'
+  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.action do |args, options|
     options.default(
-      comments: true,
+      rbi: false,
+      rbs: false,
+      sord_comments: true,
       regenerate: true,
       break_params: 4,
       replace_errors_with_untyped: false,
+      replace_unresolved_with_untyped: false,
       exclude_messages: nil,
       include_messages: nil,
+      keep_original_comments: false,
+      skip_constants: false,
+      use_original_initialize_return: 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(',')
 
-    if options.include_messages && options.exclude_messages
-      Sord::Logging.error('Please specify only one of --include-messages and --exclude-messages.')
-      exit 1
-    elsif options.include_messages
-      whitelist = options.include_messages.split(',').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(', ')}")
-        exit 1
-      end
-      Sord::Logging.enabled_types = whitelist | [:done]
-    elsif options.exclude_messages
-      blacklist = options.exclude_messages.split(',').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(', ')}")
+    if !(plugin_options[:rbi] || plugin_options[:rbs])
+      if args.first
+        if args.first.end_with?('.rbi')
+          Sord::Logging.infer('Assuming from filename you wish to generate in RBI format')
+          plugin_options[:rbi] = true
+        elsif args.first.end_with?('.rbs')
+          Sord::Logging.infer('Assuming from filename you wish to generate in RBS format')
+          plugin_options[:rbs] = true
+        else
+          Sord::Logging.error('An output format could not be inferred from your filename; please specify --rbi or --rbs')
+          exit 1
+        end
+      else
+        Sord::Logging.error('No output format given; please specify --rbi or --rbs')
         exit 1
       end
-      Sord::Logging.enabled_types = Sord::Logging::AVAILABLE_TYPES - blacklist
     end
 
-    if options.regenerate
-      begin
-        Sord::Logging.info('Running YARD...')
-        Bundler.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.')
-        exit 1
-      end
+    if (plugin_options[:rbi] && plugin_options[:rbs])
+      Sord::Logging.error('You cannot specify both --rbi and --rbs; please use only one')
+      exit 1
+    end
+
+    plugin = Sord::ParlourPlugin.new(plugin_options)
+
+    if plugin_options[:rbi]
+      klass = Parlour::RbiGenerator
+      generator_method = :rbi
+    elsif plugin_options[:rbs]
+      klass = Parlour::RbsGenerator
+      generator_method = :rbs
     end
 
-    Sord::RbiGenerator.new(options.__hash__).run(args.first)
+    plugin.parlour = klass.new(break_params: plugin_options[:break_params])
+    plugin.generate(plugin.parlour.root)
+    
+    File.write(args.first, plugin.parlour.send(generator_method))
   end
 end