zeitwerk 2.2.1 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7d5a0f54405ad45dd6afc9bf54bde579f66a75fb142cdbbfb5476157dd75493
-  data.tar.gz: b81311bb19c3b699a6720a3bb3d6df503b858a439c5f1f2605e029117de36bcb
+  metadata.gz: b0c408b8f6001e150b16b1e06b1b05d31bcbf4f0144535c995093c822065be3d
+  data.tar.gz: af26de0ecd68b8ebc1836ea431d59c6d7e10d79937c402e3529fc4275631c950
 SHA512:
-  metadata.gz: 4f6fd6e8f7bd479ca6935d1f57d065151aff3be6977ad068f6b4ecdce200bbd131f4db4f2cc1bc2a719cb332b538cf24be55eb936a51572ac5c06676d21763f2
-  data.tar.gz: d4266c65e380b356ff4df7394f2f1882f72ac32b5226dedd717f6b4064c8ac1b8fd3d70ec08b6f9838debfc3690d2f3eee2d6885e446f087a686a619c872c718
+  metadata.gz: 012c9a70cd31973a7251f46f62c102bf11155a6ea90dcdfa62bb2cd1859fca07cfed268dd130528fc55eab4ea0d440347e7ed0cb78f54dca861f96f56014541d
+  data.tar.gz: 7243c0f9b6c39dd389f0570fe03f11a8cadb01b74ae5d5efaa9b895ecf3b2717b5eb71e027c555f1cfeb95457dd5f5d8ace4516eb3a77500b05b1c8f973c1a94

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,8 +32,11 @@
         - [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)
@@ -50,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
@@ -130,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 `#{__dir__}/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
 
@@ -164,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("#{__dir__}/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("#{__dir__}/*/actions")
+```
+
 <a id="markdown-nested-root-directories" name="nested-root-directories"></a>
 ### Nested root directories
 
@@ -183,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
@@ -199,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
 
-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:
+`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 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)
@@ -217,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`.
-
-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.
+# lib/my_gem.rb (main file)
 
-Reloading removes the currently loaded classes and modules and resets the loader so that it will pick whatever is in the file system now.
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.setup
 
-It is important to highlight that this is an instance method. Don't worry about project dependencies managed by Zeitwerk, their loaders are independent.
+module MyGem
+  include MyLogger # (*)
+end
+```
 
-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.
+That works, and there is no `require "my_gem/my_logger"`. When `(*)` is reached, Zeitwerk seamlessly autoloads `MyGem::MyLogger`.
 
-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
@@ -269,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
@@ -279,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
 
@@ -566,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
 
@@ -581,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

data/lib/zeitwerk/explicit_namespace.rb

@@ -14,24 +14,22 @@ module Zeitwerk
       # the file system, to the loader responsible for them.
       #
       # @private
-      # @return [{String => Zeitwerk::Loader}]
+      # @sig Hash[String, Zeitwerk::Loader]
       attr_reader :cpaths
 
       # @private
-      # @return [Mutex]
+      # @sig Mutex
       attr_reader :mutex
 
       # @private
-      # @return [TracePoint]
+      # @sig TracePoint
       attr_reader :tracer
 
       # Asserts `cpath` corresponds to an explicit namespace for which `loader`
       # is responsible.
       #
       # @private
-      # @param cpath [String]
-      # @param loader [Zeitwerk::Loader]
-      # @return [void]
+      # @sig (String, Zeitwerk::Loader) -> void
       def register(cpath, loader)
         mutex.synchronize do
           cpaths[cpath] = loader
@@ -42,19 +40,22 @@ module Zeitwerk
       end
 
       # @private
-      # @param loader [Zeitwerk::Loader]
-      # @return [void]
+      # @sig (Zeitwerk::Loader) -> void
       def unregister(loader)
         cpaths.delete_if { |_cpath, l| l == loader }
         disable_tracer_if_unneeded
       end
 
+      private
+
+      # @sig () -> void
       def disable_tracer_if_unneeded
         mutex.synchronize do
           tracer.disable if cpaths.empty?
         end
       end
 
+      # @sig (TracePoint) -> void
       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

data/lib/zeitwerk/gem_inflector.rb

@@ -2,16 +2,14 @@
 
 module Zeitwerk
   class GemInflector < Inflector
-    # @param root_file [String]
+    # @sig (String) -> void
     def initialize(root_file)
       namespace     = File.basename(root_file, ".rb")
       lib_dir       = File.dirname(root_file)
       @version_file = File.join(lib_dir, namespace, "version.rb")
     end
 
-    # @param basename [String]
-    # @param abspath [String]
-    # @return [String]
+    # @sig (String, String) -> String
     def camelize(basename, abspath)
       abspath == @version_file ? "VERSION" : super
     end

data/lib/zeitwerk/inflector.rb

@@ -11,11 +11,9 @@ module Zeitwerk
     #
     # Takes into account hard-coded mappings configured with `inflect`.
     #
-    # @param basename [String]
-    # @param _abspath [String]
-    # @return [String]
+    # @sig (String, String) -> String
     def camelize(basename, _abspath)
-      overrides[basename] || basename.split('_').map!(&:capitalize).join
+      overrides[basename] || basename.split('_').each(&:capitalize!).join
     end
 
     # Configures hard-coded inflections:
@@ -30,8 +28,7 @@ module Zeitwerk
     #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
     #   inflector.camelize("users_controller", abspath) # => "UsersController"
     #
-    # @param inflections [{String => String}]
-    # @return [void]
+    # @sig (Hash[String, String]) -> void
     def inflect(inflections)
       overrides.merge!(inflections)
     end
@@ -41,7 +38,7 @@ module Zeitwerk
     # Hard-coded basename to constant name user maps that override the default
     # inflection logic.
     #
-    # @return [{String => String}]
+    # @sig () -> Hash[String, String]
     def overrides
       @overrides ||= {}
     end

data/lib/zeitwerk/kernel.rb

@@ -3,13 +3,23 @@
 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.
   alias_method :zeitwerk_original_require, :require
 
-  # @param path [String]
-  # @return [Boolean]
+  # @sig (String) -> true | false
   def require(path)
     if loader = Zeitwerk::Registry.loader_for(path)
       if path.end_with?(".rb")
@@ -30,4 +40,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