rbs 4.1.0 → 4.1.1.dev.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cb4ca04de969abdc9d7f58e67fb98a0ce0d39e6669dab1be23241ba08a1b883
-  data.tar.gz: c758f606ee5737b64c45fd4da9c99f6522f1a62a0b8a37b4023d37fcb69b6d59
+  metadata.gz: 4c6080d3cf9cb3af2188509104f6b43f59f47a08313cc82ac9c1d9e052dc1dc9
+  data.tar.gz: 131ca181e7e1516b8b4b938e9fce97c97ab4c3ad2b73b47d3f0e4e42996797ac
 SHA512:
-  metadata.gz: 26dbbd5af3941363c80a282d63dfda59d0aba521bea2c75e45c3dd58336a18920d859ef426b0c8bab67535be7e3651f8f2f83a78ed068477dd5ccf8adb09df4c
-  data.tar.gz: 0a5c85aa87e7ddb72519953952bb0bec098c8322cd379fb0e5e8dfb6ac0b1a8f4df70ee225cb3361b719d0b506b5d9eff0c43db08ce235d7ac233adb320d9d8a
+  metadata.gz: 1b6c4bb23f7b593523cad221f31bfdd4d3399e8b93aac56813e2731680a4965d5571ce85ddbded21cd5353993f53719e2f8de91e1d4be7932ec5116c0abb3643
+  data.tar.gz: 95f2e854dc6e2f9115f258809110ec920468c6e1aadedfc7b98a13decb4c501bc0fd59958e8ffb06077bf34faf32a6d7a0310f8b2fc56f5b7a6477b521fca949

data/.github/dependabot.yml

@@ -21,4 +21,4 @@ updates:
     schedule:
       interval: 'weekly'
     labels:
-      - 'no-milestone'
+      - 'skip-changelog'

data/.github/workflows/bundle-update.yml

@@ -58,6 +58,6 @@ jobs:
             --body "Automated weekly bundle update" \
             --head "$(git rev-parse --abbrev-ref HEAD)" \
             --base "${{ github.event.repository.default_branch }}" \
-            --label "no-milestone"
+            --label "skip-changelog"
 
           gh pr merge --auto --merge "$(git rev-parse --abbrev-ref HEAD)"

data/.github/workflows/release-gems.yml

