rbs 4.1.0 → 4.2.0

data/docs/release.md

@@ -1,69 +1,303 @@
 # Releasing RBS
 
+A release is a pull request and one workflow run. Everything that leaves the
+repository — the tag, both gems, and the GitHub release — is produced by the
+`Release gems` workflow, so nothing has to be built or pushed from a laptop.
+
 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 |
+| Gem | Platform | Parser |
+| --- | --- | --- |
+| `rbs-X.Y.Z.gem` | `ruby` (MRI) | C extension, compiled on install |
+| `rbs-X.Y.Z-java.gem` | `java` (JRuby) | `rbs_parser.wasm`, built by the workflow |
 
 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.
 
+There are three kinds of release, and they differ in what gets written up:
+
+| Version | CHANGELOG section | GitHub release |
+| --- | --- | --- |
+| `X.Y.Z` | The whole cycle since the previous release proper, prereleases included | Published |
+| `X.Y.Z.pre.N` | What changed since `X.Y.Z.pre.N-1` | Published, marked as a prerelease |
+| `X.Y.Z.dev.N` | None | None |
+
+`.dev.N` releases are cut from the development line for people who need a change
+early, so they are gems and tags and nothing else.
+
 ## 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.
+Push rights to the `rbs` gem on RubyGems are **not** needed: the workflow
+authenticates through a trusted publisher registered for this repository and
+`release-gems.yml`. What is needed is write access to the repository, since that
+is what lets you dispatch the workflow.
 
 ## Steps
 
-### 1. Release the `ruby` gem
+The release pull request in step 1 is merged by a person who has reviewed it. Its merge commit is
+what step 2 dispatches, tags, and pushes to RubyGems, and none of that can be taken back — so
+prepare that pull request and stop there, rather than merging it and carrying on to step 2.
+
+The bump that starts a new minor is the only other pull request that sets `RBS::VERSION`. It
+publishes nothing and another bump undoes it, so one opened on an explicit request can go through
+on its own.
+
+### 1. Prepare the release
+
+Open a pull request that carries everything the release needs:
+
+- `lib/rbs/version.rb` — set `RBS::VERSION` to the version being released.
+- `Gemfile.lock` — run `bundle install` after the bump; the lockfile records the version too.
+- `CHANGELOG.md` — add a section for the new version, directly under the `# CHANGELOG` heading.
+  Sections are newest first.
 
-Once the version is bumped and committed, run on CRuby:
+Label the pull request `skip-changelog`. It carries no change of its own, and without the label it
+shows up in the next release's list — that is why 4.1.0's changelog contains a `Version 4.1.0`
+entry.
+
+`rake gem:changelog` lists the pull requests merged since the last release, already formatted:
 
 ```console
-$ bundle exec rake release
+$ bundle exec rake gem:changelog | pbcopy
 ```
 
