Reset Bootsnap RBS cache on lockfile changes

Stores the current `Gemfile.lock` digest in Tapioca's dedicated Bootsnap cache and resets the Bootsnap payload when the digest changes.

Skips stale read-only caches so consumers do not use rewritten iseqs built for a different lockfile.

Author: KaanOzkan

README.md

@@ -857,7 +857,16 @@ The rewriting is automatic on every `tapioca` invocation: [`require-hooks`](http
 $ TAPIOCA_RBS_CACHE=1 bin/tapioca dsl
 ```
 
-Tapioca configures Bootsnap's iseq cache against a dedicated directory (`tmp/cache/bootsnap-tapioca-rbs` by default; override with `TAPIOCA_BOOTSNAP_CACHE_DIR`). The first run is slower because every file is rewritten and the result is baked into the iseq cache; subsequent runs against the same directory skip the rewrite entirely.
+Tapioca configures Bootsnap's iseq cache against a dedicated directory (`tmp/cache/bootsnap-tapioca-rbs` by
+default; override with `TAPIOCA_BOOTSNAP_CACHE_DIR`).
+
+Tapioca writes the current `Gemfile.lock` digest to `.gemfile-lock-digest` inside that cache directory. When the
+lockfile changes, Tapioca sees the digest mismatch and resets Bootsnap's cache payload before configuring Bootsnap.
+This lets gem bumps that affect rewriting, such as `tapioca`, start from a fresh cache without accumulating old cache
+directories.
+
+The first run is slower because every file is rewritten and the result is baked into the iseq cache; subsequent runs
+against the same lockfile skip the rewrite entirely.
 
 `Bootsnap.setup` mutates a process-wide singleton, and a second call would overwrite Tapioca's dedicated cache directory and start writing rewritten iseqs into the host's normal cache. Tapioca enforces this under `TAPIOCA_RBS_CACHE=1`: after its own setup runs, any subsequent `Bootsnap.setup` raises a clear error pointing at the fix. Gate your host's `Bootsnap.setup` on the same env var. Rails apps do this in `config/boot.rb`:
 

lib/tapioca/rbs/bootsnap_cache.rb

@@ -0,0 +1,64 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "bundler"
+require "digest"
+require "fileutils"
+
+module Tapioca
+  module RBS
+    # Prepares the Bootsnap iseq cache used for RBS rewrite output.
+    #
+    # RBS rewrite output can change when the lockfile changes, even if the
+    # source files are unchanged.
+    # To account for this, we store the current Gemfile.lock SHA256 in a
+    # `.gemfile-lock-digest` file.
+    # On writable runs, a digest mismatch deletes Bootsnap's cache payload and
+    # records the new digest, so this run rebuilds the cache from scratch. On
+    # read-only runs, a digest mismatch means the cache is stale and must not be
+    # used.
+    module BootsnapCache
+      PrepareResult = Struct.new(:setup_bootsnap, keyword_init: true)
+
+      DIGEST_FILE = ".gemfile-lock-digest" #: String
+
+      class << self
+        #: (String, readonly: bool) -> PrepareResult
+        def prepare_for_setup(cache_dir, readonly:)
+          digest = gemfile_lock_digest
+
+          if readonly
+            return PrepareResult.new(setup_bootsnap: digest_matches?(cache_dir, digest))
+          end
+
+          unless digest_matches?(cache_dir, digest)
+            FileUtils.rm_rf(File.join(cache_dir, "bootsnap"))
+            FileUtils.rm_f(digest_path(cache_dir))
+            FileUtils.mkdir_p(cache_dir)
+            File.write(digest_path(cache_dir), digest)
+          end
+
+          PrepareResult.new(setup_bootsnap: true)
+        end
+
+        private
+
+        #: -> String
+        def gemfile_lock_digest
+          Digest::SHA256.file(Bundler.default_lockfile).hexdigest
+        end
+
+        #: (String, String) -> bool
+        def digest_matches?(cache_dir, digest)
+          path = digest_path(cache_dir)
+          File.file?(path) && File.read(path).chomp == digest
+        end
+
+        #: (String) -> String
+        def digest_path(cache_dir)
+          File.join(cache_dir, DIGEST_FILE)
+        end
+      end
+    end
+  end
+end

lib/tapioca/rbs/rewriter.rb

@@ -1,6 +1,8 @@
 # typed: strict
 # frozen_string_literal: true
 
+require "tapioca/rbs/bootsnap_cache"
+
 # This code rewrites RBS comments back into Sorbet's signatures as the files are being loaded.
 # This will allow `sorbet-runtime` to wrap the methods as if they were originally written with the `sig{}` blocks.
 # This will in turn allow Tapioca to use this signatures to generate typed RBI files.
@@ -19,42 +21,62 @@ module BootsnapGuard
       def setup(**_kwargs)
         Kernel.raise HostBootsnapSetupError, <<~MSG
           Bootsnap.setup was called while TAPIOCA_RBS_CACHE=1 is set. Tapioca already
-          configured bootsnap with a dedicated cache directory; re-running setup
-          would overwrite that config and start writing rewritten iseqs into your
-          host's cache.
+          configured bootsnap for RBS rewriting; re-running setup would overwrite
+          that config and start writing rewritten iseqs into your host's cache.
 
           Gate your host's Bootsnap.setup on the env var, e.g. in config/boot.rb:
 
             require "bootsnap/setup" unless ENV["TAPIOCA_RBS_CACHE"] == "1"
         MSG
       end
     end
+
+    module BootsnapSetup
+      class << self
+        extend T::Sig
+
+        sig { void }
+        def setup
+          require "bootsnap"
+
+          # Respect BOOTSNAP_READONLY for consumers reading a pre-populated cache
+          # (e.g. a CI prime step).
+          readonly = !["0", "false", false].include?(ENV.fetch("BOOTSNAP_READONLY") { false })
+          cache_dir = ENV.fetch("TAPIOCA_BOOTSNAP_CACHE_DIR", File.join(Dir.pwd, "tmp/cache/bootsnap-tapioca-rbs"))
+          # A read-only cache with a mismatched lockfile digest may contain stale rewritten iseqs,
+          # and this process cannot reset it.
+          return unless Tapioca::RBS::BootsnapCache.prepare_for_setup(
+            cache_dir,
+            readonly: readonly,
+          ).setup_bootsnap
+
+          Bootsnap.setup(
+            cache_dir: cache_dir,
+            development_mode: true,
+            load_path_cache: true,
+            compile_cache_iseq: true,
+            compile_cache_yaml: true,
+            readonly: readonly,
+            revalidation: true,
+          )
+          Bootsnap.log_stats!
+        ensure
+          Bootsnap.singleton_class.prepend(Tapioca::RBS::BootsnapGuard) if defined?(Bootsnap)
+        end
+      end
+    end
   end
 end
 
-# When TAPIOCA_RBS_CACHE=1, set up bootsnap with a dedicated cache directory
-# and load require-hooks so the RBS-rewritten iseqs get cached. Subsequent
-# runs read the rewritten iseq directly and skip the rewrite.
+# When TAPIOCA_RBS_CACHE=1, use a dedicated Bootsnap cache directory for
+# RBS-rewritten iseqs. Stale read-only caches are skipped because this process
+# cannot reset them.
 #
-# After our setup, BootsnapGuard is prepended so the host application can't
-# replace our cache directory.
+# BootsnapGuard is prepended so the host application can't replace our cache
+# configuration.
 if ENV["TAPIOCA_RBS_CACHE"] == "1"
   begin
-    require "bootsnap"
-    # Respect BOOTSNAP_READONLY for consumers reading a pre-populated cache
-    # (e.g. a CI prime step).
-    readonly = !["0", "false", false].include?(ENV.fetch("BOOTSNAP_READONLY") { false })
-    Bootsnap.setup(
-      cache_dir: ENV.fetch("TAPIOCA_BOOTSNAP_CACHE_DIR", File.join(Dir.pwd, "tmp/cache/bootsnap-tapioca-rbs")),
-      development_mode: true,
-      load_path_cache: true,
-      compile_cache_iseq: true,
-      compile_cache_yaml: true,
-      readonly: readonly,
-      revalidation: true,
-    )
-    Bootsnap.log_stats!
-    Bootsnap.singleton_class.prepend(Tapioca::RBS::BootsnapGuard)
+    Tapioca::RBS::BootsnapSetup.setup
   rescue LoadError
     # Bootsnap is not in the bundle, skip iseq caching.
   end

spec/tapioca/cli/dsl_spec.rb

@@ -680,6 +680,63 @@ class Post
           assert_success_status(result)
         end
 
+        it "resets the bootsnap cache when Gemfile.lock changes" do
+          @project.write!("lib/post.rb", <<~RB)
+            require "smart_properties"
+
+            class Post
+              include SmartProperties
+              property :title, accepts: String
+            end
+          RB
+
+          env = {
+            "TAPIOCA_RBS_CACHE" => "1",
+            "TAPIOCA_BOOTSNAP_CACHE_DIR" => "tmp/cache/test-bootsnap-tapioca-rbs",
+          }
+
+          result = @project.tapioca("dsl --only-bootsnap-rbs-cache Post", env: env)
+
+          assert_success_status(result)
+          @project.write!("tmp/cache/test-bootsnap-tapioca-rbs/bootsnap/stale-cache-entry", "stale")
+
+          @project.write!("Gemfile.lock", "#{@gemfile_lock}\n")
+          result = @project.tapioca("dsl --only-bootsnap-rbs-cache Post", env: env)
+
+          assert_success_status(result)
+          refute_project_file_exist("tmp/cache/test-bootsnap-tapioca-rbs/bootsnap/stale-cache-entry")
+          assert_project_file_exist("tmp/cache/test-bootsnap-tapioca-rbs/.gemfile-lock-digest")
+        end
+
+        it "skips a stale read-only bootsnap cache when Gemfile.lock changes" do
+          @project.write!("lib/post.rb", <<~RB)
+            require "smart_properties"
+
+            class Post
+              include SmartProperties
+              property :title, accepts: String
+            end
+          RB
+
+          env = {
+            "TAPIOCA_RBS_CACHE" => "1",
+            "TAPIOCA_BOOTSNAP_CACHE_DIR" => "tmp/cache/test-readonly-bootsnap-tapioca-rbs",
+          }
+
+          result = @project.tapioca("dsl --only-bootsnap-rbs-cache Post", env: env)
+
+          assert_success_status(result)
+          original_digest = @project.read("tmp/cache/test-readonly-bootsnap-tapioca-rbs/.gemfile-lock-digest")
+          @project.write!("Gemfile.lock", "#{@gemfile_lock}\n")
+
+          result = @project.tapioca("dsl Post", env: env.merge("BOOTSNAP_READONLY" => "1"))
+
+          assert_success_status(result)
+          assert_empty_stderr(result)
+          assert_project_file_exist("sorbet/rbi/dsl/post.rbi")
+          assert_project_file_equal("tmp/cache/test-readonly-bootsnap-tapioca-rbs/.gemfile-lock-digest", original_digest)
+        end
+
         it "warns when --only-bootsnap-rbs-cache is set without TAPIOCA_RBS_CACHE=1" do
           @project.write!("lib/post.rb", <<~RB)
             require "smart_properties"