rbs 4.0.0.dev.4 → 4.1.0.pre.2

data/docs/rbs_by_example.md

@@ -107,14 +107,14 @@ end
 For now, it's safe to ignore them, but they're included for completeness.
 
 ```rbs
-class Array[Elem]
+class Array[E]
   def *: (String) -> String
-       | (Integer) -> Array[Elem]
+       | (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 `Elem` (in our example case, `Elem` corresponds to `Integer`).
+`Integer`, it returns an `Array` of the same contained type `E` (in our example case, `E` corresponds to `Integer`).
 
 ### Union types
 
@@ -150,9 +150,9 @@ end
 ```
 
 ```rbs
-class Enumerable[Elem]
-  def first: () -> Elem?
-           | (Integer) -> Array[Elem]
+class Enumerable[E]
+  def first: () -> E?
+           | (Integer) -> Array[E]
 end
 ```
 
@@ -160,12 +160,12 @@ end
 
 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 `Elem`, and the `?` suffix nilable marker.
+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 `(Elem | nil)`.
+The `?` syntax is a convenient shorthand for a union with nil. An equivalent union type would be `(E | nil)`.
 
 ### Keyword Arguments
 
@@ -222,9 +222,9 @@ end
 ```
 
 ```rbs
-class Array[Elem]
-  def filter: () { (Elem) -> boolish } -> ::Array[Elem]
-            | () -> ::Enumerator[Elem, ::Array[Elem]]
+class Array[E]
+  def filter: () { (E) -> boolish } -> ::Array[E]
+            | () -> ::Enumerator[E, ::Array[E]]
 end
 ```
 
@@ -264,13 +264,13 @@ a.collect.with_index {|x, i| x * i}
 ```
 
 ```rbs
-class Array[Elem]
-  def collect: [U] () { (Elem) -> U } -> Array[U]
-             | () -> Enumerator[Elem, Array[untyped]]
+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 `Elem`, and return a value of type `U`. Then `#collect` will return an `Array` of type `U`.
+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]`.
 
@@ -284,9 +284,9 @@ In this example, the method receives its signature from the inferred return type
 ```
 
 ```rbs
-class Enumerable[Elem]
-  def partition: () { (Elem) -> boolish } -> [Array[Elem], Array[Elem]]
-               | () -> ::Enumerator[Elem, [Array[Elem], Array[Elem] ]]
+class Enumerable[E]
+  def partition: () { (E) -> boolish } -> [Array[E], Array[E]]
+               | () -> ::Enumerator[E, [Array[E], Array[E] ]]
 end
 ```
 
@@ -300,9 +300,9 @@ Tuples can be of any size, and they can have mixed types.
 ```
 
 ```rbs
-class Enumerable[Elem]
+class Enumerable[E]
   def to_h: () -> ::Hash[untyped, untyped]
-          | [T, U] () { (Elem) -> [T, U] } -> ::Hash[T, U]
+          | [T, U] () { (E) -> [T, U] } -> ::Hash[T, U]
 end
 ```
 

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
+   ```

data/docs/sigs.md

@@ -131,10 +131,10 @@ You may need to specify `-r` or `-I` to load signatures.
 The default is `-I sig`.
 
 ```shell
-RBS_TEST_OPT='-r pathname -I sig'
+RBS_TEST_OPT='-r logger -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'`
+Replacing `logger` 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`.
 
@@ -148,7 +148,7 @@ So, a typical command line to start the test would look like the following:
 $ RBS_TEST_LOGLEVEL=error \
   RBS_TEST_TARGET='Kaigi::*' \
   RBS_TEST_SKIP='Kaigi::MonkeyPatch' \
-  RBS_TEST_OPT='-rset -rpathname -Isig -Iprivate' \
+  RBS_TEST_OPT='-rlogger -Isig -Iprivate' \
   RBS_TEST_RAISE=true \
   RUBYOPT='-rbundler/setup -rrbs/test/setup' \
   bundle exec rake test

data/docs/syntax.md

@@ -3,17 +3,17 @@
 ## Types
 
 ```markdown
-_type_ ::= _class-name_ _type-arguments_                 (Class instance type)
-         | _interface-name_ _type-arguments_             (Interface type)
-         | _alias-name_ _type-arguments_                 (Alias type)
-         | `singleton(` _class-name_ `)`                 (Class singleton type)
-         | _literal_                                     (Literal type)
-         | _type_ `|` _type_                             (Union type)
-         | _type_ `&` _type_                             (Intersection type)
-         | _type_ `?`                                    (Optional type)
-         | `{` _record-name_ `:` _type_ `,` etc. `}`     (Record type)
-         | `[]` | `[` _type_ `,` etc. `]`                (Tuples)
-         | _type-variable_                               (Type variables)
+_type_ ::= _class-name_ _type-arguments_                     (Class instance type)
+         | _interface-name_ _type-arguments_                 (Interface type)
+         | _alias-name_ _type-arguments_                     (Alias type)
+         | `singleton(` _class-name_ `)` _type-arguments_    (Class singleton type)
+         | _literal_                                         (Literal type)
+         | _type_ `|` _type_                                 (Union type)
+         | _type_ `&` _type_                                 (Intersection type)
+         | _type_ `?`                                        (Optional type)
+         | `{` _record-name_ `:` _type_ `,` etc. `}`         (Record type)
+         | `[]` | `[` _type_ `,` etc. `]`                    (Tuples)
+         | _type-variable_                                   (Type variables)
          | `self`
          | `instance`
          | `class`
@@ -85,7 +85,8 @@ Class singleton type denotes _the type of a singleton object of a class_.
 
 ```rbs
 singleton(String)
-singleton(::Hash)            # Class singleton type cannot be parametrized.
+singleton(::Hash)            # Class singleton type
+singleton(Array)[String]     # Class singleton type with type application
 ```
 
 ### Literal type
@@ -195,8 +196,8 @@ It is an alias of `top` type, and you can use `boolish` if we want to allow any
 We can see an example at the definition of `Enumerable#find`:
 
 ```rbs
-module Enumerable[Elem, Return]
-  def find: () { (Elem) -> boolish } -> Elem?
+module Enumerable[E, R]
+  def find: () { (E) -> boolish } -> E?
 end
 ```
 
@@ -650,7 +651,7 @@ _module-type-parameters_ ::=                                                  #
 
 Class declaration can have type parameters and superclass. When you omit superclass, `::Object` is assumed.
 
-* Super class arguments and generic class upperbounds are not *classish-context* nor *self-context*
+* Super class arguments and generic class bounds are not *classish-context* nor *self-context*
 
 ### Module declaration
 
@@ -668,7 +669,7 @@ end
 
 The `Enumerable` module above requires `each` method for enumerating objects.
 
-* Self type arguments and generic class upperbounds are not *classish-context* nor *self-context*
+* Self type arguments and generic class bounds are not *classish-context* nor *self-context*
 
 ### Class/module alias declaration
 
@@ -764,7 +765,8 @@ _module-type-parameter_ ::= _generics-unchecked_ _generics-variance_ _type-varia
 _method-type-param_ ::= _type-variable_ _generics-bound_
 
 _generics-bound_ ::=                 (No type bound)
-                   | `<` _type_      (The generics parameter is bounded)
+                   | `<` _type_      (The generics parameter has an upper bound)
+                   | '>' _type_      (The generics parameter has a lower bound)
 
 _default-type_ ::=                    (No default type)
                  | `=` _type_         (The generics parameter has default type)
@@ -777,6 +779,9 @@ _generics-unchecked_ ::=              (Empty)
                        | `unchecked`  (Skips variance annotation validation)
 ```
 
+A type parameter can have both upper and lower bounds, which can be specified in either order:
+`[T < UpperBound > LowerBound]` or `[T > LowerBound < UpperBound]`.
+
 RBS allows class/module/interface/type alias definitions and methods to be generic.
 
 ```rbs
