rbs 4.1.0-java

data/docs/rbs_by_example.md

@@ -0,0 +1,309 @@
+# RBS By Example
+
+## Goal
+
+The purpose of this doc is to teach you how to write RBS signatures by using the standard library's methods as a guide.
+
+## Examples
+
+In each example, the first snippet is for *Ruby* and the second one is for *RBS*.
+
+### Zero argument methods
+
+**Example:** `String#empty?`
+
+```ruby
+"".empty?
+# => true
+"hello".empty?
+# => false
+```
+
+```rbs
+class String
+  def empty?: () -> bool
+end
+```
+
+`String`'s `#empty` method takes no parameters, and returns a boolean value
+
+### Single argument methods
+
+**Example:** `String#include?`
+
+```ruby
+"homeowner".include?("house")
+# => false
+"homeowner".include?("meow")
+# => true
+```
+
+```rbs
+class String
+  def include?: (String) -> bool
+end
+```
+
+`String`'s `include?` method takes one argument, a `String`, and returns a
+boolean value
+
+### Variable argument methods
+
+**Example:** `String#end_with?`
+
+```ruby
+"hello?".end_with?("!")
+# => false
+"hello?".end_with?("?")
+# => true
+"hello?".end_with?("?", "!")
+# => true
+"hello?".end_with?(".", "!")
+# => false
+```
+
+```rbs
+class String
+  def end_with?: (*String) -> bool
+end
+```
+
+`String`'s `#end_with?` method takes any number of `String` arguments, and
+returns a boolean value.
+
+### Optional positional arguments
+
+**Example:** `String#ljust`
+
+```ruby
+"hello".ljust(4)
+#=> "hello"
+"hello".ljust(20)
+#=> "hello               "
+"hello".ljust(20, '1234')
+#=> "hello123412341234123"
+```
+
+```rbs
+class String
+  def ljust: (Integer, ?String) -> String
+end
+```
+
+`String`'s `ljust` takes one `Integer` argument, and an optional `String` argument, indicated by the the `?` prefix marker. It returns a `String`.
+
+### Multiple signatures for a single method
+
+**Example:** `Array#*`
+
+```ruby
+[1, 2, 3] * ","
+# => "1,2,3"
+[1, 2, 3] * 2
+# => [1, 2, 3, 1, 2, 3]
+```
+
+*Note:* Some of the signatures after this point include type variables (e.g. `Elem`, `T`).
+For now, it's safe to ignore them, but they're included for completeness.
+
+```rbs
+class Array[E]
+  def *: (String) -> String
+       | (Integer) -> Array[E]
+end
+```
+
+`Array`'s `*` method, when given a `String` returns a `String`. When given an
+`Integer`, it returns an `Array` of the same contained type `E` (in our example case, `E` corresponds to `Integer`).
+
+### Union types
+
+**Example:** `String#<<`
+
+```ruby
+a = "hello "
+a << "world"
+#=> "hello world"
+a << 33
+#=> "hello world!"
+```
+
+```rbs
+class String
+  def <<: (String | Integer) -> String
+end
+```
+
+`String`'s `<<` operator takes either a `String` or an `Integer`, and returns a `String`.
+
+### Nilable types
+
+```ruby
+[1, 2, 3].first
+# => 1
+[].first
+# => nil
+[1, 2, 3].first(2)
+# => [1, 2]
+[].first(2)
+# => []
+```
+
+```rbs
+class Enumerable[E]
+  def first: () -> E?
+           | (Integer) -> Array[E]
+end
+```
+
+`Enumerable`'s `#first` method has two different signatures.
+
+When called with no arguments, the return value will either be an instance of
+whatever type is contained in the enumerable, or `nil`. We represent that with
+the type variable `E`, and the `?` suffix nilable marker.
+
+When called with an `Integer` positional argument, the return value will be an
+`Array` of whatever type is contained.
+
+The `?` syntax is a convenient shorthand for a union with nil. An equivalent union type would be `(E | nil)`.
+
+### Keyword Arguments
+
+**Example**: `String#lines`
+
+```ruby
+"hello\nworld\n".lines
+# => ["hello\n", "world\n"]
+"hello  world".lines(' ')
+# => ["hello ", " ", "world"]
+"hello\nworld\n".lines(chomp: true)
+# => ["hello", "world"]
+```
+
+```rbs
+class String
+  def lines: (?String, ?chomp: bool) -> Array[String]
+end
+```
+
+`String`'s `#lines` method take two arguments: one optional String argument, and another optional boolean keyword argument. It returns an `Array` of `String`s.
+
+Keyword arguments are declared similar to in ruby, with the keyword immediately followed by a colon. Keyword arguments that are optional are indicated as optional using the same `?` prefix as positional arguments.
+
+
+### Class methods
+
+**Example**: `Time.now`
+
+```ruby
+Time.now
+# => 2009-06-24 12:39:54 +0900
+```
+
+```rbs
+class Time
+  def self.now: () -> Time
+end
+```
+
+`Time`'s class method `now` takes no arguments, and returns an instance of the
+`Time` class.
+
+### Block Arguments
+
+**Example**: `Array#filter`
+
+```ruby
+[1,2,3,4,5].filter {|num| num.even? }
+# => [2, 4]
+%w[ a b c d e f ].filter {|v| v =~ /[aeiou]/ }
+# => ["a", "e"]
+[1,2,3,4,5].filter
+```
+
+```rbs
+class Array[E]
+  def filter: () { (E) -> boolish } -> ::Array[E]
+            | () -> ::Enumerator[E, ::Array[E]]
+end
+```
+
+`Array`'s `#filter` method, when called with no arguments returns an Enumerator.
+
+When called with a block, the method returns an `Array` of whatever type the original contained. The block will take one argument, of the type of the contained value, and the block will return a truthy or falsy value.
+
+`boolish` is a special keyword for any type that will be treated as if it were a `bool`.
+
+### Type Variables
+
+**Example**: `Hash`, `Hash#keys`
+
+```ruby
+h = { "a" => 100, "b" => 200, "c" => 300, "d" => 400 }
+h.keys
+# => ["a", "b", "c", "d"]
+```
+
+```rbs
+class Hash[K, V]
+  def keys: () -> Array[K]
+end
+```
+
+Generic types in RBS are parameterized at declaration time. These type variables are then available throughout all the methods contained in the `class` block.
+
+`Hash`'s `#keys` method takes no arguments, and returns an `Array` of the first type parameter. In the above example, `a` is of concrete type `Hash[String, Integer]`, so `#keys` returns an `Array` for `String`.
+
+
+```ruby
+a = [ "a", "b", "c", "d" ]
+a.collect {|x| x + "!"}
+# => ["a!", "b!", "c!", "d!"]
+a.collect.with_index {|x, i| x * i}
+# => ["", "b", "cc", "ddd"]
+```
+
+```rbs
+class Array[E]
+  def collect: [U] () { (E) -> U } -> Array[U]
+             | () -> Enumerator[E, Array[untyped]]
+end
+```
+
+Type variables can also be introduced in methods. Here, in `Array`'s `#collect` method, we introduce a type variable `U`. The block passed to `#collect` will receive a parameter of type `E`, and return a value of type `U`. Then `#collect` will return an `Array` of type `U`.
+
+In this example, the method receives its signature from the inferred return type of the passed block. When then block is absent, as in when the method returns an `Enumerator`, we can't infer the type, and so the return value of the enumerator can only be described as `Array[untyped]`.
+
+### Tuples
+
+**Examples**: `Enumerable#partition`, `Enumerable#to_h`
+
+```ruby
+(1..6).partition { |v| v.even? }
+# => [[2, 4, 6], [1, 3, 5]]
+```
+
+```rbs
+class Enumerable[E]
+  def partition: () { (E) -> boolish } -> [Array[E], Array[E]]
+               | () -> ::Enumerator[E, [Array[E], Array[E] ]]
+end
+```
+
+`Enumerable`'s `partition` method, when given a block, returns a 2-item tuple of `Array`s containing the original type of the `Enumerable`.
+
+Tuples can be of any size, and they can have mixed types.
+
+```ruby
+(1..5).to_h {|x| [x, x ** 2]}
+# => {1=>1, 2=>4, 3=>9, 4=>16, 5=>25}
+```
+
+```rbs
+class Enumerable[E]
+  def to_h: () -> ::Hash[untyped, untyped]
+          | [T, U] () { (E) -> [T, U] } -> ::Hash[T, U]
+end
+```
+
+`Enumerable`'s `to_h` method, when given a block that returns a 2-item tuple, returns a `Hash` with keys the type of the first position in the tuple, and values the type of the second position in the tuple.

