zeitwerk 2.6.6 → 2.6.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 220865ab50f0336d05c8b907a08a94a8bf92843ba688c1a9686163a190b0754e
-  data.tar.gz: a9d62662351c60a3b264a68726a84c41fc4b6f92eaae855fb4887e3eb4cf14a1
+  metadata.gz: 418f16f6224359c716a990f72ae916c980a3f388b09ab018c0972b8558530620
+  data.tar.gz: '04847c6c8f8f894fe3c2b3c39d175b5854b583d3a02ef5cca27a53cb1b8dafd4'
 SHA512:
-  metadata.gz: b802eaabb27e6268eafa8d35d4402819551203c5fd2a1692d9a9bae65075bf668f5aecfaf3fa6c763987796b60fd5bde4704aebda4a8bfa1c74a526c27264ab5
-  data.tar.gz: c4a53a60b49e5cb83aee148271b26fee8de15fd072327e52363438b0531d9953961305375ec727cc3a0ff2c021254eb081056350165922bd9f6f8b1e1b3e96f3
+  metadata.gz: f86272e84721cf9b8b1e07182b1b60cfe732ef2c266dbe076225d32af52fc9a30c278a14651ddbb3d435636646dd23c948d3fe0f00ed9b8393abdeb34dd40028
+  data.tar.gz: 562738b53779310e899c2065c7046844d27daabb5f354972e4c9b65bec3e5c0cdade92d19ed815fe7b0dc01538603daa3e4dd2f0049fe9a7a2e74313c0f040f6

data/README.md

@@ -3,7 +3,7 @@
 
 
 [![Gem Version](https://img.shields.io/gem/v/zeitwerk.svg?style=for-the-badge)](https://rubygems.org/gems/zeitwerk)
-[![Build Status](https://img.shields.io/github/workflow/status/fxn/zeitwerk/CI?event=push&style=for-the-badge)](https://github.com/fxn/zeitwerk/actions?query=event%3Apush)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/fxn/zeitwerk/ci.yml?branch=main&event=push&style=for-the-badge)](https://github.com/fxn/zeitwerk/actions/workflows/ci.yml?query=branch%3main)
 
 <!-- TOC -->
 
@@ -24,6 +24,7 @@
   - [Setup](#setup)
     - [Generic](#generic)
     - [for_gem](#for_gem)
+    - [for_gem_extension](#for_gem_extension)
   - [Autoloading](#autoloading)
   - [Eager loading](#eager-loading)
     - [Eager load exclusions](#eager-load-exclusions)
@@ -58,9 +59,6 @@
   - [Encodings](#encodings)
   - [Rules of thumb](#rules-of-thumb)
   - [Debuggers](#debuggers)
-    - [debug.rb](#debugrb)
-    - [Byebug](#byebug)
-    - [Break](#break)
 - [Pronunciation](#pronunciation)
 - [Supported Ruby versions](#supported-ruby-versions)
 - [Testing](#testing)
@@ -176,7 +174,7 @@ class HttpCrawler
 end
 ```
 
-The first example needs a custom [inflection](https://github.com/fxn/zeitwerk#inflection) rule:
+The first example needs a custom [inflection](#inflection) rule:
 
 ```ruby
 loader.inflector.inflect("max_retries" => "MAX_RETRIES")
@@ -391,6 +389,12 @@ module MyGem
 end
 ```
 
+Due to technical reasons, the entry point of the gem has to be loaded with `Kernel#require`, which is the standard way to load a gem. Loading that file with `Kernel#load` or `Kernel#require_relative` won't generally work.
+
+`Zeitwerk::Loader.for_gem` is idempotent when invoked from the same file, to support gems that want to reload (unlikely).
+
+If the entry point of your gem lives in a subdirectory of `lib` because it is reopening a namespace defined somewhere else, please use the generic API to setup the loader, and make sure you check the section [_Reopening third-party namespaces_](#reopening-third-party-namespaces) down below.
+
 Loaders returned by `Zeitwerk::Loader.for_gem` issue warnings if `lib` has extra Ruby files or directories.
 
 For example, if the gem has Rails generators under `lib/generators`, by convention that directory defines a `Generators` Ruby module. If `generators` is just a container for non-autoloadable code and templates, not acting as a project namespace, you need to setup things accordingly.
@@ -407,9 +411,64 @@ Otherwise, there's a flag to say the extra stuff is OK:
 Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
 ```
 
-This method is idempotent when invoked from the same file, to support gems that want to reload (unlikely).
+<a id="markdown-for_gem_extension" name="for_gem_extension"></a>
+#### for_gem_extension
+
+Let's suppose you are writing a gem to extend `Net::HTTP` with some niche feature. By [convention](https://guides.rubygems.org/name-your-gem/):
+
+* The gem should be called `net-http-niche_feature`. That is, hyphens for the extended part, a hyphen, and underscores for yours.
+* The namespace should be `Net::HTTP::NicheFeature`.
+* The entry point should be `lib/net/http/niche_feature.rb`.
+* Optionally, the gem could have a top-level `lib/net-http-niche_feature.rb`, but, if defined, that one should have just a `require` call for the entry point.
+
+The top-level file mentioned in the last point is optional. In particular, from
+
+```ruby
+gem "net-http-niche_feature"
+```
+
+if the hyphenated file does not exist, Bundler notes the conventional hyphenated pattern and issues a `require` for `net/http/niche_feature`.
 
-If the entry point of your gem lives in a subdirectory of `lib` because it is reopening a namespace defined somewhere else, please use the generic API to setup the loader, and make sure you check the section [_Reopening third-party namespaces_](https://github.com/fxn/zeitwerk#reopening-third-party-namespaces) down below.
+Gem extensions following the conventions above have a dedicated loader constructor: `Zeitwerk::Loader.for_gem_extension`.
+
+The structure of the gem would be like this:
+
+```ruby
+# lib/net-http-niche_feature.rb (optional)
+
+# For technical reasons, this cannot be require_relative.
+require "net/http/niche_feature"
+
+
+# lib/net/http/niche_feature.rb
+
+require "net/http"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem_extension(Net::HTTP)
+loader.setup
+
+module Net::HTTP::NicheFeature
+  # Since the setup has been performed, at this point we are already able
+  # to reference project constants, in this case Net::HTTP::NicheFeature::MyMixin.
+  include MyMixin
+end
+
+
+# lib/net/http/niche_feature/version.rb
+
+module Net::HTTP::NicheFeature
+  VERSION = "1.0.0"
+end
+```
+
+`Zeitwerk::Loader.for_gem_extension` expects as argument the namespace being extended, which has to be a non-anonymous class or module object.
+
+If it exists, `lib/net/http/niche_feature/version.rb` is expected to define `Net::HTTP::NicheFeature::VERSION`.
+
+Due to technical reasons, the entry point of the gem has to be loaded with `Kernel#require`. Loading that file with `Kernel#load` or `Kernel#require_relative` won't generally work. This is important if you load the entry point from the optional hyphenated top-level file.
+
+`Zeitwerk::Loader.for_gem_extension` is idempotent when invoked from the same file, to support gems that want to reload (unlikely).
 
 <a id="markdown-autoloading" name="autoloading"></a>
 ### Autoloading
@@ -445,7 +504,7 @@ loader.eager_load
 
 That skips [ignored files and directories](#ignoring-parts-of-the-project).
 
-In gems, the method needs to be invoked after the main namespace has been defined, as shown in [Synopsis](https://github.com/fxn/zeitwerk#synopsis).
+In gems, the method needs to be invoked after the main namespace has been defined, as shown in [Synopsis](#synopsis).
 
 Eager loading is synchronized and idempotent.
 
@@ -486,7 +545,7 @@ This is useful when the loader is not eager loading the entire project, but you
 
 Both strings and `Pathname` objects are supported as arguments. If the argument is not a directory managed by the receiver, the method raises `Zeitwerk::Error`.
 
-[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](https://github.com/fxn/zeitwerk#shadowed-files) are not eager loaded.
+[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](#shadowed-files) are not eager loaded.
 
 `Zeitwerk::Loader#eager_load_dir` is idempotent, but compatible with reloading. If you eager load a directory and then reload, eager loading that directory will load its (current) contents again.
 
@@ -519,11 +578,11 @@ root_dir3/my_app/routes
 
 where `root_directory{1,2,3}` are root directories, eager loading `MyApp::Routes` will eager load the contents of the three corresponding directories.
 
-There might exist external source trees implementing part of the namespace. This happens routinely, because top-level constants are stored in the globally shared `Object`. It happens also when deliberately [reopening third-party namespaces](reopening-third-party-namespaces). Such external code is not eager loaded, the implementation is carefully scoped to what the receiver manages to avoid side-effects elsewhere.
+There might exist external source trees implementing part of the namespace. This happens routinely, because top-level constants are stored in the globally shared `Object`. It happens also when deliberately [reopening third-party namespaces](#reopening-third-party-namespaces). Such external code is not eager loaded, the implementation is carefully scoped to what the receiver manages to avoid side-effects elsewhere.
 
 This method is flexible about what it accepts. Its semantics have to be interpreted as: "_If_ you manage this namespace, or part of this namespace, please eager load what you got". In particular, if the receiver does not manage the namespace, it will simply do nothing, this is not an error condition.
 
-[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](https://github.com/fxn/zeitwerk#shadowed-files) are not eager loaded.
+[Eager load exclusions](#eager-load-exclusions), [ignored files and directories](#ignoring-parts-of-the-project), and [shadowed files](#shadowed-files) are not eager loaded.
 
 `Zeitwerk::Loader#eager_load_namespace` is idempotent, but compatible with reloading. If you eager load a namespace and then reload, eager loading that namespace will load its (current) descendants again.
 
@@ -576,7 +635,7 @@ loader.load_file("#{__dir__}/custom_web_app/routes.rb")
 
 This is useful when the loader is not eager loading the entire project, but you still need an individual file to be loaded for things to function properly.
 
-Both strings and `Pathname` objects are supported as arguments. The method raises `Zeitwerk::Error` if the argument is not a Ruby file, is [ignored](#ignoring-parts-of-the-project), is [shadowed](https://github.com/fxn/zeitwerk#shadowed-files), or is not managed by the receiver.
+Both strings and `Pathname` objects are supported as arguments. The method raises `Zeitwerk::Error` if the argument is not a Ruby file, is [ignored](#ignoring-parts-of-the-project), is [shadowed](#shadowed-files), or is not managed by the receiver.
 
 `Zeitwerk::Loader#load_file` is idempotent, but compatible with reloading. If you load a file and then reload, a new call will load its (current) contents again.
 
@@ -951,6 +1010,8 @@ However, sometimes it might still be convenient to tell Zeitwerk to completely i
 
 You can ignore file names, directory names, and glob patterns. Glob patterns are expanded when they are added and again on each reload.
 
+There is an edge case related to nested root directories. Conceptually, root directories are independent source trees. If you ignore a parent of a nested root directory, the nested root directory is not affected. You need to ignore it explictly if you want it ignored too.
+
 Let's see some use cases.
 
 <a id="markdown-use-case-files-that-do-not-follow-the-conventions" name="use-case-files-that-do-not-follow-the-conventions"></a>
@@ -1085,8 +1146,9 @@ For technical reasons, raw constant assignment is not supported:
 
 ```ruby
 # trip.rb
-Trip = Class.new { ... }  # NOT SUPPORTED
-Trip = Struct.new { ... } # NOT SUPPORTED
+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.
@@ -1169,6 +1231,8 @@ loader.push_dir(Pathname.new("/bar"), namespace: Bar)
 loader.dirs(namespaces: true) # => { "/foo" => Object, "/bar" => Bar }
 ```
 
+By default, ignored root directories are filtered out. If you want them included, please pass `ignored: true`.
+
 These collections are read-only. Please add to them with `Zeitwerk::Loader#push_dir`.
 
 <a id="markdown-encodings" name="encodings"></a>
@@ -1201,22 +1265,9 @@ The test suite passes on Windows with codepage `Windows-1252` if all the involve
 <a id="markdown-debuggers" name="debuggers"></a>
 ### Debuggers
 
-<a id="markdown-debugrb" name="debugrb"></a>
-#### debug.rb
-
-The new [debug.rb](https://github.com/ruby/debug) gem and Zeitwerk are mostly compatible. This is the new debugger that is going to ship with Ruby 3.1.
-
-There's one exception, though: Due to a technical limitation of tracepoints, explicit namespaces are not autoloaded while expressions are evaluated in the REPL. See [ruby/debug#408](https://github.com/ruby/debug/issues/408).
-
-<a id="markdown-byebug" name="byebug"></a>
-#### Byebug
-
-Zeitwerk and [Byebug](https://github.com/deivid-rodriguez/byebug) have a similar edge incompatibility.
-
-<a id="markdown-break" name="break"></a>
-#### Break
+Zeitwerk works fine with [debug.rb](https://github.com/ruby/debug) and [Break](https://github.com/gsamokovarov/break).
 
-Zeitwerk works fine with [@gsamokovarov](https://github.com/gsamokovarov)'s [Break](https://github.com/gsamokovarov/break) debugger.
+[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).
 
 <a id="markdown-pronunciation" name="pronunciation"></a>
 ## Pronunciation

data/lib/zeitwerk/explicit_namespace.rb

@@ -47,6 +47,13 @@ module Zeitwerk
         disable_tracer_if_unneeded
       end
 
+      # This is an internal method only used by the test suite.
+      #
+      # @sig (String) -> bool
+      internal def registered?(cpath)
+        cpaths.key?(cpath)
+      end
+
       # @sig () -> void
       private def disable_tracer_if_unneeded
         mutex.synchronize do

data/lib/zeitwerk/gem_inflector.rb

@@ -5,8 +5,8 @@ module Zeitwerk
     # @sig (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")
+      root_dir      = File.dirname(root_file)
+      @version_file = File.join(root_dir, namespace, "version.rb")
     end
 
     # @sig (String, String) -> String

data/lib/zeitwerk/gem_loader.rb

@@ -3,27 +3,31 @@
 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
     # @sig (String, bool) -> Zeitwerk::GemLoader
-    def self._new(root_file, warn_on_extra_files:)
-      new(root_file, warn_on_extra_files: warn_on_extra_files)
+    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
-    def initialize(root_file, warn_on_extra_files:)
+    def initialize(root_file, namespace:, warn_on_extra_files:)
       super()
 
-      @tag                 = File.basename(root_file, ".rb")
+      @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)
-      @lib                 = File.dirname(root_file)
+      @root_dir            = File.dirname(root_file)
       @warn_on_extra_files = warn_on_extra_files
 
-      push_dir(@lib)
+      push_dir(@root_dir, namespace: namespace)
     end
 
     # @sig () -> void
@@ -38,7 +42,7 @@ module Zeitwerk
     def warn_on_extra_files
       expected_namespace_dir = @root_file.delete_suffix(".rb")
 
-      ls(@lib) do |basename, abspath|
+      ls(@root_dir) do |basename, abspath|
         next if abspath == @root_file
         next if abspath == expected_namespace_dir
 

data/lib/zeitwerk/loader/callbacks.rb

@@ -11,18 +11,18 @@ module Zeitwerk::Loader::Callbacks
     cref  = autoloads.delete(file)
     cpath = cpath(*cref)
 
-    # If reloading is enabled, we need to put this constant for unloading
-    # regardless of what cdef? says. In Ruby < 3.1 the internal state is not
-    # fully cleared. Module#constants still includes it, and you need to
-    # remove_const. See https://github.com/ruby/ruby/pull/4715.
-    to_unload[cpath] = [file, cref] if reloading_enabled?
     Zeitwerk::Registry.unregister_autoload(file)
 
     if cdef?(*cref)
       log("constant #{cpath} loaded from file #{file}") if logger
+      to_unload[cpath] = [file, cref] if reloading_enabled?
       run_on_load_callbacks(cpath, cget(*cref), file) unless on_load_callbacks.empty?
     else
-      raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath}, but didn't", cref.last)
+      msg = "expected file #{file} to define constant #{cpath}, but didn't"
+      log(msg) if logger
+      crem(*cref)
+      to_unload[cpath] = [file, cref] if reloading_enabled?
+      raise Zeitwerk::NameError.new(msg, cref.last)
     end
   end
 

data/lib/zeitwerk/loader/config.rb

@@ -109,8 +109,7 @@ module Zeitwerk::Loader::Config
   # @raise [Zeitwerk::Error]
   # @sig (String | Pathname, Module) -> void
   def push_dir(path, namespace: Object)
-    # Note that Class < Module.
-    unless namespace.is_a?(Module)
+    unless namespace.is_a?(Module) # Note that Class < Module.
       raise Zeitwerk::Error, "#{namespace.inspect} is not a class or module object, should be"
     end
 
@@ -149,14 +148,24 @@ module Zeitwerk::Loader::Config
   # instead. Keys are the absolute paths of the root directories as strings,
   # values are their corresponding namespaces, class or module objects.
   #
+  # If `ignored` is falsey (default), ignored root directories are filtered out.
+  #
   # These are read-only collections, please add to them with `push_dir`.
   #
   # @sig () -> Array[String] | Hash[String, Module]
-  def dirs(namespaces: false)
+  def dirs(namespaces: false, ignored: false)
     if namespaces
-      roots.clone
+      if ignored || ignored_paths.empty?
+        roots.clone
+      else
+        roots.reject { |root_dir, _namespace| ignored_path?(root_dir) }
+      end
     else
-      roots.keys
+      if ignored || ignored_paths.empty?
+        roots.keys
+      else
+        roots.keys.reject { |root_dir| ignored_path?(root_dir) }
+      end
     end.freeze
   end
 
@@ -288,9 +297,9 @@ module Zeitwerk::Loader::Config
     # Common use case.
     return false if ignored_paths.empty?
 
-    walk_up(abspath) do |abspath|
-      return true  if ignored_path?(abspath)
-      return false if roots.key?(abspath)
+    walk_up(abspath) do |path|
+      return true  if ignored_path?(path)
+      return false if roots.key?(path)
     end
 
     false
@@ -318,9 +327,9 @@ module Zeitwerk::Loader::Config
     # Optimize this common use case.
     return false if eager_load_exclusions.empty?
 
-    walk_up(abspath) do |abspath|
-      return true  if eager_load_exclusions.member?(abspath)
-      return false if roots.key?(abspath)
+    walk_up(abspath) do |path|
+      return true  if eager_load_exclusions.member?(path)
+      return false if roots.key?(path)
     end
 
     false

data/lib/zeitwerk/loader/eager_load.rb

@@ -183,7 +183,7 @@ module Zeitwerk::Loader::EagerLoad
   end
 
   # In order to invoke this method, the caller has to ensure `child` is a
-  # strict namespace descendendant of `root_namespace`.
+  # strict namespace descendant of `root_namespace`.
   #
   # @sig (Module, String, Module, Boolean) -> void
   private def eager_load_child_namespace(child, child_name, root_dir, root_namespace)

data/lib/zeitwerk/loader/helpers.rb

@@ -134,4 +134,10 @@ module Zeitwerk::Loader::Helpers
   private def cget(parent, cname)
     parent.const_get(cname, false)
   end
+
+  # @raise [NameError]
+  # @sig (Module, Symbol) -> Object
+  private def crem(parent, cname)
+    parent.__send__(:remove_const, cname)
+  end
 end

data/lib/zeitwerk/loader.rb

@@ -9,6 +9,8 @@ module Zeitwerk
     require_relative "loader/config"
     require_relative "loader/eager_load"
 
+    extend Internal
+
     include RealModName
     include Callbacks
     include Helpers
@@ -26,9 +28,9 @@ module Zeitwerk
     #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, :Pricing]
     #   ...
     #
-    # @private
     # @sig Hash[String, [Module, Symbol]]
     attr_reader :autoloads
+    internal :autoloads
 
     # We keep track of autoloaded directories to remove them from the registry
     # at the end of eager loading.
@@ -36,9 +38,9 @@ module Zeitwerk
     # Files are removed as they are autoloaded, but directories need to wait due
     # to concurrency (see why in Zeitwerk::Loader::Callbacks#on_dir_autoloaded).
     #
-    # @private
     # @sig Array[String]
     attr_reader :autoloaded_dirs
+    internal :autoloaded_dirs
 
     # Stores metadata needed for unloading. Its entries look like this:
     #
@@ -52,9 +54,9 @@ module Zeitwerk
     # If reloading is enabled, this hash is filled as constants are autoloaded
     # or eager loaded. Otherwise, the collection remains empty.
     #
-    # @private
     # @sig Hash[String, [String, [Module, Symbol]]]
     attr_reader :to_unload
+    internal :to_unload
 
     # Maps namespace constant paths to their respective directories.
     #
@@ -70,9 +72,9 @@ module Zeitwerk
     # and that its children are spread over those directories. We'll visit them
     # to set up the corresponding autoloads.
     #
-    # @private
     # @sig Hash[String, Array[String]]
     attr_reader :namespace_dirs
+    internal :namespace_dirs
 
     # A shadowed file is a file managed by this loader that is ignored when
     # setting autoloads because its matching constant is already taken.
@@ -81,17 +83,17 @@ module Zeitwerk
     # has only scanned the top-level, `shadowed_files` does not have shadowed
     # files that may exist deep in the project tree yet.
     #
-    # @private
     # @sig Set[String]
     attr_reader :shadowed_files
+    internal :shadowed_files
 
-    # @private
     # @sig Mutex
     attr_reader :mutex
+    private :mutex
 
-    # @private
     # @sig Mutex
     attr_reader :mutex2
+    private :mutex2
 
     def initialize
       super
@@ -134,7 +136,7 @@ module Zeitwerk
     # unload them.
     #
     # This method is public but undocumented. Main interface is `reload`, which
-    # means `unload` + `setup`. This one is avaiable to be used together with
+    # means `unload` + `setup`. This one is available to be used together with
     # `unregister`, which is undocumented too.
     #
     # @sig () -> void
@@ -254,21 +256,23 @@ module Zeitwerk
     # The return value of this predicate is only meaningful if the loader has
     # scanned the file. This is the case in the spots where we use it.
     #
-    # @private
     # @sig (String) -> Boolean
-    def shadowed_file?(file)
+    internal def shadowed_file?(file)
       shadowed_files.member?(file)
     end
 
     # --- Class methods ---------------------------------------------------------------------------
 
     class << self
+      include RealModName
+
       # @sig #call | #debug | nil
       attr_accessor :default_logger
 
       # This is a shortcut for
       #
       #   require "zeitwerk"
+      #
       #   loader = Zeitwerk::Loader.new
       #   loader.tag = File.basename(__FILE__, ".rb")
       #   loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
@@ -283,7 +287,36 @@ module Zeitwerk
       # @sig (bool) -> Zeitwerk::GemLoader
       def for_gem(warn_on_extra_files: true)
         called_from = caller_locations(1, 1).first.path
-        Registry.loader_for_gem(called_from, warn_on_extra_files: warn_on_extra_files)
+        Registry.loader_for_gem(called_from, namespace: Object, warn_on_extra_files: warn_on_extra_files)
+      end
+
+      # This is a shortcut for
+      #
+      #   require "zeitwerk"
+      #
+      #   loader = Zeitwerk::Loader.new
+      #   loader.tag = namespace.name + "-" + File.basename(__FILE__, ".rb")
+      #   loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
+      #   loader.push_dir(__dir__, namespace: namespace)
+      #
+      # except that this method returns the same object in subsequent calls from
+      # the same file, in the unlikely case the gem wants to be able to reload.
+      #
+      # This method returns a subclass of Zeitwerk::Loader, but the exact type
+      # is private, client code can only rely on the interface.
+      #
+      # @sig (bool) -> Zeitwerk::GemLoader
+      def for_gem_extension(namespace)
+        unless namespace.is_a?(Module) # Note that Class < Module.
+          raise Zeitwerk::Error, "#{namespace.inspect} is not a class or module object, should be"
+        end
+
+        unless real_mod_name(namespace)
+          raise Zeitwerk::Error, "extending anonymous namespaces is unsupported"
+        end
+
+        called_from = caller_locations(1, 1).first.path
+        Registry.loader_for_gem(called_from, namespace: namespace, warn_on_extra_files: false)
       end
 
       # Broadcasts `eager_load` to all loaders. Those that have not been setup
@@ -323,10 +356,8 @@ module Zeitwerk
       end
     end
 
-    private # -------------------------------------------------------------------------------------
-
     # @sig (String, Module) -> void
-    def set_autoloads_in_dir(dir, parent)
+    private def set_autoloads_in_dir(dir, parent)
       ls(dir) do |basename, abspath|
         begin
           if ruby?(basename)
@@ -361,13 +392,22 @@ module Zeitwerk
     end
 
     # @sig (Module, Symbol, String) -> void
-    def autoload_subdir(parent, cname, subdir)
+    private def autoload_subdir(parent, cname, subdir)
       if autoload_path = autoload_path_set_by_me_for?(parent, cname)
         cpath = cpath(parent, cname)
-        register_explicit_namespace(cpath) if ruby?(autoload_path)
-        # We do not need to issue another autoload, the existing one is enough
-        # no matter if it is for a file or a directory. Just remember the
-        # subdirectory has to be visited if the namespace is used.
+        if ruby?(autoload_path)
+          # Scanning visited a Ruby file first, and now a directory for the same
+          # constant has been found. This means we are dealing with an explicit
+          # namespace whose definition was seen first.
+          #
+          # 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(cpath)
+        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.
+        # Just remember the subdirectory conforms this namespace.
         namespace_dirs[cpath] << subdir
       elsif !cdef?(parent, cname)
         # First time we find this namespace, set an autoload for it.
@@ -382,7 +422,7 @@ module Zeitwerk
     end
 
     # @sig (Module, Symbol, String) -> void
-    def autoload_file(parent, cname, file)
+    private def autoload_file(parent, cname, file)
       if autoload_path = strict_autoload_path(parent, cname) || Registry.inception?(cpath(parent, cname))
         # First autoload for a Ruby file wins, just ignore subsequent ones.
         if ruby?(autoload_path)
@@ -408,7 +448,7 @@ module Zeitwerk
     # the file where we've found the namespace is explicitly defined.
     #
     # @sig (dir: String, file: String, parent: Module, cname: Symbol) -> void
-    def promote_namespace_from_implicit_to_explicit(dir:, file:, parent:, cname:)
+    private def promote_namespace_from_implicit_to_explicit(dir:, file:, parent:, cname:)
       autoloads.delete(dir)
       Registry.unregister_autoload(dir)
 
@@ -419,7 +459,7 @@ module Zeitwerk
     end
 
     # @sig (Module, Symbol, String) -> void
-    def set_autoload(parent, cname, abspath)
+    private def set_autoload(parent, cname, abspath)
       parent.autoload(cname, abspath)
 
       if logger
@@ -440,7 +480,7 @@ module Zeitwerk
     end
 
     # @sig (Module, Symbol) -> String?
-    def autoload_path_set_by_me_for?(parent, cname)
+    private def autoload_path_set_by_me_for?(parent, cname)
       if autoload_path = strict_autoload_path(parent, cname)
         autoload_path if autoloads.key?(autoload_path)
       else
@@ -449,12 +489,12 @@ module Zeitwerk
     end
 
     # @sig (String) -> void
-    def register_explicit_namespace(cpath)
+    private def register_explicit_namespace(cpath)
       ExplicitNamespace.__register(cpath, self)
     end
 
     # @sig (String) -> void
-    def raise_if_conflicting_directory(dir)
+    private def raise_if_conflicting_directory(dir)
       MUTEX.synchronize do
         dir_slash = dir + "/"
 
@@ -479,23 +519,23 @@ module Zeitwerk
     end
 
     # @sig (String, Object, String) -> void
-    def run_on_unload_callbacks(cpath, value, abspath)
+    private def run_on_unload_callbacks(cpath, value, abspath)
       # Order matters. If present, run the most specific one.
       on_unload_callbacks[cpath]&.each { |c| c.call(value, abspath) }
       on_unload_callbacks[:ANY]&.each { |c| c.call(cpath, value, abspath) }
     end
 
     # @sig (Module, Symbol) -> void
-    def unload_autoload(parent, cname)
-      parent.__send__(:remove_const, cname)
+    private def unload_autoload(parent, cname)
+      crem(parent, cname)
       log("autoload for #{cpath(parent, cname)} removed") if logger
     end
 
     # @sig (Module, Symbol) -> void
-    def unload_cref(parent, cname)
+    private def unload_cref(parent, cname)
       # Let's optimistically remove_const. The way we use it, this is going to
       # succeed always if all is good.
-      parent.__send__(:remove_const, cname)
+      crem(parent, cname)
     rescue ::NameError
       # There are a few edge scenarios in which this may happen. If the constant
       # is gone, that is OK, anyway.

data/lib/zeitwerk/registry.rb

@@ -86,8 +86,8 @@ module Zeitwerk
       #
       # @private
       # @sig (String) -> Zeitwerk::Loader
-      def loader_for_gem(root_file, warn_on_extra_files:)
-        gem_loaders_by_root_file[root_file] ||= GemLoader._new(root_file, warn_on_extra_files: warn_on_extra_files)
+      def loader_for_gem(root_file, namespace:, warn_on_extra_files:)
+        gem_loaders_by_root_file[root_file] ||= GemLoader.__new(root_file, namespace: namespace, warn_on_extra_files: warn_on_extra_files)
       end
 
       # @private

data/lib/zeitwerk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.6
+  version: 2.6.8
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-08 00:00:00.000000000 Z
+date: 2023-04-28 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -61,7 +61,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.4.11
 signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader