require-hooks 0.2.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17073754a96afb51c85cb5848e11b6348969d05107027081a4b3242552ffc3a8
-  data.tar.gz: 89167c71710dc23e4d39176246f55d1996f0f4d51b92b2778624d13939bac72d
+  metadata.gz: 046c644cbb446d1abd3263c3c1ee0c578cddac17693d102172e123f1a880966a
+  data.tar.gz: a102736a0665a9de69c9aba242033a479af9b090bf135fa729e74b9bd8f6e006
 SHA512:
-  metadata.gz: e99100a54066cff2c1bea42a727bdd828def92516037927625ec02f874d306e26533f76112a57beceb8cd7abc5c4bd5b2c435572d5fccb6de3627b6d588f8731
-  data.tar.gz: b3da21f9a2fff2e8796d093fcbcb67fa7e35c226ab45389a49c9749c0fa1f7b9faebbe3461f937afbbf0efd188068c0251722b7664c79b6f5ba251fa996a86ad
+  metadata.gz: 35e088739e021cc4e83827122ce2daa63934439f6e4d0c9597ccafdaf6f6a08b50eba9302cfed1ced10538a62b317406ded4da1882b06f4d04b527a5e4902b47
+  data.tar.gz: 801d491df8a08926067f47b44ee2372d73a53fada8cdfe36b62c0d66191f52f6900499121fc87a326125f00e443848734e5f7756df541d7e92f688ae293e5026

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## 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.
+
+- Improve `Kernel#require` patch performance.
+
+- Reduce context object creation and use a single object when only one context defined.
+
 ## 0.2.3 (2026-01-13)
 
 - Gem metadata fixes.

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

@@ -1,19 +1,41 @@
 # frozen_string_literal: true
 
 module RequireHooks
-  @@around_load = []
-  @@source_transform = []
-  @@hijack_load = []
-
   class Context
-    def initialize(around_load, source_transform, hijack_load)
-      @around_load = around_load
-      @source_transform = source_transform
-      @hijack_load = hijack_load
+    attr_reader :around_load, :source_transform, :hijack_load,
+      :patterns, :exclude_patterns
+
+    def initialize(patterns: nil, exclude_patterns: nil)
+      @patterns = patterns.freeze
+      @exclude_patterns = exclude_patterns.freeze
+
+      @around_load = []
+      @source_transform = []
+      @hijack_load = []
+
+      @empty = nil
+      @readonly = nil
+    end
+
+    def to_key
+      [patterns, exclude_patterns]
+    end
+
+    def match?(path)
+      return false unless !patterns || patterns.any? { |pattern| File.fnmatch?(pattern, path) }
+      return false if exclude_patterns&.any? { |pattern| File.fnmatch?(pattern, path) }
+      true
     end
 
     def empty?
-      @around_load.empty? && @source_transform.empty? && @hijack_load.empty?
+      return @empty unless @empty.nil?
+      @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?
@@ -55,8 +77,18 @@ 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
+  @@noop_context = Context.new
+  @@contexts = {}
+
   class << self
     attr_accessor :print_warnings
 
@@ -69,7 +101,7 @@ module RequireHooks
     #      block.call.tap { puts "Loaded #{path}" }
     #    end
     def around_load(patterns: nil, exclude_patterns: nil, &block)
-      @@around_load << [patterns, exclude_patterns, block]
+      register_hook(:around_load, block, patterns: patterns, exclude_patterns: exclude_patterns)
     end
 
     # Define hooks to perform source-to-source transformations.
@@ -83,7 +115,7 @@ module RequireHooks
     #      "# frozen_string_literal: true\n#{source}"
     #    end
     def source_transform(patterns: nil, exclude_patterns: nil, &block)
-      @@source_transform << [patterns, exclude_patterns, block]
+      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.
@@ -101,32 +133,60 @@ module RequireHooks
     #     end
     #   end
     def hijack_load(patterns: nil, exclude_patterns: nil, &block)
-      @@hijack_load << [patterns, exclude_patterns, block]
+      register_hook(:hijack_load, block, patterns: patterns, exclude_patterns: exclude_patterns)
     end
 
     def context_for(path)
-      around_load = @@around_load.select do |patterns, exclude_patterns, _block|
-        next unless !patterns || patterns.any? { |pattern| File.fnmatch?(pattern, path) }
-        next if exclude_patterns&.any? { |pattern| File.fnmatch?(pattern, path) }
+      # Fast-track in case we have just a single non-global context defined
+      if @@default_context
+        return @@default_context if @@default_context.match?(path)
 