@@ -834,13 +839,38 @@ class PrettyPrint[T < _Output]
 end
 ```
 
-If a type parameter has an upper bound, the type parameter must be instantiated with types that is a subtype of the upper bound.
+If a type parameter has an upper bound, the type parameter must be instantiated with types that are a subtype of the upper bound.
 
 ```rbs
 type str_printer = PrettyPrint[String]    # OK
 type int_printer = PrettyPrint[Integer]   # Type error
 ```
 
+If a type parameter has a lower bound, the type parameter must be instantiated with types that are a supertype of the lower bound.
+
+```rbs
+class PrettyPrint[T > Numeric]
+end
+
+type obj_printer = PrettyPrint[Object]    # OK
+type int_printer = PrettyPrint[Integer]   # Type error
+```
+
+A type parameter can have both an upper and a lower bound, and these bounds can be specified in any order.
+
+```rbs
+class FlexibleProcessor[T > Integer < Numeric]
+  # This class processes types T that are supertypes of Integer but also subtypes of Numeric.
+  # This includes Integer, Rational, Complex, Float, and Numeric itself.
+  def calculate: (T) -> T
+end
+
+type int_processor = FlexibleProcessor[Integer]   # OK (Integer > Integer and Integer < Numeric)
+type num_processor = FlexibleProcessor[Numeric]   # OK (Numeric > Integer and Numeric < Numeric)
+type obj_processor = FlexibleProcessor[Object]    # Type error (Object is not < Numeric)
+type str_processor = FlexibleProcessor[String]    # Type error (String is not > Integer)
+```
+
 The generics type parameter of modules, classes, interfaces, or type aliases can have a default type.
 
 ```rbs

data/docs/type_fingerprint.md

@@ -0,0 +1,21 @@
+# Type Fingerprint of RBS Inline AST
+
+Type fingerprint of RBS Inline AST is an object that can be used to detect if the RBS Inline AST is updated and the type checker should type check the whole codebase again.
+
+1. If the AST update is related to the type information, the fingerprint is changed -- adding new type, including new module, changing method type, etc. The type checker should type check the codebase with updated type information.
+2. If the AST updated is not related to the type information, the fingerprint keeps the last value -- changing the method implementation, adding a method call in the top level, adding white spaces and new lines, etc. The type checker can skip updating the type information, and type checking only the implementation of the file is sufficient.
+3. Documentation comments are considered type related information for now.
+
+## Type Fingerprint Calculation
+
+The type fingerprint is calculated by converting AST nodes to standardized data structures that represent only the type-relevant information. Each AST class implements a `type_fingerprint` method that returns mainly arrays and strings.
+
+We expect not using the values for something other than change detection. Compare old and new fingerprints, and we can detect the change between the RBS inline AST if the fingerprints are different.
+
+The fingerprint methods are implemented across:
+
+- `AST::Ruby::Annotations::*#type_fingerprint` - Returns `untyped` (arrays, strings, or nil)
+- `AST::Ruby::Members::*#type_fingerprint` - Returns `untyped` (typically arrays)
+- `AST::Ruby::Declarations::*#type_fingerprint` - Returns `untyped` (typically arrays)
+- `InlineParser::Result#type_fingerprint` - Returns `untyped` (array of declaration fingerprints)
+

data/docs/wasm_serialization.md

@@ -0,0 +1,80 @@
+# RBS AST binary serialization
+
+This document describes the binary format used to move a parsed RBS AST out of
+the parser and into Ruby objects without going through the Ruby C API. It exists
+so that RBS can run on Ruby implementations that cannot load the C extension
+(notably JRuby): the parser runs inside WebAssembly, serializes the result with
+this format, and the host rebuilds `RBS::AST` objects in pure Ruby.
+
+The encoder (`rbs_serialize_node`, `src/serialize.c`) and the schema that drives
+the decoder (`RBS::WASM::SerializationSchema`, `lib/rbs/wasm/serialization_schema.rb`)
+are both generated from `config.yml`, so they always agree. The decoder itself
+is `RBS::WASM::Deserializer`.
+
+## Conventions
+
+- All multi-byte integers are **little-endian**.
+- `u8`, `u32` are unsigned; `i32` is signed.
+- `str` is a `u32` byte length followed by that many raw bytes (no terminator).
+- A value is reconstructed to mirror exactly what `ast_translation.c` produces,
+  including string encodings: string/integer literal nodes are UTF-8, while
+  comments, annotations and symbols use the source buffer's encoding.
+
+## Nodes
+
+Every node begins with a `u8` **tag**:
+
+- `0` — a NULL node (`nil` on the Ruby side).
+- `1..N` — a node type, in the order they appear in `SerializationSchema::SCHEMA`.
+- `SYMBOL_TAG` (`N + 1`) — an interned symbol, followed by `str` (the symbol's
+  bytes). Decoded with `String#to_sym`.
+
+A few node types are encoded specially, matching their bespoke handling in
+`ast_translation.c`:
+
+| Node | Payload after tag | Decoded as |
+| --- | --- | --- |
+| `RBS::AST::Bool` | `u8` | `true` / `false` |
+| `RBS::AST::Integer` | `str` | `String#to_i` |
+| `RBS::AST::String` | `str` | the string (UTF-8) |
+| `RBS::Types::Record::FieldType` | node, then `u8` | `[type, required]` |
+| `RBS::Signature` | node-list, then node-list | `[directives, declarations]` |
+| `RBS::Namespace` | node-list, then `u8` | `RBS::Namespace[path, absolute]` |
+| `RBS::TypeName` | node, then node | `RBS::TypeName[namespace, name]` |
+
+Every other node is encoded generically:
+
+1. If the node exposes a location, its **base location** is written (see below),
+   followed by one location range per declared child, in order.
+2. Each field is written in declaration order, encoded by its type (see below).
+
+The decoder constructs `Klass.new(location:, **fields)` (omitting `location:`
+for nodes that do not expose one). For `Class`, `Module`, `Interface`,
+`TypeAlias` and `MethodType`, `RBS::AST::TypeParam.resolve_variables` is applied
+to `type_params` first, exactly as the C translation does.
+
+## Fields
+
+| Field type | Encoding |
+| --- | --- |
+| node (`rbs_node`, `rbs_type_name`, `rbs_ast_comment`, `rbs_ast_symbol`, ...) | a node (recursive; NULL allowed) |
+| `rbs_node_list` | `u32` count, then that many nodes |
+| `rbs_hash` | `u32` count, then count × (key node, value node) |
+| `rbs_string` | `str` (source encoding) |
+| `bool` | `u8` |
+| enum | `u8` index into the enum's values (see `SCHEMA`) |
+| `rbs_location_range` | a location range |
+| `rbs_location_range_list` | `u32` count, then that many location ranges |
+| `rbs_attr_ivar_name` | `u8` tag: `0` → `nil`, `1` → `false`, `2` → `str` → symbol |
+
+## Location ranges
+
+A location range is a `u8` presence flag:
+
+- `0` — null range (`nil`, or a node with no location).
+- `1` — followed by `i32` start and `i32` end **character** positions.
+
+The base location and child ranges together let the decoder rebuild an
+`RBS::Location` (with its required/optional children) through the public
+`RBS::Location` API, so the same decoder works whether `RBS::Location` is backed
+by the C extension or a pure-Ruby implementation.

data/exe/rbs

@@ -4,4 +4,4 @@ $LOAD_PATH << File.join(__dir__, "../lib")
 require "rbs"
 require "rbs/cli"
 
-RBS::CLI.new(stdout: STDOUT, stderr: STDERR).run(ARGV.dup)
+exit RBS::CLI.new(stdout: STDOUT, stderr: STDERR).run(ARGV.dup)