zeitwerk 2.6.16 → 2.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b69678cbbd525cff55aa4cd08d1f3a785d69cac3e851e3cc2a168ef029163a3
-  data.tar.gz: 9da1ded3c41f766feee609adedc9706d4efb4cfd3701c6944f0e781986d578ef
+  metadata.gz: 1500c4f54c6ac7e64eef74c8702682764fa845533a5b16c67a48ee11781ef3e0
+  data.tar.gz: f7201576b8b59ab3786cd4bc6fd58f3cd3afa3d8dcc1e86477121000f06ac50a
 SHA512:
-  metadata.gz: 76f28b7d765b0209f489cb23f939143a6d1800e997e9a1722a0482aaf4e942f59eef26ec1e9e98a7e722710ba01c3de706f01a64594688310ca7908edb5c4de1
-  data.tar.gz: 2da1dfd280a4fb987f281094e45ce9c1797323680cd90f586c60660516995262aaeb4d38c55e8c330a5c879f5471567633ffe72298371c33a05b5cb6f3805285
+  metadata.gz: ab113d90c9a42ec5c75c6ebe68ab5a04395f1b33228de42de6952f2e673a329f30de85477977ec11d582df82f40c4dc5c08e8ba2305f46a6d07ac4e88c564887
+  data.tar.gz: 73fb9dc78a9a7148119b306f93a513f841e4888d421fbf178963bbfa1368a8c7c66cd8661a28e8d95d14f51dab16fb4ff886f23183ec13a74847c45c1850f30d

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/{kernel.rb → core_ext/kernel.rb}

@@ -19,9 +19,9 @@ module Kernel
     alias_method :zeitwerk_original_require, :require
   end
 
-  # @sig (String) -> true | false
+  #: (String) -> bool
   def require(path)
-    if loader = Zeitwerk::Registry.loader_for(path)
+    if loader = Zeitwerk::Registry.autoloads.registered?(path)
       if path.end_with?(".rb")
         required = zeitwerk_original_require(path)
         loader.__on_file_autoloaded(path) if required
@@ -34,7 +34,7 @@ module Kernel
       required = zeitwerk_original_require(path)
       if required
         abspath = $LOADED_FEATURES.last
-        if loader = Zeitwerk::Registry.loader_for(abspath)
+        if loader = Zeitwerk::Registry.autoloads.registered?(abspath)
           loader.__on_file_autoloaded(abspath)
         end
       end

data/lib/zeitwerk/core_ext/module.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Zeitwerk::ConstAdded # :nodoc:
+  #: (Symbol) -> void
+  def const_added(cname)
+    if loader = Zeitwerk::Registry.explicit_namespaces.loader_for(self, cname)
+      namespace = const_get(cname, false)
+      cref = Zeitwerk::Cref.new(self, cname)
+
+      unless namespace.is_a?(Module)
+        raise Zeitwerk::Error, "#{cref} is expected to be a namespace, should be a class or module (got #{namespace.class})"
+      end
+
+      loader.__on_namespace_loaded(cref, namespace)
+    end
+    super
+  end
+
+  Module.prepend(self)
+end