data/docs/release.md

@@ -0,0 +1,69 @@
+# Releasing RBS
+
+Each release ships **two gems**:
+
+| Gem | Platform | Parser | How it is built |
+| --- | --- | --- | --- |
+| `rbs-X.Y.Z.gem` | `ruby` (MRI) | C extension | `rake release` (re-builds it) |
+| `rbs-X.Y.Z-java.gem` | `java` (JRuby) | WebAssembly (`lib/rbs/wasm`) | Docker image, pushed manually |
+
+The `-java` gem contains no native code — just `rbs_parser.wasm`. The Chicory/ASM
+jars it needs are not shipped in the gem; they are declared as `jar-dependencies`
+requirements and fetched from Maven when the gem is installed. So the gem can be
+built once in any environment and runs on every JRuby.
+
+## Prerequisites
+
+- Push rights to the `rbs` gem on RubyGems (`gem signin`). If your account has
+  MFA enabled, `gem push` / `rake release` will prompt for an OTP.
+- Docker, for the `-java` gem. The WASI SDK is baked into the image, so there is
+  nothing to install on the host.
+
+## Steps
+
+### 1. Release the `ruby` gem
+
+Once the version is bumped and committed, run on CRuby:
+
+```console
+$ bundle exec rake release
+```
+
+This re-builds the `ruby`-platform gem and then:
+
+- creates the tag `vX.Y.Z`,
+- pushes the current branch and the tag to `origin`,
+- pushes the gem to RubyGems,
+- runs `release:note`, which opens a GitHub **draft** release (with
+  `--prerelease` for `*.pre.*` versions) and prints the remaining manual steps.
+
+### 2. Build and push the `java` gem
+
+The `java` gem is not built by `rake release`, so build and push it manually:
+
+```console
+# Build from the committed state (the gemspec's file list comes from `git ls-files`).
+$ docker build -f Dockerfile.jruby -t rbs-jruby .
+
+# Build rbs_parser.wasm and the -java gem into ./pkg on the host. The Chicory/ASM
+# jars are not bundled; they are fetched from Maven when the gem is installed.
+$ docker run --rm -e RBS_PLATFORM=java -v "$PWD/pkg:/out" rbs-jruby \
+    gem build rbs.gemspec -o /out/rbs-X.Y.Z-java.gem
+
+$ gem push pkg/rbs-X.Y.Z-java.gem
+```
+
+Optionally confirm it installs and runs on JRuby before pushing:
+
+```console
+$ docker run --rm -v "$PWD/pkg:/pkg" -w /tmp rbs-jruby bash -c \
+    'gem install /pkg/rbs-X.Y.Z-java.gem && ruby -e "require %q{rbs}; puts [RUBY_ENGINE, RBS::VERSION].join(%q{ })"'
+```
+
+## Notes
+
+- Prereleases (`X.Y.Z.pre.N`) are only installed with `gem install rbs --pre`;
+  a plain `gem install rbs` is unaffected. On JRuby, `gem install rbs [--pre]`
+  resolves to the `-java` gem automatically.
+- The Dockerfile pins the WASI SDK / Chicory / ASM versions to match the
+  `wasm` and `jruby` CI workflows. Keep them in sync when bumping.

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/rust.md

