require-hooks 0.4.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5179f6010729ac30b40c0040f2d00956164c8f765d41e2d095eeefa9b96da842
-  data.tar.gz: f836cd71ec64084e4145ac572a555b7a32b7abdacd7d7d25965766bca2d264bc
+  metadata.gz: 9e75b55ac6829e71745efc569fd472288bfc17f85b569413c947f145c8f3a866
+  data.tar.gz: 72a6083f17c215f429b7f1ae14b637c38c613cd2f7dffe2a8ead2ce8be2de956
 SHA512:
-  metadata.gz: 93559e1cc1b84d23e17b60abb8f92e47c67ea6f66f1dcbc4243b34f3d68345674c96da73aa890ba8c79e226209877a48aa4438343a51ba3ce736160403597abb
-  data.tar.gz: 4c36e011286728aee0f43a81411875c38fee956e34105c4dcba87bc4cf52aaee6a2d4e97d332bd2727551c85bc009ddba646b3a9764ca19c3521b7687bf43a1c
+  metadata.gz: ccb59bc078a1bd1b748b721427240fb136ccc269148472b4963d5db052f7696b2ba8356bb3a14228561ca4f6e3e830962f182a834d6ae0dd036d0c73faac22d8
+  data.tar.gz: 47cd3bc2f622f9062361099e64dd179166f2d72f02e8d1366fa548b14fd62265f1a35b4db046755b84feafc34dab3bbcaa9eb28430600da3ccb09edf2a9db5bb

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## master
 
+## 0.5.1 (2026-08-26)
+
+- Add `RequireHooks::Bootsnap.add_version_hash` for external cache inputs.
+
+## 0.5.0 (2026-08-26)
+
+- Use Bootsnap compiler namespaces for cache invalidation without changing Bootsnap's cache directory.
+
 ## 0.4.1 (2026-07-22)
 
 - Bring back Ruby 2.3 compatibility.

data/README.md

@@ -124,7 +124,15 @@ require "require-hooks/setup"
 
 The _around load_ hooks are executed for all files independently of whether they are cached or not. Source transformation and hijacking is only done for non-cached files.
 
-Thus, if you introduce new source transformers or hijackers, you must invalidate the cache. (We plan to implement automatic invalidation in future versions.)
+Require Hooks separates cached instructions by hook configuration. New source transformers and hijackers invalidate affected cache entries automatically.
+
+If a transform depends on an external library or configuration, add that input to the cache key:
+
+```ruby
+RequireHooks::Bootsnap.add_version_hash { "parser-#{Parser::VERSION}-#{options_digest}" }
+```
+
+The value can be a String or a callable that returns a String. Require Hooks hashes each contribution and combines all contributions with its hook key. The callable runs when Require Hooks computes the key, so it does not freeze the key before later hooks register.
 
 ## Limitations
 

data/lib/require-hooks/mode/bootsnap.rb

@@ -28,75 +28,136 @@ module RequireHooks
       end
     end
 
-    # For new Bootsnap
-    module CompilerExt
-      def input_to_storage(source, path, *)
+    # Bootsnap before 1.24 does not support compiler namespaces.
+    module LegacyCacheExt
+      def fetch(path, cache_dir: self.cache_dir)
         ctx = RequireHooks.context_for(path)
-        return super if ctx.empty?
+        cache_dir = File.join(cache_dir, RequireHooks::Bootsnap.version_hash) unless ctx.empty?
+
+        super
+      end
+    end
+
+    # Bootsnap 1.24+ compiler wrapper. Its namespace isolates transformed ISeqs
+    # without changing Bootsnap's process-wide cache directory.
+    class VersionedCompiler
+      attr_reader :namespace, :version_hash
 
+      def initialize(compiler, version_hash)
+        @compiler = compiler
+        @version_hash = version_hash
+        @namespace = "#{compiler.namespace}-require-hooks-#{version_hash}"
+      end
+
+      def input_to_storage(source, path, *args)
+        iseq = compile(RequireHooks.context_for(path), path, nil)
+        return @compiler.input_to_storage(source, path, *args) unless iseq
+
+        iseq.to_binary
+      rescue SyntaxError, TypeError
+        ::Bootsnap::CompileCache::UNCOMPILABLE
+      end
+
+      def storage_to_output(*args)
+        @compiler.storage_to_output(*args)
+      end
+
+      def input_to_output(source, path, args)
+        compile(RequireHooks.context_for(path), path, args) || @compiler.input_to_output(source, path, args)
+      end
+
+      private
+
+      def compile(ctx, path, args)
         new_contents = ctx.perform_source_transform(path)
         hijacked = ctx.try_hijack_load(path, new_contents)
 
         if hijacked
-          raise TypeError, "Unsupported bytecode format for #{path}: #{hijack.class}" unless hijacked.is_a?(::RubyVM::InstructionSequence)
-          return hijacked.to_binary
-        elsif new_contents
-          return RubyVM::InstructionSequence.compile(new_contents, path, path, 1, @compile_options).to_binary
+          raise TypeError, "Unsupported bytecode format for #{path}: #{hijacked.class}" unless hijacked.is_a?(::RubyVM::InstructionSequence)
+          return hijacked
         end
 