data/lib/zeitwerk/cref/map.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+# Description of the structure
+# ----------------------------
+#
+# This class emulates a hash table whose keys are of type Zeitwerk::Cref.
+#
+# It is a synchronized 2-level hash.
+#
+# The keys of the top one, stored in `@map`, are class and module objects, but
+# their hash code is forced to be their object IDs because class and module
+# objects may not be hashable (https://github.com/fxn/zeitwerk/issues/188).
+#
+# Then, each one of them stores a hash table with their constants and values.
+# Constants are stored as symbols.
+#
+# For example, if we store values 0, 1, and 2 for the crefs that would
+# correspond to `M::X`, `M::Y`, and `N::Z`, the map will look like this:
+#
+#   { M => { X: 0, :Y => 1 }, N => { Z: 2 } }
+#
+# This structure is internal, so only the needed interface is implemented.
+#
+# Alternative approaches
+# -----------------------
+#
+# 1. We could also use a 1-level hash whose keys are constant paths. In the
+#    example above it would be:
+#
+#      { "M::X" => 0, "M::Y" => 1, "N::Z" => 2 }
+#
+#    The gem used this approach for several years.
+#
+#  2. Write a custom `hash`/`eql?` in Zeitwerk::Cref. Hash code would be
+#
+#       real_mod_hash(@mod) ^ @cname.hash
+#
+#     where `real_mod_hash(@mod)` would actually be a call to the real `hash`
+#     method in Module. Like what we do for module names to bypass overrides.
+#
+#  3. Similar to 2, but use
+#
+#       @mod.object_id ^ @cname.object_id
+#
+#     as hash code instead.
+#
+# Benchamrks
+# ----------
+#
+# Writing:
+#
+#   map - baseline
+#   (3) - 1.74x  slower
+#   (2) - 2.91x  slower
+#   (1) - 3.87x  slower
+#
+# Reading:
+#
+#   map - baseline
+#   (3) - 1.99x  slower
+#   (2) - 2.80x  slower
+#   (1) - 3.48x  slower
+#
+# Extra ball
+# ----------
+#
+# In addition to that, the map is synchronized and provides `delete_mod_cname`,
+# which is ad-hoc for the hot path in `const_added`, we do not need to create
+# unnecessary cref objects for constants we do not manage (but we do not know in
+# advance there).
+
+#: [Value]
+class Zeitwerk::Cref::Map # :nodoc: all
+  #: () -> void
+  def initialize
+    @map = {}
+    @map.compare_by_identity
+    @mutex = Mutex.new
+  end
+
+  #: (Zeitwerk::Cref, Value) -> Value
+  def []=(cref, value)
+    @mutex.synchronize do
+      cnames = (@map[cref.mod] ||= {})
+      cnames[cref.cname] = value
+    end
+  end
+
+  #: (Zeitwerk::Cref) -> Value?
+  def [](cref)
+    @mutex.synchronize do
+      @map[cref.mod]&.[](cref.cname)
+    end
+  end
+
+  #: (Zeitwerk::Cref, { () -> Value }) -> Value
+  def get_or_set(cref, &block)
+    @mutex.synchronize do
+      cnames = (@map[cref.mod] ||= {})
+      cnames.fetch(cref.cname) { cnames[cref.cname] = block.call }
+    end
+  end
+
+  #: (Zeitwerk::Cref) -> Value?
+  def delete(cref)
+    delete_mod_cname(cref.mod, cref.cname)
+  end
+
+  # Ad-hoc for loader_for, called from const_added. That is a hot path, I prefer
+  # to not create a cref in every call, since that is global.
+  #
+  #: (Module, Symbol) -> Value?
+  def delete_mod_cname(mod, cname)
+    @mutex.synchronize do
+      if cnames = @map[mod]
+        value = cnames.delete(cname)
+        @map.delete(mod) if cnames.empty?
+        value
+      end
+    end
+  end
+
+  #: (Value) -> void
+  def delete_by_value(value)
+    @mutex.synchronize do
+      @map.delete_if do |mod, cnames|
+        cnames.delete_if { _2 == value }
+        cnames.empty?
+      end
+    end
+  end
+
+  # Order of yielded crefs is undefined.
+  #
+  #: () { (Zeitwerk::Cref) -> void } -> void
+  def each_key
+    @mutex.synchronize do
+      @map.each do |mod, cnames|
+        cnames.each_key do |cname|
+          yield Zeitwerk::Cref.new(mod, cname)
+        end
+      end
+    end
+  end
+
+  #: () -> void
+  def clear
+    @mutex.synchronize do
+      @map.clear
+    end
+  end
+
+  #: () -> bool
+  def empty? # for tests
+    @mutex.synchronize do
+      @map.empty?
+    end
+  end
+end

data/lib/zeitwerk/cref.rb

@@ -2,97 +2,67 @@
 
 # This private class encapsulates pairs (mod, cname).
 #
-# Objects represent the constant cname in the class or module object mod, and
-# have API to manage them that encapsulates the constants API. Examples:
+# Objects represent the constant `cname` in the class or module object `mod`,
+# and have API to manage them. Examples:
 #
 #   cref.path
 #   cref.set(value)
 #   cref.get
 #
-# The constant may or may not exist in mod.
+# The constant may or may not exist in `mod`.
 class Zeitwerk::Cref
+  require_relative "cref/map"
+
   include Zeitwerk::RealModName
 
-  # @sig Symbol
+  #: Module
+  attr_reader :mod
+
+  #: Symbol
   attr_reader :cname
 
   # The type of the first argument is Module because Class < Module, class
   # objects are also valid.
   #
-  # @sig (Module, Symbol) -> void
+  #: (Module, Symbol) -> void
   def initialize(mod, cname)
     @mod   = mod
     @cname = cname
     @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
+  #: () -> String
+  def path
+    @path ||= Object == @mod ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}".freeze
   end