@@ -0,0 +1,96 @@
+# Rust Crates
+
+RBS provides two Rust crates:
+
+- **`ruby-rbs-sys`** -- Low-level FFI bindings to the RBS C parser
+- **`ruby-rbs`** -- High-level safe Rust API for parsing RBS signatures
+
+Both crates are published to [crates.io](https://crates.io/) and are developed within the `rust/` directory of this repository.
+
+## Vendored RBS Source
+
+The Rust crates depend on the RBS C parser source code (`include/`, `src/`) and configuration (`config.yml`) from this repository. These files are vendored into each crate's `vendor/rbs/` directory, which is managed by Rake tasks and not tracked by git.
+
+The file `rust/rbs_version` records which version of RBS the Rust crates are pinned to.
+
+## Setup
+
+After cloning the repository, set up the vendored source before building the Rust crates:
+
+```bash
+rake rust:rbs:sync       # Uses the pinned version from rust/rbs_version
+```
+
+Then build and test:
+
+```bash
+cd rust
+cargo test
+```
+
+## Rake Tasks
+
+### `rake rust:rbs:sync`
+
+Copies the source files from the pinned version into each crate's `vendor/rbs/`. The copied files are made read-only to prevent accidental edits.
+
+### `rake rust:rbs:pin[VERSION]`
+
+Records a git tag in `rust/rbs_version`. For example:
+
+```bash
+rake rust:rbs:pin[v4.0.3]
+```
+
+### `rake rust:publish:ruby-rbs-sys` / `rake rust:publish:ruby-rbs`
+
+Publishes each crate to crates.io individually. Each task:
+
+1. Verifies `rust/rbs_version` is set
+2. Verifies vendor directories contain real files (not symlinks)
+3. Verifies the git working tree is clean
+4. Creates a release branch and commits the vendor files
+5. Runs a dry-run to check packaging
+6. Publishes the crate
+
+Set `RBS_RUST_PUBLISH_DRY_RUN=1` to only run the dry-run step and skip the actual publish to crates.io. This is used in CI to verify that the crates can be packaged correctly.
+
+### `rake rust:rbs:symlink`
+
+If your development needs unreleased version of RBS source code, use `rake rust:rbs:symlink` to set up symlinks in vendor directories to refer the worktree source code. Changes to the C parser source are immediately reflected in Rust builds.
+
+## Publishing Workflow
+
+1. Pin the RBS version to release against:
+
+   ```bash
+   rake rust:rbs:pin[v4.0.3]
+   ```
+
+2. Sync the vendored source:
+
+   ```bash
+   rake rust:rbs:sync
+   ```
+
+3. Update crate versions in `rust/ruby-rbs-sys/Cargo.toml` and `rust/ruby-rbs/Cargo.toml`.
+
+4. Build and test:
+
+   ```bash
+   cd rust && cargo test
+   ```
+
+5. Commit the version changes and `rust/rbs_version`:
+
+   ```bash
+   git add rust/rbs_version rust/ruby-rbs-sys/Cargo.toml rust/ruby-rbs/Cargo.toml
+   git commit -m "Bump Rust crate versions"
+   ```
+
+6. Publish each crate:
+
+   ```bash
+   rake rust:publish:ruby-rbs-sys
+   rake rust:publish:ruby-rbs
+   ```