zeitwerk 2.6.17 → 2.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51e7aed4aef39ce0a2caaea2f23852ea4f2e8fcb7b65819d14a4d92e7aec70d0
-  data.tar.gz: 7e310bac85d85018cb840339a42958b9fbc6fac566fee51e6a5c599a3cb132e3
+  metadata.gz: aba46812169c8e26085b099c708093b00a29bfd39e8d8210d29bc99e7df0e7fa
+  data.tar.gz: 0fc20386009d52d21a0cb79a64c5d800f7aecfce5a38e8430a10dc5d04c2609d
 SHA512:
-  metadata.gz: 0274e4685362f6585b9fb90291561926c8b45434ea3df71858ed99c5dfbffd54e814ed6dfcc4c6e8bfd8a9f266dbe4261bf6010856558474ad7e85045851e4cd
-  data.tar.gz: 210f457fad164472582fc67264bed2bd981612588bd3a8cdce265b2f2c67b12d10d9d2b9abb555dead008df20d5a73955072e703305e8f55b9d4dd5877d9b693
+  metadata.gz: 3edac5ad6f940caa70c4cac093bf271b8399b078d7124f450513c963ec5099e9b9082841ceb9893b81f1edf8e34dc642ec811403415fb230211670c63a950766
+  data.tar.gz: 47339a8b35dc06108fde9aadd62e83b1ea4e4ef22854c31849069f09ece1115dce07d63ec354fe96fbc599bba411ecff48db6a8b0c8b150ad7ee016787e9d75c

data/README.md

