zeitwerk 2.2.0 → 2.8.2

data/lib/zeitwerk/core_ext/kernel.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Kernel
+  module_function
+
+  # Zeitwerk's main idea is to define autoloads for project constants, and then
+  # intercept them when triggered in this thin `Kernel#require` wrapper.
+  #
+  # That allows us to complete the circle, invoke callbacks, autovivify modules,
+  # define autoloads for just autoloaded namespaces, update internal state, etc.
+  #
+  # On the other hand, if you publish a new version of a gem that is now managed
+  # by Zeitwerk, client code can reference directly your classes and modules and
+  # should not require anything. But if someone has legacy require calls around,
+  # they will work as expected, and in a compatible way. This feature is by now
+  # EXPERIMENTAL and UNDOCUMENTED.
+  alias_method :zeitwerk_original_require, :require
+  class << self
+    alias_method :zeitwerk_original_require, :require
+  end
+
+  #: (String) -> bool
+  def require(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
+        required
+      else
+        loader.__on_dir_autoloaded(path)
+        true
+      end
+    else
+      required = zeitwerk_original_require(path)
+      if required
+        abspath = $LOADED_FEATURES.last
+        if loader = Zeitwerk::Registry.autoloads.registered?(abspath)
+          loader.__on_file_autoloaded(abspath)
+        end
+      end
+      required
+    end
+  end
+
+  # By now, I have seen no way so far to decorate require_relative.
+  #
+  # For starters, at least in CRuby, require_relative does not delegate to
+  # require. Both require and require_relative delegate the bulk of their work
+  # to an internal C function called rb_require_safe. So, our require wrapper is
+  # not executed.
+  #
+  # On the other hand, we cannot use the aliasing technique above because
+  # require_relative receives a path relative to the directory of the file in
+  # which the call is performed. If a wrapper here invoked the original method,
+  # Ruby would resolve the relative path taking lib/zeitwerk as base directory.
+  #
+  # A workaround could be to extract the base directory from caller_locations,
+  # but what if someone else decorated require_relative before us? You can't
+  # really know with certainty where's the original call site in the stack.
+  #
+  # However, the main use case for require_relative is to load files from your
+  # own project. Projects managed by Zeitwerk don't do this for files managed by
+  # Zeitwerk, precisely.
+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.
+#
+# 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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# 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. Examples:
+#
+#   cref.path
+#   cref.set(value)
+#   cref.get
+#
+# The constant may or may not exist in `mod`.
+class Zeitwerk::Cref
+  require_relative 'cref/map'
+
+  include Zeitwerk::RealModName
+
+  #: Module
+  attr_reader :mod
+
+  #: Symbol
+  attr_reader :cname
+
+  # The type of the first argument is Module because Class < Module, class
+  # objects are also valid.
+  #
+  #: (Module, Symbol) -> void
+  def initialize(mod, cname)
+    @mod   = mod
+    @cname = cname
+    @path  = nil
+  end
+
+  #: () -> String
+  def path
+    @path ||= Object == @mod ? @cname.name : "#{real_mod_name(@mod)}::#{@cname.name}".freeze
+  end
+  alias to_s path
+
+  #: () -> String?
+  def autoload?
+    @mod.autoload?(@cname, false)
+  end
+
+  #: (String) -> nil
+  def autoload(abspath)
+    @mod.autoload(@cname, abspath)
+  end
+
+  #: () -> bool
+  def defined?
+    @mod.const_defined?(@cname, false)
+  end
+
+  #: (top) -> top
+  def set(value)
+    @mod.const_set(@cname, value)
+  end
+
+  #: () -> top ! NameError
+  def get
+    @mod.const_get(@cname, false)
+  end
+
+  #: () -> 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

@@ -1,10 +1,34 @@
+# frozen_string_literal: true
+
 module Zeitwerk
   class Error < StandardError
   end
 
   class ReloadingDisabledError < Error
+    #: () -> void
+    def initialize
+      super("can't reload, please call loader.enable_reloading before setup")
+    end
   end
 
   class NameError < ::NameError
   end
+
+  class SetupRequired < Error
+    #: () -> void
+    def initialize
+      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,18 +2,16 @@
 
 module Zeitwerk
   class GemInflector < Inflector
-    # @param root_file [String]
+    #: (String) -> void
     def initialize(root_file)
-      namespace     = File.basename(root_file, ".rb")
-      lib_dir       = File.dirname(root_file)
-      @version_file = File.join(lib_dir, namespace, "version.rb")
+      namespace     = File.basename(root_file, '.rb')
+      root_dir      = File.dirname(root_file)
+      @version_file = File.join(root_dir, namespace, 'version.rb')
     end
 
-    # @param basename [String]
-    # @param abspath [String]
-    # @return [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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Zeitwerk
+  # @private
+  class GemLoader < Loader
+    include RealModName
+
+    # Users should not create instances directly, the public interface is
+    # `Zeitwerk::Loader.for_gem`.
+    private_class_method :new
+
+    # @private
+    #: (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
+
+    #: (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)
+
+      @inflector           = GemInflector.new(root_file)
+      @root_file           = File.expand_path(root_file)
+      @root_dir            = File.dirname(root_file)
+      @warn_on_extra_files = warn_on_extra_files
+
+      push_dir(@root_dir, namespace: namespace)
+    end
+
+    #: () -> void
+    def setup
+      warn_on_extra_files if @warn_on_extra_files
+      super
+    end
+
+    private
+
+    #: () -> void
+    def warn_on_extra_files
+      expected_namespace_dir = @root_file.delete_suffix('.rb')
+
+      @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 = cname_for(basename_without_ext, abspath)
+
+        warn(<<~EOS)
+          WARNING: Zeitwerk defines the constant #{cname} after the #{ftype}
+
+              #{abspath}
+
+          To prevent that, please configure the loader to ignore it:
+
+              loader.ignore("\#{__dir__}/#{basename}")
+
+          Otherwise, there is a flag to silence this warning:
+
+              Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+        EOS
+      end
+    end
+  end
+end

data/lib/zeitwerk/inflector.rb

@@ -5,33 +5,30 @@ 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`.
     #
-    # @param basename [String]
-    # @param _abspath [String]
-    # @return [String]
+    #: (String, String) -> String
     def camelize(basename, _abspath)
-      overrides[basename] || basename.split('_').map!(&:capitalize).join
+      overrides[basename] || basename.split('_').each(&:capitalize!).join
     end
 
     # Configures hard-coded inflections:
     #
     #   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) # => "PostsController"
+    #   inflector.camelize('html_parser', abspath)      # => 'HTMLParser'
+    #   inflector.camelize('mysql_adapter', abspath)    # => 'MySQLAdapter'
+    #   inflector.camelize('users_controller', abspath) # => 'UsersController'
     #
-    # @param inflections [{String => String}]
-    # @return [void]
+    #: (Hash[String, String]) -> void
     def inflect(inflections)
       overrides.merge!(inflections)
     end
@@ -41,7 +38,7 @@ module Zeitwerk
     # Hard-coded basename to constant name user maps that override the default
     # inflection logic.
     #
-    # @return [{String => String}]
+    #: () -> Hash[String, String]
     def overrides
       @overrides ||= {}
     end

data/lib/zeitwerk/internal.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# This is a private module.
+module Zeitwerk::Internal
+  #: (Symbol) -> void
+  def internal(method_name)
+    private method_name
+
+    mangled = "__#{method_name}"
+    alias_method mangled, method_name
+    public mangled
+  end
+end

data/lib/zeitwerk/loader/callbacks.rb

@@ -1,32 +1,45 @@
-module Zeitwerk::Loader::Callbacks
-  include Zeitwerk::RealModName
+# frozen_string_literal: true
+
+module Zeitwerk::Loader::Callbacks # :nodoc: all
+  extend Zeitwerk::Internal
 
   # Invoked from our decorated Kernel#require when a managed file is autoloaded.
   #
-  # @private
-  # @param file [String]
-  # @return [void]
-  def on_file_autoloaded(file)
+  #: (String) -> void ! Zeitwerk::NameError
+  internal def on_file_autoloaded(file)
     cref = autoloads.delete(file)
-    to_unload[cpath(*cref)] = [file, cref] if reloading_enabled?
-    Zeitwerk::Registry.unregister_autoload(file)
 
-    if logger && cdef?(*cref)
-      log("constant #{cpath(*cref)} loaded from file #{file}")
-    elsif !cdef?(*cref)
-      raise NameError, "expected file #{file} to define constant #{cpath(*cref)}, but didn't"
+    Zeitwerk::Registry.autoloads.unregister(file)
+
+    if cref.defined?
+      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}, but didn't"
+      log { msg }
+
+      # Ruby still keeps the autoload defined, but we remove it because the
+      # contract in Zeitwerk is more strict.
+      cref.remove
+
+      # 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[file] = cref if reloading_enabled?
+
+      raise Zeitwerk::NameError.new(msg, cref.cname)
     end
   end
 
   # Invoked from our decorated Kernel#require when a managed directory is
   # autoloaded.
   #
-  # @private
-  # @param dir [String]
-  # @return [void]
-  def on_dir_autoloaded(dir)
-    # Module#autoload does not serialize concurrent requires, and we handle
-    # directories ourselves, so the callback needs to account for concurrency.
+  #: (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
+    # the callback needs to account for concurrency.
     #
     # Multi-threading would introduce a race condition here in which thread t1
     # autovivifies the module, and while autoloads for its children are being
@@ -35,13 +48,13 @@ module Zeitwerk::Loader::Callbacks
     # Without the mutex and subsequent delete call, t2 would reset the module.
     # That not only would reassign the constant (undesirable per se) but, worse,
     # the module object created by t2 wouldn't have any of the autoloads for its
-    # children, since t1 would have correctly deleted its lazy_subdirs entry.
-    mutex2.synchronize do
+    # children, since t1 would have correctly deleted its namespace_dirs entry.
+    dirs_autoload_monitor.synchronize do
       if cref = autoloads.delete(dir)
-        autovivified_module = cref[0].const_set(cref[1], Module.new)
-        log("module #{autovivified_module.name} autovivified from directory #{dir}") if logger
+        implicit_namespace = cref.set(Module.new)
+        log { "module #{cref} autovivified from directory #{dir}" }
 
-        to_unload[autovivified_module.name] = [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
@@ -49,23 +62,35 @@ module Zeitwerk::Loader::Callbacks
         # these to be able to unregister later if eager loading.
         autoloaded_dirs << dir
 
-        on_namespace_loaded(autovivified_module)
+        on_namespace_loaded(cref, implicit_namespace)
+
+        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
-  # @param namespace [Module]
-  # @return [void]
-  def on_namespace_loaded(namespace)
-    if subdirs = lazy_subdirs.delete(real_mod_name(namespace))
-      subdirs.each do |subdir|
-        set_autoloads_in_dir(subdir, 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, external: false)
       end
     end
   end
+
+  private
+
+  #: (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)
+    callbacks&.each { |c| c.call(value, abspath) }
+
+    callbacks = on_load_callbacks[:ANY]
+    callbacks&.each { |c| c.call(cpath, value, abspath) }
+  end
 end