@@ -0,0 +1,164 @@
+name: Release gems
+
+# Builds, publishes, and announces a release. Dispatch it against the `vX.Y.Z` tag
+# of the release: the tag is created first so that everything published afterwards
+# traces back to an immutable ref, and so the reversible step comes before the
+# irreversible one.
+#
+# Dispatching against a branch builds and verifies the gems and stops there, which
+# is how the build is exercised without releasing anything.
+#
+# | 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`, prebuilt here |
+#
+# See docs/release.md. The `java` gem is built on CRuby: the platform comes from
+# `RBS_PLATFORM`, not from the engine running `gem build`. JRuby is only needed to
+# run the result, which the workflow does before it would publish anything.
+#
+# One job on purpose. Tagging, pushing the gems, and opening the GitHub release
+# all belong to a single release, and keeping them in one place keeps their order
+# readable -- the tag is created before anything is published, so the reversible
+# step comes before the irreversible one.
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  # Keep in sync with .github/workflows/wasm.yml and .github/workflows/jruby.yml.
+  WASI_SDK_VERSION: "33"
+  WASI_SDK_RELEASE: "33.0"
+
+jobs:
+  release:
+    name: release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # publish the GitHub release
+      id-token: write # trusted publishing to RubyGems
+    steps:
+      # The gemspec takes its file list from `git ls-files`, so both gems are built
+      # from the committed state.
+      - uses: actions/checkout@v7
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ruby
+          bundler: none
+      - name: Update rubygems & bundler
+        run: gem update --system
+      - name: Install gems
+        run: |
+          bundle config set --local without libs:profilers
+          bundle install --jobs 4 --retry 3
+
+      - name: Read the version
+        id: version
+        run: echo "version=$(ruby -e 'load "lib/rbs/version.rb"; print RBS::VERSION')" >> "$GITHUB_OUTPUT"
+
+      # Fail before spending a minute on the build, and before anything is pushed:
+      # the tag is what the release is named after, so it has to be the version the
+      # tagged commit actually declares.
+      - name: Check the tag against RBS::VERSION
+        if: github.ref_type == 'tag'
+        run: |
+          if [ "${{ github.ref_name }}" != "v${{ steps.version.outputs.version }}" ]; then
+            echo "::error::tag ${{ github.ref_name }} does not match RBS::VERSION ${{ steps.version.outputs.version }}"
+            exit 1
+          fi
+
+      - name: Build the ruby gem
+        run: |
+          mkdir -p pkg
+          gem build rbs.gemspec -o "pkg/rbs-${{ steps.version.outputs.version }}.gem"
+
+      # `rake wasm:jruby_setup` compiles src/**/*.c to WebAssembly and copies the
+      # result to lib/rbs/wasm/, where the gemspec picks it up. clang runs as a
+      # subprocess, so this works on CRuby.
+      - name: Install the WASI SDK
+        run: |
+          url="https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-${WASI_SDK_VERSION}/wasi-sdk-${WASI_SDK_RELEASE}-x86_64-linux.tar.gz"
+          mkdir -p "$HOME/wasi-sdk"
+          curl -sSL "$url" | tar xz --strip-components=1 -C "$HOME/wasi-sdk"
+          echo "WASI_SDK_PATH=$HOME/wasi-sdk" >> "$GITHUB_ENV"
+      - name: Build rbs_parser.wasm
+        run: bundle exec rake wasm:jruby_setup
+
+      - name: Build the java gem
+        env:
+          RBS_PLATFORM: java
+        run: gem build rbs.gemspec -o "pkg/rbs-${{ steps.version.outputs.version }}-java.gem"
+
+      # `git ls-files` vouches for everything else, but rbs_parser.wasm is a build
+      # artifact, so the java gem is the one that can come out quietly wrong.
+      - name: Check the built gems
+        run: |
+          ruby -rrubygems/package -e '
+            ruby_gem, java_gem = ARGV.map { Gem::Package.new(_1).spec }
+
+            raise "unexpected platform: #{ruby_gem.platform}" unless ruby_gem.platform.to_s == "ruby"
+            raise "the C extension is not declared" if ruby_gem.extensions.empty?
+
+            raise "unexpected platform: #{java_gem.platform}" unless java_gem.platform.to_s == "java"
+            raise "rbs_parser.wasm is missing" unless java_gem.files.include?("lib/rbs/wasm/rbs_parser.wasm")
+            raise "the java gem must not declare an extension" unless java_gem.extensions.empty?
+
+            [ruby_gem, java_gem].each { puts "#{_1.full_name}: #{_1.files.size} files" }
+          ' "pkg/rbs-${{ steps.version.outputs.version }}.gem" \
+            "pkg/rbs-${{ steps.version.outputs.version }}-java.gem"
+
+      # The checks above cannot tell whether rbs_parser.wasm actually runs. Install
+      # the gem the way a user would -- jar-dependencies fetches Chicory and ASM
+      # from Maven during the install -- and parse something with it, so the
+      # WebAssembly runtime is exercised end to end before anything is published.
+      - name: Set up JRuby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: jruby
+          bundler: none
+      - name: Check the java gem on JRuby
+        run: |
+          gem install "pkg/rbs-${{ steps.version.outputs.version }}-java.gem"
+          ruby -e '
+            require "rbs"
+            _, _, decls = RBS::Parser.parse_signature("class Foo end")
+            names = decls.map { _1.name.to_s }
+            raise "parsed #{names.inspect}, expected [\"Foo\"]" unless names == ["Foo"]
+            puts "#{RUBY_ENGINE} #{RUBY_VERSION}: rbs #{RBS::VERSION} parses through the WebAssembly runtime"
+          '
+
+      - name: Switch back to CRuby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ruby
+          bundler: none
+
+      # Uploaded before publishing, so a failed push still leaves the gems behind.
+      - uses: actions/upload-artifact@v7
+        with:
+          name: gems
+          path: pkg/*.gem
+          if-no-files-found: error
+
+      # Everything below runs only for a release tag.
+      - name: Configure RubyGems credentials
+        if: github.ref_type == 'tag'
+        # No floating major tag on this action, so the exact release is pinned.
+        uses: rubygems/configure-rubygems-credentials@v2.1.0
+
+      - name: Push the gems
+        if: github.ref_type == 'tag'
+        run: |
+          gem push "pkg/rbs-${{ steps.version.outputs.version }}.gem"
+          gem push "pkg/rbs-${{ steps.version.outputs.version }}-java.gem"
+
+      # Last, so that a failed push never announces a release that has no gems.
+      - name: Publish the GitHub release
+        if: github.ref_type == 'tag'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: bundle exec rake gem:gh_release

data/Rakefile

@@ -55,8 +55,15 @@ task :confirm_lexer => :lexer do
 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"
+  puts "Testing if generated code is updated with respect to templates"
+
+  # Every template generates the file it is named after: `templates/<path>.erb` generates `<path>`.
+  generated = Dir.glob("templates/**/*.erb").sort.map { _1.delete_prefix("templates/").delete_suffix(".erb") }
+
+  missing = generated.reject { File.exist?(_1) }
+  raise "Templates without a generated file: #{missing.join(", ")}. Is the `templates` task missing an entry?" unless missing.empty?
+
+  sh "git diff --exit-code -- #{generated.join(" ")}"
 end
 
 # Task to format C code using clang-format
