sord 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f5c3d1135923a51f529b350dc7fd3c9f42300ab1fda040269b4d9a4d44bd271
-  data.tar.gz: 3bbd67ff8649ffb37cb50b2082ca62ae2affaea24ed69c9f502a52ccfbf42315
+  metadata.gz: a4302b93ba07124b24e91c6db6a2757d2fe148c573f3b86a918c72155e83d0d5
+  data.tar.gz: 610ce8222970fb4da8f5d01368a21b1aef4067936f6883b2eb5522e567e8fcce
 SHA512:
-  metadata.gz: 1b54a2809ce34de42b24abd32b5a69df07f4461dde01089eb2be35ed480b1e63e57be424882d4d934ca4ecca6de4783b116b913a49484af05df22a30f1c01589
-  data.tar.gz: 2bc7a9731b69a894432ed65859376169dfdd61bebc9ed87b69b0951b7f7c2b2f41a937a7ecbb48a1f67c0baf34f47cbc0b5c23b8ce39d7551e6124fc41a64022
+  metadata.gz: 2a3798003e636dc6baba752bbae52718eefb3f43a5562d7fb3659e39d0a0245c39dd10d297433f05df12f60ac102b93a6ad1b71bc0e1fcb2bf3405233dfb834c
+  data.tar.gz: 0b9a87eea2db2c948006c89c0970175c98471f0e98358a190c17e6c8e064ff59c5849ea73b0081ef6cd09975488884e333b359a44f8d79a8dac78d6f7f461c3e

data/.gitignore

@@ -11,3 +11,5 @@
 .rspec_status
 .vscode/
 Gemfile.lock
+
+sord_examples/

data/README.md

@@ -2,9 +2,9 @@
 
 ## Overview
 
-Sord is a **So**rbet and YA**RD** 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://sorbet.org)
+crossover. It can automatically generate Sorbet type signatures 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!
@@ -16,14 +16,17 @@ Sord has the following features:
   - 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`)
+  - Support for ordered list types (`[Array(Integer, Symbol)]` becomes `[Integer, Symbol]`)
+  - Support for boolean types (`[true, false]` becomes `T::Boolean`)
+  - Support for `&block` parameters documented with `@yieldparam` and `@yieldreturn`
 
 ## Usage
 
 Install Sord with `gem install sord`.
 
-**NOTE**: You need to run `yard` before you generate the `.rbi` file or
-Sord won't have any information to work with.
-
 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):
@@ -32,9 +35,18 @@ of your project and invoke `sord`, passing a path where you'd like to save your
 sord defs.rbi
 ```
 
