rbs-relaxed 3.9.0.1

data/docs/repo.md

@@ -0,0 +1,125 @@
+# Third-party RBS Repository
+
+This is the spec of the directory structure for RBS files of gems without RBS files. It allows distributing RBS type definitions of gems separately from the `.gemspec` files so that the Ruby developers can type check their Ruby programs even if the dependent gems don't ship with their type definitions.
+
+The spec includes:
+
+* The directory structure, and
+* The RBS file lookup rules given _repository root_, gem name, and version.
+
+## Motivating Example
+
+Assume there is a rubygem called `bug-free-doodle` and our application depends on the library. We are trying to type check our application and we need RBS files of `bug-free-doodle`. The problem is that the `bug-free-doodle` gem doesn't ship with RBS files. The type checkers cannot resolve the type of constant `Bug::Free::Doodle` and its methods.
+
+One workaround is to add type definitions of the library in the application signatures.
+
+```rbs
+# sig/polyfill/bug-free-doodle.rbs
+
+module Bug
+  module Free
+    class Doodle
+      attr_reader name: Symbol
+      attr_reader strokes: Array[Stroke]
+
+      def initialize: (name: Symbol) -> void
+    end
+  end
+end
+```
+
+You may want to distribute the RBS file to anyone who needs it. Which version do we support? Testing it? How to load the RBS files? This is the spec you need!
+
+### Third-party RBS repository
+
+Make a directory (or you may want to `git init`) to put your _third party RBSs_.
+
+```sh
+$ make my-rbs      # Or you may want a git repository: git init my-rbs
+$ cd my-rbs
+$ mkdir gems
+```
+
+We call the `my-rbs/gems` directory _repository root_. Note that it is different from the root of the git repository. The RBS repository root is the directory that contains directories of gem names.
+
+Make a directory for the gem and the version.
+
+```sh
+$ mkdir gems/bug-free-doodle
+$ mkdir gems/bug-free-doodle/1.2.3
+```
+
+And copy the RBS file in it.
+
+```sh
+$ cp your-app/sig/polyfill/bug-free-doodle.rbs gems/bug-free-doodle/1.2.3
+```
+
+### Reading Third-party RBS
+
+`rbs` command accepts `--repo` option which points to a _repository root_. You can specify `-r` option to let the command know which gems you want to load.
+
+In this case, the _repository root_ is `./gems` and we are trying to load `bug-free-doodle` gem.
+
+```sh
+$ rbs --repo=gems -r bug-free-doodle paths
+```
+
+The `-r` option also accepts gem name with version.
+
+```sh
+$ rbs --repo=gems -r bug-free-doodle:1.2.3 paths
+```
+
+Note that the version resolution is not compatible with semantic versioning. It is optimistic. It resolves to some version unless no version for the gem is available.
+
+## Directory Structure
+
+There are directories for each gem under _repository root_. We also have directories for each version of each gem.
+
+- $REPO_ROOT/bug-free-doodle/0.2.0
+- $REPO_ROOT/bug-free-doodle/1.0
+- $REPO_ROOT/bug-free-doodle/1.2.3
+- $REPO_ROOT/bug-free-doodle/2.0
+
+Note that we assume that we have git repositories for each RBS repository, and we have a directory at the root of the git repository for _repository root_.
+
+So the git repository structure would be something like the following:
+
+- /Gemfile
+- /Gemfile.lock
+- /README.md
+- /LICENSE
+- /gems/bug-free-doodle/1.2.3/bug-free-doodle.rbs
+
+You should have `Gemfile` and `Gemfile.lock` to manage dependencies, `README.md` and `LICENSE` to documentation, and `gems` directory as _repository root_.
+
+(We call _repository root_ `gems` in this doc, but the name can be anything you like.)
+
+## Version Resolution
+
+The version resolution in RBS is optimistic. We don't block loading RBS files for _incompatible_ version in terms of semantic versioning.
+
+It tries to resolve version _n_ as follows:
+
+1. It resolves to _m_ such that _m_ is the latest version available and _m_ <= _n_ holds.
+2. It resolves to the oldest version when rule 1 cannot find version _m_.
+
+If two versions, `0.4.0`, `1.0.0` are available for a gem:
+
+| Requested version | Resolved version |
+|-------------------|------------------|
+| `0.3.0`           | `0.4.0` (Rule 2) |
+| `0.4.0`           | `0.4.0`          |
+| `0.5.0`           | `0.4.0`          |
+| `1.0.0`           | `1.0.0`          |
+| `2.0.0`           | `1.0.0`          |
+
+This is not compatible with the concept of semantic versioning. We don't want to block users to load RBS even for incompatible versions of gems.
+
+We believe this makes more sense because:
+
+* Using (potentially) incompatible type definitions are better than no type definition.
+* Users can stop loading RBS if incompatibility causes an issue and falling back to hand-written polyfills.
+
+