@@ -147,6 +154,9 @@ 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
+rule %r{^ext/(.*)\.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"
@@ -495,46 +505,329 @@ NOTES
 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
+# Pull requests with one of these labels are omitted from the changelog.
+CHANGELOG_SKIP_LABELS = ["skip-changelog"]
 
-  if patch == 0
-    milestone = "RBS #{major}.#{minor}"
-  else
-    milestone = "RBS #{major}.#{minor}.x"
-  end
+# Resolves the commit-ish the changelog starts from.
+#
+# `version` is a version number, a tag, or any commit-ish. When it is omitted, the latest tag
+# matching `tag_glob` is used, skipping the ones matching `exclude_globs`.
+#
+def resolve_changelog_base(version, tag_glob:, exclude_globs: [])
+  require "open3"
+
+  from =
+    if version
+      # `4.1.0` and `v4.1.0` both mean the tag `v4.1.0`, while `master` or a SHA is used as is.
+      version.match?(/\A\d/) ? "v#{version}" : version
+    else
+      command = ["git", "describe", "--tags", "--match", tag_glob, "--abbrev=0"]
+      exclude_globs.each { |glob| command.push("--exclude", glob) }
 
-  puts "🔍 Finding pull requests that is associated to milestone `#{milestone}`..."
+      output, status = Open3.capture2(*command)
+      raise "🚨 Cannot detect the latest tag matching `#{tag_glob}`. Give the previous version explicitly." unless status.success?
+      output.chomp
+    end
+
+  _, status = Open3.capture2("git", "rev-parse", "--verify", "--quiet", "#{from}^{commit}")
+  raise "🚨 No such commit-ish: `#{from}`" unless status.success?
 
-  command = [
-    "gh",
-    "pr",
-    "list",
-    "--limit=10000",
-    "--json",
-    "url,title,number",
-    "--search" ,
-    "milestone:\"#{milestone}\" is:merged sort:updated-desc -label:Released"
-  ]
+  from
+end
 
+# Runs a GraphQL query against the repository of the working directory.
+#
+# `body` is the selection set inside `repository`, so a query can use the `$owner` and `$name`
+# variables. Returns the contents of `data.repository`.
+#
+def changelog_graphql(body)
   require "open3"
+  require "json"
+
+  @changelog_repository ||=
+    begin
+      output, status = Open3.capture2("gh", "repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner")
+      raise status.inspect unless status.success?
+      output.chomp.split("/", 2)
+    end
+  owner, name = @changelog_repository
+
+  query = <<~GRAPHQL
+    query($owner: String!, $name: String!) {
+      repository(owner: $owner, name: $name) {
+        #{body}
+      }
+    }
+  GRAPHQL
+
+  output, status = Open3.capture2(
+    "gh", "api", "graphql",
+    "-f", "query=#{query}",
+    "-f", "owner=#{owner}",
+    "-f", "name=#{name}",
+    binmode: true
+  )
+  raise status.inspect unless status.success?
+
+  # GitHub always answers in UTF-8, while the default external encoding follows the locale. Without
+  # this, a pull request body with an emoji fails to parse under `LANG=C`, as in GitHub Actions.
+  JSON.parse(output.force_encoding(Encoding::UTF_8), symbolize_names: true).dig(:data, :repository)
+end
+
+# Lists the commits between `from` and `HEAD`, newest first.
+#
+# Giving `paths` limits the commits to the ones touching the paths.
+#
+def changelog_commits(from, paths: [])
+  require "open3"
+
+  command = ["git", "log", "--format=%H", "#{from}..HEAD"]
+  # `--simplify-merges` keeps the default history simplification from following only one parent of
+  # a merge commit, which can drop the other side. Note that `--full-history` alone is wrong here:
+  # it also lists merge commits that do not touch the paths, bringing back the excluded pull
+  # requests. The two flags produce the same commits as the default mode for this repository today.
+  command.push("--full-history", "--simplify-merges", "--", *paths) unless paths.empty?
+
   output, status = Open3.capture2(*command)
   raise status.inspect unless status.success?
 
-  require "json"
-  json = JSON.parse(output, symbolize_names: true)
+  output.lines.map(&:chomp).reject(&:empty?)
+end
 
-  unless json.empty?
-    puts
-    json.each do |line|
-      puts "* #{line[:title]} ([##{line[:number]}](#{line[:url]}))"
+# Finds the pull requests the commits came from, keeping the order of `commits`.
+#
+# Returns the pull requests for the changelog and the ones omitted by `skip_labels`.
+#
+def changelog_pull_requests(commits, skip_labels: CHANGELOG_SKIP_LABELS)
+  pull_requests = {}
+  skipped = {}
+
+  commits.each_slice(50) do |slice|
+    # Ask GitHub which pull requests the commits came from, so that any merge strategy -- merge
+    # commit, squash, or rebase -- is handled without parsing commit messages.
+    aliases = slice.map.with_index do |commit, index|
+      <<~GRAPHQL
+        c#{index}: object(oid: "#{commit}") {
+          ... on Commit {
+            associatedPullRequests(first: 10) {
+              nodes {
+                number title url merged
+                labels(first: 100) { nodes { name } }
+              }
+            }
+          }
+        }
+      GRAPHQL
     end
+
+    changelog_graphql(aliases.join("\n")).each_value do |commit|
+      next unless commit
+
+      commit.dig(:associatedPullRequests, :nodes).each do |pr|
+        next unless pr[:merged]
+
+        pr = { number: pr[:number], title: pr[:title], url: pr[:url], labels: pr.dig(:labels, :nodes).map { |label| label[:name] } }
+        if (pr[:labels] & skip_labels).empty?
+          pull_requests[pr[:number]] ||= pr
+        else
+          skipped[pr[:number]] ||= pr
+        end
+      end
+    end
+  end
+
+  [pull_requests.values, skipped.values]
+end
+
+# Fetches the details that help classifying the pull requests: the changed files and the body.
+#
+def changelog_pull_request_details(pull_requests)
+  pull_requests.each_slice(50).flat_map do |slice|
+    aliases = slice.map do |pr|
+      <<~GRAPHQL
+        p#{pr[:number]}: pullRequest(number: #{pr[:number]}) {
+          body
+          author { login }
+          files(first: 100) {
+            nodes { path }
+            pageInfo { hasNextPage }
+          }
+        }
+      GRAPHQL
+    end
+
+    details = changelog_graphql(aliases.join("\n"))
+
+    slice.map do |pr|
+      detail = details[:"p#{pr[:number]}"] or next pr
+
+      pr.merge(
+        author: detail.dig(:author, :login),
+        # The body is a hint for writing the changelog, not a copy source. Keep it short.
+        body: detail[:body].to_s.strip.slice(0, 1000),
+        files: detail.dig(:files, :nodes).map { |file| file[:path] },
+        files_truncated: detail.dig(:files, :pageInfo, :hasNextPage)
+      )
+    end
+  end
+end
+
+# Reports the pull requests omitted by their label, so that they do not disappear silently.
+#
+def warn_skipped_pull_requests(skipped, skip_labels)
+  return if skipped.empty?
+
+  numbers = skipped.map { |pr| "##{pr[:number]}" }
+  numbers = numbers.take(20).push("and #{numbers.size - 20} more") if numbers.size > 20
+
+  $stderr.puts
+  $stderr.puts "  (⏭️  Skipped #{skipped.size} pull request(s) labeled #{skip_labels.map { |label| "`#{label}`" }.join(" or ")}: #{numbers.join(", ")})"
+end
+
+# Prints the changelog template listing the pull requests merged between `from` and `HEAD`.
+#
+# The changelog goes to STDOUT and everything else goes to STDERR, so that the output can be
+# piped to another command: `rake gem:changelog | pbcopy`
+#
+def print_changelog(from, paths: [], skip_labels: CHANGELOG_SKIP_LABELS)
+  $stderr.puts "🔍 Finding pull requests merged between `#{from}` and `HEAD`..."
+
+  commits = changelog_commits(from, paths: paths)
+  if commits.empty?
+    $stderr.puts "  (🤔 There is no commit after `#{from}`.)"
+    return
+  end
+
+  pull_requests, skipped = changelog_pull_requests(commits, skip_labels: skip_labels)
+
+  if pull_requests.empty?
+    $stderr.puts "  (🤔 No pull request is associated to the commits after `#{from}`.)"
   else
-    puts "  (🤑 There is no *unreleased* pull request associated to the milestone.)"
+    $stderr.puts
+    pull_requests.each do |pr|
+      puts "* #{pr[:title]} ([##{pr[:number]}](#{pr[:url]}))"
+    end
+    $stdout.flush
+  end
+
+  warn_skipped_pull_requests(skipped, skip_labels)
+end
+
+# Prints the same pull requests as `print_changelog` as JSON, with the details that help
+# classifying them into the sections of CHANGELOG.md.
+#
+# This is the input for the release automation, so it always prints a valid JSON document.
+#
+def print_changelog_json(from, paths: [], skip_labels: CHANGELOG_SKIP_LABELS)
+  require "json"
+
+  $stderr.puts "🔍 Finding pull requests merged between `#{from}` and `HEAD`..."
+
+  commits = changelog_commits(from, paths: paths)
+  pull_requests, skipped = changelog_pull_requests(commits, skip_labels: skip_labels)
+  pull_requests = changelog_pull_request_details(pull_requests)
+
+  $stderr.puts "  (📋 #{pull_requests.size} pull request(s))"
+
+  puts JSON.pretty_generate(
+    {
+      from: from,
+      to: "HEAD",
+      pull_requests: pull_requests,
+      skipped: skipped
+    }
+  )
+  $stdout.flush
+
+  warn_skipped_pull_requests(skipped, skip_labels)
+end
+
+namespace :gem do
+  # The gem is developed in the whole repository except the Rust crate, which has its own release
+  # cycle. Note that this is an *exclusion*, not a list of the directories shipped in the gem:
+  # changes in `test/` or `.github/` are part of the gem's changelog too.
+  # A constant defined in a `namespace` block is a top-level constant, so it needs the prefix.
+  GEM_CHANGELOG_PATHS = [".", ":(exclude)rust"]
+
+  # The tags a release proper starts *after*, rather than at.
+  GEM_PRERELEASE_TAGS = ["v*.pre*", "v*.dev*"]
+
+  # Where the changelog of the release being prepared starts, derived from `RBS::VERSION`:
+  #
+  # * `X.Y.Z.pre.N` documents what changed since `X.Y.Z.pre.N-1`, so it starts from the latest tag.
+  # * `X.Y.Z` documents the whole cycle, the prereleases included, so it skips the prerelease tags
+  #   in between and starts from the previous release proper.
+  #
+  # This is the step that is easy to get wrong by hand: on a release proper the latest tag is a
+  # prerelease, so the obvious default would produce only the tail of the cycle. Passing a version
+  # explicitly overrides all of it.
+  #
+  def changelog_base(version)
+    excluded = Gem::Version.new(RBS::VERSION).prerelease? ? [] : GEM_PRERELEASE_TAGS
+    resolve_changelog_base(version, tag_glob: "v*", exclude_globs: excluded)
+  end
+
+  desc "Generate changelog template from GH pull requests merged since the previous release"
+  task :changelog, [:version] do |_task, args|
+    print_changelog(changelog_base(args[:version]), paths: GEM_CHANGELOG_PATHS)
+  end
+
+  namespace :changelog do
+    desc "Print the pull requests of `gem:changelog` as JSON, with the changed files and body of each"
+    task :json, [:version] do |_task, args|
+      print_changelog_json(changelog_base(args[:version]), paths: GEM_CHANGELOG_PATHS)
+    end
+  end
+
+  desc "Publish the GitHub release for RBS::VERSION, unless it is a `.dev.` version"
+  task :gh_release do
+    require "open3"
+
+    version = Gem::Version.new(RBS::VERSION)
+    major, minor, *_ = RBS::VERSION.split(".")
+    tag = "v#{RBS::VERSION}"
+
+    # There are three kinds of release: `X.Y.Z`, `X.Y.Z.pre.N`, and `X.Y.Z.dev.N`.
+    # The `.dev.N` ones are cut from the development line for people who need a
+    # specific change early; they are not written up in the changelog, so there are
+    # no notes to publish and nothing worth announcing.
+    if version.segments.include?("dev")
+      puts "⏭️  #{RBS::VERSION} is a dev release, so there is no GitHub release to publish."
+      next
+    end
+
+    # The release is created against an existing tag, so that the artifacts and the
+    # notes describe a commit that is already immutable.
+    _, status = Open3.capture2("git", "rev-parse", "--verify", "--quiet", "#{tag}^{commit}")
+    raise "🚨 No such tag: `#{tag}`. Tag the release before creating the GitHub release." unless status.success?
+
+    # The topmost section of the changelog is this release, minus its own heading.
+    # The encoding is explicit because the default external encoding follows the
+    # locale, and the changelog is not ASCII.
+    content = File.read(File.join(__dir__, "CHANGELOG.md"), encoding: Encoding::UTF_8)
+    section = content.scan(/^## \d.*?(?=^## \d)/m)[0] or raise "🚨 Cannot find a release section in CHANGELOG.md"
+    heading, _, body = section.partition("\n")
+    heading.include?(RBS::VERSION) or raise "🚨 CHANGELOG.md starts with `#{heading.strip}`, which is not #{RBS::VERSION}"
+
+    notes = <<~NOTES
+      [Release note](https://github.com/ruby/rbs/wiki/Release-Note-#{major}.#{minor})
+
+      #{body.strip}
+    NOTES
+
+    # Published rather than drafted: the notes are the changelog section that was
+    # already reviewed in the release pull request, so there is nothing left to edit.
+    command = [
+      "gh", "release", "create", tag,
+      "--title=#{RBS::VERSION}",
+      "--notes=#{notes}"
+    ]
+    command << "--prerelease" if version.prerelease?
+
+    output, status = Open3.capture2(*command)
+    raise "🚨 `gh release create` failed: #{status.inspect}" unless status.success?
+
+    puts "📝 Released #{tag}: #{output.chomp}"
   end
 end
 

data/config.yml

@@ -769,6 +769,7 @@ nodes:
         c_type: rbs_location_range
       - name: type_name
         c_type: rbs_type_name
+        optional: true  # NULL when the name is left out, to be inferred from the Ruby code
       - name: type_name_location
         c_type: rbs_location_range
         optional: true
@@ -781,6 +782,7 @@ nodes:
         c_type: rbs_location_range
       - name: type_name
         c_type: rbs_type_name
+        optional: true  # NULL when the name is left out, to be inferred from the Ruby code
       - name: type_name_location
         c_type: rbs_location_range
         optional: true

data/docs/release.md

@@ -1,69 +1,151 @@
 # Releasing RBS
 
+A release is a pull request, a tag, and one workflow run. Everything that leaves
+the repository — 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
+### 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.
 
-- 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.
+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.
 
-### 2. Build and push the `java` gem
+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.
 
-The `java` gem is not built by `rake release`, so build and push it manually:
+```markdown
+## X.Y.Z (YYYY-MM-DD)
 
-```console
-# Build from the committed state (the gemspec's file list comes from `git ls-files`).
-$ docker build -f Dockerfile.jruby -t rbs-jruby .
+### Signature updates
+
+### Language updates
 
-# 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
+### Library changes
 
-$ gem push pkg/rbs-X.Y.Z-java.gem
+#### rbs prototype
+
+#### rbs collection
+
+### Miscellaneous
 ```
 
-Optionally confirm it installs and runs on JRuby before pushing:
+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 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. Tag the release
+
+Once the pull request is merged, tag the merge commit and push the tag:
 
 ```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{ })"'
+$ git switch master && git pull
+$ git tag "v$(ruby -e 'load "lib/rbs/version.rb"; print RBS::VERSION')"
+$ git push origin --tags
 ```
 
+The tag comes before anything is published, so that the gems and the release notes describe a
+commit that is already immutable — and because a tag can be deleted, while a version pushed to
+RubyGems can only be yanked.
+
+### 3. Run the `Release gems` workflow against the tag
+
+Dispatch [`release-gems.yml`](../.github/workflows/release-gems.yml) from the Actions tab, picking
+the `vX.Y.Z` tag — **not** a branch — in the ref selector. The trusted publisher has no branch
+condition, so the ref you pick is what decides what gets published; the workflow refuses to run
+unless the tag matches `RBS::VERSION`.
+
+It then:
+
+- 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,
+- pushes both to RubyGems through trusted publishing,
+- publishes the GitHub release with the notes from CHANGELOG.md, skipping this last step for
+  `.dev.N` versions.
+
+Dispatching against a branch runs everything up to the artifact and stops, which is how the build
+is exercised without releasing.
+
+### 4. Start the next development cycle
+
+Open another pull request setting `RBS::VERSION` to the next prerelease (`4.1.1` → `4.1.2.pre`),
+with `Gemfile.lock` regenerated, labeled `skip-changelog` like the release pull request itself.
+Without it the version on `master` keeps claiming to be the released version for the whole
+development period, and `rake gem:changelog` reads that version to decide where the next changelog
+starts.
+
 ## 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.
+- `Dockerfile.jruby` pins the WASI SDK / Chicory / ASM versions to match the
+  `wasm`, `jruby`, and `release-gems` workflows. Keep them in sync when bumping.

data/include/rbs/ast.h

@@ -583,7 +583,7 @@ typedef struct rbs_ast_ruby_annotations_class_alias_annotation {
 
     rbs_location_range prefix_location;
     rbs_location_range keyword_location;
-    struct rbs_type_name *RBS_NONNULL type_name;
+    struct rbs_type_name *RBS_NULLABLE type_name;
     rbs_location_range type_name_location;
 } rbs_ast_ruby_annotations_class_alias_annotation_t;
 
@@ -631,7 +631,7 @@ typedef struct rbs_ast_ruby_annotations_module_alias_annotation {
 
     rbs_location_range prefix_location;
     rbs_location_range keyword_location;
-    struct rbs_type_name *RBS_NONNULL type_name;
+    struct rbs_type_name *RBS_NULLABLE type_name;
     rbs_location_range type_name_location;
 } rbs_ast_ruby_annotations_module_alias_annotation_t;
 
@@ -998,12 +998,12 @@ rbs_ast_members_prepend_t *RBS_NONNULL rbs_ast_members_prepend_new(rbs_allocator
 rbs_ast_members_private_t *RBS_NONNULL rbs_ast_members_private_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location);
 rbs_ast_members_public_t *RBS_NONNULL rbs_ast_members_public_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location);
 rbs_ast_ruby_annotations_block_param_type_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_block_param_type_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range ampersand_location, rbs_location_range name_location, rbs_location_range colon_location, rbs_location_range question_location, rbs_location_range type_location, rbs_node_t *RBS_NONNULL type_, rbs_location_range comment_location);
-rbs_ast_ruby_annotations_class_alias_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_class_alias_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range keyword_location, rbs_type_name_t *RBS_NONNULL type_name, rbs_location_range type_name_location);
+rbs_ast_ruby_annotations_class_alias_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_class_alias_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range keyword_location, rbs_type_name_t *RBS_NULLABLE type_name, rbs_location_range type_name_location);
 rbs_ast_ruby_annotations_colon_method_type_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_colon_method_type_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_node_list_t *RBS_NONNULL annotations, rbs_node_t *RBS_NONNULL method_type);
 rbs_ast_ruby_annotations_double_splat_param_type_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_double_splat_param_type_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range star2_location, rbs_location_range name_location, rbs_location_range colon_location, rbs_node_t *RBS_NONNULL param_type, rbs_location_range comment_location);
 rbs_ast_ruby_annotations_instance_variable_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_instance_variable_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_ast_symbol_t *RBS_NONNULL ivar_name, rbs_location_range ivar_name_location, rbs_location_range colon_location, rbs_node_t *RBS_NONNULL type, rbs_location_range comment_location);
 rbs_ast_ruby_annotations_method_types_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_method_types_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_node_list_t *RBS_NONNULL overloads, rbs_location_range_list_t *RBS_NONNULL vertical_bar_locations, rbs_location_range dot3_location);
-rbs_ast_ruby_annotations_module_alias_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_module_alias_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range keyword_location, rbs_type_name_t *RBS_NONNULL type_name, rbs_location_range type_name_location);
+rbs_ast_ruby_annotations_module_alias_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_module_alias_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range keyword_location, rbs_type_name_t *RBS_NULLABLE type_name, rbs_location_range type_name_location);
 rbs_ast_ruby_annotations_module_self_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_module_self_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range keyword_location, rbs_location_range colon_location, rbs_type_name_t *RBS_NONNULL name, rbs_node_list_t *RBS_NONNULL args, rbs_location_range open_bracket_location, rbs_location_range close_bracket_location, rbs_location_range_list_t *RBS_NONNULL args_comma_locations, rbs_location_range comment_location);
 rbs_ast_ruby_annotations_node_type_assertion_t *RBS_NONNULL rbs_ast_ruby_annotations_node_type_assertion_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_node_t *RBS_NONNULL type);
 rbs_ast_ruby_annotations_param_type_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_param_type_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range name_location, rbs_location_range colon_location, rbs_node_t *RBS_NONNULL param_type, rbs_location_range comment_location);

data/lib/rbs/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RBS
-  VERSION = "4.1.0"
+  VERSION = "4.1.1.dev.1"
 end

data/src/ast.c

@@ -913,7 +913,7 @@ rbs_ast_ruby_annotations_block_param_type_annotation_t *RBS_NONNULL rbs_ast_ruby
     return instance;
 }
 #line 140 "templates/src/ast.c.erb"
-rbs_ast_ruby_annotations_class_alias_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_class_alias_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range keyword_location, rbs_type_name_t *RBS_NONNULL type_name, rbs_location_range type_name_location) {
+rbs_ast_ruby_annotations_class_alias_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_class_alias_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range keyword_location, rbs_type_name_t *RBS_NULLABLE type_name, rbs_location_range type_name_location) {
     rbs_ast_ruby_annotations_class_alias_annotation_t *instance = rbs_allocator_alloc(allocator, rbs_ast_ruby_annotations_class_alias_annotation_t);
 
     *instance = (rbs_ast_ruby_annotations_class_alias_annotation_t) {
@@ -1001,7 +1001,7 @@ rbs_ast_ruby_annotations_method_types_annotation_t *RBS_NONNULL rbs_ast_ruby_ann
     return instance;
 }
 #line 140 "templates/src/ast.c.erb"
-rbs_ast_ruby_annotations_module_alias_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_module_alias_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range keyword_location, rbs_type_name_t *RBS_NONNULL type_name, rbs_location_range type_name_location) {
+rbs_ast_ruby_annotations_module_alias_annotation_t *RBS_NONNULL rbs_ast_ruby_annotations_module_alias_annotation_new(rbs_allocator_t *RBS_NONNULL allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range keyword_location, rbs_type_name_t *RBS_NULLABLE type_name, rbs_location_range type_name_location) {
     rbs_ast_ruby_annotations_module_alias_annotation_t *instance = rbs_allocator_alloc(allocator, rbs_ast_ruby_annotations_module_alias_annotation_t);
 
     *instance = (rbs_ast_ruby_annotations_module_alias_annotation_t) {

data/src/parser.c

@@ -405,18 +405,21 @@ NODISCARD
 static bool parse_keyword_key(rbs_parser_t *parser, rbs_ast_symbol_t **key) {
     rbs_parser_advance(parser);
 
-    rbs_location_range symbol_range = rbs_location_range_current_token(parser);
+    rbs_range_t symbol_range = parser->current_token.range;
 
     if (parser->next_token.type == pQUESTION) {
+        // The `?` is part of the key, so it is part of the location too.
+        symbol_range.end = parser->next_token.range.end;
+
         *key = rbs_ast_symbol_new(
             ALLOCATOR(),
-            symbol_range,
+            RBS_RANGE_LEX2AST(symbol_range),
             &parser->constant_pool,
             intern_token_start_end(parser, parser->current_token, parser->next_token)
         );
         rbs_parser_advance(parser);
     } else {
-        *key = rbs_ast_symbol_new(ALLOCATOR(), symbol_range, &parser->constant_pool, INTERN_TOKEN(parser, parser->current_token));
+        *key = rbs_ast_symbol_new(ALLOCATOR(), RBS_RANGE_LEX2AST(symbol_range), &parser->constant_pool, INTERN_TOKEN(parser, parser->current_token));
     }
 
     return true;

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbs
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.1.1.dev.1
 platform: ruby
 authors:
 - Soutaro Matsumoto
@@ -70,7 +70,7 @@ files:
 - ".github/workflows/comments.yml"
 - ".github/workflows/dependabot.yml"
 - ".github/workflows/jruby.yml"
-- ".github/workflows/milestone.yml"
+- ".github/workflows/release-gems.yml"
 - ".github/workflows/ruby.yml"
 - ".github/workflows/rust.yml"
 - ".github/workflows/truffleruby.yml"
@@ -649,7 +649,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.17
 specification_version: 4
 summary: Type signature for Ruby.
 test_files: []

data/.github/workflows/milestone.yml

@@ -1,91 +0,0 @@
-name: Check milestone
-
-on:
-  pull_request:
-    types: [opened, edited, labeled, unlabeled, milestoned, demilestoned, synchronize]
-  merge_group: {}
-
-permissions:
-  contents: read
-
-jobs:
-  check:
-    runs-on: ubuntu-latest
-
-    steps:
-      # The milestone is a property of the pull request, so there is nothing to
-      # check once it enters the merge queue. This job still has to run there
-      # because `check` is a required status check -- it just reports success
-      # without doing anything.
-      - uses: actions/checkout@v7
-        if: github.event_name == 'pull_request'
-
-      - name: Extract RBS::Version
-        id: version
-        if: github.event_name == 'pull_request'
-        run: |
-          # Extract version string from lib/rbs/version.rb
-          version=$(ruby -e 'load "lib/rbs/version.rb"; print RBS::VERSION')
-          echo "version=$version" >> "$GITHUB_OUTPUT"
-
-          # Parse major.minor.patch
-          IFS='.' read -r major minor patch _rest <<< "$version"
-          echo "major=$major" >> "$GITHUB_OUTPUT"
-          echo "minor=$minor" >> "$GITHUB_OUTPUT"
-          echo "patch=$patch" >> "$GITHUB_OUTPUT"
-
-          echo "RBS::VERSION = $version (major=$major, minor=$minor, patch=$patch)"
-
-      - name: Check milestone
-        if: github.event_name == 'pull_request'
-        uses: actions/github-script@v9
-        with:
-          script: |
-            const pr = context.payload.pull_request;
-            const milestone = pr.milestone;
-            const labels = pr.labels.map(l => l.name);
-
-            const version = '${{ steps.version.outputs.version }}';
-            const major = '${{ steps.version.outputs.major }}';
-            const minor = '${{ steps.version.outputs.minor }}';
-            const patch = parseInt('${{ steps.version.outputs.patch }}', 10);
-
-            if (!milestone) {
-              if (labels.includes('no-milestone')) {
-                core.info('No milestone set, but no-milestone label is present — OK');
-                return;
-              }
-              core.setFailed(
-                'No milestone set. Add a milestone or add the "no-milestone" label.'
-              );
-              return;
-            }
-
-            if (labels.includes('no-milestone')) {
-              core.setFailed(
-                'Milestone is set but "no-milestone" label is present. Remove the label or the milestone.'
-              );
-              return;
-            }
-
-            const milestoneName = milestone.title;
-            core.info(`Milestone: "${milestoneName}", RBS::VERSION: ${version}`);
-
-            // Expected milestone based on version:
-            //   patch == 0 → "RBS major.minor"   (e.g. "RBS 4.0")
-            //   patch >= 1 → "RBS major.minor.x"  (e.g. "RBS 4.0.x")
-            let expectedMilestone;
-            if (patch === 0) {
-              expectedMilestone = `RBS ${major}.${minor}`;
-            } else {
-              expectedMilestone = `RBS ${major}.${minor}.x`;
-            }
-
-            if (milestoneName !== expectedMilestone) {
-              core.setFailed(
-                `Milestone "${milestoneName}" does not match RBS::VERSION ${version}. ` +
-                `Expected milestone: "${expectedMilestone}"`
-              );
-            } else {
-              core.info(`Milestone "${milestoneName}" matches RBS::VERSION ${version}`);
-            }