zeitwerk 2.1.7 → 2.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cf7265c8e1a167cdf0107bdef2643d219317855b0f5a06b77048672e3a192a3
-  data.tar.gz: d1429158609c03b57f85b261290e61d88c7762f02693232336a0f4eb94bc7417
+  metadata.gz: b7d5a0f54405ad45dd6afc9bf54bde579f66a75fb142cdbbfb5476157dd75493
+  data.tar.gz: b81311bb19c3b699a6720a3bb3d6df503b858a439c5f1f2605e029117de36bcb
 SHA512:
-  metadata.gz: 3457b0e4afeb1e134db7815e538c8251aab11bda9b9feb8eec07257506786693f9f9ec0c0eb7a11c0663502f48778b37939cb47483d84b369ed82830518ff78a
-  data.tar.gz: 4996a053629f48004cb4c86f24a649295baaf1afbde0a2a5b5be0c3163205376659382ac3a9322586e2b86fee200c8bf97c5bb8faa2ae17c19aa0b169457af09
+  metadata.gz: 4f6fd6e8f7bd479ca6935d1f57d065151aff3be6977ad068f6b4ecdce200bbd131f4db4f2cc1bc2a719cb332b538cf24be55eb936a51572ac5c06676d21763f2
+  data.tar.gz: d4266c65e380b356ff4df7394f2f1882f72ac32b5226dedd717f6b4064c8ac1b8fd3d70ec08b6f9838debfc3690d2f3eee2d6885e446f087a686a619c872c718

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2019–ω Xavier Noria
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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/travis/com/fxn/zeitwerk.svg?style=for-the-badge&branch=master)](https://travis-ci.com/fxn/zeitwerk)
+[![Build Status](https://img.shields.io/travis/com/fxn/zeitwerk/master?style=for-the-badge)](https://travis-ci.com/fxn/zeitwerk)
 
 <!-- TOC -->
 
@@ -17,7 +17,6 @@
     - [Setup](#setup)
     - [Reloading](#reloading)
     - [Eager loading](#eager-loading)
-    - [Preloading](#preloading)
     - [Inflection](#inflection)
         - [Zeitwerk::Inflector](#zeitwerkinflector)
         - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
@@ -30,8 +29,10 @@
         - [Use case: Test files mixed with implementation files](#use-case-test-files-mixed-with-implementation-files)
     - [Edge cases](#edge-cases)
     - [Rules of thumb](#rules-of-thumb)
+    - [Autoloading, explicit namespaces, and debuggers](#autoloading-explicit-namespaces-and-debuggers)
 - [Pronunciation](#pronunciation)
 - [Supported Ruby versions](#supported-ruby-versions)
+- [Testing](#testing)
 - [Motivation](#motivation)
 - [Thanks](#thanks)
 - [License](#license)
@@ -61,12 +62,13 @@ Main interface for gems:
 
 require "zeitwerk"
 loader = Zeitwerk::Loader.for_gem
-loader.setup      # ready!
-loader.eager_load # optionally
+loader.setup # ready!
 
 module MyGem
   # ...
 end
+
+loader.eager_load # optionally
 ```
 
 Main generic interface:
@@ -199,6 +201,22 @@ loader.setup
 
 The loader returned by `Zeitwerk::Loader.for_gem` has the directory of the caller pushed, normally that is the absolute path of `lib`. In that sense, `for_gem` can be used also by projects with a gem structure, even if they are not technically gems. That is, you don't need a gemspec or anything.
 
+If the main module of a library references project constants at the top-level, Zeitwerk has to be ready to load them. Their definitions, in turn, may reference other project constants. And this is recursive. Therefore, it is important that the `setup` call happens above the main module definition:
+
+```ruby
+# lib/my_gem.rb (main file)
+
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module MyGem
+  # Since the setup has been performed, at this point we are already able
+  # to reference project constants, in this case MyGem::MyLogger.
+  include MyLogger
+end
+```
+
 Zeitwerk works internally only with absolute paths to avoid costly file searches in `$LOAD_PATH`. Indeed, the root directories do not even need to belong to `$LOAD_PATH`, everything just works by design if they don't.
 
 <a id="markdown-reloading" name="reloading"></a>
@@ -221,7 +239,7 @@ Enabling reloading after setup raises `Zeitwerk::Error`. Similarly, calling `rel
 
 Generally speaking, reloading is useful while developing running services like web applications. Gems that implement regular libraries, so to speak, or services running in testing or production environments, won't normally have a use case for reloading. If reloading is not enabled, Zeitwerk is able to use less memory.
 
-Reloading removes the currently loaded classes and modules, resets the loader so that it will pick whatever is in the file system now, and runs preloads if there are any.
+Reloading removes the currently loaded classes and modules and resets the loader so that it will pick whatever is in the file system now.
 
 It is important to highlight that this is an instance method. Don't worry about project dependencies managed by Zeitwerk, their loaders are independent.
 
@@ -247,6 +265,8 @@ loader.setup
 loader.eager_load # won't eager load the database adapters
 ```
 
+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).
+
 Eager loading is synchronized and idempotent.
 
 If you want to eager load yourself and all dependencies using Zeitwerk, you can broadcast the `eager_load` call to all instances:
@@ -259,22 +279,6 @@ This may be handy in top-level services, like web applications.
 
 Note that thanks to idempotence `Zeitwerk::Loader.eager_load_all` won't eager load twice if any of the instances already eager loaded.
 
-<a id="markdown-preloading" name="preloading"></a>
-### Preloading
-
-Zeitwerk instances are able to preload files and directories.
-
-```ruby
-loader.preload("app/models/videogame.rb")
-loader.preload("app/models/book.rb")
-```
-
-The call can happen before `setup` (preloads during setup), or after `setup` (preloads on the spot). Each reload preloads too.
-
-This is a feature specifically thought for STIs in Rails, preloading the leafs of a STI tree ensures all classes are known when doing a query.
-
-The example above depicts several calls are supported, but `preload` accepts multiple arguments and arrays of strings as well.
-
 <a id="markdown-inflection" name="inflection"></a>
 ### Inflection
 
@@ -291,14 +295,34 @@ users_controller -> UsersController
 html_parser      -> HtmlParser
 ```
 
+The camelize logic can be overridden easily for individual basenames:
+
+```ruby
+loader.inflector.inflect(
+  "html_parser"   => "HTMLParser",
+  "mysql_adapter" => "MySQLAdapter"
+)
+```
+
+The `inflect` method can be invoked several times if you prefer this other style:
+
+```ruby
+loader.inflector.inflect "html_parser" => "HTMLParser"
+loader.inflector.inflect "mysql_adapter" => "MySQLAdapter"
+```
+
+Overrides need to be configured before calling `setup`.
+
 There are no inflection rules or global configuration that can affect this inflector. It is deterministic.
 
-This is the default inflector.
+Loaders instantiated with `Zeitwerk::Loader.new` have an inflector of this type, independent of each other.
 
 <a id="markdown-zeitwerkgeminflector" name="zeitwerkgeminflector"></a>
 #### Zeitwerk::GemInflector
 
-The loader instantiated behind the scenes by `Zeitwerk::Loader.for_gem` gets assigned by default an inflector that is like the basic one, except it expects `lib/my_gem/version.rb` to define `MyGem::VERSION`.
+This inflector is like the basic one, except it expects `lib/my_gem/version.rb` to define `MyGem::VERSION`.
+
+Loaders instantiated with `Zeitwerk::Loader.for_gem` have an inflector of this type, independent of each other.
 
 <a id="markdown-custom-inflector" name="custom-inflector"></a>
 #### Custom inflector
@@ -309,12 +333,9 @@ The inflectors that ship with Zeitwerk are deterministic and simple. But you can
 # frozen_string_literal: true
 
 class MyInflector < Zeitwerk::Inflector
-  def camelize(basename, _abspath)
-    case basename
-    when "api"
-      "API"
-    when "mysql_adapter"
-      "MySQLAdapter"
+  def camelize(basename, abspath)
+    if basename =~ /\Ahtml_(.*)/
+      "HTML" + super($1, abspath)
     else
       super
     end
@@ -334,6 +355,49 @@ loader.inflector = MyInflector.new
 
 This needs to be done before calling `setup`.
 
+If a custom inflector definition in a gem takes too much space in the main file, you can extract it. For example, this is a simple pattern:
+
+```ruby
+# lib/my_gem/inflector.rb
+module MyGem
+  class Inflector < Zeitwerk::GemInflector
+    ...
+  end
+end
+
+# lib/my_gem.rb
+require "zeitwerk"
+require_relative "my_gem/inflector"
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector = MyGem::Inflector.new(__FILE__)
+loader.setup
+
+module MyGem
+  # ...
+end
+```
+
+Since `MyGem` is referenced before the namespace is defined in the main file, it is important to use this style:
+
+```ruby
+# Correct, effectively defines MyGem.
+module MyGem
+  class Inflector < Zeitwerk::GemInflector
+    # ...
+  end
+end
+```
+
+instead of:
+
+```ruby
+# Raises uninitialized constant MyGem (NameError).
+class MyGem::Inflector < Zeitwerk::GemInflector
+  # ...
+end
+```
+
 <a id="markdown-logging" name="logging"></a>
 ### Logging
 
@@ -399,7 +463,7 @@ Zeitwerk ignores automatically any file or directory whose name starts with a do
 
 However, sometimes it might still be convenient to tell Zeitwerk to completely ignore some particular Ruby file or directory. That is possible with `ignore`, which accepts an arbitrary number of strings or `Pathname` objects, and also an array of them.
 
-You can ignore file names, directory names, and glob patterns. Glob patterns are expanded on setup and on reload.
+You can ignore file names, directory names, and glob patterns. Glob patterns are expanded when they are added and again on each reload.
 
 Let's see some use cases.
 
@@ -460,6 +524,8 @@ The chosen adapter, then, has to be loaded by hand somehow:
 require "my_gem/db_adapters/#{config[:db_adapter]}"
 ```
 
+Note that since the directory is ignored, the required adapter can instantiate another loader to manage its subtree, if desired. Such loader would coexist with the main one just fine.
+
 <a id="markdown-use-case-test-files-mixed-with-implementation-files" name="use-case-test-files-mixed-with-implementation-files"></a>
 #### Use case: Test files mixed with implementation files
 
@@ -515,6 +581,15 @@ This only affects explicit namespaces, those idioms work well for any other ordi
 
 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-autoloading-explicit-namespaces-and-debuggers" name="autoloading-explicit-namespaces-and-debuggers"></a>
+### Autoloading, explicit namespaces, and debuggers
+
+As of this writing, Zeitwerk is unable to autoload classes or modules that belong to [explicit namespaces](#explicit-namespaces) inside debugger sessions. You'll get a `NameError`.
+
+The root cause is that debuggers set trace points, and Zeitwerk does too to support explicit namespaces. A debugger session happens inside a trace point handler, and Ruby does not invoke other handlers from within a running handler. Therefore, the code that manages explicit namespaces in Zeitwerk does not get called by the interpreter. See [this issue](https://github.com/deivid-rodriguez/byebug/issues/564#issuecomment-499413606) for further details.
+
+As a workaround, you can eager load. Zeitwerk tries hard to succeed or fail consistently both autoloading and eager loading, so switching to eager loading should not introduce any interference in your debugging logic, generally speaking.
+
 <a id="markdown-pronunciation" name="pronunciation"></a>
 ## Pronunciation
 
@@ -525,6 +600,32 @@ This only affects explicit namespaces, those idioms work well for any other ordi
 
 Zeitwerk works with MRI 2.4.4 and above.
 
+<a id="markdown-testing" name="testing"></a>
+## Testing
+
+In order to run the test suite of Zeitwerk, `cd` into the project root and execute
+
+```
+bin/test
+```
+
+To run one particular suite, pass its file name as an argument:
+
+```
+bin/test test/lib/zeitwerk/test_eager_load.rb
+```
+
+Furthermore, the project has a development dependency on [`minitest-focus`](https://github.com/seattlerb/minitest-focus). To run an individual test mark it with `focus`:
+
+```ruby
+focus
+test "capitalizes the first letter" do
+  assert_equal "User", camelize("user")
+end
+```
+
+and run `bin/test`.
+
 <a id="markdown-motivation" name="motivation"></a>
 ## Motivation
 
@@ -539,6 +640,8 @@ I'd like to thank [@matthewd](https://github.com/matthewd) for the discussions w
 
 Also, would like to thank [@Shopify](https://github.com/Shopify), [@rafaelfranca](https://github.com/rafaelfranca), and [@dylanahsmith](https://github.com/dylanahsmith), for sharing [this PoC](https://github.com/Shopify/autoload_reloader). The technique Zeitwerk uses to support explicit namespaces was copied from that project.
 
+Jean Boussier ([@casperisfine](https://github.com/casperisfine), [@byroot](https://github.com/byroot)) deserves special mention. Jean migrated autoloading in Shopify when Zeitwerk integration in Rails was yet unreleased. His work and positive attitude have been outstanding, and thanks to his feedback the interface and performance of Zeitwerk are way, way better. Kudos man ❤️.
+
 Finally, many thanks to [@schurig](https://github.com/schurig) for recording an [audio file](http://share.hashref.com/zeitwerk/zeitwerk_pronunciation.mp3) with the pronunciation of "Zeitwerk" in perfect German. 💯
 
 <a id="markdown-license" name="license"></a>

data/lib/zeitwerk.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Zeitwerk
+  require_relative "zeitwerk/real_mod_name"
   require_relative "zeitwerk/loader"
   require_relative "zeitwerk/registry"
   require_relative "zeitwerk/explicit_namespace"

data/lib/zeitwerk/error.rb

@@ -4,4 +4,7 @@ module Zeitwerk
 
   class ReloadingDisabledError < Error
   end
+
+  class NameError < ::NameError
+  end
 end

data/lib/zeitwerk/explicit_namespace.rb

@@ -8,6 +8,8 @@ module Zeitwerk
   # loading their constant before setup. This is documented.
   module ExplicitNamespace # :nodoc: all
     class << self
+      include RealModName
+
       # Maps constant paths that correspond to explicit namespaces according to
       # the file system, to the loader responsible for them.
       #
@@ -52,21 +54,27 @@ module Zeitwerk
           tracer.disable if cpaths.empty?
         end
       end
+
+      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?
+
+        # Note that it makes sense to compute the hash code unconditionally,
+        # because the trace point is disabled if cpaths is empty.
+        if loader = cpaths.delete(real_mod_name(event.self))
+          loader.on_namespace_loaded(event.self)
+          disable_tracer_if_unneeded
+        end
+      end
     end
 
     @cpaths = {}
     @mutex  = Mutex.new
-    @tracer = TracePoint.new(:class) do |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 `Module#name`.
-      next if event.self.singleton_class?
 
-      # Note that it makes sense to compute the hash code unconditionally,
-      # because the trace point is disabled if cpaths is empty.
-      if loader = cpaths.delete(event.self.name)
-        loader.on_namespace_loaded(event.self)
-        disable_tracer_if_unneeded
-      end
-    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))
   end
 end

data/lib/zeitwerk/gem_inflector.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  class GemInflector < Inflector # :nodoc:
+  class GemInflector < Inflector
     # @param root_file [String]
     def initialize(root_file)
       namespace     = File.basename(root_file, ".rb")
@@ -13,7 +13,7 @@ module Zeitwerk
     # @param abspath [String]
     # @return [String]
     def camelize(basename, abspath)
-      (basename == "version" && abspath == @version_file) ? "VERSION" : super
+      abspath == @version_file ? "VERSION" : super
     end
   end
 end

data/lib/zeitwerk/inflector.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  class Inflector # :nodoc:
+  class Inflector
     # Very basic snake case -> camel case conversion.
     #
     #   inflector = Zeitwerk::Inflector.new
@@ -9,11 +9,41 @@ module Zeitwerk
     #   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]
     def camelize(basename, _abspath)
-      basename.split('_').map!(&:capitalize).join
+      overrides[basename] || basename.split('_').map!(&:capitalize).join
+    end
+
+    # Configures hard-coded inflections:
+    #
+    #   inflector = Zeitwerk::Inflector.new
+    #   inflector.inflect(
+    #     "html_parser"   => "HTMLParser",
+    #     "mysql_adapter" => "MySQLAdapter"
+    #   )
+    #
+    #   inflector.camelize("html_parser", abspath)      # => "HTMLParser"
+    #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
+    #   inflector.camelize("users_controller", abspath) # => "UsersController"
+    #
+    # @param inflections [{String => String}]
+    # @return [void]
+    def inflect(inflections)
+      overrides.merge!(inflections)
+    end
+
+    private
+
+    # Hard-coded basename to constant name user maps that override the default
+    # inflection logic.
+    #
+    # @return [{String => String}]
+    def overrides
+      @overrides ||= {}
     end
   end
 end

data/lib/zeitwerk/loader.rb

@@ -7,6 +7,7 @@ module Zeitwerk
   class Loader
     require_relative "loader/callbacks"
     include Callbacks
+    include RealModName
 
     # @return [String]
     attr_reader :tag
@@ -43,7 +44,7 @@ module Zeitwerk
     #
     # @private
     # @return [Set<String>]
-    attr_reader :ignored
+    attr_reader :ignored_glob_patterns
 
     # The actual collection of absolute file and directory names at the time the
     # ignored glob patterns were expanded. Computed on setup, and recomputed on
@@ -132,7 +133,7 @@ module Zeitwerk
 
       @root_dirs             = {}
       @preloads              = []
-      @ignored               = Set.new
+      @ignored_glob_patterns = Set.new
       @ignored_paths         = Set.new
       @autoloads             = {}
       @autoloaded_dirs       = []
@@ -224,16 +225,12 @@ module Zeitwerk
     #
     # @param paths [<String, Pathname, <String, Pathname>>]
     # @return [void]
-    def ignore(*paths)
-      mutex.synchronize { ignored.merge(expand_paths(paths)) }
-    end
-
-    # @private
-    # @return [void]
-    def expand_ignored_glob_patterns
-      # Note that Dir.glob works with regular file names just fine. That is,
-      # glob patterns technically need no wildcards.
-      ignored_paths.replace(ignored.flat_map { |path| Dir.glob(path) })
+    def ignore(*glob_patterns)
+      glob_patterns = expand_paths(glob_patterns)
+      mutex.synchronize do
+        ignored_glob_patterns.merge(glob_patterns)
+        ignored_paths.merge(expand_glob_patterns(glob_patterns))
+      end
     end
 
     # Sets autoloads in the root namespace and preloads files, if any.
@@ -243,7 +240,6 @@ module Zeitwerk
       mutex.synchronize do
         break if @setup
 
-        expand_ignored_glob_patterns
         actual_root_dirs.each { |root_dir| set_autoloads_in_dir(root_dir, Object) }
         do_preload
 
@@ -325,6 +321,7 @@ module Zeitwerk
     def reload
       if reloading_enabled?
         unload
+        recompute_ignored_paths
         setup
       else
         raise ReloadingDisabledError, "can't reload, please call loader.enable_reloading before setup"
@@ -353,7 +350,7 @@ module Zeitwerk
               if cref = autoloads[File.realpath(abspath)]
                 cref[0].const_get(cref[1], false)
               end
-            elsif dir?(abspath)
+            elsif dir?(abspath) && !root_dirs.key?(abspath)
               cname = inflector.camelize(basename, abspath)
               queue << [namespace.const_get(cname, false), abspath]
             end
@@ -402,6 +399,22 @@ module Zeitwerk
       @logger = ->(msg) { puts msg }
     end
 
+    # @private
+    # @param dir [String]
+    # @return [Boolean]
+    def manages?(dir)
+      dir = dir + "/"
+      ignored_paths.each do |ignored_path|
+        return false if dir.start_with?(ignored_path + "/")
+      end
+
+      root_dirs.each_key do |root_dir|
+        return true if root_dir.start_with?(dir) || dir.start_with?(root_dir + "/")
+      end
+
+      false
+    end
+
     # --- Class methods ---------------------------------------------------------------------------
 
     class << self
@@ -461,21 +474,38 @@ module Zeitwerk
     # @return [void]
     def set_autoloads_in_dir(dir, parent)
       ls(dir) do |basename, abspath|
-        if ruby?(basename)
-          basename.slice!(-3, 3)
-          cname = inflector.camelize(basename, abspath).to_sym
-          autoload_file(parent, cname, abspath)
-        elsif dir?(abspath)
-          # In a Rails application, `app/models/concerns` is a subdirectory of
-          # `app/models`, but both of them are root directories.
-          #
-          # To resolve the ambiguity file name -> constant path this introduces,
-          # the `app/models/concerns` directory is totally ignored as a namespace,
-          # it counts only as root. The guard checks that.
-          unless root_dirs.key?(abspath)
+        begin
+          if ruby?(basename)
+            basename.slice!(-3, 3)
             cname = inflector.camelize(basename, abspath).to_sym
-            autoload_subdir(parent, cname, abspath)
+            autoload_file(parent, cname, abspath)
+          elsif dir?(abspath)
+            # In a Rails application, `app/models/concerns` is a subdirectory of
+            # `app/models`, but both of them are root directories.
+            #
+            # To resolve the ambiguity file name -> constant path this introduces,
+            # the `app/models/concerns` directory is totally ignored as a namespace,
+            # it counts only as root. The guard checks that.
+            unless root_dirs.key?(abspath)
+              cname = inflector.camelize(basename, abspath).to_sym
+              autoload_subdir(parent, cname, abspath)
+            end
           end
+        rescue ::NameError => error
+          path_type = ruby?(abspath) ? "file" : "directory"
+
+          raise NameError, <<~MESSAGE
+            #{error.message} inferred by #{inflector.class} from #{path_type}
+
+              #{abspath}
+
+            Possible ways to address this:
+
+              * Tell Zeitwerk to ignore this particular #{path_type}.
+              * Tell Zeitwerk to ignore one of its parent directories.
+              * Rename the #{path_type} to comply with the naming conventions.
+              * Modify the inflector to handle this case.
+          MESSAGE
         end
       end
     end
@@ -593,8 +623,14 @@ module Zeitwerk
     # @param parent [Module]
     # @param cname [Symbol]
     # @return [String, nil]
-    def strict_autoload_path(parent, cname)
-      parent.autoload?(cname) if cdef?(parent, cname)
+    if method(:autoload?).arity == 1
+      def strict_autoload_path(parent, cname)
+        parent.autoload?(cname) if cdef?(parent, cname)
+      end
+    else
+      def strict_autoload_path(parent, cname)
+        parent.autoload?(cname, false)
+      end
     end
 
     # This method is called this way because I prefer `preload` to be the method
@@ -636,7 +672,7 @@ module Zeitwerk
     # @param cname [Symbol]
     # @return [String]
     def cpath(parent, cname)
-      parent.equal?(Object) ? cname.to_s : "#{parent.name}::#{cname}"
+      parent.equal?(Object) ? cname.to_s : "#{real_mod_name(parent)}::#{cname}"
     end
 
     # @param dir [String]
@@ -665,7 +701,20 @@ module Zeitwerk
     # @param paths [<String, Pathname, <String, Pathname>>]
     # @return [<String>]
     def expand_paths(paths)
-      Array(paths).flatten.map! { |path| File.expand_path(path) }
+      paths.flatten.map! { |path| File.expand_path(path) }
+    end
+
+    # @param glob_patterns [<String>]
+    # @return [<String>]
+    def expand_glob_patterns(glob_patterns)
+      # Note that Dir.glob works with regular file names just fine. That is,
+      # glob patterns technically need no wildcards.
+      glob_patterns.flat_map { |glob_pattern| Dir.glob(glob_pattern) }
+    end
+
+    # @return [void]
+    def recompute_ignored_paths
+      ignored_paths.replace(expand_glob_patterns(ignored_glob_patterns))
     end
 
     # @param message [String]
@@ -686,16 +735,12 @@ module Zeitwerk
     def raise_if_conflicting_directory(dir)
       self.class.mutex.synchronize do
         Registry.loaders.each do |loader|
-          next if loader == self
-
-          loader.dirs.each do |already_managed_dir|
-            if dir.start_with?(already_managed_dir) || already_managed_dir.start_with?(dir)
-              require "pp"
-              raise Error,
-                "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{dir}," \
-                " which is already managed by\n\n#{loader.pretty_inspect}\n"
-              EOS
-            end
+          if loader != self && loader.manages?(dir)
+            require "pp"
+            raise Error,
+              "loader\n\n#{pretty_inspect}\n\nwants to manage directory #{dir}," \
+              " which is already managed by\n\n#{loader.pretty_inspect}\n"
+            EOS
           end
         end
       end

data/lib/zeitwerk/loader/callbacks.rb

@@ -1,4 +1,6 @@
 module Zeitwerk::Loader::Callbacks
+  include Zeitwerk::RealModName
+
   # Invoked from our decorated Kernel#require when a managed file is autoloaded.
   #
   # @private
@@ -12,7 +14,7 @@ module Zeitwerk::Loader::Callbacks
     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"
+      raise Zeitwerk::NameError, "expected file #{file} to define constant #{cpath(*cref)}, but didn't"
     end
   end
 
@@ -60,7 +62,7 @@ module Zeitwerk::Loader::Callbacks
   # @param namespace [Module]
   # @return [void]
   def on_namespace_loaded(namespace)
-    if subdirs = lazy_subdirs.delete(namespace.name)
+    if subdirs = lazy_subdirs.delete(real_mod_name(namespace))
       subdirs.each do |subdir|
         set_autoloads_in_dir(subdir, namespace)
       end

data/lib/zeitwerk/real_mod_name.rb

@@ -0,0 +1,21 @@
+module Zeitwerk::RealModName
+  UNBOUND_METHOD_MODULE_NAME = Module.instance_method(:name)
+  private_constant :UNBOUND_METHOD_MODULE_NAME
+
+  # Returns the real name of the class or module, as set after the first
+  # constant to which it was assigned (or nil).
+  #
+  # The name method can be overridden, hence the indirection in this method.
+  #
+  # @param mod [Class, Module]
+  # @return [String, nil]
+  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
+  end
+end

data/lib/zeitwerk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.1.7
+  version: 2.2.1
 platform: ruby
 authors:
 - Xavier Noria
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-06-28 00:00:00.000000000 Z
+date: 2019-11-01 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -20,6 +20,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- MIT-LICENSE
 - README.md
 - lib/zeitwerk.rb
 - lib/zeitwerk/error.rb
@@ -29,6 +30,7 @@ files:
 - lib/zeitwerk/kernel.rb
 - lib/zeitwerk/loader.rb
 - lib/zeitwerk/loader/callbacks.rb
+- lib/zeitwerk/real_mod_name.rb
 - lib/zeitwerk/registry.rb
 - lib/zeitwerk/version.rb
 homepage: https://github.com/fxn/zeitwerk