zeitwerk 2.2.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2af50b4d74832ccd3c08e3445c09a941ed56758c57acd20e8d88436f79e16ea2
-  data.tar.gz: 23f693ca2b9fc44870c26991cd91c587031825e9d29c90dd5285f2c7a3731f6a
+  metadata.gz: 682fa352a9d6d4bf68d07cf2cbfbb539de3cfec4e8af2f930894ab27c707ca93
+  data.tar.gz: 1e7ce6157e6046cdb60f0f1b531f1f39fb97cad3537392114be5cf84dae672c9
 SHA512:
-  metadata.gz: 1d47e1a735c5314ec56f9c16d66695222209109dddb7da3a663969b852295eed82d8eee56fc48a48cb6b0604e508940f474533e98c7d824175c344420a64baec
-  data.tar.gz: be275743889771c745fc90d300a4cbd01911b5b4547c41ea1df6429af1357b9328fb69293a03a282677295f27528220f180f1ca943f43b5567677b856baa3e06
+  metadata.gz: e308baba1a8fbe4d7c64d7195c753d795a53caefa7264d2404117cb620f2081f6b0fc05c056dafb035b44430102e4472b7eb9fb3a4fd9d70aa124b7f9a3a8313
+  data.tar.gz: 5139d5abaeed86e256493b592460b13b19fd7602f7c099f7017b55af9f16a91429e84074a4e31fe79bf28235e02cbba3055cc4bda579bbc7de2a391c5997a393

data/README.md

@@ -12,11 +12,15 @@
 - [File structure](#file-structure)
     - [Implicit namespaces](#implicit-namespaces)
     - [Explicit namespaces](#explicit-namespaces)
+    - [Collapsing directories](#collapsing-directories)
     - [Nested root directories](#nested-root-directories)
 - [Usage](#usage)
     - [Setup](#setup)
-    - [Reloading](#reloading)
+        - [Generic](#generic)
+        - [for_gem](#for_gem)
+    - [Autoloading](#autoloading)
     - [Eager loading](#eager-loading)
+    - [Reloading](#reloading)
     - [Inflection](#inflection)
         - [Zeitwerk::Inflector](#zeitwerkinflector)
         - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
@@ -28,10 +32,14 @@
         - [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)
+    - [Reopening third-party namespaces](#reopening-third-party-namespaces)
     - [Rules of thumb](#rules-of-thumb)
-    - [Autoloading, explicit namespaces, and debuggers](#autoloading-explicit-namespaces-and-debuggers)
+    - [Debuggers](#debuggers)
+        - [Break](#break)
+        - [Byebug](#byebug)
 - [Pronunciation](#pronunciation)
 - [Supported Ruby versions](#supported-ruby-versions)
+- [Testing](#testing)
 - [Motivation](#motivation)
 - [Thanks](#thanks)
 - [License](#license)
@@ -49,7 +57,9 @@ Zeitwerk is also able to reload code, which may be handy while developing web ap
 
 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.
 
-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.
+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 at most 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
@@ -129,6 +139,22 @@ app/models/user.rb                        -> User
 app/controllers/admin/users_controller.rb -> Admin::UsersController
 ```
 
+Alternatively, you can associate a custom namespace to a root directory by passing a class or module object in the optional `namespace` keyword argument.
+
+For example, Active Job queue adapters have to define a constant after their name in `ActiveJob::QueueAdapters`.
+
+So, if you declare
+
+```ruby
+require "active_job"
+require "active_job/queue_adapters"
+loader.push_dir("#{__dir__}/adapters", namespace: ActiveJob::QueueAdapters)
+```
+
+your adapter can be stored directly in that directory instead of the canonical `lib/active_job/queue_adapters`.
+
+Please, note that the given namespace must be non-reloadable, though autoloaded constants in that namespace can be. That is, if you associate `app/api` with an existing `Api` module, that module should not be reloadable. However, if the project defines and autoloads the class `Api::V2::Deliveries`, that one can be reloaded.
+
 <a id="markdown-implicit-namespaces" name="implicit-namespaces"></a>
 ### Implicit namespaces
 
@@ -163,6 +189,32 @@ end
 
 An explicit namespace must be managed by one single loader. Loaders that reopen namespaces owned by other projects are responsible for loading their constants before setup.
 
+<a id="markdown-collapsing-directories" name="collapsing-directories"></a>
+### Collapsing directories
+
+Say some directories in a project exist for organizational purposes only, and you prefer not to have them as namespaces. For example, the `actions` subdirectory in the next example is not meant to represent a namespace, it is there only to group all actions related to bookings:
+
+```
+booking.rb                -> Booking
+booking/actions/create.rb -> Booking::Create
+```
+
+To make it work that way, configure Zeitwerk to collapse said directory:
+
+```ruby
+loader.collapse("booking/actions")
+```
+
+This method accepts an arbitrary number of strings or `Pathname` objects, and also an array of them.
+
+You can pass directories and glob patterns. Glob patterns are expanded when they are added, and again on each reload.
+
+To illustrate usage of glob patterns, if `actions` in the example above is part of a standardized structure, you could use a wildcard:
+
+```ruby
+loader.collapse("*/actions")
+```
+
 <a id="markdown-nested-root-directories" name="nested-root-directories"></a>
 ### Nested root directories
 
@@ -182,6 +234,9 @@ should define `Geolocatable`, not `Concerns::Geolocatable`.
 <a id="markdown-setup" name="setup"></a>
 ### Setup
 
+<a id="markdown-generic" name="generic"></a>
+#### Generic
+
 Loaders are ready to load code right after calling `setup` on them:
 
 ```ruby
@@ -198,9 +253,36 @@ loader.push_dir(...)
 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.
+<a id="markdown-for_gem" name="for_gem"></a>
+#### for_gem
+
+`Zeitwerk::Loader.for_gem` is a convenience shortcut for the common case in which a gem has its entry point directly under the `lib` directory:
+
+```
+lib/my_gem.rb         # MyGem
+lib/my_gem/version.rb # MyGem::VERSION
+lib/my_gem/foo.rb     # MyGem::Foo
+```
+
+Neither a gemspec nor a version file are technically required, this helper works as long as the code is organized using that standard structure.
 
-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:
+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.
+
+Conceptually, `for_gem` translates to:
+
+```ruby
+# lib/my_gem.rb
+
+require "zeitwerk"
+loader = Zeitwerk::Loader.new
+loader.tag = File.basename(__FILE__, ".rb")
+loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
+loader.push_dir(__dir__)
+```
+
+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.
+
+If the main module 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)
@@ -216,35 +298,28 @@ module MyGem
 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-autoloading" name="autoloading"></a>
+### Autoloading
 
-<a id="markdown-reloading" name="reloading"></a>
-### Reloading
+After `setup`, you are able to reference classes and modules from the project without issuing `require` calls for them. They are all available everywhere, autoloading loads them on demand. This works even if the reference to the class or module is first hit in client code, outside your project.
 
-Zeitwerk is able to reload code, but you need to enable this feature:
+Let's revisit the example above:
 
 ```ruby
-loader = Zeitwerk::Loader.new
-loader.push_dir(...)
-loader.enable_reloading # you need to opt-in before setup
-loader.setup
-...
-loader.reload
-```
-
-There is no way to undo this, either you want to reload or you don't.
-
-Enabling reloading after setup raises `Zeitwerk::Error`. Similarly, calling `reload` without having enabled reloading also raises `Zeitwerk::Error`.
+# lib/my_gem.rb (main file)
 
-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.
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.setup
 
-Reloading removes the currently loaded classes and modules and resets the loader so that it will pick whatever is in the file system now.
+module MyGem
+  include MyLogger # (*)
+end
+```
 
-It is important to highlight that this is an instance method. Don't worry about project dependencies managed by Zeitwerk, their loaders are independent.
+That works, and there is no `require "my_gem/my_logger"`. When `(*)` is reached, Zeitwerk seamlessly autoloads `MyGem::MyLogger`.
 
-In order for reloading to be thread-safe, you need to implement some coordination. For example, a web framework that serves each request with its own thread may have a globally accessible RW lock. When a request comes in, the framework acquires the lock for reading at the beginning, and the code in the framework that calls `loader.reload` needs to acquire the lock for writing.
-
-On reloading, client code has to update anything that would otherwise be storing a stale object. For example, if the routing layer of a web framework stores controller class objects or instances in internal structures, on reload it has to refresh them somehow, possibly reevaluating routes.
+If autoloading a file does not define the expected class or module, Zeitwerk raises `Zeitwerk::NameError`, which is a subclass of `NameError`.
 
 <a id="markdown-eager-loading" name="eager-loading"></a>
 ### Eager loading
@@ -268,6 +343,8 @@ In gems, the method needs to be invoked after the main namespace has been define
 
 Eager loading is synchronized and idempotent.
 
+If eager loading a file does not define the expected class or module, Zeitwerk raises `Zeitwerk::NameError`, which is a subclass of `NameError`.
+
 If you want to eager load yourself and all dependencies using Zeitwerk, you can broadcast the `eager_load` call to all instances:
 
 ```ruby
@@ -278,6 +355,34 @@ 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-reloading" name="reloading"></a>
+### Reloading
+
+Zeitwerk is able to reload code, but you need to enable this feature:
+
+```ruby
+loader = Zeitwerk::Loader.new
+loader.push_dir(...)
+loader.enable_reloading # you need to opt-in before setup
+loader.setup
+...
+loader.reload
+```
+
+There is no way to undo this, either you want to reload or you don't.
+
+Enabling reloading after setup raises `Zeitwerk::Error`. Attempting to reload without having it enabled raises `Zeitwerk::ReloadingDisabledError`.
+
+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 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.
+
+In order for reloading to be thread-safe, you need to implement some coordination. For example, a web framework that serves each request with its own thread may have a globally accessible RW lock. When a request comes in, the framework acquires the lock for reading at the beginning, and the code in the framework that calls `loader.reload` needs to acquire the lock for writing.
+
+On reloading, client code has to update anything that would otherwise be storing a stale object. For example, if the routing layer of a web framework stores controller class objects or instances in internal structures, on reload it has to refresh them somehow, possibly reevaluating routes.
+
 <a id="markdown-inflection" name="inflection"></a>
 ### Inflection
 
@@ -565,6 +670,42 @@ Trip = Struct.new { ... } # NOT SUPPORTED
 
 This only affects explicit namespaces, those idioms work well for any other ordinary class or module.
 
+<a id="markdown-reopening-third-party-namespaces" name="reopening-third-party-namespaces"></a>
+### Reopening third-party namespaces
+
+Projects managed by Zeitwerk can work with namespaces defined by third-party libraries. However, they have to be loaded in memory before calling `setup`.
+
+For example, let's imagine you're writing a gem that implements an adapter for [Active Job](https://guides.rubyonrails.org/active_job_basics.html) that uses AwesomeQueue as backend. By convention, your gem has to define a class called `ActiveJob::QueueAdapters::AwesomeQueue`, and it has to do so in a file with a matching path:
+
+```ruby
+# lib/active_job/queue_adapters/awesome_queue.rb
+module ActiveJob
+  module QueueAdapters
+    class AwesomeQueue
+      # ...
+    end
+  end
+end
+```
+
+It is very important that your gem _reopens_ the modules `ActiveJob` and `ActiveJob::QueueAdapters` instead of _defining_ them. Because their proper definition lives in Active Job. Furthermore, if the project reloads, you do not want any of `ActiveJob` or `ActiveJob::QueueAdapters` to be reloaded.
+
+Bottom line, Zeitwerk should not be managing those namespaces. Active Job owns them and defines them. Your gem needs to _reopen_ them.
+
+In order to do so, you need to make sure those modules are loaded before calling `setup`. For instance, in the entry file for the gem:
+
+```ruby
+# Ensure these namespaces are reopened, not defined.
+require "active_job"
+require "active_job/queue_adapters"
+
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+```
+
+With that, when Zeitwerk scans the file system and reaches the gem directories `lib/active_job` and `lib/active_job/queue_adapters`, it detects the corresponding modules already exist and therefore understands it does not have to manage them. The loader just descends into those directories. Eventually will reach `lib/active_job/queue_adapters/awesome_queue.rb`, and since `ActiveJob::QueueAdapters::AwesomeQueue` is unknown, Zeitwerk will manage it. Which is what happens regularly with the files in your gem. On reload, the namespaces are safe, won't be reloaded. The loader only reloads what it manages, which in this case is the adapter itself.
+
 <a id="markdown-rules-of-thumb" name="rules-of-thumb"></a>
 ### Rules of thumb
 
@@ -580,14 +721,18 @@ 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
+<a id="markdown-debuggers" name="debuggers"></a>
+### Debuggers
+
+<a id="markdown-break" name="break"></a>
+#### Break
 
-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`.
+Zeitwerk works fine with [@gsamokovarov](https://github.com/gsamokovarov)'s [Break](https://github.com/gsamokovarov/break) debugger.
 
-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.
+<a id="markdown-byebug" name="byebug"></a>
+#### Byebug
 
-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.
+Zeitwerk and [Byebug](https://github.com/deivid-rodriguez/byebug) are incompatible, classes or modules that belong to [explicit namespaces](#explicit-namespaces) are not autoloaded inside a Byebug session. See [this issue](https://github.com/deivid-rodriguez/byebug/issues/564#issuecomment-499413606) for further details.
 
 <a id="markdown-pronunciation" name="pronunciation"></a>
 ## Pronunciation
@@ -599,6 +744,32 @@ As a workaround, you can eager load. Zeitwerk tries hard to succeed or fail cons
 
 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
 
@@ -613,6 +784,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/inflector.rb

@@ -15,7 +15,7 @@ module Zeitwerk
     # @param _abspath [String]
     # @return [String]
     def camelize(basename, _abspath)
-      overrides[basename] || basename.split('_').map!(&:capitalize).join
+      overrides[basename] || basename.split('_').each(&:capitalize!).join
     end
 
     # Configures hard-coded inflections:
@@ -28,7 +28,7 @@ module Zeitwerk
     #
     #   inflector.camelize("html_parser", abspath)      # => "HTMLParser"
     #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
-    #   inflector.camelize("users_controller", abspath) # => "PostsController"
+    #   inflector.camelize("users_controller", abspath) # => "UsersController"
     #
     # @param inflections [{String => String}]
     # @return [void]

data/lib/zeitwerk/kernel.rb

@@ -3,6 +3,17 @@
 module Kernel
   module_function
 
+  # We are going to decorate Kerner#require with two goals.
+  #
+  # First, by intercepting Kernel#require calls, we are able to autovivify
+  # modules on required directories, and also do internal housekeeping when
+  # managed files are loaded.
+  #
+  # On the other hand, if you publish a new version of a gem that is now managed
+  # by Zeitwerk, client code can reference directly your classes and modules and
+  # should not require anything. But if someone has legacy require calls around,
+  # they will work as expected, and in a compatible way.
+  #
   # We cannot decorate with prepend + super because Kernel has already been
   # included in Object, and changes in ancestors don't get propagated into
   # already existing ancestor chains.
@@ -30,4 +41,24 @@ module Kernel
       end
     end
   end
+
+  # By now, I have seen no way so far to decorate require_relative.
+  #
+  # For starters, at least in CRuby, require_relative does not delegate to
+  # require. Both require and require_relative delegate the bulk of their work
+  # to an internal C function called rb_require_safe. So, our require wrapper is
+  # not executed.
+  #
+  # On the other hand, we cannot use the aliasing technique above because
+  # require_relative receives a path relative to the directory of the file in
+  # which the call is performed. If a wrapper here invoked the original method,
+  # Ruby would resolve the relative path taking lib/zeitwerk as base directory.
+  #
+  # A workaround could be to extract the base directory from caller_locations,
+  # but what if someone else decorated require_relative before us? You can't
+  # really know with certainty where's the original call site in the stack.
+  #
+  # However, the main use case for require_relative is to load files from your
+  # own project. Projects managed by Zeitwerk don't do this for files managed by
+  # Zeitwerk, precisely.
 end

data/lib/zeitwerk/loader.rb

@@ -39,7 +39,7 @@ module Zeitwerk
     # @return [<String>]
     attr_reader :preloads
 
-    # Absolute paths of files, directories, of glob patterns to be totally
+    # Absolute paths of files, directories, or glob patterns to be totally
     # ignored.
     #
     # @private
@@ -54,6 +54,19 @@ module Zeitwerk
     # @return [Set<String>]
     attr_reader :ignored_paths
 
+    # Absolute paths of directories or glob patterns to be collapsed.
+    #
+    # @private
+    # @return [Set<String>]
+    attr_reader :collapse_glob_patterns
+
+    # The actual collection of absolute directory names at the time the collapse
+    # glob patterns were expanded. Computed on setup, and recomputed on reload.
+    #
+    # @private
+    # @return [Set<String>]
+    attr_reader :collapse_dirs
+
     # Maps real absolute paths for which an autoload has been set ---and not
     # executed--- to their corresponding parent class or module and constant
     # name.
@@ -131,15 +144,17 @@ module Zeitwerk
       @inflector = Inflector.new
       @logger    = self.class.default_logger
 
-      @root_dirs             = {}
-      @preloads              = []
-      @ignored_glob_patterns = Set.new
-      @ignored_paths         = Set.new
-      @autoloads             = {}
-      @autoloaded_dirs       = []
-      @to_unload             = {}
-      @lazy_subdirs          = {}
-      @eager_load_exclusions = Set.new
+      @root_dirs              = {}
+      @preloads               = []
+      @ignored_glob_patterns  = Set.new
+      @ignored_paths          = Set.new
+      @collapse_glob_patterns = Set.new
+      @collapse_dirs          = Set.new
+      @autoloads              = {}
+      @autoloaded_dirs        = []
+      @to_unload              = {}
+      @lazy_subdirs           = {}
+      @eager_load_exclusions  = Set.new
 
       # TODO: find a better name for these mutexes.
       @mutex        = Mutex.new
@@ -154,6 +169,7 @@ module Zeitwerk
 
     # Sets a tag for the loader, useful for logging.
     #
+    # @param tag [#to_s]
     # @return [void]
     def tag=(tag)
       @tag = tag.to_s
@@ -174,13 +190,19 @@ module Zeitwerk
     # or descendants.
     #
     # @param path [<String, Pathname>]
+    # @param namespace [Class, Module]
     # @raise [Zeitwerk::Error]
     # @return [void]
-    def push_dir(path)
+    def push_dir(path, namespace: Object)
+      # Note that Class < Module.
+      unless namespace.is_a?(Module)
+        raise Error, "#{namespace.inspect} is not a class or module object, should be"
+      end
+
       abspath = File.expand_path(path)
       if dir?(abspath)
         raise_if_conflicting_directory(abspath)
-        root_dirs[abspath] = true
+        root_dirs[abspath] = namespace
       else
         raise Error, "the root directory #{abspath} does not exist"
       end
@@ -233,6 +255,18 @@ module Zeitwerk
       end
     end
 
+    # Configure directories or glob patterns to be collapsed.
+    #
+    # @param paths [<String, Pathname, <String, Pathname>>]
+    # @return [void]
+    def collapse(*glob_patterns)
+      glob_patterns = expand_paths(glob_patterns)
+      mutex.synchronize do
+        collapse_glob_patterns.merge(glob_patterns)
+        collapse_dirs.merge(expand_glob_patterns(glob_patterns))
+      end
+    end
+
     # Sets autoloads in the root namespace and preloads files, if any.
     #
     # @return [void]
@@ -240,7 +274,9 @@ module Zeitwerk
       mutex.synchronize do
         break if @setup
 
-        actual_root_dirs.each { |root_dir| set_autoloads_in_dir(root_dir, Object) }
+        actual_root_dirs.each do |root_dir, namespace|
+          set_autoloads_in_dir(root_dir, namespace)
+        end
         do_preload
 
         @setup = true
@@ -306,7 +342,8 @@ module Zeitwerk
         Registry.on_unload(self)
         ExplicitNamespace.unregister(self)
 
-        @setup = false
+        @setup        = false
+        @eager_loaded = false
       end
     end
 
@@ -322,6 +359,7 @@ module Zeitwerk
       if reloading_enabled?
         unload
         recompute_ignored_paths
+        recompute_collapse_dirs
         setup
       else
         raise ReloadingDisabledError, "can't reload, please call loader.enable_reloading before setup"
@@ -338,8 +376,11 @@ module Zeitwerk
       mutex.synchronize do
         break if @eager_loaded
 
-        queue = actual_root_dirs.reject { |dir| eager_load_exclusions.member?(dir) }
-        queue.map! { |dir| [Object, dir] }
+        queue = []
+        actual_root_dirs.each do |root_dir, namespace|
+          queue << [namespace, root_dir] unless eager_load_exclusions.member?(root_dir)
+        end
+
         while to_eager_load = queue.shift
           namespace, dir = to_eager_load
 
@@ -351,8 +392,12 @@ module Zeitwerk
                 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]
+              if collapse_dirs.member?(abspath)
+                queue << [namespace, abspath]
+              else
+                cname = inflector.camelize(basename, abspath)
+                queue << [namespace.const_get(cname, false), abspath]
+              end
             end
           end
         end
@@ -430,7 +475,7 @@ module Zeitwerk
       #   require "zeitwerk"
       #   loader = Zeitwerk::Loader.new
       #   loader.tag = File.basename(__FILE__, ".rb")
-      #   loader.inflector = Zeitwerk::GemInflector.new
+      #   loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
       #   loader.push_dir(__dir__)
       #
       # except that this method returns the same object in subsequent calls from
@@ -464,7 +509,7 @@ module Zeitwerk
 
     # @return [<String>]
     def actual_root_dirs
-      root_dirs.keys.delete_if do |root_dir|
+      root_dirs.reject do |root_dir, _namespace|
         !dir?(root_dir) || ignored_paths.member?(root_dir)
       end
     end
@@ -476,7 +521,7 @@ module Zeitwerk
       ls(dir) do |basename, abspath|
         begin
           if ruby?(basename)
-            basename.slice!(-3, 3)
+            basename[-3..-1] = ''
             cname = inflector.camelize(basename, abspath).to_sym
             autoload_file(parent, cname, abspath)
           elsif dir?(abspath)
@@ -488,13 +533,17 @@ module Zeitwerk
             # 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)
+              if collapse_dirs.member?(abspath)
+                set_autoloads_in_dir(abspath, parent)
+              else
+                autoload_subdir(parent, cname, abspath)
+              end
             end
           end
         rescue ::NameError => error
           path_type = ruby?(abspath) ? "file" : "directory"
 
-          raise NameError, <<~MESSAGE
+          raise NameError.new(<<~MESSAGE, error.name)
             #{error.message} inferred by #{inflector.class} from #{path_type}
 
               #{abspath}
@@ -558,7 +607,7 @@ module Zeitwerk
     end
 
     # @param dir [String] directory that would have autovivified a module
-    # @param file [String] the file where the namespace is explictly defined
+    # @param file [String] the file where the namespace is explicitly defined
     # @param parent [Module]
     # @param cname [Symbol]
     # @return [void]
@@ -578,7 +627,10 @@ module Zeitwerk
       # $LOADED_FEATURES stores real paths since Ruby 2.4.4. We set and save the
       # real path to be able to delete it from $LOADED_FEATURES on unload, and to
       # be able to do a lookup later in Kernel#require for manual require calls.
-      realpath = File.realpath(abspath)
+      #
+      # We freeze realpath because that saves allocations in Module#autoload.
+      # See #125.
+      realpath = File.realpath(abspath).freeze
       parent.autoload(cname, realpath)
       if logger
         if ruby?(realpath)
@@ -623,8 +675,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
@@ -675,8 +733,13 @@ module Zeitwerk
     def ls(dir)
       Dir.foreach(dir) do |basename|
         next if basename.start_with?(".")
+
         abspath = File.join(dir, basename)
-        yield basename, abspath unless ignored_paths.member?(abspath)
+        next if ignored_paths.member?(abspath)
+
+        # We freeze abspath because that saves allocations when passed later to
+        # File methods. See #125.
+        yield basename, abspath.freeze
       end
     end
 
@@ -711,6 +774,11 @@ module Zeitwerk
       ignored_paths.replace(expand_glob_patterns(ignored_glob_patterns))
     end
 
+    # @return [void]
+    def recompute_collapse_dirs
+      collapse_dirs.replace(expand_glob_patterns(collapse_glob_patterns))
+    end
+
     # @param message [String]
     # @return [void]
     def log(message)

data/lib/zeitwerk/loader/callbacks.rb

@@ -14,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.new("expected file #{file} to define constant #{cpath(*cref)}, but didn't", cref.last)
     end
   end
 

data/lib/zeitwerk/real_mod_name.rb

@@ -9,7 +9,13 @@ module Zeitwerk::RealModName
   #
   # @param mod [Class, Module]
   # @return [String, nil]
-  def real_mod_name(mod)
-    UNBOUND_METHOD_MODULE_NAME.bind(mod).call
+  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.2.0"
+  VERSION = "2.4.0"
 end

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Xavier Noria
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-10-09 00:00:00.000000000 Z
+date: 2020-07-14 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
       and application may have their own independent autoloader, with its own
-      configuration, inflector, and logger. Supports autoloading, preloading,
+      configuration, inflector, and logger. Supports autoloading,
       reloading, and eager loading.
 email: fxn@hashref.com
 executables: []
@@ -36,7 +36,11 @@ files:
 homepage: https://github.com/fxn/zeitwerk
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/fxn/zeitwerk
+  changelog_uri: https://github.com/fxn/zeitwerk/blob/master/CHANGELOG.md
+  source_code_uri: https://github.com/fxn/zeitwerk
+  bug_tracker_uri: https://github.com/fxn/zeitwerk/issues
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -52,7 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader