sord 0.9.0 → 3.0.0.beta.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfebf9f7b35b936d5a448430b99c0aaa79cb13af0183cdf438c9d210b79fcbe4
-  data.tar.gz: fd5d9f369fbc55d34bac6b3338cb481a3a0a3ed748d47130327f841e5ac3d8a7
+  metadata.gz: 7a96fafb7c0a8a07c5462a5138b836837e65e2dd14f68d9f51ebd502170c84f9
+  data.tar.gz: 8d82f8e1848f0422cdd4729933f867f78daffeeb226a54b826d5fd75660e73ac
 SHA512:
-  metadata.gz: 0407ed5b5770dd46c40df84dd40ba598d650a237f5f5a59127c66d30078970b36c803165dccbb9c6057784bee7763031f15d081fb0aabede6d100d5e943acd10
-  data.tar.gz: '07849f1278d3d40a3230c45293bc23d6c5ab31360f1d43a55ebc04eefc448e80481fc740180a776d6d999193798a30e1aa961a406c77e9f92d998a67ae43c4e2'
+  metadata.gz: f885ba62dd5b528f63e644d6cc6d000b33f372ea07ec7f372b1231464f5989e5353db508d553d997cdb772dc5ad075cf8fc3d37ede901f16efaa031438b59474
+  data.tar.gz: 859a054fdf1e1609035862c4f95d3b03622dcf7fe97c97afae120e80168102af0806dd8463aa00815f2e294cb0c895f511a9387b4f22e8464dc8aa9dc4f9a333

data/.parlour

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

data/CHANGELOG.md

@@ -3,6 +3,64 @@ 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.2] - 2020-10-05
+### Added
+- Sord is no longer limited to a known set of generics, and will instead
+  generate `Parlour::Types::Generic` types for user-defined generics.
+
+## [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.

data/README.md

@@ -2,25 +2,28 @@
 
 ## Overview
 
