require-hooks 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9357c7e14301ad7ab541c2e2fabbda1f03df56e748aee55245dfc44ef98519f4
-  data.tar.gz: 87b05cf3ec16a3c9c4e9c1a46a3ec267ca03717923fe8abdccd4e46deb212791
+  metadata.gz: 9e75b55ac6829e71745efc569fd472288bfc17f85b569413c947f145c8f3a866
+  data.tar.gz: 72a6083f17c215f429b7f1ae14b637c38c613cd2f7dffe2a8ead2ce8be2de956
 SHA512:
-  metadata.gz: a9e828449e13517a11c03d9521c4170507f08862e6a4e75fa01360a2c17191dbecfa3a745a1433bd7546f190c1599f17be7a4dc76869bbd798fd1e47e859a130
-  data.tar.gz: e1e80635ac8c7ceb90c1580797145c3c15636d463635f3ccf57578024619af150f4dbe94eb279aff7dc62c231ed1de3733b5db3e7a1b38a21002e8ef0ca8a063
+  metadata.gz: ccb59bc078a1bd1b748b721427240fb136ccc269148472b4963d5db052f7696b2ba8356bb3a14228561ca4f6e3e830962f182a834d6ae0dd036d0c73faac22d8
+  data.tar.gz: 47cd3bc2f622f9062361099e64dd179166f2d72f02e8d1366fa548b14fd62265f1a35b4db046755b84feafc34dab3bbcaa9eb28430600da3ccb09edf2a9db5bb

data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 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.

data/README.md

@@ -126,6 +126,14 @@ The _around load_ hooks are executed for all files independently of whether they
 
 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
 
 - Coverage tracking is only supported in Ruby 4.0.4+ (or 3.4.10+ for 3.4.x series); for older versions in 3.4 and 4.0 series, you can enable `eval` coverage tracking to make it work with Require Hooks (`Coverage.start(eval: true, ...)` or `SimpleCov.enable_coverage :eval`). For Ruby 3.2.x and 3.3.x, only around hooks are supported.

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

@@ -41,11 +41,12 @@ module RequireHooks
     # Bootsnap 1.24+ compiler wrapper. Its namespace isolates transformed ISeqs
     # without changing Bootsnap's process-wide cache directory.
     class VersionedCompiler
-      attr_reader :namespace
+      attr_reader :namespace, :version_hash
 
-      def initialize(compiler)
+      def initialize(compiler, version_hash)
         @compiler = compiler
-        @namespace = "#{compiler.namespace}-require-hooks-#{RequireHooks::Bootsnap.version_hash}"
+        @version_hash = version_hash
+        @namespace = "#{compiler.namespace}-require-hooks-#{version_hash}"
       end
 
       def input_to_storage(source, path, *args)
@@ -120,11 +121,37 @@ module RequireHooks
         compiler = @original_compiler_selector&.call(path) || iseq.default_compiler
         return compiler if RequireHooks.context_for(path).empty?
 
-        @compilers[compiler] ||= VersionedCompiler.new(compiler)
+        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_hash ||= 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
 
       def version_hash=(version_hash)

data/lib/require-hooks/version.rb

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

metadata

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