@@ -54,7 +54,6 @@
     - [Use case: The adapter pattern](#use-case-the-adapter-pattern)
     - [Use case: Test files mixed with implementation files](#use-case-test-files-mixed-with-implementation-files)
   - [Shadowed files](#shadowed-files)
-  - [Edge cases](#edge-cases)
   - [Beware of circular dependencies](#beware-of-circular-dependencies)
   - [Reopening third-party namespaces](#reopening-third-party-namespaces)
   - [Introspection](#introspection)
@@ -63,7 +62,6 @@
     - [`Zeitwerk::Loader#all_expected_cpaths`](#zeitwerkloaderall_expected_cpaths)
   - [Encodings](#encodings)
   - [Rules of thumb](#rules-of-thumb)
-  - [Debuggers](#debuggers)
 - [Pronunciation](#pronunciation)
 - [Supported Ruby versions](#supported-ruby-versions)
 - [Testing](#testing)
@@ -283,6 +281,8 @@ class Hotel < ApplicationRecord
 end
 ```
 
+When autoloaded, Zeitwerk verifies the expected constant (`Hotel` in the example) stores a class or module object. If it doesn't, `Zeitwerk::Error` is raised.
+
 An explicit namespace must be managed by one single loader. Loaders that reopen namespaces owned by other projects are responsible for loading their constants before setup.
 
 <a id="markdown-collapsing-directories" name="collapsing-directories"></a>
@@ -1178,36 +1178,6 @@ file #{file} is ignored because #{constant_path} is already defined
 
 Shadowing only applies to Ruby files, namespace definition can be spread over multiple directories. And you can also reopen third-party namespaces if done [orderly](#reopening-third-party-namespaces).
 
-<a id="markdown-edge-cases" name="edge-cases"></a>
-### Edge cases
-
-[Explicit namespaces](#explicit-namespaces) like `Trip` here:
-
-```ruby
-# trip.rb
-class Trip
-  include Geolocation
-end
-
-# trip/geolocation.rb
-module Trip::Geolocation
-  ...
-end
-```
-
-have to be defined with the `class`/`module` keywords, as in the example above.
-
-For technical reasons, raw constant assignment is not supported:
-
-```ruby
-# trip.rb
-Trip = Class { ...}        # NOT SUPPORTED
-Trip = Struct.new { ... }  # NOT SUPPORTED
-Trip = Data.define { ... } # NOT SUPPORTED
-```
-
-This only affects explicit namespaces, those idioms work well for any other ordinary class or module.
-
 <a id="markdown-beware-of-circular-dependencies" name="beware-of-circular-dependencies"></a>
 ### Beware of circular dependencies
 
@@ -1406,15 +1376,6 @@ The test suite passes on Windows with codepage `Windows-1252` if all the involve
 
 6. In a given process, ideally, there should be at most one loader with reloading enabled. Technically, you can have more, but it may get tricky if one refers to constants managed by the other one. Do that only if you know what you are doing.
 
-<a id="markdown-debuggers" name="debuggers"></a>
-### Debuggers
-
-Zeitwerk and [debug.rb](https://github.com/ruby/debug) are fully compatible if CRuby is ≥ 3.1 (see [ruby/debug#558](https://github.com/ruby/debug/pull/558)).
-
-[Byebug](https://github.com/deivid-rodriguez/byebug) is compatible except for an edge case explained in [deivid-rodriguez/byebug#564](https://github.com/deivid-rodriguez/byebug/issues/564). Prior to CRuby 3.1, `debug.rb` has a similar edge incompatibility.
-
-[Break](https://github.com/gsamokovarov/break) is fully compatible.
-
 <a id="markdown-pronunciation" name="pronunciation"></a>
 ## Pronunciation
 
@@ -1423,9 +1384,12 @@ Zeitwerk and [debug.rb](https://github.com/ruby/debug) are fully compatible if C
 <a id="markdown-supported-ruby-versions" name="supported-ruby-versions"></a>
 ## Supported Ruby versions
 
-Zeitwerk works with CRuby 2.5 and above.
+Starting with version 2.7, Zeitwerk requires Ruby 3.2 or newer.
 
-On TruffleRuby all is good except for thread-safety. Right now, in TruffleRuby `Module#autoload` does not block threads accessing a constant that is being autoloaded. CRuby prevents such access to avoid concurrent threads from seeing partial evaluations of the corresponding file. Zeitwerk inherits autoloading thread-safety from this property. This is not an issue if your project gets eager loaded, or if you lazy load in single-threaded environments. (See https://github.com/oracle/truffleruby/issues/2431.)
+Zeitwerk 2.7 requires TruffleRuby 24.1.2+ due to https://github.com/oracle/truffleruby/issues/3683.
+Alternatively, TruffleRuby users can use a `< 2.7` version constraint for the `zeitwerk` gem.
+As of this writing, [autoloading is not fully thread-safe yet on TruffleRuby](https://github.com/oracle/truffleruby/issues/2431).
+If your program is multi-threaded, you need to eager load before threads are created.
 
 JRuby 9.3.0.0 is almost there. As of this writing, the test suite of Zeitwerk passes on JRuby except for three tests. (See https://github.com/jruby/jruby/issues/6781.)
 

data/lib/zeitwerk/core_ext/module.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Zeitwerk::ConstAdded
+  def const_added(cname)
+    if loader = Zeitwerk::ExplicitNamespace.__loader_for(self, cname)
+      namespace = const_get(cname, false)
+
+      unless namespace.is_a?(Module)
+        cref = Zeitwerk::Cref.new(self, cname)
+        raise Zeitwerk::Error, "#{cref.path} is expected to be a namespace, should be a class or module (got #{namespace.class})"
+      end
+
+      loader.on_namespace_loaded(namespace)
+    end
+    super
+  end
+
+  Module.prepend(self)
+end

data/lib/zeitwerk/cref.rb

@@ -13,6 +13,9 @@
 class Zeitwerk::Cref
   include Zeitwerk::RealModName
 
+  # @sig Module
+  attr_reader :mod
+
   # @sig Symbol
   attr_reader :cname
 
@@ -26,48 +29,14 @@ class Zeitwerk::Cref
     @path  = nil
   end
 
-  if Symbol.method_defined?(:name)
-    # Symbol#name was introduced in Ruby 3.0. It returns always the same
-    # frozen object, so we may save a few string allocations.
-    #
-    # @sig () -> String
-    def path
-      @path ||= Object.equal?(@mod) ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}"
-    end
-  else
-    # @sig () -> String
-    def path
-      @path ||= Object.equal?(@mod) ? @cname.to_s : "#{real_mod_name(@mod)}::#{@cname}"
-    end
+  # @sig () -> String
+  def path
+    @path ||= Object.equal?(@mod) ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}".freeze
   end
 
-  # The autoload? predicate takes into account the ancestor chain of the
-  # receiver, like const_defined? and other methods in the constants API do.
-  #
-  # For example, given
-  #
-  #   class A
-  #     autoload :X, "x.rb"
-  #   end
-  #
-  #   class B < A
-  #   end
-  #
-  # B.autoload?(:X) returns "x.rb".
-  #
-  # We need a way to retrieve it ignoring ancestors.
-  #
   # @sig () -> String?
-  if method(:autoload?).arity == 1
-    # @sig () -> String?
-    def autoload?
-      @mod.autoload?(@cname) if self.defined?
-    end
-  else
-    # @sig () -> String?
-    def autoload?
-      @mod.autoload?(@cname, false)
-    end
+  def autoload?
+    @mod.autoload?(@cname, false)
   end
 
   # @sig (String) -> bool

data/lib/zeitwerk/explicit_namespace.rb

@@ -1,93 +1,113 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  # Centralizes the logic for the trace point used to detect the creation of
-  # explicit namespaces, needed to descend into matching subdirectories right
-  # after the constant has been defined.
+  # This module is essentially a registry for explicit namespaces.
+  #
+  # When a loader determines that a certain file should define an explicit
+  # namespace, it registers it here, associating its cref with itself.
+  #
+  # If the namespace is autoloaded, our const_added callback retrieves its
+  # loader by calling loader_for. That way, the loader is able to scan the
+  # subdirectories that conform the namespace and set autoloads for their
+  # expected constants just in time.
+  #
+  # Once autoloaded, the namespace is unregistered.
   #
   # The implementation assumes an explicit namespace is managed by one loader.
   # Loaders that reopen namespaces owned by other projects are responsible for
   # loading their constant before setup. This is documented.
   module ExplicitNamespace # :nodoc: all
+    # Maps cnames or cpaths of explicit namespaces with their corresponding
+    # loader. They are symbols for top-level ones, and strings for nested ones:
+    #
+    #   {
+    #     :Admin => #<Zeitwerk::Loader:...>,
+    #     "Hotel::Pricing" => #<Zeitwerk::Loader:...>
+    #   }
+    #
+    # There are two types of keys to make loader_for as fast as possible, since
+    # it is invoked by our const_added for all autoloads and constant actually
+    # added. Globally. With this trick, for top-level constants we do not need
+    # to call Symbol#name and perform a string lookup. Instead, we can directly
+    # perform a fast symbol lookup.
+    #
+    # Entries are added as the namespaces are found, and removed as they are
+    # autoloaded.
+    #
+    # @sig Hash[(Symbol | String) => Zeitwerk::Loader]
+    @loaders = {}
+
     class << self
       include RealModName
       extend Internal
 
-      # Maps constant paths that correspond to explicit namespaces according to
-      # the file system, to the loader responsible for them.
-      #
-      # @sig Hash[String, Zeitwerk::Loader]
-      attr_reader :cpaths
-      private :cpaths
-
-      # @sig Mutex
-      attr_reader :mutex
-      private :mutex
-
-      # @sig TracePoint
-      attr_reader :tracer
-      private :tracer
-
-      # Asserts `cpath` corresponds to an explicit namespace for which `loader`
-      # is responsible.
+      # Registers `cref` as being the constant path of an explicit namespace
+      # managed by `loader`.
       #
       # @sig (String, Zeitwerk::Loader) -> void
-      internal def register(cpath, loader)
-        mutex.synchronize do
-          cpaths[cpath] = loader
-          # We check enabled? because, looking at the C source code, enabling an
-          # enabled tracer does not seem to be a simple no-op.
-          tracer.enable unless tracer.enabled?
+      internal def register(cref, loader)
+        if Object.equal?(cref.mod)
+          @loaders[cref.cname] = loader
+        else
+          @loaders[cref.path] = loader
+        end
+      end
+
+      # @sig (Module, Symbol) -> Zeitwerk::Loader?
+      internal def loader_for(mod, cname)
+        if Object.equal?(mod)
+          @loaders.delete(cname)
+        else
+          @loaders.delete("#{real_mod_name(mod)}::#{cname}")
         end
       end
 
       # @sig (Zeitwerk::Loader) -> void
       internal def unregister_loader(loader)
-        cpaths.delete_if { |_cpath, l| l == loader }
-        disable_tracer_if_unneeded
+        @loaders.delete_if { _2.equal?(loader) }
       end
 
       # This is an internal method only used by the test suite.
       #
-      # @sig (String) -> bool
-      internal def registered?(cpath)
-        cpaths.key?(cpath)
+      # @sig (String) -> Zeitwerk::Loader?
+      internal def registered?(cname_or_cpath)
+        @loaders[cname_or_cpath]
       end
 
+      # This is an internal method only used by the test suite.
+      #
       # @sig () -> void
-      private def disable_tracer_if_unneeded
-        mutex.synchronize do
-          tracer.disable if cpaths.empty?
-        end
+      internal def clear
+        @loaders.clear
       end
 
-      # @sig (TracePoint) -> void
-      private def tracepoint_class_callback(event)
-        # If the class is a singleton class, we won't do anything with it so we
-        # can bail out immediately. This is several orders of magnitude faster
-        # than accessing its name.
-        return if event.self.singleton_class?
+      module Synchronized
+        extend Internal
+
+        MUTEX = Mutex.new
 
-        # It might be tempting to return if name.nil?, to avoid the computation
-        # of a hash code and delete call. But Ruby does not trigger the :class
-        # event on Class.new or Module.new, so that would incur in an extra call
-        # for nothing.
-        #
-        # On the other hand, if we were called, cpaths is not empty. Otherwise
-        # the tracer is disabled. So we do need to go ahead with the hash code
-        # computation and delete call.
-        if loader = cpaths.delete(real_mod_name(event.self))
-          loader.on_namespace_loaded(event.self)
-          disable_tracer_if_unneeded
+        internal def register(...)
+          MUTEX.synchronize { super }
         end
-      end
-    end
 
-    @cpaths = {}
-    @mutex  = Mutex.new
+        internal def loader_for(...)
+          MUTEX.synchronize { super }
+        end
+
+        internal def unregister_loader(...)
+          MUTEX.synchronize { super }
+        end
 
-    # We go through a method instead of defining a block mainly to have a better
-    # label when profiling.
-    @tracer = TracePoint.new(:class, &method(:tracepoint_class_callback))
+        internal def registered?(...)
+          MUTEX.synchronize { super }
+        end
+
+        internal def clear
+          MUTEX.synchronize { super }
+        end
+      end
+
+      prepend Synchronized unless RUBY_ENGINE == "ruby"
+    end
   end
 end

data/lib/zeitwerk/loader/callbacks.rb

@@ -6,6 +6,7 @@ module Zeitwerk::Loader::Callbacks
 
   # Invoked from our decorated Kernel#require when a managed file is autoloaded.
   #
+  # @raise [Zeitwerk::NameError]
   # @sig (String) -> void
   internal def on_file_autoloaded(file)
     cref = autoloads.delete(file)
@@ -72,7 +73,7 @@ module Zeitwerk::Loader::Callbacks
   end
 
   # Invoked when a class or module is created or reopened, either from the
-  # tracer or from module autovivification. If the namespace has matching
+  # const_added or from module autovivification. If the namespace has matching
   # subdirectories, we descend into them now.
   #
   # @private

data/lib/zeitwerk/loader/eager_load.rb

@@ -84,7 +84,7 @@ module Zeitwerk::Loader::EagerLoad
     return unless mod_name
 
     actual_roots.each do |root_dir, root_namespace|
-      if mod.equal?(Object)
+      if Object.equal?(mod)
         # A shortcircuiting test depends on the invocation of this method.
         # Please keep them in sync if refactored.
         actual_eager_load_dir(root_dir, root_namespace)

data/lib/zeitwerk/loader/helpers.rb

@@ -57,9 +57,7 @@ module Zeitwerk::Loader::Helpers
     to_visit = [dir]
 
     while (dir = to_visit.shift)
-      children = Dir.children(dir)
-
-      children.each do |basename|
+      Dir.each_child(dir) do |basename|
         next if hidden?(basename)
 
         abspath = File.join(dir, basename)

data/lib/zeitwerk/loader.rb

@@ -469,7 +469,7 @@ module Zeitwerk
           # Registering is idempotent, and we have to keep the autoload pointing
           # to the file. This may run again if more directories are found later
           # on, no big deal.
-          register_explicit_namespace(cref.path)
+          register_explicit_namespace(cref)
         end
         # If the existing autoload points to a file, it has to be preserved, if
         # not, it is fine as it is. In either case, we do not need to override.
@@ -515,8 +515,10 @@ module Zeitwerk
 
       log("earlier autoload for #{cref.path} discarded, it is actually an explicit namespace defined in #{file}") if logger
 
+      # Order matters: When Module#const_added is triggered by the autoload, we
+      # don't want the namespace to be registered yet.
       define_autoload(cref, file)
-      register_explicit_namespace(cref.path)
+      register_explicit_namespace(cref)
     end
 
     # @sig (Module, Symbol, String) -> void
@@ -545,13 +547,13 @@ module Zeitwerk
       if autoload_path = cref.autoload?
         autoload_path if autoloads.key?(autoload_path)
       else
-        Registry.inception?(cref.path)
+        Registry.inception?(cref.path, self)
       end
     end
 
-    # @sig (String) -> void
-    private def register_explicit_namespace(cpath)
-      ExplicitNamespace.__register(cpath, self)
+    # @sig (Zeitwerk::Cref) -> void
+    private def register_explicit_namespace(cref)
+      ExplicitNamespace.__register(cref, self)
     end
 
     # @sig (String) -> void

data/lib/zeitwerk/real_mod_name.rb

@@ -10,13 +10,7 @@ module Zeitwerk::RealModName
   # The name method can be overridden, hence the indirection in this method.
   #
   # @sig (Module) -> String?
-  if UnboundMethod.method_defined?(:bind_call)
-    def real_mod_name(mod)
-      UNBOUND_METHOD_MODULE_NAME.bind_call(mod)
-    end
-  else
-    def real_mod_name(mod)
-      UNBOUND_METHOD_MODULE_NAME.bind(mod).call
-    end
+  def real_mod_name(mod)
+    UNBOUND_METHOD_MODULE_NAME.bind_call(mod)
   end
 end

data/lib/zeitwerk/registry.rb

@@ -110,9 +110,12 @@ module Zeitwerk
 
       # @private
       # @sig (String) -> String?
-      def inception?(cpath)
+      def inception?(cpath, registered_by_loader=nil)
         if pair = inceptions[cpath]
-          pair.first
+          abspath, loader = pair
+          if registered_by_loader.nil? || registered_by_loader.equal?(loader)
+            abspath
+          end
         end
       end
 

data/lib/zeitwerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  VERSION = "2.6.17"
+  VERSION = "2.7.1"
 end

data/lib/zeitwerk.rb

@@ -11,10 +11,12 @@ module Zeitwerk
   require_relative "zeitwerk/inflector"
   require_relative "zeitwerk/gem_inflector"
   require_relative "zeitwerk/null_inflector"
-  require_relative "zeitwerk/kernel"
   require_relative "zeitwerk/error"
   require_relative "zeitwerk/version"
 
+  require_relative "zeitwerk/core_ext/kernel"
+  require_relative "zeitwerk/core_ext/module"
+
   # This is a dangerous method.
   #
   # @experimental

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.17
+  version: 2.7.1
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-29 00:00:00.000000000 Z
+date: 2024-10-18 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -23,6 +23,8 @@ files:
 - MIT-LICENSE
 - README.md
 - lib/zeitwerk.rb
+- lib/zeitwerk/core_ext/kernel.rb
+- lib/zeitwerk/core_ext/module.rb
 - lib/zeitwerk/cref.rb
 - lib/zeitwerk/error.rb
 - lib/zeitwerk/explicit_namespace.rb
@@ -30,7 +32,6 @@ files:
 - lib/zeitwerk/gem_loader.rb
 - lib/zeitwerk/inflector.rb
 - lib/zeitwerk/internal.rb
-- lib/zeitwerk/kernel.rb
 - lib/zeitwerk/loader.rb
 - lib/zeitwerk/loader/callbacks.rb
 - lib/zeitwerk/loader/config.rb
@@ -56,14 +57,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.15
+rubygems_version: 3.5.21
 signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader