sord 7.0.0 → 7.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cd5e0c9f0db7151e0f04f309f277fecb64ce6aaf2fefdff88f749ce7a6d02d1
-  data.tar.gz: 8ef9d26ef5b4e6cf6acc7a6bfa9f46887a07891346e37cdb46b5e48d903c22bd
+  metadata.gz: 8f9681f7b1837fb0fb51588fb60d8bb94406b9bb9a488670244542971b0b66c7
+  data.tar.gz: 7db1dc6e7a1e3cf43d08ef6850da15eaebf18463fb5a329cdf42acb7da12c0a0
 SHA512:
-  metadata.gz: 5b5dbaa497fe039afcb125a9e7801bdb124ed1e06b2ba0970b3743f9cfad1aa92a982710fa0f2eb5da9647803e8b2e8d6d11e3b236891687eca35c4f16c25626
-  data.tar.gz: 3b432c0005c9cc1d00b6ec4c42a52eb8be6e8dc8425e6eb2a168b1c503e6f6df5fa5ea2a2cfb4c3e4fad98de88104e2166f8cda469305ec383719080a7836ffe
+  metadata.gz: 84ae70452bf558690f4da7c7fb6c2b1ba65b4cf906a813b04c27766b7ad7ddb549013b49f149593c0a4366016689c0f21f904c09cd3533a19f42ea814655fea7
+  data.tar.gz: 349e397a495df5dd01d7a13eac6541f9d2b0446dbc150e74be756dbc02ead11e7c558ec27f111d852f6c39f4719deb6ba6c56bffed99a44af5a11570f20ea3fc

data/.github/workflows/examples.yml

@@ -0,0 +1,22 @@
+name: Run Sord on examples
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    continue-on-error: false
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 3.4 # Use latest for best chance of dependencies resolving
+    - name: Install dependencies
+      run: bundle install
+    - name: Install example dependencies
+      run: sudo apt-get install libldap2-dev libidn11-dev # Dependencies for `addressable`
+    - name: Run examples (RBI)
+      run: bundle exec rake examples:seed[rbi]
+    - name: Run examples (RBS)
+      run: bundle exec rake examples:reseed[rbs]

data/.github/workflows/ruby.yml

@@ -6,7 +6,7 @@ jobs:
   test:
     strategy:
       matrix:
-        ruby: [3.0, 3.1]
+        ruby: [3.0, 3.1, 3.2, 3.3, 3.4]
     continue-on-error: false
 
     runs-on: ubuntu-latest

data/CHANGELOG.md

@@ -3,6 +3,22 @@ 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/).
 
+## [7.1.0] - 2025-07-07
+### Added
+- `nil` can be used as an alias for `NilClass` in more places in YARD types. (Thanks @apiology)
+- The Solargraph convention `undefined` can now be used as an "untyped" type. (Thanks @apiology)
+
+### Changed
+- If a constant's value does not parse successfully, type information can still be generated for
+  that constant, and Sord emits a warning. Previously, this would cause a fatal exception.
+- The version restriction on the RBS gem has been relaxed, to permit usage of 4.x versions.
+  RBS 3.x can still be used as before.
+  (Thanks @apiology)
+
+### Fixed
+- Sord now correctly resolves namespaces when classes have a namespace, e.g. `class X::Y`.
+  (Thanks @dorner)
+
 ## [7.0.0] - 2025-03-03
 ### Added
 - Messages now show the file and line number that the message originated from. (Thanks @apiology)

data/Rakefile

@@ -19,85 +19,138 @@ REPOS = {
   zeitwerk: 'https://github.com/fxn/zeitwerk'
 }
 
-namespace :examples do
-  require 'fileutils'
-  require 'rainbow'
+# Thrown by tasks to present a "friendly" error message and abort the task.
+class TaskError < StandardError
+end
 
-  desc "Clone git repositories and run Sord on them as examples"
-  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
+# Handles Sord examples, including checkout and running Sord to generate types.
+class ExampleRunner
+  attr_reader :mode, :mode_arg, :clean
+  alias clean? clean
+
+  # @return [<Symbol>] Names of gems where Sord failed.
+  attr_accessor :failed_examples
 
-    if args[:mode] == 'rbi'
-      mode_arg = '--rbi'
-    elsif args[:mode] == 'rbs'
-      mode_arg = '--rbs'
+  # @param [String] mode "rbi" or "rbs".
+  # @param [Boolean] clean Run Sord with additional options to generate minimal type output.
+  def initialize(mode:, clean: false)
+    @mode = mode
+    @clean = clean
+
+    if mode == 'rbi'
+      @mode_arg = '--rbi'
+    elsif mode == 'rbs'
+      @mode_arg = '--rbs'
     else
-      puts Rainbow('please specify \'rbi\' or \'rbs\'!').red
-      exit
+      raise TaskError, 'please specify \'rbi\' or \'rbs\'!'
+    end
+
+    @failed_examples = []
+  end
+
+  # Create the `sord_examples` directory, ready for checkouts.
+  # @raise [TaskError] If it already exists.
+  def create_examples_dir
+    if File.directory?(File.join(__dir__, 'sord_examples'))
+      raise TaskError, 'sord_examples directory already exists, please delete the directory or run a reseed!'
     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
+  end
+
+  # Check that the `sord_examples` directory exists.
+  # @raise [TaskError] If it doesn't.
+  def validate_examples_dir
+    unless File.directory?(File.join(__dir__, 'sord_examples'))
+      raise TaskError, 'The sord_examples directory does not exist. Have you run the seed task?'
+    end
+  end
+
+  # Check out a repository, add Sord to its Gemfile, and install its dependencies.
+  # @param [Symbol] name Name of the checkout.
+  # @param [String] url Git URL.
+  def prepare_checkout(name, url)
+    Dir.chdir(File.join(__dir__, 'sord_examples')) do
+      puts "Cloning #{name}..."
+      system("git clone #{url} --depth=1")
+
+      Dir.chdir(name.to_s) do
         # Add sord to gemfile.
         `echo "gem 'sord', path: '../../'" >> Gemfile`
+
         # Run bundle install.
         system('bundle install')
-        # Generate sri
-        puts "Generating rbi for #{name}..."
-        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
+  end
 
-    puts Rainbow("Seeding complete!").green
+  # Run Sord on a checked-out repository.
+  # @param [Symbol] name Name of the checkout.
+  def generate_types(name)
+    puts "Generating rbi for #{name}..."
+
+    Dir.chdir(File.join(__dir__, 'sord_examples', name.to_s)) do
+      if clean?
+        system("bundle exec sord ../#{name}.#{mode} #{mode_arg} --no-sord-comments --replace-errors-with-untyped --replace-unresolved-with-untyped")
+      else
+        system("bundle exec sord ../#{name}.#{mode} #{mode_arg}")
+      end
+
+      if $?.success?
+        puts "#{name}.#{mode} generated!"
+      else
+        puts "Sord exited with error"
+        failed_examples << name
+      end
+    end
   end
 
-  desc 'Regenerate the rbi files in 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
+  # Check that all Sord executions were successful.
+  # @raise [TaskError] If any failed.
+  def validate_sord_success
+    if failed_examples.any?
+      raise TaskError, "Not all Sord runs were successful: #{failed_examples.map(&:to_s).join(', ')}"
     end
+  end
+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
+namespace :examples do
+  require 'fileutils'
+  require 'rainbow'
+
+  desc "Clone git repositories and run Sord on them as examples"
+  task :seed, [:mode, :clean] do |t, args|
+    examples = ExampleRunner.new(**args)
+    examples.create_examples_dir
+
+    Bundler.with_clean_env do
+      REPOS.each do |name, url|
+        examples.prepare_checkout(name, url)
+        examples.generate_types(name)
+      end
     end
+    examples.validate_sord_success
+
+    puts Rainbow("Seeding complete!").green
+
+  rescue TaskError => e
+    abort Rainbow(e.to_s).red
+  end
+
+  desc 'Regenerate the rbi files in sord_examples.'
+  task :reseed, [:mode, :clean] do |t, args|
+    examples = ExampleRunner.new(**args)
+    examples.validate_examples_dir
 
     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}.#{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 '..'
+      examples.generate_types(name)
     end
+    examples.validate_sord_success
 
     puts Rainbow("Re-seeding complete!").green
+
+  rescue TaskError => e
+    abort Rainbow(e.to_s).red
   end
   
   desc 'Delete the sord_examples directory to allow the seeder to run again.'

data/lib/sord/generator.rb

@@ -143,22 +143,29 @@ module Sord
         when :rbi
           # Parse so we can set up constant with correct heredoc syntax
           kwargs = {}
-          value_node = Parser::CurrentRuby.parse(constant.value)
-          loc = value_node.loc
-          if loc.instance_of? Parser::Source::Map::Heredoc
-            #
-            # heredocs in Ruby come after the full expression is complete.  e.g.,
-            # puts(>>FOO)
-            #   bar
-            # FOO
-            #
-            # so if we want to wrap them in a T.let, we need to parse out the expression vs the rest
-            kwargs[:heredocs] = constant.value[loc.heredoc_body.begin_pos...loc.heredoc_end.end_pos]
-            expression = loc.expression
-            value = constant.value[expression.begin_pos...expression.end_pos]
-          else
-            value = constant.value
+
+          value = constant.value
+          begin
+            value_node = Parser::CurrentRuby.parse(constant.value)
+            loc = value_node.loc
+            if loc.instance_of? Parser::Source::Map::Heredoc
+              #
+              # heredocs in Ruby come after the full expression is complete.  e.g.,
+              # puts(>>FOO)
+              #   bar
+              # FOO
+              #
+              # so if we want to wrap them in a T.let, we need to parse out the expression vs the rest
+              kwargs[:heredocs] = constant.value[loc.heredoc_body.begin_pos...loc.heredoc_end.end_pos]
+              expression = loc.expression
+              value = constant.value[expression.begin_pos...expression.end_pos]
+            end
+
+          rescue Parser::SyntaxError => e
+            # Emit a warning, since this may cause a syntax error when parsing the RBI
+            Logging.warn("syntax error on constant value: #{e}", constant)
           end
+
           @current_object.create_constant(constant_name, value: "T.let(#{value}, T.untyped)", **kwargs) do |c|
             c.add_comments(constant.docstring.all.split("\n"))
           end
@@ -681,10 +688,8 @@ module Sord
         end
       end
     rescue
-      Logging.error($!)
-      $@.each do |line|
-        puts "         #{line}"
-      end
+      Logging.error("An internal error occurred while running Sord: #{$!}")
+      raise
     end
 
     # Given two pairs of arrays representing method parameters, in the form

data/lib/sord/resolver.rb

@@ -70,14 +70,21 @@ module Sord
       klasses = [
         Parlour::RbiGenerator::Constant,
         Parlour::RbiGenerator::ModuleNamespace,
-        Parlour::RbiGenerator::ClassNamespace
+        Parlour::RbiGenerator::ClassNamespace,
+        Parlour::RbiGenerator::Namespace
+      ]
+      child_only_classes = [
+        Parlour::RbiGenerator::Namespace
       ]
       nodes.each do |node|
-        next unless klasses.include?(node.class)
-        new_path = path + [node.name]
-        names_to_paths[node.name] ||= Set.new
-        names_to_paths[node.name] << new_path.join('::')
-        add_rbi_objects_to_paths(node.children, names_to_paths, new_path) if node.respond_to?(:children)
+        if klasses.include?(node.class)
+          new_path = path + [node.name]
+          unless child_only_classes.include?(node.class)
+            names_to_paths[node.name] ||= Set.new
+            names_to_paths[node.name] << new_path.join('::')
+          end
+          add_rbi_objects_to_paths(node.children, names_to_paths, new_path) if node.respond_to?(:children)
+        end
       end
     end
 

data/lib/sord/type_converter.rb

@@ -129,8 +129,12 @@ module Sord
       case yard
       when nil # Type not specified
         Parlour::Types::Untyped.new
+      when "nil"
+        Parlour::Types::Raw.new('NilClass')
       when  "bool", "Bool", "boolean", "Boolean", "true", "false"
         Parlour::Types::Boolean.new
+      when "undefined" # solargraph convention
+        Parlour::Types::Untyped.new
       when 'self'
         Parlour::Types::Self.new
       when Array
@@ -195,10 +199,11 @@ module Sord
         relative_generic_type = generic_type.start_with?('::') \
           ? generic_type[2..-1] : generic_type
 
-        parameters = split_type_parameters(type_parameters)
+        yard_parameters = split_type_parameters(type_parameters)
+        parameters = yard_parameters
           .map { |x| yard_to_parlour(x, item, config) }
-        if SINGLE_ARG_GENERIC_TYPES.include?(relative_generic_type) && parameters.length > 1
-          Parlour::Types.const_get(relative_generic_type).new(Parlour::Types::Union.new(parameters))
+        if SINGLE_ARG_GENERIC_TYPES.include?(relative_generic_type) && yard_parameters.length > 1
+          Parlour::Types.const_get(relative_generic_type).new(yard_to_parlour(yard_parameters, item, config))
         elsif relative_generic_type == 'Class'
           if parameters.length == 1
             Parlour::Types::Class.new(parameters.first)

data/lib/sord/version.rb

@@ -1,4 +1,4 @@
 # typed: strong
 module Sord
-  VERSION = '7.0.0'
+  VERSION = '7.1.0'
 end

data/rbi/sord.rbi

@@ -1,7 +1,7 @@
 # typed: strong
 # typed: strong
 module Sord
-  VERSION = T.let('7.0.0', T.untyped)
+  VERSION = T.let('7.1.0', T.untyped)
 
   # Handles writing logs to stdout and any other classes which request them.
   module Logging

data/sord.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'commander', '~> 5.0'
   spec.add_dependency "parser"
   spec.add_dependency 'parlour', '~> 9.1'
-  spec.add_dependency 'rbs', '~> 3.0'
+  spec.add_dependency 'rbs', '>=3.0', '<5'
 
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 13.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sord
 version: !ruby/object:Gem::Version
-  version: 7.0.0
+  version: 7.1.0
 platform: ruby
 authors:
 - Aaron Christiansen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-03 00:00:00.000000000 Z
+date: 2025-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -84,16 +84,22 @@ dependencies:
   name: rbs
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -174,6 +180,7 @@ extra_rdoc_files: []
 files:
 - ".github/ISSUE_TEMPLATE/bug_report.md"
 - ".github/ISSUE_TEMPLATE/feature-request.md"
+- ".github/workflows/examples.yml"
 - ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".parlour"
@@ -214,7 +221,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.4.1
 signing_key:
 specification_version: 4
 summary: Generate Sorbet RBI files from YARD documentation