require-hooks 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36e7f23cef600d120d9139555f3e3ef4b8bd46b9929387b99dce99280108615c
-  data.tar.gz: c89a896109b87d81d2e1a7690398bc337b6723c2ae006c5a2a0f0c7a8e01c52a
+  metadata.gz: 046c644cbb446d1abd3263c3c1ee0c578cddac17693d102172e123f1a880966a
+  data.tar.gz: a102736a0665a9de69c9aba242033a479af9b090bf135fa729e74b9bd8f6e006
 SHA512:
-  metadata.gz: 4af96e3f1d117b10e7cedc4cb564e47768ac5eb44e8f83e666e90b9f98178fd827a19641caa0f2dd3e674736ec7aa0982e11d184fa780e46fc89a0c399098f00
-  data.tar.gz: c0c60d8e40d22743aa24c671b88989c6aef61c58d39cdefe39e26c73905fc08286d0fb68d09e409e0762e8ccbfe5334926d7c35321f2442bf4158e5e8dda0d1e
+  metadata.gz: 35e088739e021cc4e83827122ce2daa63934439f6e4d0c9597ccafdaf6f6a08b50eba9302cfed1ced10538a62b317406ded4da1882b06f4d04b527a5e4902b47
+  data.tar.gz: 801d491df8a08926067f47b44ee2372d73a53fada8cdfe36b62c0d66191f52f6900499121fc87a326125f00e443848734e5f7756df541d7e92f688ae293e5026

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## master
 
+## 0.4.0 (2026-04-29)
+
+- Improved Bootsnap cache invalidation logic on hooks configuration changes.
+
+- Latest Bootsnap compatibility
+
+- Coverage compatibility (w/ some limitations)
+
 ## 0.3.0 (2026-04-22)
 
 - Fix the order of around hooks execution (after part) when using `#load_iseq` driven hooks.

data/README.md

@@ -9,6 +9,8 @@ Require Hooks is a library providing universal interface for injecting custom co
 
 Require hooks allows you to interfere with `Kernel#require` (incl. `Kernel#require_relative`) and `Kernel#load`.
 