-This re-builds the `ruby`-platform gem and then:
+Where it starts follows `RBS::VERSION`, so bump the version first: a prerelease starts from the
+latest tag, and a release proper skips the prerelease tags and starts from the previous release
+proper. Pass a version to override it (`rake 'gem:changelog[4.1.0]'`). Only the list goes to
+STDOUT, so it pipes cleanly. Pull requests labeled `skip-changelog` are left out and reported on
+STDERR, and pull requests that only touch `rust/` are left out because the crates have their own
+release cycle.
+
+On a release proper, the `X.Y.Z.pre.N` sections above the previous release are replaced by the one
+section being written — their pull requests are in it, and the notes they were published with stay
+on their own GitHub releases.
+
+Sort the list into the sections below. `rake gem:changelog:json` prints the same pull requests with
+the changed files, labels, and body of each, which is what the sorting is based on.
+
+Both tasks reach GitHub through `gh`, which a Claude Code on the web session cannot do. See
+[Assembling the changelog without `gh`](#assembling-the-changelog-without-gh), which runs them on a
+runner instead.
+
+```markdown
+## X.Y.Z (YYYY-MM-DD)
+
+### Signature updates
+
+### Language updates
+
+### Library changes
+
+#### rbs prototype
+
+#### rbs collection
+
+### Miscellaneous
+```
+
+The sections always appear in this order; delete the ones that end up empty, which is most of them
+on a small release. Two things scale with the size of the release:
+
+- **Summary paragraphs**, above the first section. A patch release usually has none, 4.1.0 has four
+  paragraphs, and 4.0.0 has nine. A prerelease has none whatever its size: the cycle it belongs to
+  is summarized once, on the release proper that folds it in.
+- **A list of the types whose signatures changed**, as the first line of `### Signature updates`,
+  written as `**Updated classes/modules/methods:**` followed by the names in backticks. Used on
+  `X.Y.0` releases only.
+
+The date is the day the gem is released, matching the `vX.Y.Z` tag — not the day this pull request
+is opened. Fix it up before step 2 if the pull request sat for a few days.
+
+### 2. Run the `Release gems` workflow
+
+Once the pull request is merged, dispatch
+[`release-gems.yml`](../.github/workflows/release-gems.yml) from the Actions tab with two inputs:
+
+| Input | Value |
+| --- | --- |
+| `commit` | The full 40-character SHA of the merge commit, taken from the merged pull request |
+| `version` | `X.Y.Z`, without the leading `v` |
+
+The ref selector picks which copy of the workflow file runs, not what gets released — leave it on
+`master`. Everything is built from `commit`, so the run is unaffected by whatever lands on `master`
+in the meantime, and a patch release cut from a release branch is dispatched the same way as any
+other: the workflow does not care which branch the commit is on.
+
+The two inputs say the same thing twice, once as a commit and once as a name, and the run stops
+before anything is built unless they agree with each other and with the repository:
+
+- `commit` has to be a full SHA that some branch contains,
+- `version` has to be the `RBS::VERSION` that commit declares,
+- CHANGELOG.md has to start with a section for `version` (skipped for `.dev.N`, which is not
+  written up),
+- `vX.Y.Z` must not exist yet.
 
-- 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.
+It then:
 
-### 2. Build and push the `java` gem
+- builds `rbs-X.Y.Z.gem`,
+- compiles `rbs_parser.wasm` and builds `rbs-X.Y.Z-java.gem`,
+- checks both: platforms, the C extension on one and its absence on the other, and that the wasm
+  module made it into the `java` gem,
+- installs the `java` gem on JRuby and parses with it, so the WebAssembly runtime is exercised
+  before anything is published,
+- uploads both gems as an artifact,
+- tags `commit` as `vX.Y.Z` and pushes the tag,
+- pushes both gems to RubyGems through trusted publishing,
+- publishes the GitHub release with the notes from CHANGELOG.md, skipping this last step for
+  `.dev.N` versions.
 
-The `java` gem is not built by `rake release`, so build and push it manually:
+The tag is created once both gems are known to build and run, and before anything is published: a
+tag can be deleted, while a version pushed to RubyGems can only be yanked.
+
+Checking the `dry_run` box runs everything up to the artifact and stops — no tag, no gems pushed,
+no release — which is how the build is exercised without releasing. `version` still has to match
+the commit, so a dry run is also how a release is rehearsed before it is cut.
+
+## The version on `master`
+
+`RBS::VERSION` on `master` is read one of two ways, told apart by how the version ends:
+
+| On `master` | Means |
+| --- | --- |
+| `X.Y.0.dev` — a bare `.dev` | `X.Y.0` is being developed |
+| A complete version — `X.Y.Z`, `X.Y.Z.pre.N`, `X.Y.Z.dev.N` | The version *after* the one named is being developed |
+
+So `4.1.1` on `master` is not a claim that `master` is 4.1.1. It says 4.1.1 has shipped and what
+comes after it is being worked on. `4.1.2.dev.1` says the same thing about itself: that release is
+out, and the line continues towards 4.1.2.
+
+Both become true the moment the release is tagged, so **nothing has to be done to `master` after a
+release**. `4.0.1` was followed by `4.0.2` with no version change in between, and `4.1.2.dev.1` is
+what `master` carries today.
+
+The bare `X.Y.0.dev` is the exception because it is the one version that names a target rather than
+a predecessor: a new minor is developed towards `X.Y.0` for a long time, before it is known whether
+the next thing to ship is `X.Y.0.pre.1` or `X.Y.0` itself. Setting it is the only version change
+that has to be made deliberately.
+
+`rake gem:changelog` reads `RBS::VERSION` too, to decide where the next changelog starts — but the
+version is set to the one being released before the changelog is generated, so it sees that rather
+than whatever `master` was carrying.
+
+## Starting a new minor
+
+`master` is the development line of one minor at a time. Moving it from `X.Y` to `X.(Y+1)` is not
+part of any one release — it is the decision that the `X.Y` line is done, taken whenever that
+becomes true — and it is the one moment the version on `master` is changed by hand. Two changes, in
+opposite places:
+
+1. **Branch the line being left behind**, from the last `master` commit that belongs to it:
+
+   ```console
+   $ git switch --create aaa-X.Y.x <that commit>
+   $ git push -u origin aaa-X.Y.x
+   ```
+
+   Branch from the commit *before* the bump below, so the branch keeps the version its line was
+   released under. Patch releases of `X.Y` are cut from here from now on, with their changes
+   cherry-picked from `master` — see [Backports](#backports). The `aaa-` prefix carries no meaning
+   beyond sorting the release branches to the top of the branch list.
+
+   The branch carries its own release tooling, since that is read from the ref rather than from
+   `master`: the `gem:` tasks, and `changelog.yml` for the changelog. Branching from `master`
+   brings both along; what needs watching is a later change to either, which reaches this line
+   only if it is cherry-picked here too.
+
+2. **Bump `master`** to `X.(Y+1).0.dev`, in a pull request with `Gemfile.lock` regenerated and
+   labeled `skip-changelog` like the release pull request itself. `4.1` was started exactly this
+   way: `aaa-4.0.x` was branched at the commit before `Start 4.1 development`, which set
+   `RBS::VERSION` to `4.1.0.dev`.
+
+Two loose ends that are easy to forget:
+
+- **The release note of the new line.** `rake gem:gh_release` links every published release to
+  `https://github.com/ruby/rbs/wiki/Release-Note-X.Y`, built from the version number without
+  checking that the page is there. Nothing has to be written when the line starts — the page comes
+  together as the first release proper of the line comes into view — but it does have to exist by
+  the time that release is published, or its notes link to an empty page.
+- **Release branches that are done.** A branch is worth keeping only while its line might still
+  get a patch. The ones that exist do not cover every line that ever had one — `3.8.1` shipped and
+  there is no `aaa-3.8.x` — so this is housekeeping rather than a rule, but starting a new minor is
+  the natural moment to look at the bottom of the branch list and delete what has been superseded.
+
+## Backports
+
+A patch release is cut from a release branch (`aaa-X.Y.x`), and what it carries beyond the previous
+release is cherry-picked from the development line. Cherry-pick with `-x`:
 
 ```console
-# Build from the committed state (the gemspec's file list comes from `git ls-files`).
-$ docker build -f Dockerfile.jruby -t rbs-jruby .
+$ git cherry-pick -x <commit>
+```
+
+`-x` records the commit the change was copied from, and that recorded line is what `rake
+gem:changelog` follows to reach the pull request the change was written and reviewed in. Without
+it, the only pull request a backported commit is associated with is the one that carried the
+backport, which says nothing about the change and is the same for every commit it brought over —
+that is why the 4.0.3 changelog credits its three entries to the same pull request.
 
-# 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
+The entry names that pull request and adds the one that carried the backport:
 
-$ gem push pkg/rbs-X.Y.Z-java.gem
+```markdown
+* {title} ([#{original}](https://github.com/ruby/rbs/pull/{original}), Backported in [#{backport}](https://github.com/ruby/rbs/pull/{backport}))
 ```
 
-Optionally confirm it installs and runs on JRuby before pushing:
+`gem:changelog` prints this form on its own, from the same `-x` trailer: the origin it resolves is
+the first link, and the pull request of the cherry-pick in front of it is the second. On the
+development line nothing is a cherry-pick, so entries there keep the plain single link.
+
+The second link is what keeps the entry from reading as a mistake. The original pull request is
+against `master`, so it is listed again when the development line ships — and with nothing to tell
+the two apart, the same link under two version headings looks like a change written into the wrong
+section. #1923 is the pair to look at: plain under 3.6.0.pre.1, annotated under 3.5.2, which
+backported it.
+
+## Assembling the changelog without `gh`
+
+`gem:changelog` and `gem:changelog:json` reach GitHub through `gh`, so they cannot run from a
+Claude Code on the web session. `api.github.com` refuses anything the shell does there, and the
+refusal is keyed on the session rather than on the client, so installing `gh` does not help:
 
 ```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{ })"'
+$ curl -s -o /dev/null -w '%{http_code}' https://api.github.com/repos/ruby/rbs
+403
 ```
 
+Nothing else about the release is affected. `gem:check_release` and `gem:tag` read git and the
+working tree, `gem:gh_release` runs on a runner, and git itself reaches github.com normally —
+clone, fetch and push all work.
+
+So the task is run where it does work. Dispatch
+[`changelog.yml`](../.github/workflows/changelog.yml), which runs it on a runner, and read the list
+from the run summary, the log, or the `changelog` artifact.
+
+| Input | Value |
+| --- | --- |
+| The ref selector | The branch the changelog is for: `aaa-X.Y.x` for a patch release, `master` otherwise |
+| `version` | Where the changelog starts, when that should not follow `RBS::VERSION`. It names the release before the one being written, so `4.1.2` produces the 4.1.3 changelog |
+| `format` | `list` for the template, `json` for the pull request details the sections are sorted from |
+
+The ref is not incidental the way it is for `release-gems.yml`: it picks the history being
+described *and* the copy of the task that describes it. So a release branch needs `changelog.yml`
+on it, the same way it needs the release tasks — dispatching on a ref without the file fails with
+`Workflow does not have 'workflow_dispatch' trigger`, since the trigger is read from the ref.
+
 ## 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.
+- The WASI SDK version is pinned in `wasm.yml`, `jruby.yml`, `release-gems.yml`, and
+  `Dockerfile.jruby`, each carrying its own copy. Keep them in sync when bumping. The
+  Chicory/ASM versions are not duplicated: they are the `jar` requirements in
+  `rbs.gemspec`, which is where the workflow, `Dockerfile.jruby` and `gem install` all
+  read them from.
+- `rake 'gem:check_release[X.Y.Z]'` and `rake gem:tag` are what the workflow runs to
+  check the release and to create the tag. Both work locally, which is the fallback
+  if the tag ever has to be created by hand.
+- Those two tasks and `rake gem:gh_release` come from the Rakefile of the commit
+  being released, not from the branch the workflow was dispatched from. Releasing
+  from a release branch (`aaa-X.Y.x`) therefore needs the release tooling on that
+  branch as well; without it the run fails on the missing task, before publishing
+  anything.

data/docs/stdlib.md

@@ -15,6 +15,14 @@ $ bundle exec rake 'generate:stdlib_test[String]'
 Created: test/stdlib/String_test.rb
 ```
 
+Core signatures are loaded by default. To generate a test for a class defined in standard library signatures,
+pass the paths containing those signatures and their dependencies after the class name.
+
+```console
+$ bundle exec rake 'generate:stdlib_test[CSV::Row,stdlib/csv/0,stdlib/forwardable/0]'
+Created: test/stdlib/CSV_Row_test.rb
+```
+
 It generates `test/stdlib/[class_name]_test.rb`.
 The test scripts would look like the following:
 

data/docs/syntax.md

@@ -48,6 +48,18 @@ _proc_ ::= `^` _parameters?_ _self-type-binding?_ _block?_ `->` _type_
          | `^` `(` `?` `)` `->` _type_                                   # Proc type with untyped parameter
 ```
 
+`\w` above, and everywhere else in this document, is `[a-zA-Z0-9_]` together
+with every character outside ASCII -- the same set Ruby takes into an
+identifier. So `ServicioÚltimaVez` is a class name and `nombre_único` is an
+alias name.
+
+The leading character is the exception. RBS reads it to tell a class name from
+an interface name from an alias name, so where it makes that distinction it has
+to be ASCII: `class 日本語` is a class in Ruby but not a name RBS can write.
+Nowhere else is restricted -- a method name, a variable name, an instance
+variable name and a class variable name may all open with any character Ruby
+accepts.
+
 ### Class instance type
 
 Class instance type denotes _an instance of a class_.

data/ext/rbs_extension/ast_translation.c

@@ -1636,6 +1636,7 @@ VALUE rbs_struct_to_ruby_value(rbs_translation_context_t ctx, rbs_node_t *instan
         VALUE arg_required_keywords = rbs_hash_to_ruby_hash(ctx, node->required_keywords);
         VALUE arg_optional_keywords = rbs_hash_to_ruby_hash(ctx, node->optional_keywords);
         VALUE arg_rest_keywords = rbs_struct_to_ruby_value(ctx, (rbs_node_t *) node->rest_keywords); // rbs_node
+        VALUE arg_forwarding = rbs_struct_to_ruby_value(ctx, (rbs_node_t *) node->forwarding);       // rbs_node
         VALUE arg_return_type = rbs_struct_to_ruby_value(ctx, (rbs_node_t *) node->return_type);     // rbs_node
 
         // Claim the shared kwargs hash, clear it, fill it, and hand it to `.new`.
@@ -1649,9 +1650,23 @@ VALUE rbs_struct_to_ruby_value(rbs_translation_context_t ctx, rbs_node_t *instan
         rb_hash_aset(h, ID2SYM(rb_intern("required_keywords")), arg_required_keywords);
         rb_hash_aset(h, ID2SYM(rb_intern("optional_keywords")), arg_optional_keywords);
         rb_hash_aset(h, ID2SYM(rb_intern("rest_keywords")), arg_rest_keywords);
+        rb_hash_aset(h, ID2SYM(rb_intern("forwarding")), arg_forwarding);
         rb_hash_aset(h, ID2SYM(rb_intern("return_type")), arg_return_type);
         return CLASS_NEW_INSTANCE(RBS_Types_Function, 1, &h);
     }
+    case RBS_TYPES_FUNCTION_FORWARDING_PARAM: {
+        rbs_types_function_forwarding_param_t *node = (rbs_types_function_forwarding_param_t *) instance;
+
+        // Compute child VALUEs into locals variables first, before any recursion into `rbs_struct_to_ruby_value()`.
+        VALUE arg_location = rbs_location_range_to_ruby_location(ctx, node->base.location);
+
+        // Claim the shared kwargs hash, clear it, fill it, and hand it to `.new`.
+        // Must not recurse between `rb_hash_clear()` and `CLASS_NEW_INSTANCE()`.
+        VALUE h = ctx.reusable_kwargs_hash;
+        rb_hash_clear(h);
+        rb_hash_aset(h, ID2SYM(rb_intern("location")), arg_location);
+        return CLASS_NEW_INSTANCE(RBS_Types_Function_ForwardingParam, 1, &h);
+    }
     case RBS_TYPES_FUNCTION_PARAM: {
         rbs_types_function_param_t *node = (rbs_types_function_param_t *) instance;
 

data/ext/rbs_extension/class_constants.c

@@ -79,6 +79,7 @@ VALUE RBS_Types_Block;
 VALUE RBS_Types_ClassInstance;
 VALUE RBS_Types_ClassSingleton;
 VALUE RBS_Types_Function;
+VALUE RBS_Types_Function_ForwardingParam;
 VALUE RBS_Types_Function_Param;
 VALUE RBS_Types_Interface;
 VALUE RBS_Types_Intersection;
@@ -173,6 +174,7 @@ void rbs__init_constants(void) {
     IMPORT_CONSTANT(RBS_Types_ClassInstance, RBS_Types, "ClassInstance");
     IMPORT_CONSTANT(RBS_Types_ClassSingleton, RBS_Types, "ClassSingleton");
     IMPORT_CONSTANT(RBS_Types_Function, RBS_Types, "Function");
+    IMPORT_CONSTANT(RBS_Types_Function_ForwardingParam, RBS_Types_Function, "ForwardingParam");
     IMPORT_CONSTANT(RBS_Types_Function_Param, RBS_Types_Function, "Param");
     IMPORT_CONSTANT(RBS_Types_Interface, RBS_Types, "Interface");
     IMPORT_CONSTANT(RBS_Types_Intersection, RBS_Types, "Intersection");

data/ext/rbs_extension/class_constants.h

@@ -87,6 +87,7 @@ extern VALUE RBS_Types_Block;
 extern VALUE RBS_Types_ClassInstance;
 extern VALUE RBS_Types_ClassSingleton;
 extern VALUE RBS_Types_Function;
+extern VALUE RBS_Types_Function_ForwardingParam;
 extern VALUE RBS_Types_Function_Param;
 extern VALUE RBS_Types_Interface;
 extern VALUE RBS_Types_Intersection;

data/ext/rbs_extension/main.c

@@ -146,44 +146,80 @@ static VALUE parse_type_try(VALUE a) {
     return rbs_struct_to_ruby_value(ctx, type);
 }
 
-static void validate_position_range(int start_pos, int end_pos) {
+/**
+ * `end_pos` may point past the end of the buffer: clamping with a large
+ * number instead of measuring the buffer is ordinary, and the lexer stops at
+ * the end on its own.
+ * */
+static void validate_position_range(VALUE string, int start_pos, int end_pos) {
     if (start_pos < 0 || end_pos < 0) {
         rb_raise(rb_eArgError, "negative position range: %d...%d", start_pos, end_pos);
     }
     if (start_pos > end_pos) {
         rb_raise(rb_eArgError, "invalid position range: %d...%d", start_pos, end_pos);
     }
+
+    long size = RSTRING_LEN(string);
+    if ((long) start_pos > size) {
+        rb_raise(rb_eArgError, "position range starts past the end of the buffer: %d...%d, buffer is %ld bytes", start_pos, end_pos, size);
+    }
 }
 
 static rbs_lexer_t *alloc_lexer_from_buffer(rbs_allocator_t *allocator, VALUE string, rb_encoding *encoding, int start_pos, int end_pos) {
-    validate_position_range(start_pos, end_pos);
+    validate_position_range(string, start_pos, end_pos);
 
     const char *encoding_name = rb_enc_name(encoding);
 
-    return rbs_lexer_new(
+    rbs_lexer_t *lexer = rbs_lexer_new(
         allocator,
         rbs_string_from_ruby_string(string),
         rbs_encoding_find((const uint8_t *) encoding_name, (const uint8_t *) (encoding_name + strlen(encoding_name))),
         start_pos,
         end_pos
     );
+
+    if (lexer == NULL) {
+        rb_raise(rb_eArgError, "position range starts inside a character: %d...%d", start_pos, end_pos);
+    }
+
+    return lexer;
 }
 
-static rbs_parser_t *alloc_parser_from_buffer(VALUE buffer, int start_pos, int end_pos) {
-    validate_position_range(start_pos, end_pos);
+// Build the parser options from the arguments the `_parse_*` entry points
+// receive. The optional syntax these enable is not part of the public
+// `RBS::Parser` API, so only the private entry points pass them through.
+static rbs_parser_options_t parser_options(VALUE enable_forwarding_params) {
+    return (rbs_parser_options_t) {
+        .enable_forwarding_params = RB_TEST(enable_forwarding_params),
+    };
+}
 
+static rbs_parser_t *alloc_parser_from_buffer_with_options(VALUE buffer, int start_pos, int end_pos, rbs_parser_options_t options) {
     VALUE string = rb_funcall(buffer, rb_intern("content"), 0);
     StringValue(string);
 
+    validate_position_range(string, start_pos, end_pos);
+
     rb_encoding *encoding = rb_enc_get(string);
     const char *encoding_name = rb_enc_name(encoding);
 
-    return rbs_parser_new(
+    rbs_parser_t *parser = rbs_parser_new_with_options(
         rbs_string_from_ruby_string(string),
         rbs_encoding_find((const uint8_t *) encoding_name, (const uint8_t *) (encoding_name + strlen(encoding_name))),
         start_pos,
-        end_pos
+        end_pos,
+        options
     );
+
+    if (parser == NULL) {
+        rb_raise(rb_eArgError, "position range starts inside a character: %d...%d", start_pos, end_pos);
+    }
+
+    return parser;
+}
+
+static rbs_parser_t *alloc_parser_from_buffer(VALUE buffer, int start_pos, int end_pos) {
+    return alloc_parser_from_buffer_with_options(buffer, start_pos, end_pos, (rbs_parser_options_t) { 0 });
 }
 
 static VALUE rbsparser_parse_type(VALUE self, VALUE buffer, VALUE start_pos, VALUE end_pos, VALUE variables, VALUE require_eof, VALUE void_allowed, VALUE self_allowed, VALUE classish_allowed) {
@@ -232,12 +268,12 @@ static VALUE parse_method_type_try(VALUE a) {
     return rbs_struct_to_ruby_value(ctx, (rbs_node_t *) method_type);
 }
 
-static VALUE rbsparser_parse_method_type(VALUE self, VALUE buffer, VALUE start_pos, VALUE end_pos, VALUE variables, VALUE require_eof) {
+static VALUE rbsparser_parse_method_type(VALUE self, VALUE buffer, VALUE start_pos, VALUE end_pos, VALUE variables, VALUE require_eof, VALUE enable_forwarding_params) {
     VALUE string = rb_funcall(buffer, rb_intern("content"), 0);
     StringValue(string);
     rb_encoding *encoding = rb_enc_get(string);
 
-    rbs_parser_t *parser = alloc_parser_from_buffer(buffer, FIX2INT(start_pos), FIX2INT(end_pos));
+    rbs_parser_t *parser = alloc_parser_from_buffer_with_options(buffer, FIX2INT(start_pos), FIX2INT(end_pos), parser_options(enable_forwarding_params));
     declare_type_variables(parser, variables, buffer);
     struct parse_method_type_arg arg = {
         .buffer = buffer,
@@ -271,12 +307,12 @@ static VALUE parse_signature_try(VALUE a) {
     return rbs_struct_to_ruby_value(ctx, (rbs_node_t *) signature);
 }
 
-static VALUE rbsparser_parse_signature(VALUE self, VALUE buffer, VALUE start_pos, VALUE end_pos) {
+static VALUE rbsparser_parse_signature(VALUE self, VALUE buffer, VALUE start_pos, VALUE end_pos, VALUE enable_forwarding_params) {
     VALUE string = rb_funcall(buffer, rb_intern("content"), 0);
     StringValue(string);
     rb_encoding *encoding = rb_enc_get(string);
 
-    rbs_parser_t *parser = alloc_parser_from_buffer(buffer, FIX2INT(start_pos), FIX2INT(end_pos));
+    rbs_parser_t *parser = alloc_parser_from_buffer_with_options(buffer, FIX2INT(start_pos), FIX2INT(end_pos), parser_options(enable_forwarding_params));
     struct parse_signature_arg arg = {
         .buffer = buffer,
         .encoding = encoding,
@@ -364,12 +400,12 @@ static VALUE parse_method_type_to_bytes_try(VALUE a) {
     return serialized_node_to_string(parser, (rbs_node_t *) method_type);
 }
 
-static VALUE rbsparser_parse_method_type_to_bytes(VALUE self, VALUE buffer, VALUE start_pos, VALUE end_pos, VALUE variables, VALUE require_eof) {
+static VALUE rbsparser_parse_method_type_to_bytes(VALUE self, VALUE buffer, VALUE start_pos, VALUE end_pos, VALUE variables, VALUE require_eof, VALUE enable_forwarding_params) {
     VALUE string = rb_funcall(buffer, rb_intern("content"), 0);
     StringValue(string);
     rb_encoding *encoding = rb_enc_get(string);
 
-    rbs_parser_t *parser = alloc_parser_from_buffer(buffer, FIX2INT(start_pos), FIX2INT(end_pos));
+    rbs_parser_t *parser = alloc_parser_from_buffer_with_options(buffer, FIX2INT(start_pos), FIX2INT(end_pos), parser_options(enable_forwarding_params));
     declare_type_variables(parser, variables, buffer);
     struct parse_method_type_arg arg = {
         .buffer = buffer,
@@ -397,12 +433,12 @@ static VALUE parse_signature_to_bytes_try(VALUE a) {
     return serialized_node_to_string(parser, (rbs_node_t *) signature);
 }
 
-static VALUE rbsparser_parse_signature_to_bytes(VALUE self, VALUE buffer, VALUE start_pos, VALUE end_pos) {
+static VALUE rbsparser_parse_signature_to_bytes(VALUE self, VALUE buffer, VALUE start_pos, VALUE end_pos, VALUE enable_forwarding_params) {
     VALUE string = rb_funcall(buffer, rb_intern("content"), 0);
     StringValue(string);
     rb_encoding *encoding = rb_enc_get(string);
 
-    rbs_parser_t *parser = alloc_parser_from_buffer(buffer, FIX2INT(start_pos), FIX2INT(end_pos));
+    rbs_parser_t *parser = alloc_parser_from_buffer_with_options(buffer, FIX2INT(start_pos), FIX2INT(end_pos), parser_options(enable_forwarding_params));
     struct parse_signature_arg arg = {
         .buffer = buffer,
         .encoding = encoding,
@@ -587,11 +623,11 @@ void rbs__init_parser(void) {
     rb_gc_register_mark_object(EMPTY_HASH);
 
     rb_define_singleton_method(RBS_Parser, "_parse_type", rbsparser_parse_type, 8);
-    rb_define_singleton_method(RBS_Parser, "_parse_method_type", rbsparser_parse_method_type, 5);
-    rb_define_singleton_method(RBS_Parser, "_parse_signature", rbsparser_parse_signature, 3);
+    rb_define_singleton_method(RBS_Parser, "_parse_method_type", rbsparser_parse_method_type, 6);
+    rb_define_singleton_method(RBS_Parser, "_parse_signature", rbsparser_parse_signature, 4);
     rb_define_singleton_method(RBS_Parser, "_parse_type_to_bytes", rbsparser_parse_type_to_bytes, 8);
-    rb_define_singleton_method(RBS_Parser, "_parse_method_type_to_bytes", rbsparser_parse_method_type_to_bytes, 5);
-    rb_define_singleton_method(RBS_Parser, "_parse_signature_to_bytes", rbsparser_parse_signature_to_bytes, 3);
+    rb_define_singleton_method(RBS_Parser, "_parse_method_type_to_bytes", rbsparser_parse_method_type_to_bytes, 6);
+    rb_define_singleton_method(RBS_Parser, "_parse_signature_to_bytes", rbsparser_parse_signature_to_bytes, 4);
     rb_define_singleton_method(RBS_Parser, "_parse_type_params", rbsparser_parse_type_params, 4);
     rb_define_singleton_method(RBS_Parser, "_parse_inline_leading_annotation", rbsparser_parse_inline_leading_annotation, 4);
     rb_define_singleton_method(RBS_Parser, "_parse_inline_trailing_annotation", rbsparser_parse_inline_trailing_annotation, 4);