data/docs/sigs.md

@@ -0,0 +1,167 @@
+# Writing Signatures Guide
+
+You can write the signature of your applications and libraries.
+Signature of your Ruby program would help:
+
+1. Understanding the code structure
+2. Finding APIs
+
+And if you ship your gem with signature, the gem users can type check their applications!
+
+## Writing signatures
+
+You first need to write your program's signature.
+See [syntax guide](syntax.md).
+
+## Testing signatures
+
+When you finish writing signature, you may want to test the signature.
+rbs provides a feature to test your signature.
+
+```console
+$ RBS_TEST_TARGET='Foo::*' bundle exec ruby -r rbs/test/setup test/foo_test.rb
+```
+
+The test installs instrumentations to spy the method calls and check if arguments/return values are correct with respect to the type of the method in signature.
+If errors are reported by the test, you will fix the signature.
+You will be sure that you ship a correct signature finally.
+
+The instrumentations are implemented using `Module#prepend`.
+It defines a module with same name of methods, which asserts the type of arguments/return values and calls `super`.
+
+## Type errors
+
+If the test detects type errors, it will print error messages.
+
+### ArgumentTypeError, BlockArgumentTypeError
+
+The message means there is an unexpected type of argument or block argument.
+
+```
+ERROR -- : [Kaigi::Speaker.new] ArgumentTypeError: expected `::String` (email) but given `:"matsumoto@soutaro.com"`
+```
+
+### ArgumentError, BlockArgumentError
+
+The message means there is an unexpected argument or missing argument.
+
+```
+[Kaigi::Speaker.new] ArgumentError: expected method type (size: ::Symbol, email: ::String, name: ::String) -> ::Kaigi::Speaker
+```
+
+### ReturnTypeError, BlockReturnTypeError
+
+The message means the return value from method or block is incorrect.
+
+```
+ERROR -- : [Kaigi::Conference#each_speaker] ReturnTypeError: expected `self` but returns `[#<Kaigi::Speaker:0x00007fb2b249e5a0 @name="Soutaro Matsumoto", @email=:"matsumoto@soutaro.com">]`
+```
+
+### UnexpectedBlockError, MissingBlockError
+
+The errors are reported when required block is not given or unused block is given.
+
+```
+ERROR -- : [Kaigi::Conference#speakers] UnexpectedBlockError: unexpected block is given for `() -> ::Array[::Kaigi::Speaker]`
+```
+
+### UnresolvedOverloadingError
+
+The error means there is a type error on overloaded methods.
+The `rbs` test framework tries to the best error message for overloaded methods too, but it reports the `UnresolvedOverloadingError` when it fails.
+
+### DuplicatedMethodDefinitionError
+
+The error is reported when a method is defined multiple times, as RBS does not allow duplicate method definitions. When you need to overload a method, use the `...` syntax:
+
+```rbs
+# First definition
+class C
+  def foo: () -> untyped
+end
+
+# Second definition, use `...` syntax to tell RBS that we're overloading the method
+class C
+  def foo: () -> untyped
+         | ...
+end
+```
+
+## Setting up the test
+
+The design of the signature testing aims to be non-intrusive. The setup is done in two steps:
+
+1. Loading the testing library
+2. Setting up the test through environment variables
+
+### Loading the library
+
+You need to require `rbs/test/setup` for signature testing.
+You can do it using `-r` option through command line argument or the `RUBYOPT` environment variable.
+
+```console
+$ ruby -r rbs/test/setup run_tests.rb
+$ RUBYOPT='-rrbs/test/setup' rake test
+```
+
+When you are using Bundler, you may need to require `bundler/setup` explicitly.
+
+```console
+$ RUBYOPT='-rbundler/setup -rrbs/test/setup' bundle exec rake test
+```
+
+### Environment variables
+
+You need to specify `RBS_TEST_TARGET` to run the test, and you can customize the test with the following environment variables.
+
+- `RBS_TEST_SKIP` (optional)
+- `RBS_TEST_OPT` (optional)
+- `RBS_TEST_LOGLEVEL` (optional)
+- `RBS_TEST_RAISE` (optional)
+
+`RBS_TEST_TARGET` is to specify the classes you want to test. `RBS_TEST_TARGET` can contain comma-separated class name pattern, which is one of an exact class name or with wildcard `*`.
+
+- `RBS_TEST_TARGET=Foo::Bar,Foo::Baz` comma separated exact class names
+- `RBS_TEST_TARGET=Foo::*` using wildcard
+
+`RBS_TEST_SKIP` is to skip some of the classes which matches with `RBS_TEST_TARGET`.
+
+`RBS_TEST_OPT` is to pass the options for rbs handling.
+You may need to specify `-r` or `-I` to load signatures.
+The default is `-I sig`.
+
+```shell
+RBS_TEST_OPT='-r pathname -I sig'
+```
+
+Replacing `pathname` with the `stdlib` you want to include. For example, if you need to load `Set` and `BigDecimal` in `stdlib`, you would need to have `RBS_TEST_OPT='-r set -r bigdecimal -I sig'`
+
+`RBS_TEST_LOGLEVEL` can be used to configure log level. Defaults to `info`.
+
+`RBS_TEST_RAISE` may help to debug the type signatures.
+If the environment variable is set, it raises an exception when a type error is detected.
+You can see the backtrace how the type error is caused and debug your program or signature.
+
+So, a typical command line to start the test would look like the following:
+
+```console
+$ RBS_TEST_LOGLEVEL=error \
+  RBS_TEST_TARGET='Kaigi::*' \
+  RBS_TEST_SKIP='Kaigi::MonkeyPatch' \
+  RBS_TEST_OPT='-rset -rpathname -Isig -Iprivate' \
+  RBS_TEST_RAISE=true \
+  RUBYOPT='-rbundler/setup -rrbs/test/setup' \
+  bundle exec rake test
+```
+
+## Testing tips
+
+### Skipping a method
+
+You can skip installing the instrumentation per-method basis using `rbs:test:skip` annotation.
+
+```rbs
+class String
+  %a{rbs:test:skip} def =~: (Regexp) -> Integer?
+end
+```

data/docs/stdlib.md

@@ -0,0 +1,147 @@
+# Testing Core API and Standard Library Types
+
+This is a guide for testing core/stdlib types.
+
+## Add Tests
+
+We support writing tests for core/stdlib signatures.
+
+### Writing tests
+
+First, execute `generate:stdlib_test` rake task with a class name that you want to test.
+
+```console
+$ bundle exec rake 'generate:stdlib_test[String]'
+Created: test/stdlib/String_test.rb
+```
+
+It generates `test/stdlib/[class_name]_test.rb`.
+The test scripts would look like the following:
+
+```rb
+class StringSingletonTest < Test::Unit::TestCase
+  include TypeAssertions
+
+  testing "singleton(::String)"
+
+  def test_initialize
+    assert_send_type "() -> String",
+                     String, :new
+    assert_send_type "(String) -> String",
+                     String, :new, ""
+    assert_send_type "(String, encoding: Encoding) -> String",
+                     String, :new, "", encoding: Encoding::ASCII_8BIT
+    assert_send_type "(String, encoding: Encoding, capacity: Integer) -> String",
+                     String, :new, "", encoding: Encoding::ASCII_8BIT, capacity: 123
+    assert_send_type "(encoding: Encoding, capacity: Integer) -> String",
+                     String, :new, encoding: Encoding::ASCII_8BIT, capacity: 123
+    assert_send_type "(ToStr) -> String",
+                     String, :new, ToStr.new("")
+    assert_send_type "(encoding: ToStr) -> String",
+                     String, :new, encoding: ToStr.new('Shift_JIS')
+    assert_send_type "(capacity: ToInt) -> String",
+                     String, :new, capacity: ToInt.new(123)
+  end
+end
+
+class StringTest < Test::Unit::TestCase
+  include TypeAssertions
+
+  testing "::String"
+
+  def test_gsub
+    assert_send_type "(Regexp, String) -> String",
+                     "string", :gsub, /./, ""
+    assert_send_type "(String, String) -> String",
+                     "string", :gsub, "a", "b"
+    assert_send_type "(Regexp) { (String) -> String } -> String",
+                     "string", :gsub, /./ do |x| "" end
+    assert_send_type "(Regexp) { (String) -> ToS } -> String",
+                     "string", :gsub, /./ do |x| ToS.new("") end
+    assert_send_type "(Regexp, Hash[String, String]) -> String",
+                     "string", :gsub, /./, {"foo" => "bar"}
+    assert_send_type "(Regexp) -> Enumerator[String, self]",
+                     "string", :gsub, /./
+    assert_send_type "(String) -> Enumerator[String, self]",
+                     "string", :gsub, ""
+    assert_send_type "(ToStr, ToStr) -> String",
+                     "string", :gsub, ToStr.new("a"), ToStr.new("b")
+  end
+end
+```
+
+You need include `TypeAssertions` which provide useful methods for you.
+`testing` method call tells which class is the subject of the class.
+You may need `library` call to test a library if the type definition is provided as a library (under `stdlib` dir).
+
+Note that the instrumentation is based on refinements and you need to write all method calls in the unit class definitions.
+If the execution of the program escape from the class definition, the instrumentation is disabled and no check will be done.
+
+#### 📣 Method type assertions
+
+`assert_send_type` method call asserts to be valid types and confirms to be able to execute without exceptions.
+And you write the sample programs which calls all of the patterns of overloads.
+
+We recommend write method types as _simple_ as possible inside the assertion.
+It's not very easy to define _simple_, but we try to explain it with a few examples.
+
+* Instead of `(String | Integer) -> Symbol?`, use `(String) -> Symbol` or `(Integer) -> nil`, because we know the exact argument type we are passing in the test
+* Instead of `self`, `instance`, or `class`, use concrete types like `String`, `singleton(IO)`, because we know the exact type of the receiver
+* Sometimes, you need union types if the method is nondeterministic -- `() -> (Integer | String)` for `[1, ""].sample` (But you can rewrite the test code as `[1].sample` instead)
+* Sometimes, you need union types for heterogeneous collections -- `() { (Integer | String) -> String } -> Array[String | Integer]` for `[1, "2"].each {|i| i.to_s }` (But you can rewrite the test code as `[1, 2].each {|i| i.to_s }`)
+* Using `void` is allowed if the RBS definition is `void`
+
+Generally _simple_ means:
+
+* The type doesn't contain `self`, `instance`, `class`, `top`, `bot`, and `untyped`
+* The type doesn't contain unions and optionals
+
+Use them if you cannot write the test without them.
+
+One clear exception to using _simple_ types is when you use `with_int` or family helpers, that yield values with each case of the given union:
+
+```ruby
+def test_something
+  with_int(3) do |int|
+    # Yields twice with `Integer` and `ToInt`
+    assert_send_type(
+      "(int) -> Integer",
+      some, :test, int
+    )
+  end
+end
+```
+
+It's clear having type aliases makes sense.
+
+#### 📣 Constant type assertions
+
+We also have `assert_const_type` method, to test the type of constant is correct with respect to RBS type definition.
+
+```ruby
+class FloatConstantTest < Test::Unit::TestCase
+  include TypeAssertions
+
+  def test_infinity
+    assert_const_type "Float", "Float::INFINITY"
+  end
+end
+```
+
+It confirms:
+
+1. The type of constant `Float::INFINITY` is `Float`
+2. The type of constant `Float::INFINITY` is correct with respect to RBS definition
+
+We don't have any strong recommendation about where the constants test should be written in.
+The `FloatConstantTest` example defines a test case only for the constant tests.
+You may write the tests inside `FloatInstanceTest` or `FloatSingletonTest`.
+
+### Running tests
+
+You can run the test with:
+
+```console
+$ bundle exec rake stdlib_test                # Run all tests
+$ bundle exec ruby test/stdlib/String_test.rb # Run specific tests
+```