-        true
-      end.map { |_patterns, _exclude_patterns, block| block }
+        return @@noop_context
+      end
+
+      matching = @@contexts.values.select { |ctx| ctx.match?(path) }
+
+      return matching[0] || @@noop_context if matching.size < 2
+
+      ctx = Context.new
+      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?
 
-      source_transform = @@source_transform.select do |patterns, exclude_patterns, _block|
-        next unless !patterns || patterns.any? { |pattern| File.fnmatch?(pattern, path) }
-        next if exclude_patterns&.any? { |pattern| File.fnmatch?(pattern, path) }
+      return unless eval_coverage_enabled?
 
-        true
-      end.map { |_patterns, _exclude_patterns, block| block }
+      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
 
-      hijack_load = @@hijack_load.select do |patterns, exclude_patterns, _block|
-        next unless !patterns || patterns.any? { |pattern| File.fnmatch?(pattern, path) }
-        next if exclude_patterns&.any? { |pattern| File.fnmatch?(pattern, path) }
+    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
 
-        true
-      end.map { |_patterns, _exclude_patterns, block| block }
+    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
 
-      Context.new(around_load, source_transform, hijack_load)
+      @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,10 +1,16 @@
 # 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)
+        return super if ctx.empty?
 
         new_contents = ctx.perform_source_transform(path)
         hijacked = ctx.try_hijack_load(path, new_contents)
@@ -22,15 +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)
-        RequireHooks.context_for(path).run_around_load_callbacks(path) { super }
+        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)
+
+        ctx.run_around_load_callbacks(path) do
+          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?
+
+            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

@@ -5,8 +5,8 @@ require "pathname"
 module RequireHooks
   module KernelPatch
     class << self
-      def load(path)
-        ctx = RequireHooks.context_for(path)
+      def load(path, ctx: nil)
+        ctx ||= RequireHooks.context_for(path)
 
         ctx.run_around_load_callbacks(path) do
           next load_without_require_hooks(path) unless ctx.source_transform? || ctx.hijack?
@@ -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
@@ -140,32 +145,6 @@ module RequireHooks
           path
         end
 
-        # Based on https://github.com/ruby/ruby/blob/b588fd552390c55809719100d803c36bc7430f2f/load.c#L403-L415
-        def feature_loaded?(feature)
-          return true if $LOADED_FEATURES.include?(feature) && !LOCK.locked_feature?(feature)
-
-          feature = Pathname.new(feature).cleanpath.to_s
-          efeature = File.expand_path(feature)
-
-          # Check absoulute and relative paths
-          return true if $LOADED_FEATURES.include?(efeature) && !LOCK.locked_feature?(efeature)
-
-          candidates = []
-
-          $LOADED_FEATURES.each do |lf|
-            candidates << lf if lf.end_with?("/#{feature}")
-          end
-
-          return false if candidates.empty?
-
-          $LOAD_PATH.each do |lp|
-            lp_feature = File.join(lp, feature)
-            return true if candidates.include?(lp_feature) && !LOCK.locked_feature?(lp_feature)
-          end
-
-          false
-        end
-
         private
 
         def lookup_feature_path(path, implitic_ext: true)
@@ -250,24 +229,26 @@ module Kernel
 
     return require_without_require_hooks(path) if ctx.empty?
 
-    return false if RequireHooks::KernelPatch::Features.feature_loaded?(feature)
+    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)
-      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,24 +1,22 @@
 # frozen_string_literal: true
 
+require "require-hooks/iseq"
+
 module RequireHooks
+  EMPTY_ISEQ = RubyVM::InstructionSequence.compile("").freeze
+
   module LoadIseq
     def load_iseq(path)
       ctx = RequireHooks.context_for(path)
 
+      # Early-return for non-trackable paths
+      return if ctx.empty?
+
       ctx.run_around_load_callbacks(path) do
-        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)
-            return hijacked
-          elsif new_contents
-            return RubyVM::InstructionSequence.compile(new_contents, path, path, 1)
-          end
-        end
-
-        defined?(super) ? super : RubyVM::InstructionSequence.compile_file(path)
+        iseq = RequireHooks::Iseq.compile_with_coverage(ctx, path) { defined?(super) && super }
+
+        iseq.eval
+        EMPTY_ISEQ
       end
     end
   end

data/lib/require-hooks/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: require-hooks
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  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
@@ -37,6 +38,7 @@ metadata:
   homepage_uri: https://github.com/ruby-next/require-hooks
   source_code_uri: https://github.com/ruby-next/require-hooks
   funding_uri: https://github.com/sponsors/palkan
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib