zeitwerk 2.6.18 → 2.8.1

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.
+#
+# Benchmarks
+# ----------
+#
+# 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,98 +2,75 @@
 
 # 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
+
+  #: () -> String?
+  def location
+    if (location = @mod.const_source_location(@cname)) && !location.empty?
+      location.join(':')
+    end
+  end
 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,8 +15,20 @@ module Zeitwerk
   end
 
   class SetupRequired < Error
+    #: () -> void
     def initialize
-      super("please, finish your configuration and call Zeitwerk::Loader#setup once all is ready")
+      super('please, finish your configuration and call Zeitwerk::Loader#setup once all is ready')
+    end
+  end
+
+  class ConflictingNamespaceDefinitionError < Error
+    #: (String, location: String?, conflicting_file: String) -> void
+    def initialize(cpath, location:, conflicting_file:)
+      if location
+        super("conflicting namespace definition for #{cpath}: #{conflicting_file} conflicts with #{location}")
+      else
+        super("conflicting namespace definition for #{cpath}: #{conflicting_file} conflicts with an already defined namespace")
+      end
     end
   end
 end

data/lib/zeitwerk/gem_inflector.rb

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

data/lib/zeitwerk/gem_loader.rb

@@ -10,17 +10,17 @@ 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()
 
-      @tag = File.basename(root_file, ".rb")
-      @tag = real_mod_name(namespace) + "-" + @tag unless namespace.equal?(Object)
+      @tag = File.basename(root_file, '.rb')
+      @tag = real_mod_name(namespace) + '-' + @tag unless namespace.equal?(Object)
 
       @inflector           = GemInflector.new(root_file)
       @root_file           = File.expand_path(root_file)
@@ -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,16 +38,16 @@ module Zeitwerk
 
     private
 
-    # @sig () -> void
+    #: () -> void
     def warn_on_extra_files
-      expected_namespace_dir = @root_file.delete_suffix(".rb")
+      expected_namespace_dir = @root_file.delete_suffix('.rb')
 
-      ls(@root_dir) do |basename, abspath, ftype|
+      @fs.ls(@root_dir) do |basename, abspath, ftype|
         next if abspath == @root_file
         next if abspath == expected_namespace_dir
 
-        basename_without_ext = basename.delete_suffix(".rb")
-        cname = inflector.camelize(basename_without_ext, abspath).to_sym
+        basename_without_ext = basename.delete_suffix('.rb')
+        cname = cname_for(basename_without_ext, abspath)
 
         warn(<<~EOS)
           WARNING: Zeitwerk defines the constant #{cname} after the #{ftype}

data/lib/zeitwerk/inflector.rb

@@ -5,13 +5,13 @@ module Zeitwerk
     # Very basic snake case -> camel case conversion.
     #
     #   inflector = Zeitwerk::Inflector.new
-    #   inflector.camelize("post", ...)             # => "Post"
-    #   inflector.camelize("users_controller", ...) # => "UsersController"
-    #   inflector.camelize("api", ...)              # => "Api"
+    #   inflector.camelize('post', ...)             # => 'Post'
+    #   inflector.camelize('users_controller', ...) # => 'UsersController'
+    #   inflector.camelize('api', ...)              # => 'Api'
     #
     # 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
@@ -20,15 +20,15 @@ module Zeitwerk
     #
     #   inflector = Zeitwerk::Inflector.new
     #   inflector.inflect(
-    #     "html_parser"   => "HTMLParser",
-    #     "mysql_adapter" => "MySQLAdapter"
+    #     'html_parser'   => 'HTMLParser',
+    #     'mysql_adapter' => 'MySQLAdapter'
     #   )
     #
-    #   inflector.camelize("html_parser", abspath)      # => "HTMLParser"
-    #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
-    #   inflector.camelize("users_controller", abspath) # => "UsersController"
+    #   inflector.camelize('html_parser', abspath)      # => 'HTMLParser'
+    #   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,24 +1,23 @@
 # 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}" }
+      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"
-      log(msg) if logger
+      msg = "expected file #{file} to define constant #{cref}, but didn't"
+      log { msg }
 
       # Ruby still keeps the autoload defined, but we remove it because the
       # contract in Zeitwerk is more strict.
@@ -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}" }
 
-        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,30 +62,29 @@ 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)
+        define_autoloads_for_dir(dir, namespace, external: false)
       end
     end
   end
 
   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)