-        super
-      rescue SyntaxError, TypeError
-        ::Bootsnap::CompileCache::UNCOMPILABLE
+        return unless new_contents
+
+        @compiler.input_to_output(new_contents, path, args) ||
+          RubyVM::InstructionSequence.compile(new_contents, path, path, 1)
       end
     end
 
     module LoadIseqExt
-      class << self
-        attr_accessor :orig_cache_dir
-      end
-
       # Around hooks must be performed every time we trigger a file load, even if
       # the file is already cached.
       def load_iseq(path)
         ctx = RequireHooks.context_for(path)
-        # Early-return for non-trackable paths
-        if ctx.empty?
-          ::Bootsnap::CompileCache::ISeq.cache_dir = LoadIseqExt.orig_cache_dir if LoadIseqExt.orig_cache_dir
-          return super
-        end
-
-        LoadIseqExt.orig_cache_dir ||= ::Bootsnap::CompileCache::ISeq.cache_dir
-        ::Bootsnap::CompileCache::ISeq.cache_dir = File.join(LoadIseqExt.orig_cache_dir, RequireHooks::Bootsnap.version_hash)
+        return super if ctx.empty?
 
         ctx.run_around_load_callbacks(path) do
-          begin
-            iseq = super
+          iseq = super
 
-            ::Bootsnap::CompileCache::ISeq.cache_dir = LoadIseqExt.orig_cache_dir
+          # Bootsnap returns nil when the coverage is on,
+          # we fallback to our custom #compile_with_coverage
+          unless iseq
+            next unless defined?(Coverage) && Coverage.running?
 
-            # Bootsnap returns nil when the coverage is on,
-            # we fallback to our custom #compile_with_coverage
-            unless iseq
-              next unless defined?(Coverage) && Coverage.running?
-
-              iseq = RequireHooks::Iseq.compile_with_coverage(ctx, path)
-            end
-
-            iseq.eval
-            EMPTY_ISEQ
-          ensure
-            ::Bootsnap::CompileCache::ISeq.cache_dir = LoadIseqExt.orig_cache_dir
+            iseq = RequireHooks::Iseq.compile_with_coverage(ctx, path)
           end
+
+          iseq.eval
+          EMPTY_ISEQ
         end
       end
     end
 
     class << self
+      def install_compiler_selector
+        iseq = ::Bootsnap::CompileCache::ISeq
+        @original_compiler_selector = iseq.compiler_selector
+        @compilers = {}.compare_by_identity
+        iseq.compiler_selector = method(:compiler_for)
+      end
+
+      def compiler_for(path)
+        iseq = ::Bootsnap::CompileCache::ISeq
+        compiler = @original_compiler_selector&.call(path) || iseq.default_compiler
+        return compiler if RequireHooks.context_for(path).empty?
+
+        version_hash = RequireHooks::Bootsnap.version_hash
+        cached = @compilers[compiler]
+        return cached if cached&.version_hash == version_hash
+
+        @compilers[compiler] = VersionedCompiler.new(compiler, version_hash)
+      end
+
+      def add_version_hash(value = nil, &block)
+        contributor = block || value
+        unless contributor.is_a?(String) || contributor.respond_to?(:call)
+          raise ArgumentError, "version hash contribution must be a String or callable"
+        end
+
+        @version_hash_contributors ||= []
+        @version_hash_contributors << (contributor.is_a?(String) ? contributor.dup.freeze : contributor)
+        @compilers&.clear
+        contributor
+      end
+
       def version_hash
-        @version_key ||= RequireHooks.contexts.values.map(&:to_cache_key).join("-")
+        return @version_hash unless @version_hash.nil?
+
+        context_keys = RequireHooks.contexts.values.map(&:to_cache_key)
+        contribution_keys = Array(@version_hash_contributors).map do |contributor|
+          value = contributor.respond_to?(:call) ? contributor.call : contributor
+          raise TypeError, "version hash contribution must return a String" unless value.is_a?(String)
+
+          Zlib.crc32(value).to_s
+        end.sort
+
+        (context_keys + contribution_keys).join("-")
       end
 
-      attr_writer :version_hash
+      def version_hash=(version_hash)
+        @version_hash = version_hash
+        @compilers&.clear
+      end
     end
   end
 
@@ -111,6 +172,10 @@ module RequireHooks
   end
 end
 
-Bootsnap::CompileCache::ISeq.singleton_class.prepend(RequireHooks::Bootsnap::CompileCacheExt)
-Bootsnap::CompileCache::ISeq::Compiler.prepend(RequireHooks::Bootsnap::CompilerExt) if defined?(Bootsnap::CompileCache::ISeq::Compiler)
+if defined?(Bootsnap::CompileCache::ISeq::Compiler)
+  RequireHooks::Bootsnap.install_compiler_selector
+else
+  Bootsnap::CompileCache::ISeq.singleton_class.prepend(RequireHooks::Bootsnap::CompileCacheExt)
+  Bootsnap::CompileCache::ISeq.singleton_class.prepend(RequireHooks::Bootsnap::LegacyCacheExt)
+end
 RubyVM::InstructionSequence.singleton_class.prepend(RequireHooks::Bootsnap::LoadIseqExt)

data/lib/require-hooks/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RequireHooks
-  VERSION = "0.4.1"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: require-hooks
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.1
 platform: ruby
 authors:
 - Vladimir Dementyev