+> Check the ["Require Hooks: Filling the Gap in Ruby's Extensibility"](https://evilmartians.com/events/require-hooks-rubykaigi) talk from RubyKaigi 2026 to learn more.
+
 <a href="https://evilmartians.com/">
 <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
 
@@ -126,6 +128,7 @@ Thus, if you introduce new source transformers or hijackers, you must invalidate
 
 ## Limitations
 
+- Coverage tracking is only supported if `eval` coverage tracking is enabled (`Coverage.start(eval: true, ...)` or `Simplecov.start { enable_coverage_for_eval; ... }`). Currently requires **Ruby 3.4+**.
 - `Kernel#load` with a wrap argument (e.g., `load "some_path", true` or `load "some_path", MyModule)`) is not supported (fallbacked to the original implementation). The biggest challenge here is to support constants nesting.
 - Some very edgy symlinking scenarios are not supported (unlikely to affect real-world projects).
 
@@ -175,9 +178,9 @@ Test script: `time bundle exec rails runner 'puts "done"'`.
 | rhooks (patch)                      |    **8m**    |
 | rhooks (bootsnap)                   |    12s       |
 
-You can see that requiring tons of files with Require Hooks in patch mode is very slow for now. Why? Mostly because we MUST check `$LOADED_FEATURES` for the presence of the file we want to load and currently we do this via `$LOADED_FEATURES.include?(path)` call, which becomes very slow when `$LOADED_FEATURES` is huge. Thus, we recommend activating Require Hooks after loading all the dependencies and limiting the scope of affected files (via the `patterns` option) on non-MRI platforms to avoid this overhead.
+You can see that requiring tons of files with Require Hooks in patch mode is very slow for now. Why? Manipulating the `$LOADED_FEATURES` index from Ruby triggers costly invalidation at the VM side when a regular `#require` occurs. We recommend activating Require Hooks after loading all the dependencies and limiting the scope of affected files (via the `patterns` option) on non-MRI platforms to avoid this overhead.
 
-**NOTE:** Why Ruby's internal implementations is fast despite from doing the same checks? It uses an internal hash table to keep track of the loaded features (`vm->loaded_features_realpaths`), not an array. Unfortunately, it's not accessible from Ruby.
+**NOTE:** This could be improved in the future if we get [optimized API](https://github.com/palkan/ruby/pull/1) for managing `$LOADED_FEATURES` from Ruby code.
 
 Here are the numbers for the same project with scoped hooks (only some folders) activated after `Bundler.require(*)`:
 

data/lib/require-hooks/api.rb

@@ -14,6 +14,7 @@ module RequireHooks
       @hijack_load = []
 
       @empty = nil
+      @readonly = nil
     end
 
     def to_key
@@ -31,6 +32,12 @@ module RequireHooks
       @empty = @around_load.empty? && @source_transform.empty? && @hijack_load.empty?
     end
 
+    def readonly?
+      return @readonly unless @readonly.nil?
+
+      @readonly = @source_transform.empty? && @hijack_load.empty?
+    end
+
     def source_transform?
       @source_transform.any?
     end
@@ -70,6 +77,12 @@ module RequireHooks
       end
       nil
     end
+
+    def merge!(another_ctx)
+      around_load.concat(another_ctx.around_load)
+      source_transform.concat(another_ctx.source_transform)
+      hijack_load.concat(another_ctx.hijack_load)
+    end
   end
 
   @@default_context = Context.new
@@ -88,13 +101,7 @@ module RequireHooks
     #      block.call.tap { puts "Loaded #{path}" }
     #    end
     def around_load(patterns: nil, exclude_patterns: nil, &block)
-      @@default_context = nil
-      ctx = Context.new(patterns: patterns, exclude_patterns: exclude_patterns)
-
-      @@contexts[ctx.to_key] ||= ctx
-      @@contexts[ctx.to_key].around_load << block
-
-      @@default_context = @@contexts.values.first if @@contexts.size == 1
+      register_hook(:around_load, block, patterns: patterns, exclude_patterns: exclude_patterns)
     end
 
     # Define hooks to perform source-to-source transformations.
@@ -108,13 +115,7 @@ module RequireHooks
     #      "# frozen_string_literal: true\n#{source}"
     #    end
     def source_transform(patterns: nil, exclude_patterns: nil, &block)
-      @@default_context = nil
-      ctx = Context.new(patterns: patterns, exclude_patterns: exclude_patterns)
-
-      @@contexts[ctx.to_key] ||= ctx
-      @@contexts[ctx.to_key].source_transform << block
-
-      @@default_context = @@contexts.values.first if @@contexts.size == 1
+      register_hook(:source_transform, block, patterns: patterns, exclude_patterns: exclude_patterns)
     end
 
     # This hook should be used to manually compile byte code to be loaded by the VM.
@@ -132,21 +133,15 @@ module RequireHooks
     #     end
     #   end
     def hijack_load(patterns: nil, exclude_patterns: nil, &block)
-      @@default_context = nil
-      ctx = Context.new(patterns: patterns, exclude_patterns: exclude_patterns)
-
-      @@contexts[ctx.to_key] ||= ctx
-      @@contexts[ctx.to_key].hijack_load << block
-
-      @@default_context = @@contexts.values.first if @@contexts.size == 1
+      register_hook(:hijack_load, block, patterns: patterns, exclude_patterns: exclude_patterns)
     end
 
     def context_for(path)
-      # Fast-track in case we have just a single context defined
+      # Fast-track in case we have just a single non-global context defined
       if @@default_context
-        return @@noop_context unless @@default_context.match?(path)
+        return @@default_context if @@default_context.match?(path)
 
-        return @@default_context
+        return @@noop_context
       end
 
       matching = @@contexts.values.select { |ctx| ctx.match?(path) }
@@ -154,13 +149,44 @@ module RequireHooks
       return matching[0] || @@noop_context if matching.size < 2
 
       ctx = Context.new
-      matching.each do |mctx|
-        ctx.around_load.concat(mctx.around_load)
-        ctx.source_transform.concat(mctx.source_transform)
-        ctx.hijack_load.concat(mctx.hijack_load)
-      end
+      matching.each { |mctx| ctx.merge!(mctx) }
 
       ctx
     end
+
+    # Hack to enable coverage for hooked files.
+    # Requires eval coverage to be on.
+    # See https://bugs.ruby-lang.org/issues/22018 (https://github.com/ruby/ruby/pull/16805)
+    def setup_path_coverage(path, contents = nil)
+      return unless defined?(Coverage) && Coverage.running?
+
+      return unless eval_coverage_enabled?
+
+      Kernel.eval("\n" * (contents || File.read(path)).lines.size, TOPLEVEL_BINDING, path, 1) # rubocop:disable Style/EvalWithLocation,Security/Eval
+    end
+
+    def contexts
+      @@contexts
+    end
+
+    private
+
+    def register_hook(type, block, patterns: nil, exclude_patterns: nil)
+      @@default_context = nil
+      ctx = Context.new(patterns: patterns, exclude_patterns: exclude_patterns)
+
+      @@contexts[ctx.to_key] ||= ctx
+      @@contexts[ctx.to_key].public_send(type) << block
+
+      @@default_context = @@contexts.values.first if @@contexts.size == 1
+    end
+
+    def eval_coverage_enabled?
+      return @eval_coverage_enabled if defined?(@eval_coverage_enabled)
+      probe_path = File.join(__dir__, "coverage_probe.rb")
+      Kernel.eval("proc { |val| val }", TOPLEVEL_BINDING, probe_path, 1) # rubocop:disable Style/EvalWithLocation
+
+      @eval_coverage_enabled = Coverage.peek_result.key?(probe_path)
+    end
   end
 end

data/lib/require-hooks/iseq.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RequireHooks
+  module Iseq
+    class << self
+      def compile_with_coverage(ctx, path)
+        iseq =
+          if ctx.source_transform? || ctx.hijack?
+            new_contents = ctx.perform_source_transform(path)
+
+            RequireHooks.setup_path_coverage(path, new_contents)
+
+            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)
+              hijacked
+            elsif new_contents
+              RubyVM::InstructionSequence.compile(new_contents, path, path, 1)
+            end
+          end
+
+        RequireHooks.setup_path_coverage(path, new_contents)
+
+        iseq ||= yield if block_given?
+
+        iseq ||= RubyVM::InstructionSequence.compile_file(path)
+
+        iseq
+      end
+    end
+  end
+end

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

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+require "require-hooks/iseq"
+
 module RequireHooks
   module Bootsnap
     EMPTY_ISEQ = RubyVM::InstructionSequence.compile("").freeze
 
+    # For older Bootsnap
     module CompileCacheExt
       def input_to_storage(source, path, *)
         ctx = RequireHooks.context_for(path)
@@ -25,25 +28,87 @@ module RequireHooks
       end
     end
 
+    # For new Bootsnap
+    module CompilerExt
+      def input_to_storage(source, path, *)
+        ctx = RequireHooks.context_for(path)
+        return super if ctx.empty?
+
+        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
+        end
+
+        super
+      rescue SyntaxError, TypeError
+        ::Bootsnap::CompileCache::UNCOMPILABLE
+      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
-        return super if ctx.empty?
+        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)
 
         ctx.run_around_load_callbacks(path) do
           iseq = super
-          return unless iseq
+
+          ::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?
+
+            iseq = RequireHooks::Iseq.compile_with_coverage(ctx, path)
+          end
 
           iseq.eval
           EMPTY_ISEQ
+        ensure
+          ::Bootsnap::CompileCache::ISeq.cache_dir = LoadIseqExt.orig_cache_dir
         end
       end
     end
+
+    class << self
+      def version_hash
+        @version_key ||= RequireHooks.contexts.values.map(&:to_cache_key).join("-")
+      end
+
+      attr_writer :version_hash
+    end
+  end
+
+  class Context
+    def to_cache_key
+      Zlib.crc32(
+        (around_load + source_transform + hijack_load).map do |pr|
+          RubyVM::InstructionSequence.disasm(pr)
+        end.join("\n")
+      ).to_s
+    end
   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)
 RubyVM::InstructionSequence.singleton_class.prepend(RequireHooks::Bootsnap::LoadIseqExt)

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

@@ -14,7 +14,9 @@ module RequireHooks
           new_contents = ctx.perform_source_transform(path)
           hijacked = ctx.try_hijack_load(path, new_contents)
 
-          return try_evaluate(path, hijacked) if hijacked
+          if hijacked
+            return try_evaluate(path, hijacked)
+          end
 
           if new_contents
             evaluate(new_contents, path)