-Sord is a [**So**rbet](https://sorbet.org) and [YA**RD**](https://sorbet.org)
-crossover. It can automatically generate Sorbet type signatures files by
-looking at the types specified in YARD documentation comments.
+Sord is a [**So**rbet](https://sorbet.org) and [YA**RD**](https://yardoc.org/)
+crossover. It can **automatically generate RBI and RBS type signature files** by
+looking at the **types specified in YARD documentation** comments.
 
 If your project is already YARD documented, then this can generate most of the
-Sorbet signatures you need!
+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.
 
 Sord has the following features:
   - Automatically generates signatures for modules, classes and methods
-  - Support for multiple parameter or return types (`T.any`)
-  - Gracefully handles missing YARD types (`T.untyped`)
+  - Support for multiple parameter or return types (`T.any`/`|`)
+  - Gracefully handles missing YARD types (`T.untyped`/`untyped`)
   - Can infer setter parameter type from the corresponding getter's return type
   - Recognises mixins (`include` and `extend`)
   - Support for generic types such as `Array<T>` and `Hash<K, V>`
   - Can infer namespaced classes (`[Bar]` can become `GemName::Foo::Bar`)
-  - Handles return types which can be `nil` (`T.nilable`)
-  - Handles duck types (`T.untyped`)
+  - Handles return types which can be `nil` (`T.nilable`/`untyped`)
+  - Handles duck types (`T.untyped`/`untyped`)
   - Support for ordered list types (`[Array(Integer, Symbol)]` becomes `[Integer, Symbol]`)
-  - Support for boolean types (`[true, false]` becomes `T::Boolean`)
+  - Support for boolean types (`[true, false]` becomes `T::Boolean`/`bool`)
   - Support for `&block` parameters documented with `@yieldparam` and `@yieldreturn`
 
 ## Usage
@@ -29,7 +32,7 @@ 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 invoke `sord`, passing a path where you'd like to save your
-`.rbi` (this file will be overwritten):
+file (this file will be overwritten):
 
 ```
 sord defs.rbi
@@ -37,7 +40,12 @@ sord defs.rbi
 
 Sord will generate YARD docs and then print information about what it's inferred
 as it runs. It is best to fix any issues in the YARD documentation, as any edits
-made to the resulting RBI file will be replaced if you re-run Sord.
+made to the resulting file will be replaced if you re-run Sord.
+
+The output type is inferred by the file extension you use, but you can also
+specify it explicitly with `--rbi` or `--rbs`.
+
+## Shipping RBI Types
 
 RBI files generated by Sord can be used in two main ways:
 
@@ -50,17 +58,22 @@ where the maintainer is unwilling to ship type signatures with the gem itself.
 
 ### Flags
 
-Sord also takes some flags to alter the generated `.rbi` file:
+Sord also takes some flags to alter the generated file:
 
-  - `--no-comments`: Generates the `.rbi` file without any comments about
-    warnings/inferences/errors.
+  - `--rbi`/`--rbs`: Override the output format inferred from the file
+    extension.
+  - `--no-sord-comments`: Generates the 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.
+  - `--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`
@@ -76,22 +89,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 [String]
     attr_accessor :name
 
-    # @return [Integer] age
+    # @return [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)
@@ -105,9 +118,8 @@ First, generate a YARD registry by running `yardoc test.rb`. Then, we can run
 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
+[INFER] Assuming from filename you wish to generate in RBI format
+[DONE ] Processed 8 objects (2 namespaces and 6 methods)
 ```
 
 The `test.rbi` file then contains a complete RBI file for `test.rb`:
@@ -116,25 +128,45 @@ The `test.rbi` file then contains a complete RBI file for `test.rb`:
 # typed: strong
 module Example
   class Person
-    sig { params(name: String, age: Integer).returns(Example::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).void }
     def initialize(name, age); end
 
-    sig { returns(String) }
-    def name(); 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
 
-    # 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(String) }
+    attr_accessor :name
 
     sig { returns(Integer) }
-    def age(); end
+    attr_accessor :age
+  end
+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
+If we had instead generated `test.rbs`, we would get this file in RBS format:
 
-    sig { params(possible_names: T::Array[String], possible_ages: T::Array[Integer]).returns(Example::Person) }
-    def self.construct_randomly(possible_names, possible_ages); end
+```ruby
+module Example
+  class Person
+    # _@param_ `name` — The name of the Person to create.
+    # 
+    # _@param_ `age` — The age of the Person to create.
+    def initialize: (String name, Integer age) -> void
+
+    # _@param_ `possible_names` — An array of potential names to choose from.
+    # 
+    # _@param_ `possible_ages` — An array of potential ages to choose from.
+    def self.construct_randomly: (Array[String] possible_names, Array[Integer] possible_ages) -> Example::Person
+
+    attr_accessor name: String
+
+    attr_accessor age: Integer
   end
 end
 ```
@@ -143,12 +175,13 @@ end
 
 The general rule of thumb for type conversions is:
 
-  - If Sord understands the YARD type, then it is converted into the Sorbet type.
+  - If Sord understands the YARD type, then it is converted into the RBI or RBS
+    type.
   - If the YARD type is missing, Sord fills in `T.untyped`.
   - If the YARD type can't be understood, Sord creates an undefined Ruby constant
     with a similar name to the unknown YARD type. For example, the obviously
     invalid YARD type `A%B` will become a constant called `SORD_ERROR_AB`.
-    You should search through your resulting RBI to find and fix and 
+    You should search through your resulting file to find and fix and 
     `SORD_ERROR`s.
 
 ## Contributing
@@ -156,11 +189,11 @@ The general rule of thumb for type conversions is:
 Bug reports and pull requests are welcome on GitHub at https://github.com/AaronC81/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.
 
 While contributing, if you want to see the results of your changes to Sord you
-can use the `examples:seed` Rake task. The task uses Sord to generate RBIs for
+can use the `examples:seed` Rake task. The task uses Sord to generate types for
 a number of open source Ruby gems, including Bundler, Haml, Rouge, and RSpec.
-`rake examples:seed` (and `rake examples:reseed` to regenerate the RBI files)
-will clone the repositories of these gems into `sord_examples/` and then
-generate the RBI files into the same directory.
+`rake examples:seed` (and `rake examples:reseed` to regenerate the files) will
+clone the repositories of these gems into `sord_examples/` and then generate the
+files into the same directory.
 
 ## License
 

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',
@@ -23,12 +24,21 @@ namespace :examples do
   require 'rainbow'
 
   desc "Clone git repositories and run Sord on them as examples"
-  task :seed, [:clean] do |t, args|
+  task :seed, [:mode, :clean] do |t, args|
     if File.directory?('sord_examples')
       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
+
     FileUtils.mkdir 'sord_examples'
     FileUtils.cd 'sord_examples'
     
@@ -45,11 +55,11 @@ namespace :examples do
         # Generate sri
         puts "Generating rbi for #{name}..."
         if args[:clean]
-          system("bundle exec sord ../#{name}.rbi --no-comments --replace-errors-with-untyped --replace-unresolved-with-untyped")
+          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}.rbi")
+          system("bundle exec sord ../#{name}.#{args[:mode]} #{mode_arg}")
         end
-        puts "#{name}.rbi generated!"
+        puts "#{name}.#{args[:mode]} generated!"
         FileUtils.cd '..'
       end
     end
@@ -58,21 +68,30 @@ namespace :examples do
   end
 
   desc 'Regenerate the rbi files in sord_examples.'
-  task :reseed, [:clean] do |t, args|
+  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
         if args[:clean]
-          system("bundle exec sord ../#{name}.rbi --no-regenerate --no-comments --replace-errors-with-untyped --replace-unresolved-with-untyped")
+          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}.rbi --no-regenerate")
+          system("bundle exec sord ../#{name}.#{args[:mode]} #{mode_arg} --no-regenerate")
         end
       end
       FileUtils.cd '..'

data/exe/sord

@@ -10,39 +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 !(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
+    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)
-    plugin.parlour = Parlour::RbiGenerator.new(break_params: plugin_options[:break_params])
+
+    if plugin_options[:rbi]
+      klass = Parlour::RbiGenerator
+      generator_method = :rbi
+    elsif plugin_options[:rbs]
+      klass = Parlour::RbsGenerator
+      generator_method = :rbs
+    end
+
+    plugin.parlour = klass.new(break_params: plugin_options[:break_params])
     plugin.generate(plugin.parlour.root)
     
-    File.write(args.first, plugin.parlour.rbi)
+    File.write(args.first, plugin.parlour.send(generator_method))
   end
 end