zeitwerk 2.1.6 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43750607caaaa5d4fff5bd52204cafb98fbd5109b51a24d9099ba83c6a2a4990
-  data.tar.gz: 8ad3251fd93af9e66a9102c13556beff5805a38660d69e4c5de37e2808e76d8f
+  metadata.gz: 2af50b4d74832ccd3c08e3445c09a941ed56758c57acd20e8d88436f79e16ea2
+  data.tar.gz: 23f693ca2b9fc44870c26991cd91c587031825e9d29c90dd5285f2c7a3731f6a
 SHA512:
-  metadata.gz: e6e87877104078f564686a15b81882a8e20a560a36999e0f8b9916aa520dd46fe1a2b7f65cacdb7b6c62d252472b6ce1370939054f026a335e21652881820814
-  data.tar.gz: 3641d412ab4b9176861b9ed9b28ea7964b6a814ebb72804c96967e511562fb87f424c48d7780345be8ccd2c53bdacfe095e3e5173e166a4185bf389740258ca6
+  metadata.gz: 1d47e1a735c5314ec56f9c16d66695222209109dddb7da3a663969b852295eed82d8eee56fc48a48cb6b0604e508940f474533e98c7d824175c344420a64baec
+  data.tar.gz: be275743889771c745fc90d300a4cbd01911b5b4547c41ea1df6429af1357b9328fb69293a03a282677295f27528220f180f1ca943f43b5567677b856baa3e06

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)
@@ -29,6 +28,8 @@
         - [Use case: The adapter pattern](#use-case-the-adapter-pattern)
         - [Use case: Test files mixed with implementation files](#use-case-test-files-mixed-with-implementation-files)
     - [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)
 - [Motivation](#motivation)
@@ -42,15 +43,13 @@
 
 Zeitwerk is an efficient and thread-safe code loader for Ruby.
 
-Given a conventional file structure, Zeitwerk loads your project's classes and modules on demand. You don't need to write `require` calls for your own files, rather, you can streamline your programming knowing that your classes and modules are available everywhere. This feature is efficient, thread-safe, and matches Ruby's semantics for constants.
+Given a [conventional file structure](#file-structure), Zeitwerk is able to load your project's classes and modules on demand (autoloading), or upfront (eager loading). You don't need to write `require` calls for your own files, rather, you can streamline your programming knowing that your classes and modules are available everywhere. This feature is efficient, thread-safe, and matches Ruby's semantics for constants.
 
-Zeitwerk issues `require` calls exclusively using absolute file names, so there are no costly file system lookups in `$LOAD_PATH`. Technically, the directories managed by Zeitwerk do not even need to be in `$LOAD_PATH`. Furthermore, by design, Zeitwerk does only one single scan of the project tree, and it descends into subdirectories lazily, only if their namespaces are used.
+Zeitwerk is also able to reload code, which may be handy while developing web applications. Coordination is needed to reload in a thread-safe manner. The documentation below explains how to do this.
 
-The library is designed so that each gem and application can have their own loader, independent of each other. Each loader has its own configuration, inflector, and optional logger.
+The gem is designed so that any project, gem dependency, application, etc. can have their own independent loader, coexisting in the same process, managing their own project trees, and independent of each other. Each loader has its own configuration, inflector, and optional logger.
 
-Zeitwerk is also able to reload code, which may be handy for web applications. Coordination is needed to reload in a thread-safe manner. The documentation below explains how to do this.
-
-Finally, in some production setups it may be optimal to eager load all code upfront. Zeitwerk is able to do that too.
+Internally, Zeitwerk issues `require` calls exclusively using absolute file names, so there are no costly file system lookups in `$LOAD_PATH`. Technically, the directories managed by Zeitwerk do not even need to be in `$LOAD_PATH`. Furthermore, Zeitwerk does only one single scan of the project tree, and it descends into subdirectories lazily, only if their namespaces are used.
 
 <a id="markdown-synopsis" name="synopsis"></a>
 ## Synopsis
@@ -63,11 +62,12 @@ Main interface for gems:
 require "zeitwerk"
 loader = Zeitwerk::Loader.for_gem
 loader.setup # ready!
-# loader.eager_load, optionally
 
 module MyGem
   # ...
 end
+
+loader.eager_load # optionally
 ```
 
 Main generic interface:
@@ -200,12 +200,28 @@ 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>
 ### Reloading
 
-Zeitwer is able to reload code, but you need to enable this feature:
+Zeitwerk is able to reload code, but you need to enable this feature:
 
 ```ruby
 loader = Zeitwerk::Loader.new
@@ -222,7 +238,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.
 
@@ -248,6 +264,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:
@@ -260,22 +278,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
 
@@ -292,14 +294,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
@@ -310,12 +332,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
@@ -335,12 +354,55 @@ 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
 
 Zeitwerk is silent by default, but you can ask loaders to trace their activity. Logging is meant just for troubleshooting, shouldn't normally be enabled.
 
-The `log!` mehtod is a quick shortcut to let the loader log to `$stdout`:
+The `log!` method is a quick shortcut to let the loader log to `$stdout`:
 
 ```
 loader.log!
@@ -400,7 +462,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.
 
@@ -461,6 +523,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
 
@@ -501,6 +565,30 @@ Trip = Struct.new { ... } # NOT SUPPORTED
 
 This only affects explicit namespaces, those idioms work well for any other ordinary class or module.
 
+<a id="markdown-rules-of-thumb" name="rules-of-thumb"></a>
+### Rules of thumb
+
+1. Different loaders should manage different directory trees. It is an error condition to configure overlapping root directories in different loaders.
+
+2. Think the mere existence of a file is effectively like writing a `require` call for them, which is executed on demand (autoload) or upfront (eager load).
+
+3. In that line, if two loaders manage files that translate to the same constant in the same namespace, the first one wins, the rest are ignored. Similar to what happens with `require` and `$LOAD_PATH`, only the first occurrence matters.
+
+4. Projects that reopen a namespace defined by some dependency have to ensure said namespace is loaded before setup. That is, the project has to make sure it reopens, rather than define. This is often accomplished just loading the dependency.
+
+5. Objects stored in reloadable constants should not be cached in places that are not reloaded. For example, non-reloadable classes should not subclass a reloadable class, or mixin a reloadable module. Otherwise, after reloading, those classes or module objects would become stale. Referring to constants in dynamic places like method calls or lambdas is fine.
+
+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
 

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

@@ -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) # => "PostsController"
+    #
+    # @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
@@ -53,23 +54,6 @@ module Zeitwerk
     # @return [Set<String>]
     attr_reader :ignored_paths
 
-    # A _shadowed file_ is a file managed by this loader that is ignored when
-    # setting autoloads because its matching constant is taken. Either the
-    # constant is already defined, or there exists an autoload for it.
-    #
-    # Think $LOAD_PATH and require, only the first occurrence of a given
-    # relative name is loaded.
-    #
-    # This set keeps track of the absolute path of shadowed files, to be able to
-    # skip them while eager loading.
-    #
-    # Note this cannot be implemented with do_not_eager_load because these
-    # files are not autoloadable.
-    #
-    # @private
-    # @return [Set<String>]
-    attr_reader :shadowed_files
-
     # Maps real absolute paths for which an autoload has been set ---and not
     # executed--- to their corresponding parent class or module and constant
     # name.
@@ -149,13 +133,12 @@ module Zeitwerk
 
       @root_dirs             = {}
       @preloads              = []
-      @ignored               = Set.new
+      @ignored_glob_patterns = Set.new
       @ignored_paths         = Set.new
       @autoloads             = {}
       @autoloaded_dirs       = []
       @to_unload             = {}
       @lazy_subdirs          = {}
-      @shadowed_files        = Set.new
       @eager_load_exclusions = Set.new
 
       # TODO: find a better name for these mutexes.
@@ -242,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.
@@ -261,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
 
@@ -324,7 +302,6 @@ module Zeitwerk
         autoloaded_dirs.clear
         to_unload.clear
         lazy_subdirs.clear
-        shadowed_files.clear
 
         Registry.on_unload(self)
         ExplicitNamespace.unregister(self)
@@ -344,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"
@@ -361,20 +339,24 @@ module Zeitwerk
         break if @eager_loaded
 
         queue = actual_root_dirs.reject { |dir| eager_load_exclusions.member?(dir) }
-        while dir = queue.shift
-          ls(dir) do |_basename, abspath|
+        queue.map! { |dir| [Object, dir] }
+        while to_eager_load = queue.shift
+          namespace, dir = to_eager_load
+
+          ls(dir) do |basename, abspath|
             next if eager_load_exclusions.member?(abspath)
 
             if ruby?(abspath)
-              require abspath unless shadowed_files.member?(abspath)
-            elsif dir?(abspath)
-              queue << abspath
+              if cref = autoloads[File.realpath(abspath)]
+                cref[0].const_get(cref[1], false)
+              end
+            elsif dir?(abspath) && !root_dirs.key?(abspath)
+              cname = inflector.camelize(basename, abspath)
+              queue << [namespace.const_get(cname, false), abspath]
             end
           end
         end
 
-        shadowed_files.clear
-
         autoloaded_dirs.each do |autoloaded_dir|
           Registry.unregister_autoload(autoloaded_dir)
         end
@@ -417,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
@@ -476,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
@@ -526,7 +541,6 @@ module Zeitwerk
       if autoload_path = autoload_for?(parent, cname)
         # First autoload for a Ruby file wins, just ignore subsequent ones.
         if ruby?(autoload_path)
-          shadowed_files.add(file)
           log("file #{file} is ignored because #{autoload_path} has precedence") if logger
         else
           promote_namespace_from_implicit_to_explicit(
@@ -537,7 +551,6 @@ module Zeitwerk
           )
         end
       elsif cdef?(parent, cname)
-        shadowed_files.add(file)
         log("file #{file} is ignored because #{cpath(parent, cname)} is already defined") if logger
       else
         set_autoload(parent, cname, file)
@@ -653,7 +666,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]
@@ -682,7 +695,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]
@@ -703,16 +729,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
@@ -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,15 @@
+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]
+  def real_mod_name(mod)
+    UNBOUND_METHOD_MODULE_NAME.bind(mod).call
+  end
+end

data/lib/zeitwerk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.1.6
+  version: 2.2.0
 platform: ruby
 authors:
 - Xavier Noria
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-30 00:00:00.000000000 Z
+date: 2019-10-09 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
@@ -50,7 +52,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.1
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader