rbs-relaxed 3.9.0.1

data/COPYING

@@ -0,0 +1,56 @@
+rbs is copyrighted free software by Soutaro Matsumoto <matsumoto@soutaro.com>.
+You can redistribute it and/or modify it under either the terms of the
+2-clause BSDL (see the file BSDL), or the conditions below:
+
+1. You may make and give away verbatim copies of the source form of the
+   software without restriction, provided that you duplicate all of the
+   original copyright notices and associated disclaimers.
+
+2. You may modify your copy of the software in any way, provided that
+   you do at least ONE of the following:
+
+   a. place your modifications in the Public Domain or otherwise
+      make them Freely Available, such as by posting said
+      modifications to Usenet or an equivalent medium, or by allowing
+      the author to include your modifications in the software.
+
+   b. use the modified software only within your corporation or
+      organization.
+
+   c. give non-standard binaries non-standard names, with
+      instructions on where to get the original software distribution.
+
+   d. make other distribution arrangements with the author.
+
+3. You may distribute the software in object code or binary form,
+   provided that you do at least ONE of the following:
+
+   a. distribute the binaries and library files of the software,
+      together with instructions (in the manual page or equivalent)
+      on where to get the original distribution.
+
+   b. accompany the distribution with the machine-readable source of
+      the software.
+
+   c. give non-standard binaries non-standard names, with
+      instructions on where to get the original software distribution.
+
+   d. make other distribution arrangements with the author.
+
+4. You may modify and include the part of the software into any other
+   software (possibly commercial).  But some files in the distribution
+   are not written by the author, so that they are not under these terms.
+
+   For the list of those files and their copying conditions, see the
+   file LEGAL.
+
+5. The scripts and library files supplied as input to or produced as
+   output from the software do not automatically fall under the
+   copyright of the software, but belong to whomever generated them,
+   and may be sold commercially, and may be aggregated with this
+   software.
+
+6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+   IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+   WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+   PURPOSE.

data/README.md

@@ -0,0 +1,203 @@
+# RBS
+
+RBS is a language to describe the structure of Ruby programs.
+You can write down the definition of a class or module: methods defined in the class, instance variables and their types, and inheritance/mix-in relations.
+It also allows declaring constants and global variables.
+
+The following is a small example of RBS for a chat app.
+
+<!-- run-start:a.rbs:bundle exec rbs -I a.rbs validate -->
+```rbs
+module ChatApp
+  VERSION: String
+
+  class User
+    attr_reader login: String
+    attr_reader email: String
+
+    def initialize: (login: String, email: String) -> void
+  end
+
+  class Bot
+    attr_reader name: String
+    attr_reader email: String
+    attr_reader owner: User
+
+    def initialize: (name: String, owner: User) -> void
+  end
+
+  class Message
+    attr_reader id: String
+    attr_reader string: String
+    attr_reader from: User | Bot                     # `|` means union types: `#from` can be `User` or `Bot`
+    attr_reader reply_to: Message?                   # `?` means optional type: `#reply_to` can be `nil`
+
+    def initialize: (from: User | Bot, string: String) -> void
+
+    def reply: (from: User | Bot, string: String) -> Message
+  end
+
+  class Channel
+    attr_reader name: String
+    attr_reader messages: Array[Message]
+    attr_reader users: Array[User]
+    attr_reader bots: Array[Bot]
+
+    def initialize: (name: String) -> void
+
+    def each_member: () { (User | Bot) -> void } -> void  # `{` and `}` means block.
+                   | () -> Enumerator[User | Bot, void]   # Method can be overloaded.
+  end
+end
+```
+<!-- run-end -->
+
+## The Target Version
+
+* The standard library signatures targets the latest release of Ruby. (`3.2` as of 2023.)
+* The library code targets non-EOL versions of Ruby. (`>= 3.0` as of 2023.)
+
+## Installation
+
+Install the `rbs` gem. `$ gem install rbs` from the command line, or add a line in your `Gemfile`.
+
+```rb
+gem "rbs"
+```
+
+## CLI
+
+The gem ships with the `rbs` command line tool to demonstrate what it can do and help develop RBS.
+
+```console
+$ rbs version
+$ rbs list
+$ rbs ancestors ::Object
+$ rbs methods ::Object
+$ rbs method Object then
+```
+
+An end user of `rbs` will probably find `rbs prototype` the most useful. This command generates boilerplate signature declarations for ruby files. For example, say you have written the below ruby script.
+
+```ruby
+# person.rb
+class Person
+  attr_reader :name
+  attr_reader :contacts
+
+  def initialize(name:)
+    @name = name
+    @contacts = []
+  end
+
+  def speak
+    "I'm #{@name} and I love Ruby!"
+  end
+end
+```
+
+Running prototype on the above will automatically generate
+
+```console
+$ rbs prototype rb person.rb
+class Person
+  @name: untyped
+
+  @contacts: untyped
+
+  attr_reader name: untyped
+
+  attr_reader contacts: untyped
+
+  def initialize: (name: untyped) -> void
+
+  def speak: () -> ::String
+end
+```
+
+It prints signatures for all methods, classes, instance variables, and constants.
+This is only a starting point, and you should edit the output to match your signature more accurately.
+
+`rbs prototype` offers three options.
+
+- `rb` generates from just the available Ruby code
+- `rbi` generates from Sorbet RBI
+- `runtime` generates from runtime API
+
+## Library
+
+There are two important concepts, _environment_ and _definition_.
+
+An _environment_ is a dictionary that keeps track of all declarations. What is the declaration associated with `String` class? An _environment_ will give you the answer.
+
+A _definition_ gives you the detail of the class. What is the type of the return value of `gsub` method of the `String` class? The _definition_ for `String` class knows the list of methods it provides and their types.
+
+The following is a small code to retrieve the definition of the `String#gsub` method.
+
+<!-- run-start:a.rb:bundle exec ruby a.rb -->
+```rb
+require "rbs"
+
+loader = RBS::EnvironmentLoader.new()
+
+# loader.add(path: Pathname("sig"))   # Load .rbs files from `sig` directory
+# loader.add(library: "pathname")     # Load pathname library
+
+environment = RBS::Environment.from_loader(loader).resolve_type_names
+
+# ::String
+string = RBS::TypeName.new(name: :String, namespace: RBS::Namespace.root)
+
+# Class declaration for ::String
+decl = environment.class_decls[string]
+
+# Builder provides the translation from `declaration` to `definition`
+builder = RBS::DefinitionBuilder.new(env: environment)
+
+# Definition of instance of String
+instance = builder.build_instance(string)
+
+# Print the types of `gsub` method:
+puts instance.methods[:gsub].method_types.join("\n")
+# Outputs =>
+#  (::Regexp | ::string pattern, ::string replacement) -> ::String
+#  (::Regexp | ::string pattern, ::Hash[::String, ::String] hash) -> ::String
+#  (::Regexp | ::string pattern) { (::String match) -> ::_ToS } -> ::String
+#  (::Regexp | ::string pattern) -> ::Enumerator[::String, self]
+
+# Definition of singleton of String
+singleton = builder.build_singleton(string)
+# No `gsub` method for String singleton
+puts singleton.methods[:gsub]
+```
+<!-- run-end -->
+
+## Guides
+
+- [Architecture](docs/architecture.md)
+- [Core and standard library signature contribution guide](docs/CONTRIBUTING.md)
+- [Writing signatures guide](docs/sigs.md)
+- [Stdlib signatures guide](docs/stdlib.md)
+- [Syntax](docs/syntax.md)
+- [RBS by Example](docs/rbs_by_example.md)
+- [RBS collection](docs/collection.md)
+- [Using `Data` and `Struct`](docs/data_and_struct.md)
+- [Releasing a gem with RBS](docs/gem.md)
+
+## Community
+
+Here is a list of some places you can talk with active maintainers.
+
+- [Ruby Discord Server (invite link)](https://discord.gg/ad2acQFtkh) -- We have `rbs` channel in Ruby Discord server.
+- [ruby-jp Slack Workspace (in Japanese)](https://ruby-jp.github.io/) -- We have `types` channel in ruby-jp slack workspace.
+- [gem_rbs_collection](https://github.com/ruby/gem_rbs_collection) -- We have a repository of third-party RBS type definitions, for the case your dependency doesn't ship with RBS files.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/rbs.

data/Rakefile

@@ -0,0 +1,417 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rbconfig"
+require 'rake/extensiontask'
+
+$LOAD_PATH << File.join(__dir__, "test")
+
+ruby = ENV["RUBY"] || RbConfig.ruby
+rbs = File.join(__dir__, "exe/rbs")
+bin = File.join(__dir__, "bin")
+
+Rake::ExtensionTask.new("rbs_extension")
+
+Rake::TestTask.new(:test => :compile) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"].reject do |path|
+    path =~ %r{test/stdlib/}
+  end
+end
+
+multitask :default => [:test, :stdlib_test, :typecheck_test, :rubocop, :validate, :test_doc]
+
+task :lexer do
+  sh "re2c -W --no-generation-date -o ext/rbs_extension/lexer.c ext/rbs_extension/lexer.re"
+end
+
+task :confirm_lexer => :lexer do
+  puts "Testing if lexer.c is updated with respect to lexer.re"
+  sh "git diff --exit-code ext/rbs_extension/lexer.c"
+end
+
+task :confirm_templates => :templates do
+  puts "Testing if generated code under include and src is updated with respect to templates"
+  sh "git diff --exit-code -- include src"
+end
+
+rule ".c" => ".re" do |t|
+  puts "⚠️⚠️⚠️ #{t.name} is older than #{t.source}. You may need to run `rake lexer` ⚠️⚠️⚠️"
+end
+
+rule %r{^src/(.*)\.c} => 'templates/%X.c.erb' do |t|
+  puts "⚠️⚠️⚠️ #{t.name} is older than #{t.source}. You may need to run `rake templates` ⚠️⚠️⚠️"
+end
+rule %r{^include/(.*)\.c} => 'templates/%X.c.erb' do |t|
+  puts "⚠️⚠️⚠️ #{t.name} is older than #{t.source}. You may need to run `rake templates` ⚠️⚠️⚠️"
+end
+
+task :annotate do
+  sh "bin/generate_docs.sh"
+end
+
+task :confirm_annotation do
+  puts "Testing if RBS docs are updated with respect to RDoc"
+  sh "git diff --exit-code core stdlib"
+end
+
+task :templates do
+  sh "#{ruby} templates/template.rb include/rbs/constants.h"
+  sh "#{ruby} templates/template.rb include/rbs/ruby_objs.h"
+  sh "#{ruby} templates/template.rb src/constants.c"
+  sh "#{ruby} templates/template.rb src/ruby_objs.c"
+end
+
+task :compile => "ext/rbs_extension/lexer.c"
+task :compile => "include/rbs/constants.h"
+task :compile => "include/rbs/ruby_objs.h"
+task :compile => "src/constants.c"
+task :compile => "src/ruby_objs.c"
+
+task :test_doc do
+  files = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").select do |file| Pathname(file).extname == ".md" end
+  end
+
+  sh "#{ruby} #{__dir__}/bin/run_in_md.rb #{files.join(" ")}"
+end
+
+task :validate => :compile do
+  require 'yaml'
+
+  sh "#{ruby} #{rbs} validate --exit-error-on-syntax-error"
+
+  libs = FileList["stdlib/*"].map {|path| File.basename(path).to_s }
+
+  # Skip RBS validation because Ruby CI runs without rubygems
+  case skip_rbs_validation = ENV["SKIP_RBS_VALIDATION"]
+  when nil
+    begin
+      Gem::Specification.find_by_name("rbs")
+      libs << "rbs"
+    rescue Gem::MissingSpecError
+      STDERR.puts "🚨🚨🚨🚨 Skipping `rbs` gem because it's not found"
+    end
+  when "true"
+    # Skip
+  else
+    STDERR.puts "🚨🚨🚨🚨 SKIP_RBS_VALIDATION is expected to be `true` or unset, given `#{skip_rbs_validation}` 🚨🚨🚨🚨"
+    libs << "rbs"
+  end
+
+  libs.each do |lib|
+    sh "#{ruby} #{rbs} -r #{lib} validate --exit-error-on-syntax-error"
+  end
+end
+
+FileList["test/stdlib/**/*_test.rb"].each do |test|
+  task test => :compile do
+    sh "#{ruby} -Ilib #{bin}/test_runner.rb #{test}"
+  end
+end
+
+task :stdlib_test => :compile do
+  test_files = FileList["test/stdlib/**/*_test.rb"].reject do |path|
+    path =~ %r{Ractor} || path =~ %r{Encoding}
+  end
+
+  if ENV["RANDOMIZE_STDLIB_TEST_ORDER"] == "true"
+    test_files.shuffle!
+  end
+
+  sh "#{ruby} -Ilib #{bin}/test_runner.rb #{test_files.join(' ')}"
+  # TODO: Ractor tests need to be run in a separate process
+  sh "#{ruby} -Ilib #{bin}/test_runner.rb test/stdlib/Ractor_test.rb"
+  sh "#{ruby} -Ilib #{bin}/test_runner.rb test/stdlib/Encoding_test.rb"
+end
+
+task :typecheck_test => :compile do
+  FileList["test/typecheck/*"].each do |test|
+    Dir.chdir(test) do
+      expectations = File.join(test, "steep_expectations.yml")
+      if File.exist?(expectations)
+        sh "steep check --with_expectations"
+      else
+        sh "steep check"
+      end
+    end
+  end
+end
+
+task :raap => :compile do
+  sh "ruby test/raap/core.rb"
+  sh "ruby test/raap/digest.rb"
+  sh "ruby test/raap/openssl.rb"
+end
+
+task :rubocop do
+  format = if ENV["CI"]
+    "github"
+  else
+    "progress"
+  end
+
+  sh "rubocop --parallel --format #{format}"
+end
+
+namespace :generate do
+  desc "Generate a test file for a stdlib class signatures"
+  task :stdlib_test, [:class] do |_task, args|
+    klass = args.fetch(:class) do
+      raise "Class name is necessary. e.g. rake 'generate:stdlib_test[String]'"
+    end
+
+    require "erb"
+    require "rbs"
+
+    class TestTarget
+      def initialize(klass)
+        @type_name = RBS::Namespace.parse(klass).to_type_name
+      end
+
+      def path
+        Pathname(ENV['RBS_GENERATE_TEST_PATH'] || "test/stdlib/#{file_name}_test.rb")
+      end
+
+      def file_name
+        @type_name.to_s.gsub(/\A::/, '').gsub(/::/, '_')
+      end
+
+      def to_s
+        @type_name.to_s
+      end
+
+      def absolute_type_name
+        @absolute_type_name ||= @type_name.absolute!
+      end
+    end
+
+    target = TestTarget.new(klass)
+    path = target.path
+    raise "#{path} already exists!" if path.exist?
+
+    class TestTemplateBuilder
+      attr_reader :target, :env
+
+      def initialize(target)
+        @target = target
+
+        loader = RBS::EnvironmentLoader.new
+        Dir['stdlib/*'].each do |lib|
+          next if lib.end_with?('builtin')
+
+          loader.add(library: File.basename(lib))
+        end
+        @env = RBS::Environment.from_loader(loader).resolve_type_names
+      end
+
+      def call
+        ERB.new(<<~ERB, trim_mode: "-").result(binding)
+          require_relative "test_helper"
+
+          <%- unless class_methods.empty? -%>
+          class <%= target %>SingletonTest < Test::Unit::TestCase
+            include TestHelper
+
+            # library "pathname", "securerandom"     # Declare library signatures to load
+            testing "singleton(::<%= target %>)"
+
+          <%- class_methods.each do |method_name, definition| -%>
+            def test_<%= test_name_for(method_name) %>
+          <%- definition.method_types.each do |method_type| -%>
+              assert_send_type "<%= method_type %>",
+                               <%= target %>, :<%= method_name %>
+          <%- end -%>
+            end
+
+          <%- end -%>
+          end
+          <%- end -%>
+
+          <%- unless instance_methods.empty? -%>
+          class <%= target %>Test < Test::Unit::TestCase
+            include TestHelper
+
+            # library "pathname", "securerandom"     # Declare library signatures to load
+            testing "::<%= target %>"
+
+          <%- instance_methods.each do |method_name, definition| -%>
+            def test_<%= test_name_for(method_name) %>
+          <%- definition.method_types.each do |method_type| -%>
+              assert_send_type "<%= method_type %>",
+                               <%= target %>.new, :<%= method_name %>
+          <%- end -%>
+            end
+
+          <%- end -%>
+          end
+          <%- end -%>
+        ERB
+      end
+
+      private
+
+      def test_name_for(method_name)
+        {
+          :==  => 'double_equal',
+          :!=  => 'not_equal',
+          :=== => 'triple_equal',
+          :[]  => 'square_bracket',
+          :[]= => 'square_bracket_assign',
+          :>   => 'greater_than',
+          :<   => 'less_than',
+          :>=  => 'greater_than_equal_to',
+          :<=  => 'less_than_equal_to',
+          :<=> => 'spaceship',
+          :+   => 'plus',
+          :-   => 'minus',
+          :*   => 'multiply',
+          :/   => 'divide',
+          :**  => 'power',
+          :%   => 'modulus',
+          :&   => 'and',
+          :|   => 'or',
+          :^   => 'xor',
+          :>>  => 'right_shift',
+          :<<  => 'left_shift',
+          :=~  => 'pattern_match',
+          :!~  => 'does_not_match',
+          :~   => 'tilde'
+        }.fetch(method_name, method_name)
+      end
+
+      def class_methods
+        @class_methods ||= RBS::DefinitionBuilder.new(env: env).build_singleton(target.absolute_type_name).methods.select {|_, definition|
+          definition.implemented_in == target.absolute_type_name
+        }
+      end
+
+      def instance_methods
+        @instance_methods ||= RBS::DefinitionBuilder.new(env: env).build_instance(target.absolute_type_name).methods.select {|_, definition|
+          definition.implemented_in == target.absolute_type_name
+        }
+      end
+    end
+
+    path.write TestTemplateBuilder.new(target).call
+
+    puts "Created: #{path}"
+  end
+end
+
+task :test_generate_stdlib do
+  sh "RBS_GENERATE_TEST_PATH=/tmp/Array_test.rb rake 'generate:stdlib_test[Array]'"
+  sh "ruby -c /tmp/Array_test.rb"
+  sh "RBS_GENERATE_TEST_PATH=/tmp/Thread_Mutex_test.rb rake 'generate:stdlib_test[Thread::Mutex]'"
+  sh "ruby -c /tmp/Thread_Mutex_test.rb"
+end
+
+# Rake::Task[:release].enhance do
+#   Rake::Task[:"release:note"].invoke
+# end
+
+namespace :release do
+  desc "Explain the post-release steps automatically"
+  task :note do
+    version = Gem::Version.new(RBS::VERSION)
+    major, minor, patch, *_ = RBS::VERSION.split(".")
+    major = major.to_i
+    minor = minor.to_i
+    patch = patch.to_i
+
+    puts "🎉🎉🎉🎉 Congratulations for **#{version}** release! 🎉🎉🎉🎉"
+    puts
+    puts "There are a few things left to complete the release. 💪"
+    puts
+
+    if patch == 0 || version.prerelease?
+      puts "* [ ] Update release note: https://github.com/ruby/rbs/wiki/Release-Note-#{major}.#{minor}"
+    end
+
+    if patch == 0 && !version.prerelease?
+      puts "* [ ] Delete `RBS XYZ is the latest version of...` from release note: https://github.com/ruby/rbs/wiki/Release-Note-#{major}.#{minor}"
+    end
+
+    puts "* [ ] Publish a release at GitHub"
+    puts "* [ ] Make some announcements on Twitter/Mustdon/Slack/???"
+
+    puts
+    puts
+
+    puts "✏️ Making a draft release on GitHub..."
+
+    content = File.read(File.join(__dir__, "CHANGELOG.md"))
+    changelog = content.scan(/^## \d.*?(?=^## \d)/m)[0]
+    changelog = changelog.sub(/^.*\n^.*\n/, "").rstrip
+
+    notes = <<NOTES
+[Release note](https://github.com/ruby/rbs/wiki/Release-Note-#{major}.#{minor})
+
+#{changelog}
+NOTES
+
+    command = [
+      "gh",
+      "release",
+      "create",
+      "--draft",
+      "v#{RBS::VERSION}",
+      "--title=#{RBS::VERSION}",
+      "--notes=#{notes}"
+    ]
+
+    if version.prerelease?
+      command << "--prerelease"
+    end
+
+    require "open3"
+    output, status = Open3.capture2(*command)
+    if status.success?
+      puts "  >> Done! Open #{output.chomp} and publish the release!"
+    end
+  end
+end
+
+
+desc "Generate changelog template from GH pull requests"
+task :changelog do
+  major, minor, patch, _pre = RBS::VERSION.split(".", 4)
+  major = major.to_i
+  minor = minor.to_i
+  patch = patch.to_i
+
+  if patch == 0
+    milestone = "RBS #{major}.#{minor}"
+  else
+    milestone = "RBS #{major}.#{minor}.x"
+  end
+
+  puts "🔍 Finding pull requests that is associated to milestone `#{milestone}`..."
+
+  command = [
+    "gh",
+    "pr",
+    "list",
+    "--limit=10000",
+    "--json",
+    "url,title,number",
+    "--search" ,
+    "milestone:\"#{milestone}\" is:merged sort:updated-desc -label:Released"
+  ]
+
+  require "open3"
+  output, status = Open3.capture2(*command)
+  raise status.inspect unless status.success?
+
+  require "json"
+  json = JSON.parse(output, symbolize_names: true)
+
+  unless json.empty?
+    puts
+    json.each do |line|
+      puts "* #{line[:title]} ([##{line[:number]}](#{line[:url]}))"
+    end
+  else
+    puts "  (🤑 There is no *unreleased* pull request associated to the milestone.)"
+  end
+end