@@ -29,6 +31,7 @@ module RequireHooks
 
       def try_evaluate(path, bytecode)
         if defined?(::RubyVM::InstructionSequence) && bytecode.is_a?(::RubyVM::InstructionSequence)
+          RequireHooks.setup_path_coverage(path)
           bytecode.eval
         else
           raise TypeError, "Unknown bytecode format for #{path}: #{bytecode.inspect}"
@@ -49,6 +52,8 @@ module RequireHooks
         end
       else
         def evaluate(code, filepath)
+          RequireHooks.setup_path_coverage(filepath, code)
+
           # This is workaround to solve the "leaking refinements" problem in MRI
           RubyVM::InstructionSequence.compile(code, filepath).tap do |iseq|
             iseq.eval
@@ -226,22 +231,24 @@ module Kernel
 
     return false if $LOADED_FEATURES.include?(realpath)
 
-    RequireHooks::KernelPatch::Features::LOCK.lock_feature(feature) do |loaded|
-      return false if loaded
+    begin
+      RequireHooks::KernelPatch::Features::LOCK.lock_feature(feature) do |loaded|
+        return false if loaded
 
-      $LOADED_FEATURES << realpath
-      RequireHooks::KernelPatch.load(realpath, ctx: ctx)
-      true
+        $LOADED_FEATURES << realpath
+        RequireHooks::KernelPatch.load(realpath, ctx: ctx)
+        true
+      end
+    rescue LoadError => e
+      $LOADED_FEATURES.delete(realpath) if realpath
+      warn "RequireHooks failed to require '#{path}' from '#{realpath}': #{e.message}" if RequireHooks.print_warnings
+      require_without_require_hooks(path)
+    rescue Errno::ENOENT, Errno::EACCES
+      raise LoadError, "cannot load such file -- #{path}"
+    rescue
+      $LOADED_FEATURES.delete(realpath) if realpath
+      raise
     end
-  rescue LoadError => e
-    $LOADED_FEATURES.delete(realpath) if realpath
-    warn "RequireHooks failed to require '#{path}': #{e.message}" if RequireHooks.print_warnings
-    require_without_require_hooks(path)
-  rescue Errno::ENOENT, Errno::EACCES
-    raise LoadError, "cannot load such file -- #{path}"
-  rescue
-    $LOADED_FEATURES.delete(realpath) if realpath
-    raise
   end
 
   alias_method :require_relative_without_require_hooks, :require_relative

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "require-hooks/iseq"
+
 module RequireHooks
   EMPTY_ISEQ = RubyVM::InstructionSequence.compile("").freeze
 
@@ -11,20 +13,8 @@ module RequireHooks
       return if ctx.empty?
 
       ctx.run_around_load_callbacks(path) do
-        iseq =
-          if ctx.source_transform? || ctx.hijack?
-            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)
-              hijacked
-            elsif new_contents
-              RubyVM::InstructionSequence.compile(new_contents, path, path, 1)
-            end
-          end
-
-        iseq ||= (defined?(super) ? super : RubyVM::InstructionSequence.compile_file(path))
+        iseq = RequireHooks::Iseq.compile_with_coverage(ctx, path) { defined?(super) && super }
+
         iseq.eval
         EMPTY_ISEQ
       end

data/lib/require-hooks/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: require-hooks
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Vladimir Dementyev
@@ -22,6 +22,7 @@ files:
 - README.md
 - lib/require-hooks.rb
 - lib/require-hooks/api.rb
+- lib/require-hooks/iseq.rb
 - lib/require-hooks/mode/bootsnap.rb
 - lib/require-hooks/mode/kernel_patch.rb
 - lib/require-hooks/mode/load_iseq.rb