-Sord will 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.
+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.
+
+RBI files generated by Sord can be used in two main ways:
+
+- [Shipped in the gem itself](https://sorbet.org/docs/rbi#rbis-within-gems).
+- Contributed to [sorbet-typed](https://github.com/sorbet/sorbet-typed).
+
+Generally, you should ship the type signatures with your gem if possible.
+sorbet-typed is meant to be a place for gems that are no longer updated or
+where the maintainer is unwilling to ship type signatures with the gem itself.
 
 ### Flags
 
@@ -42,6 +54,19 @@ 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-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.
+  - `--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`
+    acts as a blacklist and suppresses the specified logging kinds. Both flags
+    take a comma-separated list of logging kinds, for example `omit,infer`.
+    When using `--include-messages`, the `done` kind is included by default.
+    (You cannot specify both `--include-messages` and `--exclude-messages`.)
 
 ## Example
 
@@ -89,22 +114,27 @@ The `test.rbi` file then contains a complete RBI file for `test.rb`:
 ```ruby
 # typed: strong
 module Example
-class Person
-  sig { params(name: String, age: Integer).returns(Example::Person) }
-  def initialize(name, age); end
-  sig { 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 { 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
+  class Person
+    sig { params(name: String, age: Integer).returns(Example::Person) }
+    def initialize(name, age); end
+
+    sig { 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 { 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
 end
 ```
 
@@ -124,6 +154,13 @@ 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
+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.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -4,3 +4,75 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
+
+REPOS = {
+  addressable: 'https://github.com/sporkmonger/addressable',
+  bundler: 'https://github.com/bundler/bundler',
+  discordrb: 'https://github.com/meew0/discordrb',
+  gitlab: 'https://github.com/NARKOZ/gitlab',
+  haml: 'https://github.com/haml/haml',
+  oga: 'https://gitlab.com/yorickpeterse/oga',
+  rouge: 'https://github.com/rouge-ruby/rouge',
+  'rspec-core': 'https://github.com/rspec/rspec-core',
+  yard: 'https://github.com/lsegal/yard',
+  zeitwerk: 'https://github.com/fxn/zeitwerk'
+}
+
+namespace :examples do
+  require 'fileutils'
+  require 'colorize'
+
+  desc "Clone git repositories and run Sord on them as examples"
+  task :seed do
+    if File.directory?('sord_examples')
+      puts 'sord_examples directory already exists, please delete the directory or run a reseed!'.red
+      exit
+    end
+
+    FileUtils.mkdir 'sord_examples'
+    FileUtils.cd 'sord_examples'
+    
+    Bundler.with_clean_env do
+      # Shallow clone each of the repositories, then bundle install and run sord.
+      REPOS.each do |name, url|
+        puts "Cloning #{name}..."
+        system("git clone #{url} --depth=1")
+        FileUtils.cd name.to_s
+        # Add sord to gemfile.
+        `echo "gem 'sord', path: '../../'" >> Gemfile`
+        # Run bundle install.
+        system('bundle install')
+        # Generate sri
+        puts "Generating rbi for #{name}..."
+        system("bundle exec sord ../#{name}.rbi")
+        puts "#{name}.rbi generated!"
+        FileUtils.cd '..'
+      end
+    end
+
+    puts "Seeding complete!".green
+  end
+
+  desc 'Regenerate the rbi files in sord_examples.'
+  task :reseed do
+    FileUtils.cd 'sord_examples'
+
+    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")
+      end
+      FileUtils.cd '..'
+    end
+
+    puts "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
+  end
+end
+

data/exe/sord

@@ -1,6 +1,7 @@
 #!/usr/bin/env ruby
 require 'sord'
 require 'commander/import'
+require 'bundler'
 
 program :name, 'sord'
 program :version, Sord::VERSION
@@ -12,19 +13,53 @@ command :gen do |c|
   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.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 '--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.action do |args, options|
-    options.default comments: true, regenerate: true
+    options.default(
+      comments: true,
+      regenerate: true,
+      break_params: 4,
+      replace_errors_with_untyped: false,
+      exclude_messages: nil,
+      include_messages: nil,
+    )
 
     if args.length != 1
       Sord::Logging.error('Must specify filename')
       exit 1
     end
 
+    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(', ')}")
+        exit 1
+      end
+      Sord::Logging.enabled_types = Sord::Logging::AVAILABLE_TYPES - blacklist
+    end
+
     if options.regenerate
       begin
         Sord::Logging.info('Running YARD...')
-        `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\'.')
@@ -33,6 +68,6 @@ command :gen do |c|
       end
     end
 
-    Sord::RbiGenerator.new(options).run(args.first)
+    Sord::RbiGenerator.new(options.__hash__).run(args.first)
   end
-end
+end

data/lib/sord/logging.rb

@@ -28,6 +28,36 @@ module Sord
       @@silent = value
     end
 
+    # An array of all available logging types.
+    AVAILABLE_TYPES = [:warn, :info, :duck, :error, :infer, :omit, :done].freeze
+
+    @@enabled_types = AVAILABLE_TYPES
+
+    # Sets the array of log messages types which should be processed. Any not on
+    # this list will be discarded. This should be a subset of AVAILABLE_TYPES.
+    # @param [Array<Symbol>] value
+    # @return [void]
+    def self.enabled_types=(value)
+      raise 'invalid types' unless valid_types?(value)
+      @@enabled_types = value
+    end
+
+    # Gets the array of log messages types which should be processed. Any not on
+    # this list will be discarded.
+    # @return [Array<Symbol>]
+    # @return [void]
+    def self.enabled_types
+      @@enabled_types
+    end
+
+    # Returns a boolean indicating whether a given array is a valid value for 
+    # #enabled_types.
+    # @param [Array<Symbol>] value
+    # @return [void]
+    def self.valid_types?(value)
+      (value - AVAILABLE_TYPES).empty?
+    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.
@@ -39,7 +69,10 @@ module Sord
     #  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)
+      return unless enabled_types.include?(kind)
+
       if item
         puts "#{header} (#{item.path.bold}) #{msg}" unless silent?
       else
@@ -56,6 +89,7 @@ module Sord
     #  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)
     end
@@ -67,6 +101,7 @@ module Sord
     #  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)
     end
@@ -79,6 +114,7 @@ module Sord
     #  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)
     end
@@ -90,6 +126,7 @@ module Sord
     #  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)
     end
@@ -102,6 +139,7 @@ module Sord
     #  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)
     end
@@ -114,16 +152,19 @@ module Sord
     #  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)
     end
 
     # Print a done message. This should be used when a process completes
     # successfully.
+    # @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.
     # @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)
     end
@@ -135,6 +176,7 @@ module Sord
     #  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)
       @@hooks.each do |hook|
         hook.(kind, msg, item, indent_level) rescue nil
@@ -149,6 +191,7 @@ module Sord
     #  specified.
     # @yieldparam [Integer] indent_level The level at which to indent the code.
     # @yieldreturn [void]
+    # @return [void]
     def self.add_hook(&blk)
       @@hooks << blk
     end

data/lib/sord/rbi_generator.rb

@@ -21,19 +21,30 @@ module Sord
     #   [message, item, line].
     attr_reader :warnings
 
+    # @return [Boolean] A boolean indicating whether the next item is the first
+    #   in its namespace. This is used to determine whether to insert a blank
+    #   line before it or not.
+    attr_accessor :next_item_is_first_in_namespace
+
     # Create a new RBI generator.
     # @param [Hash] options
-    # @return [RbiGenerator]
+    # @option options [Integer] break_params
+    # @option options [Boolean] replace_errors_with_untyped
+    # @option options [Boolean] comments
+    # @return [void]
     def initialize(options)
       @rbi_contents = ['# typed: strong']
       @namespace_count = 0
       @method_count = 0
+      @break_params = options[:break_params]
+      @replace_errors_with_untyped = options[:replace_errors_with_untyped]
       @warnings = []
+      @next_item_is_first_in_namespace = true
 
       # Hook the logger so that messages are added as comments to the RBI file
       Logging.add_hook do |type, msg, item, indent_level = 0|
         rbi_contents << "#{'  ' * (indent_level + 1)}# sord #{type} - #{msg}"
-      end if options.comments
+      end if options[:comments]
 
       # Hook the logger so that warnings are collected
       Logging.add_hook do |type, msg, item, indent_level = 0|
@@ -54,21 +65,57 @@ module Sord
       @method_count += 1
     end
 
+    # Adds a single blank line to the RBI file, unless this item is the first
+    # in its namespace.
+    # @return [void]
+    def add_blank
+      rbi_contents << '' unless next_item_is_first_in_namespace
+      self.next_item_is_first_in_namespace = false
+    end
+
     # Given a YARD CodeObject, add lines defining its mixins (that is, extends
-    # and includes) to the current RBI file.
+    # and includes) to the current RBI file. Returns the number of mixins.
     # @param [YARD::CodeObjects::Base] item
     # @param [Integer] indent_level
-    # @return [void]
+    # @return [Integer]
     def add_mixins(item, indent_level)
-      extends = item.instance_mixins
-      includes = item.class_mixins
+      includes = item.instance_mixins
+      extends = item.class_mixins
 
-      extends.each do |this_extend|
+      extends.reverse_each do |this_extend|
         rbi_contents << "#{'  ' * (indent_level + 1)}extend #{this_extend.path}"
       end
-      includes.each do |this_include|
+      includes.reverse_each do |this_include|
         rbi_contents << "#{'  ' * (indent_level + 1)}include #{this_include.path}"
       end
+
+      extends.length + includes.length
+    end
+
+    # Given an array of parameters and a return type, inserts the signature for
+    # a method with those properties into the current RBI file.
+    # @param [Array<String>] params
+    # @param [String] returns
+    # @param [Integer] indent_level
+    # @return [void]
+    def add_signature(params, returns, indent_level)
+      if params.empty?
+        rbi_contents << "#{'  ' * (indent_level + 1)}sig { #{returns} }"
+        return
+      end
+
+      if params.length >= @break_params
+        rbi_contents << "#{'  ' * (indent_level + 1)}sig do"
+        rbi_contents << "#{'  ' * (indent_level + 2)}params("
+        params.each.with_index do |param, i|
+          terminator = params.length - 1 == i ? '' : ','
+          rbi_contents << "#{'  ' * (indent_level + 3)}#{param}#{terminator}"
+        end
+        rbi_contents << "#{'  ' * (indent_level + 2)}).#{returns}"
+        rbi_contents << "#{'  ' * (indent_level + 1)}end"
+      else
+        rbi_contents << "#{'  ' * (indent_level + 1)}sig { params(#{params.join(', ')}).#{returns} }"
+      end
     end
 
     # Given a YARD NamespaceObject, add lines defining its methods and their
@@ -77,8 +124,6 @@ module Sord
     # @param [Integer] indent_level
     # @return [void]
     def add_methods(item, indent_level)
-      # TODO: block documentation
-
       item.meths.each do |meth|
         count_method
 
@@ -88,6 +133,8 @@ module Sord
           next
         end
 
+        add_blank
+
         parameter_list = meth.parameters.map do |name, default|
           # Handle these three main cases:
           # - def method(param) or def method(param:)
@@ -107,55 +154,94 @@ module Sord
         # (The gsubs allow for better splat-argument compatibility)
         parameter_names_to_tags = meth.parameters.map do |name, _|
           [name, meth.tags('param')
-            .find { |p| p.name.gsub('*', '') == name.gsub('*', '') }]
+            .find { |p| p.name&.gsub('*', '') == name.gsub('*', '') }]
         end.to_h
 
         sig_params_list = parameter_names_to_tags.map do |name, tag|
           name = name.gsub('*', '')
 
           if tag
-            "#{name}: #{TypeConverter.yard_to_sorbet(tag.types, meth)}"
+            "#{name}: #{TypeConverter.yard_to_sorbet(tag.types, meth, indent_level, @replace_errors_with_untyped)}"
           elsif name.start_with? '&'
-            # Cut the ampersand from the block parameter name.
-            "#{name[1..-1]}: T.untyped"
+            # Cut the ampersand from the block parameter name
+            name = name.gsub('&', '')
+
+            # Find yieldparams and yieldreturn
+            yieldparams = meth.tags('yieldparam')
+            yieldreturn = meth.tag('yieldreturn')&.types
+            yieldreturn = nil if yieldreturn&.length == 1 &&
+              yieldreturn&.first&.downcase == 'void'
+
+            # Create strings
+            params_string = yieldparams.map do |param|
+              "#{param.name.gsub('*', '')}: #{TypeConverter.yard_to_sorbet(param.types, meth, indent_level, @replace_errors_with_untyped)}" unless param.name.nil?
+            end.join(', ')
+            return_string = TypeConverter.yard_to_sorbet(yieldreturn, meth, indent_level, @replace_errors_with_untyped)
+
+            # Create proc types, if possible
+            if yieldparams.empty? && yieldreturn.nil?
+              "#{name}: T.untyped"
+            elsif yieldreturn.nil?
+              "#{name}: T.proc#{params_string.empty? ? '' : ".params(#{params_string})"}.void"
+            else
+              "#{name}: T.proc#{params_string.empty? ? '' : ".params(#{params_string})"}.returns(#{return_string})"
+            end
           elsif meth.path.end_with? '='
             # Look for the matching getter method
             getter_path = meth.path[0...-1]
             getter = item.meths.find { |m| m.path == getter_path }
 
             unless getter
-              Logging.omit("no YARD type given for #{name.inspect}, using T.untyped", meth, indent_level)
-              next "#{name}: T.untyped"
+              if parameter_names_to_tags.length == 1 \
+                && meth.tags('param').length == 1 \
+                && meth.tag('param').types
+  
+                Logging.infer("argument name in single @param inferred as #{parameter_names_to_tags.first.first.inspect}", meth, indent_level)
+                next "#{name}: #{TypeConverter.yard_to_sorbet(meth.tag('param').types, meth, indent_level, @replace_errors_with_untyped)}"
+              else  
+                Logging.omit("no YARD type given for #{name.inspect}, using T.untyped", meth, indent_level)
+                next "#{name}: T.untyped"
+              end
             end
 
             inferred_type = TypeConverter.yard_to_sorbet(
-              getter.tags('return').flat_map(&:types), meth)
+              getter.tags('return').flat_map(&:types), meth, indent_level, @replace_errors_with_untyped)
             
             Logging.infer("inferred type of parameter #{name.inspect} as #{inferred_type} using getter's return type", meth, indent_level)
             # Get rid of : on keyword arguments.
             name = name.chop if name.end_with?(':')
             "#{name}: #{inferred_type}"
           else
-            Logging.omit("no YARD type given for #{name.inspect}, using T.untyped", meth, indent_level)
-            # Get rid of : on keyword arguments.
-            name = name.chop if name.end_with?(':')
-            "#{name}: T.untyped"
+            # Is this the only argument, and was a @param specified without an
+            # argument name? If so, infer it
+            if parameter_names_to_tags.length == 1 \
+              && meth.tags('param').length == 1 \
+              && meth.tag('param').types
+
+              Logging.infer("argument name in single @param inferred as #{parameter_names_to_tags.first.first.inspect}", meth, indent_level)
+              "#{name}: #{TypeConverter.yard_to_sorbet(meth.tag('param').types, meth, indent_level, @replace_errors_with_untyped)}"
+            else
+              Logging.omit("no YARD type given for #{name.inspect}, using T.untyped", meth, indent_level)
+              # Get rid of : on keyword arguments.
+              name = name.chop if name.end_with?(':')
+              "#{name}: T.untyped"
+            end
           end
-        end.join(", ")
+        end
 
         return_tags = meth.tags('return')
         returns = if return_tags.length == 0
-          "void"
+          Logging.omit("no YARD return type given, using T.untyped", meth, indent_level)
+          "returns(T.untyped)"
         elsif return_tags.length == 1 && return_tags&.first&.types&.first&.downcase == "void"
           "void"
         else
-          "returns(#{TypeConverter.yard_to_sorbet(meth.tag('return').types, meth)})"
+          "returns(#{TypeConverter.yard_to_sorbet(meth.tag('return').types, meth, indent_level, @replace_errors_with_untyped)})"
         end
 
         prefix = meth.scope == :class ? 'self.' : ''
 
-        sig = sig_params_list.empty? ? "#{'  ' * (indent_level + 1)}sig { #{returns} }" : "#{'  ' * (indent_level + 1)}sig { params(#{sig_params_list}).#{returns} }"
-        rbi_contents << sig
+        add_signature(sig_params_list, returns, indent_level)
 
         rbi_contents << "#{'  ' * (indent_level + 1)}def #{prefix}#{meth.name}(#{parameter_list}); end"
       end
@@ -165,41 +251,55 @@ module Sord
     # and children to the RBI file.
     # @param [YARD::CodeObjects::NamespaceObject] item
     # @param [Integer] indent_level
+    # @return [void]
     def add_namespace(item, indent_level = 0)
       count_namespace
+      add_blank
 
       if item.type == :class && item.superclass.to_s != "Object"
         rbi_contents << "#{'  ' * indent_level}class #{item.name} < #{item.superclass.path}" 
       else
         rbi_contents << "#{'  ' * indent_level}#{item.type} #{item.name}"
       end
-      add_mixins(item, indent_level)
+
+      self.next_item_is_first_in_namespace = true
+      if add_mixins(item, indent_level) > 0
+        self.next_item_is_first_in_namespace = false
+      end
       add_methods(item, indent_level)
 
       item.children.select { |x| [:class, :module].include?(x.type) }
         .each { |child| add_namespace(child, indent_level + 1) }
 
+      self.next_item_is_first_in_namespace = false
+
       rbi_contents << "#{'  ' * indent_level}end"
     end
 
-    # Generates the RBI file and writes it to the given file path.
-    # @param [String] filename
+    # Generates the RBI file from the loading registry and returns its contents.
+    # You must load a registry first!
+    # @return [String]
+    def generate
+      # Generate top-level modules, which recurses to all modules
+      YARD::Registry.root.children
+        .select { |x| [:class, :module].include?(x.type) }
+        .each { |child| add_namespace(child) }
+
+      rbi_contents.join("\n")
+    end
+
+    # Generates the RBI file and writes it to the given file path, printing a
+    # summary and any warnings at the end. The registry is also loaded.
+    # @param [String, nil] filename
     # @return [void]
     def run(filename)
-      raise "No filename specified" unless filename
+      raise 'No filename specified' unless filename
 
       # Get YARD ready
       YARD::Registry.load!
 
-      # TODO: constants?
-
-      # Generate top-level modules, which recurses to all modules
-      YARD::Registry.root.children
-        .select { |x| [:class, :module].include?(x.type) }
-        .each { |child| add_namespace(child) }
-
       # Write the file
-      File.write(filename, rbi_contents.join(?\n))
+      File.write(filename, generate)
 
       if object_count.zero?
         Logging.warn("No objects processed.")
@@ -213,11 +313,15 @@ module Sord
 
       unless warnings.empty?
         Logging.warn("There were #{warnings.length} important warnings in the RBI file, listed below.")
-        Logging.warn("The types which caused them have been replaced with SORD_ERROR_ constants.")
+        if @replace_errors_with_untyped
+          Logging.warn("The types which caused them have been replaced with T.untyped.")
+        else
+          Logging.warn("The types which caused them have been replaced with SORD_ERROR_ constants.")
+        end
         Logging.warn("Please edit the file near the line numbers given to fix these errors.")
         Logging.warn("Alternatively, edit your YARD documentation so that your types are valid and re-run Sord.")
         warnings.each do |(msg, item, line)|
-          puts "        #{"Line #{line} |".light_black} (#{item.path.bold}) #{msg}"
+          puts "        #{"Line #{line} |".light_black} (#{item&.path&.bold}) #{msg}"
         end
       end
     rescue