+  alias to_s path
 
-  # 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
+  #: () -> String?
+  def autoload?
+    @mod.autoload?(@cname, false)
   end
 
-  # @sig (String) -> bool
+  #: (String) -> nil
   def autoload(abspath)
     @mod.autoload(@cname, abspath)
   end
 
-  # @sig () -> bool
+  #: () -> bool
   def defined?
     @mod.const_defined?(@cname, false)
   end
 
-  # @sig (Object) -> Object
+  #: (top) -> top
   def set(value)
     @mod.const_set(@cname, value)
   end
 
-  # @raise [NameError]
-  # @sig () -> Object
+  #: () -> top ! NameError
   def get
     @mod.const_get(@cname, false)
   end
 
-  # @raise [NameError]
-  # @sig () -> void
+  #: () -> void ! NameError
   def remove
     @mod.__send__(:remove_const, @cname)
   end

data/lib/zeitwerk/error.rb

@@ -5,6 +5,7 @@ module Zeitwerk
   end
 
   class ReloadingDisabledError < Error
+    #: () -> void
     def initialize
       super("can't reload, please call loader.enable_reloading before setup")
     end
@@ -14,6 +15,7 @@ module Zeitwerk
   end
 
   class SetupRequired < Error
+    #: () -> void
     def initialize
       super("please, finish your configuration and call Zeitwerk::Loader#setup once all is ready")
     end

data/lib/zeitwerk/gem_inflector.rb

@@ -2,14 +2,14 @@
 
 module Zeitwerk
   class GemInflector < Inflector
-    # @sig (String) -> void
+    #: (String) -> void
     def initialize(root_file)
       namespace     = File.basename(root_file, ".rb")
       root_dir      = File.dirname(root_file)
       @version_file = File.join(root_dir, namespace, "version.rb")
     end
 
-    # @sig (String, String) -> String
+    #: (String, String) -> String
     def camelize(basename, abspath)
       abspath == @version_file ? "VERSION" : super
     end

data/lib/zeitwerk/gem_loader.rb

@@ -10,12 +10,12 @@ module Zeitwerk
     private_class_method :new
 
     # @private
-    # @sig (String, bool) -> Zeitwerk::GemLoader
+    #: (String, namespace: Module, warn_on_extra_files: boolish) -> Zeitwerk::GemLoader
     def self.__new(root_file, namespace:, warn_on_extra_files:)
       new(root_file, namespace: namespace, warn_on_extra_files: warn_on_extra_files)
     end
 
-    # @sig (String, bool) -> void
+    #: (String, namespace: Module, warn_on_extra_files: boolish) -> void
     def initialize(root_file, namespace:, warn_on_extra_files:)
       super()
 
@@ -30,7 +30,7 @@ module Zeitwerk
       push_dir(@root_dir, namespace: namespace)
     end
 
-    # @sig () -> void
+    #: () -> void
     def setup
       warn_on_extra_files if @warn_on_extra_files
       super
@@ -38,7 +38,7 @@ module Zeitwerk
 
     private
 
-    # @sig () -> void
+    #: () -> void
     def warn_on_extra_files
       expected_namespace_dir = @root_file.delete_suffix(".rb")
 

data/lib/zeitwerk/inflector.rb

@@ -11,7 +11,7 @@ module Zeitwerk
     #
     # Takes into account hard-coded mappings configured with `inflect`.
     #
-    # @sig (String, String) -> String
+    #: (String, String) -> String
     def camelize(basename, _abspath)
       overrides[basename] || basename.split('_').each(&:capitalize!).join
     end
@@ -28,7 +28,7 @@ module Zeitwerk
     #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
     #   inflector.camelize("users_controller", abspath) # => "UsersController"
     #
-    # @sig (Hash[String, String]) -> void
+    #: (Hash[String, String]) -> void
     def inflect(inflections)
       overrides.merge!(inflections)
     end
@@ -38,7 +38,7 @@ module Zeitwerk
     # Hard-coded basename to constant name user maps that override the default
     # inflection logic.
     #
-    # @sig () -> Hash[String, String]
+    #: () -> Hash[String, String]
     def overrides
       @overrides ||= {}
     end

data/lib/zeitwerk/internal.rb

@@ -2,6 +2,7 @@
 
 # This is a private module.
 module Zeitwerk::Internal
+  #: (Symbol) -> void
   def internal(method_name)
     private method_name
 

data/lib/zeitwerk/loader/callbacks.rb

@@ -1,23 +1,22 @@
 # frozen_string_literal: true
 
-module Zeitwerk::Loader::Callbacks
-  include Zeitwerk::RealModName
+module Zeitwerk::Loader::Callbacks # :nodoc: all
   extend Zeitwerk::Internal
 
   # Invoked from our decorated Kernel#require when a managed file is autoloaded.
   #
-  # @sig (String) -> void
+  #: (String) -> void ! Zeitwerk::NameError
   internal def on_file_autoloaded(file)
     cref = autoloads.delete(file)
 
-    Zeitwerk::Registry.unregister_autoload(file)
+    Zeitwerk::Registry.autoloads.unregister(file)
 
     if cref.defined?
-      log("constant #{cref.path} loaded from file #{file}") if logger
-      to_unload[cref.path] = [file, cref] if reloading_enabled?
+      log("constant #{cref} loaded from file #{file}") if logger
+      to_unload[file] = cref if reloading_enabled?
       run_on_load_callbacks(cref.path, cref.get, file) unless on_load_callbacks.empty?
     else
-      msg = "expected file #{file} to define constant #{cref.path}, but didn't"
+      msg = "expected file #{file} to define constant #{cref}, but didn't"
       log(msg) if logger
 
       # Ruby still keeps the autoload defined, but we remove it because the
@@ -27,7 +26,7 @@ module Zeitwerk::Loader::Callbacks
       # Since the expected constant was not defined, there is nothing to unload.
       # However, if the exception is rescued and reloading is enabled, we still
       # need to deleted the file from $LOADED_FEATURES.
-      to_unload[cref.path] = [file, cref] if reloading_enabled?
+      to_unload[file] = cref if reloading_enabled?
 
       raise Zeitwerk::NameError.new(msg, cref.cname)
     end
@@ -36,7 +35,7 @@ module Zeitwerk::Loader::Callbacks
   # Invoked from our decorated Kernel#require when a managed directory is
   # autoloaded.
   #
-  # @sig (String) -> void
+  #: (String) -> void
   internal def on_dir_autoloaded(dir)
     # Module#autoload does not serialize concurrent requires in CRuby < 3.2, and
     # we handle directories ourselves without going through Kernel#require, so
@@ -53,10 +52,9 @@ module Zeitwerk::Loader::Callbacks
     dirs_autoload_monitor.synchronize do
       if cref = autoloads.delete(dir)
         implicit_namespace = cref.set(Module.new)
-        cpath = implicit_namespace.name
-        log("module #{cpath} autovivified from directory #{dir}") if logger
+        log("module #{cref} autovivified from directory #{dir}") if logger
 
-        to_unload[cpath] = [dir, cref] if reloading_enabled?
+        to_unload[dir] = cref if reloading_enabled?
 
         # We don't unregister `dir` in the registry because concurrent threads
         # wouldn't find a loader associated to it in Kernel#require and would
@@ -64,21 +62,20 @@ module Zeitwerk::Loader::Callbacks
         # these to be able to unregister later if eager loading.
         autoloaded_dirs << dir
 
-        on_namespace_loaded(implicit_namespace)
+        on_namespace_loaded(cref, implicit_namespace)
 
-        run_on_load_callbacks(cpath, implicit_namespace, dir) unless on_load_callbacks.empty?
+        run_on_load_callbacks(cref.path, implicit_namespace, dir) unless on_load_callbacks.empty?
       end
     end
   end
 
-  # Invoked when a class or module is created or reopened, either from the
-  # tracer or from module autovivification. If the namespace has matching
-  # subdirectories, we descend into them now.
+  # Invoked when a namespace is created, either from const_added or from module
+  # autovivification. If the namespace has matching subdirectories, we descend
+  # into them now.
   #
-  # @private
-  # @sig (Module) -> void
-  def on_namespace_loaded(namespace)
-    if dirs = namespace_dirs.delete(real_mod_name(namespace))
+  #: (Zeitwerk::Cref, Module) -> void
+  internal def on_namespace_loaded(cref, namespace)
+    if dirs = namespace_dirs.delete(cref)
       dirs.each do |dir|
         define_autoloads_for_dir(dir, namespace)
       end
@@ -87,7 +84,7 @@ module Zeitwerk::Loader::Callbacks
 
   private
 
-  # @sig (String, Object) -> void
+  #: (String, top, String) -> void
   def run_on_load_callbacks(cpath, value, abspath)
     # Order matters. If present, run the most specific one.
     callbacks = reloading_enabled? ? on_load_callbacks[cpath] : on_load_callbacks.delete(cpath)