rbs 4.1.0.pre.2-java

data/Rakefile

@@ -0,0 +1,869 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rbconfig"
+require 'rake/extensiontask'
+
+$LOAD_PATH << File.join(__dir__, "test")
+
+ruby = ENV["RUBY"] || RbConfig.ruby
+rbs = File.join(__dir__, "exe/rbs")
+bin = File.join(__dir__, "bin")
+
+Rake::ExtensionTask.new("rbs_extension")
+
+compile_task = Rake::Task[:compile]
+
+task :setup_extconf_compile_commands_json do
+  ENV["COMPILE_COMMANDS_JSON"] = "1"
+end
+
+compile_task.prerequisites.unshift(:setup_extconf_compile_commands_json)
+
+test_config = lambda do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"].reject do |path|
+    path =~ %r{test/stdlib/}
+  end
+  if defined?(RubyMemcheck)
+    if t.is_a?(RubyMemcheck::TestTask)
+      t.verbose = true
+      t.options = '-v'
+    end
+  end
+end
+
+if RUBY_ENGINE == "jruby"
+  # JRuby runs the parser in WebAssembly instead of the C extension, so there is
+  # nothing to compile. The wasm runtime must be assembled first with
+  # `rake wasm:jruby_setup` (which needs CRuby + the WASI SDK).
+  Rake::TestTask.new(:test, &test_config)
+else
+  Rake::TestTask.new(test: :compile, &test_config)
+end
+
+multitask :default => [:test, :stdlib_test, :typecheck_test, :rubocop, :validate, :test_doc]
+
+task :lexer do
+  sh "re2c -W --no-generation-date -o src/lexer.c src/lexer.re"
+  sh "clang-format -i -style=file src/lexer.c"
+end
+
+task :confirm_lexer => :lexer do
+  puts "Testing if lexer.c is updated with respect to lexer.re"
+  sh "git diff --exit-code src/lexer.c"
+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"
+end
+
+# Task to format C code using clang-format
+namespace :format do
+  dirs = ["src", "ext", "include"]
+
+  # Find all C source and header files
+  files = `find #{dirs.join(" ")} -type f \\( -name "*.c" -o -name "*.h" \\)`.split("\n")
+
+  desc "Format C source files using clang-format"
+  task :c do
+    puts "Formatting C files..."
+
+    # Check if clang-format is installed
+    unless system("which clang-format > /dev/null 2>&1")
+      abort "Error: clang-format not found. Please install clang-format first."
+    end
+
+    if files.empty?
+      puts "No C files found to format"
+      next
+    end
+
+    puts "Found #{files.length} files to format (excluding generated files)"
+
+    exit_status = 0
+    files.each do |file|
+      puts "Formatting #{file}"
+      unless system("clang-format -i -style=file #{file}")
+        puts "❌ Error formatting #{file}"
+        exit_status = 1
+      end
+    end
+
+    exit exit_status unless exit_status == 0
+    puts "✅ All files formatted successfully"
+  end
+
+  desc "Check if C source files are properly formatted"
+  task :c_check do
+    puts "Checking C file formatting..."
+
+    # Check if clang-format is installed
+    unless system("which clang-format > /dev/null 2>&1")
+      abort "Error: clang-format not found. Please install clang-format first."
+    end
+
+    if files.empty?
+      puts "No C files found to check"
+      next
+    end
+
+    puts "Found #{files.length} files to check (excluding generated files)"
+
+    needs_format = false
+    files.each do |file|
+      formatted = `clang-format -style=file #{file}`
+      original = File.read(file)
+
+      if formatted != original
+        puts "❌ #{file} needs formatting"
+        puts "Diff:"
+        # Save formatted version to temp file and run diff
+        temp_file = "#{file}.formatted"
+        File.write(temp_file, formatted)
+        system("diff -u #{file} #{temp_file}")
+        File.unlink(temp_file)
+        needs_format = true
+      end
+    end
+
+    if needs_format
+      warn "Some files need formatting. Run 'rake format:c' to format them."
+      exit 1
+    else
+      puts "✅ All files are properly formatted"
+    end
+  end
+end
+
+rule ".c" => ".re" do |t|
+  puts "⚠️⚠️⚠️ #{t.name} is older than #{t.source}. You may need to run `rake lexer` ⚠️⚠️⚠️"
+end
+
+rule %r{^src/(.*)\.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{^include/(.*)\.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"
+end
+
+task :confirm_annotation do
+  puts "Testing if RBS docs are updated with respect to RDoc"
+  sh "git diff --exit-code core stdlib"
+end
+
+task :templates do
+  sh "#{ruby} templates/template.rb ext/rbs_extension/ast_translation.h"
+  sh "#{ruby} templates/template.rb ext/rbs_extension/ast_translation.c"
+
+  sh "#{ruby} templates/template.rb ext/rbs_extension/class_constants.h"
+  sh "#{ruby} templates/template.rb ext/rbs_extension/class_constants.c"
+
+  sh "#{ruby} templates/template.rb include/rbs/ast.h"
+  sh "#{ruby} templates/template.rb src/ast.c"
+
+  sh "#{ruby} templates/template.rb include/rbs/serialize.h"
+  sh "#{ruby} templates/template.rb src/serialize.c"
+  sh "#{ruby} templates/template.rb lib/rbs/wasm/serialization_schema.rb"
+
+  # Format the generated files
+  Rake::Task["format:c"].invoke
+end
+
+task :compile => "ext/rbs_extension/class_constants.h"
+task :compile => "ext/rbs_extension/class_constants.c"
+task :compile => "src/lexer.c"
+
+task :test_doc do
+  files = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").select do |file| Pathname(file).extname == ".md" end
+  end
+
+  sh "#{ruby} #{__dir__}/bin/run_in_md.rb #{files.join(" ")}"
+end
+
+task :validate => :compile do
+  require 'yaml'
+
+  sh "#{ruby} #{rbs} validate"
+
+  libs = FileList["stdlib/*"].map {|path| File.basename(path).to_s }
+
+  # Skip RBS validation because Ruby CI runs without rubygems
+  case skip_rbs_validation = ENV["SKIP_RBS_VALIDATION"]
+  when nil
+    begin
+      Gem::Specification.find_by_name("rbs")
+      libs << "rbs"
+    rescue Gem::MissingSpecError
+      STDERR.puts "🚨🚨🚨🚨 Skipping `rbs` gem because it's not found"
+    end
+  when "true"
+    # Skip
+  else
+    STDERR.puts "🚨🚨🚨🚨 SKIP_RBS_VALIDATION is expected to be `true` or unset, given `#{skip_rbs_validation}` 🚨🚨🚨🚨"
+    libs << "rbs"
+  end
+
+  libs.delete("bigdecimal-math") or raise
+  libs.delete("bigdecimal") or raise
+
+  libs.each do |lib|
+    args = ["-r", lib]
+
+    if lib == "rbs"
+      args << "-r" << "prism"
+      args << "-r" << "logger"
+    end
+
+    sh "#{ruby} #{rbs} #{args.join(' ')} validate"
+  end
+end
+
+FileList["test/stdlib/**/*_test.rb"].each do |test|
+  task test => :compile do
+    sh "#{ruby} -Ilib #{bin}/test_runner.rb #{test}"
+  end
+end
+
+task :stdlib_test => :compile do
+  test_files = FileList["test/stdlib/**/*_test.rb"].reject do |path|
+    path =~ %r{Ractor} || path =~ %r{Encoding} || path =~ %r{CGI-escape_test}
+  end
+
+  if ENV["RANDOMIZE_STDLIB_TEST_ORDER"] == "true"
+    test_files.shuffle!
+  end
+
+  sh "#{ruby} -Ilib #{bin}/test_runner.rb #{test_files.join(' ')}"
+  # TODO: Ractor tests need to be run in a separate process
+  sh "#{ruby} -Ilib #{bin}/test_runner.rb test/stdlib/CGI-escape_test.rb"
+  sh "#{ruby} -Ilib #{bin}/test_runner.rb test/stdlib/Ractor_test.rb"
+  sh "#{ruby} -Ilib #{bin}/test_runner.rb test/stdlib/Encoding_test.rb"
+end
+
+task :typecheck_test => :compile do
+  FileList["test/typecheck/*"].each do |test|
+    Dir.chdir(test) do
+      expectations = File.join(test, "steep_expectations.yml")
+      if File.exist?(expectations)
+        sh "steep check --with_expectations"
+      else
+        sh "steep check"
+      end
+    end
+  end
+end
+
+task :raap => :compile do
+  sh "ruby test/raap/core.rb"
+  sh "ruby test/raap/digest.rb"
+  sh "ruby test/raap/openssl.rb"
+end
+
+task :rubocop do
+  format = if ENV["CI"]
+    "github"
+  else
+    "progress"
+  end
+
+  sh "rubocop --parallel --format #{format}"
+end
+
+namespace :generate do
+  desc "Generate a test file for a stdlib class signatures"
+  task :stdlib_test, [:class] do |_task, args|
+    klass = args.fetch(:class) do
+      raise "Class name is necessary. e.g. rake 'generate:stdlib_test[String]'"
+    end
+
+    require "erb"
+    require "rbs"
+
+    class TestTarget
+      def initialize(klass)
+        @type_name = RBS::Namespace.parse(klass).to_type_name
+      end
+
+      def path
+        Pathname(ENV['RBS_GENERATE_TEST_PATH'] || "test/stdlib/#{file_name}_test.rb")
+      end
+
+      def file_name
+        @type_name.to_s.gsub(/\A::/, '').gsub(/::/, '_')
+      end
+
+      def to_s
+        @type_name.to_s
+      end
+
+      def absolute_type_name
+        @absolute_type_name ||= @type_name.absolute!
+      end
+    end
+
+    target = TestTarget.new(klass)
+    path = target.path
+    raise "#{path} already exists!" if path.exist?
+
+    class TestTemplateBuilder
+      attr_reader :target, :env
+
+      def initialize(target)
+        @target = target
+
+        loader = RBS::EnvironmentLoader.new
+        Dir['stdlib/*'].each do |lib|
+          next if lib.end_with?('builtin')
+
+          loader.add(library: File.basename(lib))
+        end
+        @env = RBS::Environment.from_loader(loader).resolve_type_names
+      end
+
+      def call
+        ERB.new(<<~ERB, trim_mode: "-").result(binding)
+          require_relative "test_helper"
+
+          <%- unless class_methods.empty? -%>
+          class <%= target %>SingletonTest < Test::Unit::TestCase
+            include TestHelper
+
+            # library "logger", "securerandom"     # Declare library signatures to load
+            testing "singleton(::<%= target %>)"
+
+          <%- class_methods.each do |method_name, definition| -%>
+            def test_<%= test_name_for(method_name) %>
+          <%- definition.method_types.each do |method_type| -%>
+              assert_send_type "<%= method_type %>",
+                               <%= target %>, :<%= method_name %>
+          <%- end -%>
+            end
+
+          <%- end -%>
+          end
+          <%- end -%>
+
+          <%- unless instance_methods.empty? -%>
+          class <%= target %>Test < Test::Unit::TestCase
+            include TestHelper
+
+            # library "logger", "securerandom"     # Declare library signatures to load
+            testing "::<%= target %>"
+
+          <%- instance_methods.each do |method_name, definition| -%>
+            def test_<%= test_name_for(method_name) %>
+          <%- definition.method_types.each do |method_type| -%>
+              assert_send_type "<%= method_type %>",
+                               <%= target %>.new, :<%= method_name %>
+          <%- end -%>
+            end
+
+          <%- end -%>
+          end
+          <%- end -%>
+        ERB
+      end
+
+      private
+
+      def test_name_for(method_name)
+        {
+          :==  => 'double_equal',
+          :!=  => 'not_equal',
+          :=== => 'triple_equal',
+          :[]  => 'square_bracket',
+          :[]= => 'square_bracket_assign',
+          :>   => 'greater_than',
+          :<   => 'less_than',
+          :>=  => 'greater_than_equal_to',
+          :<=  => 'less_than_equal_to',
+          :<=> => 'spaceship',
+          :+   => 'plus',
+          :-   => 'minus',
+          :*   => 'multiply',
+          :/   => 'divide',
+          :**  => 'power',
+          :%   => 'modulus',
+          :&   => 'and',
+          :|   => 'or',
+          :^   => 'xor',
+          :>>  => 'right_shift',
+          :<<  => 'left_shift',
+          :=~  => 'pattern_match',
+          :!~  => 'does_not_match',
+          :~   => 'tilde'
+        }.fetch(method_name, method_name)
+      end
+
+      def class_methods
+        @class_methods ||= RBS::DefinitionBuilder.new(env: env).build_singleton(target.absolute_type_name).methods.select {|_, definition|
+          definition.implemented_in == target.absolute_type_name
+        }
+      end
+
+      def instance_methods
+        @instance_methods ||= RBS::DefinitionBuilder.new(env: env).build_instance(target.absolute_type_name).methods.select {|_, definition|
+          definition.implemented_in == target.absolute_type_name
+        }
+      end
+    end
+
+    path.write TestTemplateBuilder.new(target).call
+
+    puts "Created: #{path}"
+  end
+end
+
+task :test_generate_stdlib do
+  sh "RBS_GENERATE_TEST_PATH=/tmp/Array_test.rb rake 'generate:stdlib_test[Array]'"
+  sh "ruby -c /tmp/Array_test.rb"
+  sh "RBS_GENERATE_TEST_PATH=/tmp/Thread_Mutex_test.rb rake 'generate:stdlib_test[Thread::Mutex]'"
+  sh "ruby -c /tmp/Thread_Mutex_test.rb"
+end
+
+Rake::Task[:release].enhance do
+  Rake::Task[:"release:note"].invoke
+end
+
+namespace :release do
+  desc "Explain the post-release steps automatically"
+  task :note do
+    version = Gem::Version.new(RBS::VERSION)
+    major, minor, patch, *_ = RBS::VERSION.split(".")
+    major = major.to_i
+    minor = minor.to_i
+    patch = patch.to_i
+
+    puts "🎉🎉🎉🎉 Congratulations for **#{version}** release! 🎉🎉🎉🎉"
+    puts
+    puts "There are a few things left to complete the release. 💪"
+    puts
+
+    if patch == 0 || version.prerelease?
+      puts "* [ ] Update release note: https://github.com/ruby/rbs/wiki/Release-Note-#{major}.#{minor}"
+    end
+
+    if patch == 0 && !version.prerelease?
+      puts "* [ ] Delete `RBS XYZ is the latest version of...` from release note: https://github.com/ruby/rbs/wiki/Release-Note-#{major}.#{minor}"
+    end
+
+    puts "* [ ] Publish a release at GitHub"
+    puts "* [ ] Make some announcements on Twitter/Mustdon/Slack/???"
+
+    puts
+    puts
+
+    puts "✏️ Making a draft release on GitHub..."
+
+    content = File.read(File.join(__dir__, "CHANGELOG.md"))
+    changelog = content.scan(/^## \d.*?(?=^## \d)/m)[0]
+    changelog = changelog.sub(/^.*\n^.*\n/, "").rstrip
+
+    notes = <<NOTES
+[Release note](https://github.com/ruby/rbs/wiki/Release-Note-#{major}.#{minor})
+
+#{changelog}
+NOTES
+
+    command = [
+      "gh",
+      "release",
+      "create",
+      "--draft",
+      "v#{RBS::VERSION}",
+      "--title=#{RBS::VERSION}",
+      "--notes=#{notes}"
+    ]
+
+    if version.prerelease?
+      command << "--prerelease"
+    end
+
+    require "open3"
+    output, status = Open3.capture2(*command)
+    if status.success?
+      puts "  >> Done! Open #{output.chomp} and publish the release!"
+    end
+  end
+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
+
+  if patch == 0
+    milestone = "RBS #{major}.#{minor}"
+  else
+    milestone = "RBS #{major}.#{minor}.x"
+  end
+
+  puts "🔍 Finding pull requests that is associated to milestone `#{milestone}`..."
+
+  command = [
+    "gh",
+    "pr",
+    "list",
+    "--limit=10000",
+    "--json",
+    "url,title,number",
+    "--search" ,
+    "milestone:\"#{milestone}\" is:merged sort:updated-desc -label:Released"
+  ]
+
+  require "open3"
+  output, status = Open3.capture2(*command)
+  raise status.inspect unless status.success?
+
+  require "json"
+  json = JSON.parse(output, symbolize_names: true)
+
+  unless json.empty?
+    puts
+    json.each do |line|
+      puts "* #{line[:title]} ([##{line[:number]}](#{line[:url]}))"
+    end
+  else
+    puts "  (🤑 There is no *unreleased* pull request associated to the milestone.)"
+  end
+end
+
+desc "Compile extension without C23 extensions"
+task :compile_c99 do
+  ENV["TEST_NO_C23"] = "true"
+  Rake::Task[:"compile"].invoke
+ensure
+  ENV.delete("TEST_NO_C23")
+end
+
+task :prepare_bench do
+  ENV.delete("DEBUG")
+  Rake::Task[:"clobber"].invoke
+  Rake::Task[:"templates"].invoke
+  Rake::Task[:"compile"].invoke
+end
+
+task :prepare_profiling do
+  ENV["DEBUG"] = "1"
+  Rake::Task[:"clobber"].invoke
+  Rake::Task[:"templates"].invoke
+  Rake::Task[:"compile"].invoke
+end
+
+namespace :wasm do
+  WASM_DIR = File.expand_path("wasm", __dir__)
+  WASM_OUTPUT = File.join(WASM_DIR, "rbs_parser.wasm")
+
+  # The parser under src/ is plain, self-contained C with no dependency on the
+  # Ruby C API, so it can be compiled to WebAssembly as-is. The only extra
+  # translation unit is the entry-point shim under wasm/.
+  def wasm_source_files
+    Dir.glob(File.join(__dir__, "src/**/*.c")).sort + [File.join(WASM_DIR, "rbs_wasm.c")]
+  end
+
+  # Locate the clang shipped with the WASI SDK.
+  #
+  # The system clang can target wasm32, but the WASI SDK additionally provides
+  # the wasi-libc sysroot and the wasm32 compiler-rt builtins that the link
+  # step needs, so we require it explicitly.
+  def wasi_clang
+    sdk = ENV["WASI_SDK_PATH"]
+    if sdk.nil? || sdk.empty?
+      raise <<~MSG
+        WASI_SDK_PATH is not set.
+
+        Install the WASI SDK from https://github.com/WebAssembly/wasi-sdk/releases
+        and point WASI_SDK_PATH at the extracted directory, for example:
+
+            export WASI_SDK_PATH=/opt/wasi-sdk
+            rake wasm:build
+      MSG
+    end
+
+    clang = File.join(sdk, "bin", "clang")
+    raise "clang not found at #{clang} (is WASI_SDK_PATH correct?)" unless File.executable?(clang)
+
+    clang
+  end
+
+  desc "Build the RBS parser as a WebAssembly module (requires WASI_SDK_PATH)"
+  task :build do
+    mkdir_p WASM_DIR
+    sh wasi_clang,
+       "--target=wasm32-wasip1",
+       # No `main`; the host calls `_initialize` and then the exported functions.
+       "-mexec-model=reactor",
+       "-std=gnu11",
+       "-O2",
+       "-Wno-unused-parameter",
+       "-I#{File.join(__dir__, "include")}",
+       "-o", WASM_OUTPUT,
+       *wasm_source_files
+    puts "Built #{WASM_OUTPUT}"
+  end
+
+  desc "Build and smoke-test the WebAssembly module (requires wasmtime)"
+  task :check => :build do
+    wasmtime = ENV["WASMTIME"] || "wasmtime"
+
+    # `rbs_wasm_selftest` parses a small fixed signature and returns 1 on
+    # success. `--invoke` prints the return value to stdout.
+    output = IO.popen([wasmtime, "run", "--invoke", "rbs_wasm_selftest", WASM_OUTPUT], err: File::NULL, &:read).to_s.strip
+
+    if output == "1"
+      puts "WebAssembly selftest passed."
+    else
+      raise "WebAssembly selftest failed: rbs_wasm_selftest returned #{output.inspect} (expected \"1\")"
+    end
+  end
+
+  # Where the runtime looks for the module and jars by default (see
+  # RBS::WASM::Runtime). These are build artifacts, bundled into the JRuby gem.
+  JRUBY_WASM_DIR = File.expand_path("lib/rbs/wasm", __dir__)
+  CHICORY_VERSION = ENV.fetch("CHICORY_VERSION", "1.7.5")
+  # `compiler` is Chicory's AOT compiler (wasm -> JVM bytecode); the asm* jars
+  # are the ow2 ASM libraries it depends on. Keep ASM_VERSION in sync with what
+  # the pinned Chicory release declares.
+  CHICORY_JARS = %w[wasm runtime log wasi compiler].freeze
+  ASM_VERSION = ENV.fetch("ASM_VERSION", "9.9.1")
+  ASM_JARS = %w[asm asm-tree asm-util asm-commons asm-analysis].freeze
+
+  desc "Download the Chicory and ASM jars the JRuby runtime needs into lib/rbs/wasm/jars"
+  task :vendor_jars do
+    require "open-uri"
+    require "fileutils"
+
+    jars_dir = File.join(JRUBY_WASM_DIR, "jars")
+    FileUtils.mkdir_p(jars_dir)
+
+    downloads = CHICORY_JARS.map { |name| ["#{name}.jar", "https://repo1.maven.org/maven2/com/dylibso/chicory/#{name}/#{CHICORY_VERSION}/#{name}-#{CHICORY_VERSION}.jar"] }
+    downloads += ASM_JARS.map { |name| ["#{name}.jar", "https://repo1.maven.org/maven2/org/ow2/asm/#{name}/#{ASM_VERSION}/#{name}-#{ASM_VERSION}.jar"] }
+
+    downloads.each do |filename, url|
+      puts "Downloading #{url}"
+      URI.open(url) { |io| File.binwrite(File.join(jars_dir, filename), io.read) } # steep:ignore
+    end
+
+    puts "Vendored Chicory #{CHICORY_VERSION} + ASM #{ASM_VERSION} into #{jars_dir}"
+  end
+
+  desc "Assemble everything the JRuby gem needs: the .wasm and the Chicory jars"
+  task :jruby_setup => [:build, :vendor_jars] do
+    cp WASM_OUTPUT, File.join(JRUBY_WASM_DIR, "rbs_parser.wasm")
+    puts "JRuby runtime is ready under #{JRUBY_WASM_DIR}"
+  end
+end
+
+namespace :rust do
+  namespace :rbs do
+    RUST_DIR = File.expand_path("rust", __dir__)
+    RBS_VERSION_FILE = File.join(RUST_DIR, "rbs_version")
+
+    VENDOR_TARGETS = {
+      "ruby-rbs-sys" => %w[include src],
+      "ruby-rbs" => %w[config.yml],
+    }
+
+    desc "Sync vendored RBS source from the pinned version"
+    task :sync do
+      unless File.exist?(RBS_VERSION_FILE)
+        raise "#{RBS_VERSION_FILE} not found. Run `rake rust:rbs:pin[VERSION]` first."
+      end
+
+      version = File.read(RBS_VERSION_FILE).strip
+      raise "#{RBS_VERSION_FILE} is empty" if version.empty?
+
+      puts "Syncing vendor/rbs/ from #{version}..."
+
+      VENDOR_TARGETS.each do |crate, entries|
+        vendor_dir = File.join(RUST_DIR, crate, "vendor", "rbs")
+
+        puts "  Copying files for #{crate}:"
+        chmod_R "u+w", vendor_dir, verbose: false if File.exist?(vendor_dir)
+        rm_rf vendor_dir, verbose: false
+        mkdir_p vendor_dir, verbose: false
+
+        entries.each do |entry|
+          target = File.join(vendor_dir, entry)
+
+          # Extract the entry from the pinned git tag using git archive
+          IO.popen(["git", "archive", "--format=tar", version, "--", entry], "rb") do |tar|
+            IO.popen(["tar", "xf", "-", "-C", vendor_dir], "wb") do |extract|
+              IO.copy_stream(tar, extract)
+            end
+          end
+
+          raise "Failed to extract #{entry} from #{version}" unless File.exist?(target)
+          puts "    #{entry}"
+        end
+
+        # Make files read-only to prevent accidental edits
+        chmod_R "a-w", vendor_dir, verbose: false
+      end
+
+      puts "📦 Synced vendor/rbs/ from #{version} (read-only)"
+    end
+
+    desc "Pin a specific RBS version for Rust crates (e.g., rake rust:rbs:pin[v4.0.3])"
+    task :pin, [:version] do |_t, args|
+      version = args[:version] or raise "Usage: rake rust:rbs:pin[VERSION]"
+
+      # Verify the tag exists
+      unless system("git", "rev-parse", "--verify", "#{version}^{commit}", out: File::NULL, err: File::NULL)
+        raise "Tag #{version} not found"
+      end
+
+      File.write(RBS_VERSION_FILE, "#{version}\n")
+      puts "📌 Pinned RBS version to #{version}"
+
+      Rake::Task["rust:rbs:sync"].invoke
+    end
+
+    desc "Create symlinks from vendor/rbs/ to the repository root (for development/CI)"
+    task :symlink do
+      VENDOR_TARGETS.each do |crate, entries|
+        vendor_dir = File.join(RUST_DIR, crate, "vendor", "rbs")
+
+        puts "Setting up symlinks for #{crate}..."
+        entries.each do |entry|
+          puts "  #{entry} -> repository root"
+        end
+
+        chmod_R "u+w", vendor_dir, verbose: false if File.exist?(vendor_dir)
+        rm_rf vendor_dir, verbose: false
+        mkdir_p vendor_dir, verbose: false
+
+        entries.each do |entry|
+          ln_s File.join("..", "..", "..", "..", entry), File.join(vendor_dir, entry), verbose: false
+        end
+      end
+
+      puts "🔗 Symlinked vendor/rbs/ to repository root"
+    end
+  end
+
+  namespace :publish do
+    def self.prepare_publish_branch(crate_name)
+      dry_run = ENV["RBS_RUST_PUBLISH_DRY_RUN"]
+
+      version_file = File.join(RUST_DIR, "rbs_version")
+
+      unless File.exist?(version_file)
+        raise "#{version_file} not found. Run `rake rust:rbs:pin[VERSION]` first."
+      end
+
+      rbs_version = File.read(version_file).strip
+      raise "#{version_file} is empty" if rbs_version.empty?
+
+      crate_version = File.read(File.join(RUST_DIR, crate_name, "Cargo.toml"))[/^version\s*=\s*"(.+)"/, 1]
+      release_branch = "rust/release-#{crate_name}-#{Time.now.strftime('%Y%m%d%H%M%S')}"
+
+      puts "=" * 60
+      puts "Rust crate publish: #{crate_name}#{dry_run ? " (DRY RUN)" : ""}"
+      puts "=" * 60
+      puts "  RBS source version:  #{rbs_version}"
+      puts "  #{crate_name}:        #{crate_version} (tag: #{crate_name}-v#{crate_version})"
+      puts "  Release branch:      #{release_branch}"
+      puts "=" * 60
+
+      # Check that vendor dirs contain real files, not symlinks
+      entries = VENDOR_TARGETS.fetch(crate_name)
+      entries.each do |entry|
+        path = File.join(RUST_DIR, crate_name, "vendor", "rbs", entry)
+        if File.symlink?(path)
+          raise "#{path} is a symlink. Run `rake rust:rbs:sync` first."
+        end
+        unless File.exist?(path)
+          raise "#{path} does not exist. Run `rake rust:rbs:sync` first."
+        end
+      end
+
+      # Ensure working tree is clean before publishing
+      unless `git status --porcelain`.strip.empty?
+        raise "💢 Working tree is dirty. Please commit or stash your changes before publishing."
+      end
+
+      # Create a release branch with vendor files committed
+      original_branch = `git rev-parse --abbrev-ref HEAD`.strip
+
+      sh "git", "checkout", "-b", release_branch, verbose: false
+      vendor_path = File.join("rust", crate_name, "vendor", "rbs")
+      sh "git", "add", "-f", vendor_path, verbose: false
+      sh "git", "commit", "-m", "Publish #{crate_name} (RBS #{rbs_version})", verbose: false
+
+      [dry_run, crate_version, original_branch]
+    end
+
+    desc "Publish ruby-rbs-sys crate to crates.io (set RBS_RUST_PUBLISH_DRY_RUN=1 for dry-run only)"
+    task :"ruby-rbs-sys" do
+      crate_name = "ruby-rbs-sys"
+      dry_run, crate_version, original_branch = prepare_publish_branch(crate_name)
+
+      begin
+        puts "🔰 Dry-run publishing..."
+
+        Dir.chdir(File.join(RUST_DIR, crate_name)) do
+          sh "cargo", "publish", "--dry-run"
+        end
+
+        puts "✅ Dry-run succeeded!"
+
+        unless dry_run
+          puts "💪 Publishing #{crate_name} for real..."
+
+          Dir.chdir(File.join(RUST_DIR, crate_name)) do
+            sh "cargo", "publish"
+          end
+
+          sh "git", "tag", "#{crate_name}-v#{crate_version}"
+          sh "git", "push", "origin", "#{crate_name}-v#{crate_version}"
+
+          puts "🎉 Published #{crate_name} successfully!"
+        end
+      ensure
+        sh "git", "checkout", original_branch, verbose: false
+      end
+    end
+
+    desc "Publish ruby-rbs crate to crates.io (set RBS_RUST_PUBLISH_DRY_RUN=1 for dry-run only)"
+    task :"ruby-rbs" do
+      crate_name = "ruby-rbs"
+      dry_run, crate_version, original_branch = prepare_publish_branch(crate_name)
+
+      begin
+        puts "🔰 Dry-run publishing..."
+
+        Dir.chdir(File.join(RUST_DIR, crate_name)) do
+          sh "cargo", "publish", "--dry-run", "--no-verify"
+        end
+
+        puts "✅ Dry-run succeeded!"
+
+        unless dry_run
+          puts "💪 Publishing #{crate_name} for real..."
+
+          Dir.chdir(File.join(RUST_DIR, crate_name)) do
+            sh "cargo", "publish"
+          end
+
+          sh "git", "tag", "#{crate_name}-v#{crate_version}"
+          sh "git", "push", "origin", "#{crate_name}-v#{crate_version}"
+
+          puts "🎉 Published #{crate_name} successfully!"
+        end
+      ensure
+        sh "git", "checkout", original_branch, verbose: false
+      end
+    end
+  end
+end