zeitwerk 2.6.8 → 2.6.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 418f16f6224359c716a990f72ae916c980a3f388b09ab018c0972b8558530620
-  data.tar.gz: '04847c6c8f8f894fe3c2b3c39d175b5854b583d3a02ef5cca27a53cb1b8dafd4'
+  metadata.gz: 2b2955613976d014a322168f1976a93b29e388b4c72ecf5acdbb0186d212fe7c
+  data.tar.gz: 57df7539d6fa37fcf41f1d37b6c2fa0a8db5af7af02333da35566fca92a03d8a
 SHA512:
-  metadata.gz: f86272e84721cf9b8b1e07182b1b60cfe732ef2c266dbe076225d32af52fc9a30c278a14651ddbb3d435636646dd23c948d3fe0f00ed9b8393abdeb34dd40028
-  data.tar.gz: 562738b53779310e899c2065c7046844d27daabb5f354972e4c9b65bec3e5c0cdade92d19ed815fe7b0dc01538603daa3e4dd2f0049fe9a7a2e74313c0f040f6
+  metadata.gz: 625ef1f9a15205afa2efea139f63b5b800660d57631fda75deccd172f72e82fb6454efe7465edb8024a9a8536b463fa523ead1582dc13aac54dfddb5535e31a9
+  data.tar.gz: d0e0b1ff25b25ce5b9d3223fa01b3f04b4eefa7e316d55bad95686265f194aee24599e146c1ef9a05dd20dc16f670733e17e494ccd469ea9aef7e4a8b2fb973c

data/README.md

@@ -3,7 +3,8 @@
 
 
 [![Gem Version](https://img.shields.io/gem/v/zeitwerk.svg?style=for-the-badge)](https://rubygems.org/gems/zeitwerk)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/fxn/zeitwerk/ci.yml?branch=main&event=push&style=for-the-badge)](https://github.com/fxn/zeitwerk/actions/workflows/ci.yml?query=branch%3main)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/fxn/zeitwerk/ci.yml?branch=main&event=push&style=for-the-badge)](https://github.com/fxn/zeitwerk/actions/workflows/ci.yml?query=branch%3Amain)
+
 
 <!-- TOC -->
 
@@ -56,6 +57,8 @@
   - [Beware of circular dependencies](#beware-of-circular-dependencies)
   - [Reopening third-party namespaces](#reopening-third-party-namespaces)
   - [Introspection](#introspection)
+    - [`Zeitwerk::Loader#dirs`](#zeitwerkloaderdirs)
+    - [`Zeitwerk::Loader#cpath_expected_at`](#zeitwerkloadercpath_expected_at)
   - [Encodings](#encodings)
   - [Rules of thumb](#rules-of-thumb)
   - [Debuggers](#debuggers)
@@ -76,15 +79,15 @@
 
 Zeitwerk is an efficient and thread-safe code loader for Ruby.
 
-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.
+Given a [conventional file structure](#file-structure), Zeitwerk is capable of loading 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; instead, you can streamline your programming by knowing that your classes and modules are available everywhere. This feature is efficient, thread-safe, and aligns with Ruby's semantics for constants.
 
-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.
+Zeitwerk also supports code reloading, which can be useful during web application development. However, coordination is required to reload in a thread-safe manner. The documentation below explains how to achieve this.
 
-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.
+The gem is designed to allow any project, gem dependency, or application to have its own independent loader. Multiple loaders can coexist in the same process, each managing its own project tree and operating independently 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`.
+Internally, Zeitwerk exclusively uses absolute file names when issuing `require` calls, eliminating the need for costly file system lookups in `$LOAD_PATH`. Technically, the directories managed by Zeitwerk don't 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.
+Furthermore, Zeitwerk performs a single scan of the project tree at most, lazily descending into subdirectories only when their namespaces are used.
 
 <a id="markdown-synopsis" name="synopsis"></a>
 ## Synopsis
@@ -144,7 +147,7 @@ Zeitwerk::Loader.eager_load_all
 <a id="markdown-the-idea-file-paths-match-constant-paths" name="the-idea-file-paths-match-constant-paths"></a>
 ### The idea: File paths match constant paths
 
-To have a file structure Zeitwerk can work with, just name files and directories after the name of the classes and modules they define:
+For Zeitwerk to work with your file structure, simply name files and directories after the classes and modules they define:
 
 ```
 lib/my_gem.rb         -> MyGem
@@ -153,7 +156,7 @@ lib/my_gem/bar_baz.rb -> MyGem::BarBaz
 lib/my_gem/woo/zoo.rb -> MyGem::Woo::Zoo
 ```
 
-You can tune that a bit by [collapsing directories](#collapsing-directories), or by [ignoring parts of the project](#ignoring-parts-of-the-project), but that is the main idea.
+You can fine-tune this behavior by [collapsing directories](#collapsing-directories) or [ignoring specific parts of the project](#ignoring-parts-of-the-project), but that is the main idea.
 
 <a id="markdown-inner-simple-constants" name="inner-simple-constants"></a>
 ### Inner simple constants
@@ -211,7 +214,7 @@ serializers/user_serializer.rb -> UserSerializer
 <a id="markdown-custom-root-namespaces" name="custom-root-namespaces"></a>
 #### Custom root namespaces
 
-While `Object` is by far the most common root namespace, you can associate a different one to a particular root directory. The method `push_dir` accepts a non-anonymous class or module object in the optional `namespace` keyword argument.
+Although `Object` is the most common root namespace, you have the flexibility to associate a different one with a specific root directory. The `push_dir` method accepts a non-anonymous class or module object as the optional `namespace` keyword argument.
 
 For example, given:
 
@@ -227,14 +230,14 @@ a file defining `ActiveJob::QueueAdapters::MyQueueAdapter` does not need the con
 adapters/my_queue_adapter.rb -> ActiveJob::QueueAdapters::MyQueueAdapter
 ```
 
-Please, note that the given root 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::Deliveries`, that one can be reloaded.
+Please note that the provided root namespace must be non-reloadable, while allowing autoloaded constants within that namespace to be reloadable. This means that if you associate the `app/api` directory with an existing `Api` module, the module itself should not be reloadable. However, if the project defines and autoloads the `Api::Deliveries` class, that class can be reloaded.
 
 <a id="markdown-nested-root-directories" name="nested-root-directories"></a>
 #### Nested root directories
 
-Root directories should not be ideally nested, but Zeitwerk supports them because in Rails, for example, both `app/models` and `app/models/concerns` belong to the autoload paths.
+Root directories are recommended not to be nested; however, Zeitwerk provides support for nested root directories since in frameworks like Rails, both `app/models` and `app/models/concerns` belong to the autoload paths.
 
-Zeitwerk detects nested root directories, and treats them as roots only. In the example above, `concerns` is not considered to be a namespace below `app/models`. For example, the file:
+Zeitwerk identifies nested root directories and treats them as independent roots. In the given example, `concerns` is not considered a namespace within `app/models`. For instance, consider the following file:
 
 ```
 app/models/concerns/geolocatable.rb
@@ -245,9 +248,9 @@ should define `Geolocatable`, not `Concerns::Geolocatable`.
 <a id="markdown-implicit-namespaces" name="implicit-namespaces"></a>
 ### Implicit namespaces
 
-If a namespace is just a simple module with no code, you do not need to define it in a file: Directories without a matching Ruby file get modules created automatically on your behalf.
+If a namespace consists only of a simple module without any code, there is no need to explicitly define it in a separate file. Zeitwerk automatically creates modules on your behalf for directories without a corresponding Ruby file.
 
-For example, if a project has an `admin` directory:
+For instance, suppose a project includes an `admin` directory:
 
 ```
 app/controllers/admin/users_controller.rb -> Admin::UsersController
@@ -255,7 +258,7 @@ app/controllers/admin/users_controller.rb -> Admin::UsersController
 
 and does not have a file called `admin.rb`, Zeitwerk automatically creates an `Admin` module on your behalf the first time `Admin` is used.
 
-For this to happen, the directory has to contain non-ignored Ruby files with extension `.rb`, directly or recursively, otherwise it is ignored. This condition is evaluated again on reloads.
+To trigger this behavior, the directory must contain non-ignored Ruby files with the `.rb` extension, either directly or recursively. Otherwise, the directory is ignored. This condition is reevaluated during reloads.
 
 <a id="markdown-explicit-namespaces" name="explicit-namespaces"></a>
 ### Explicit namespaces
@@ -733,9 +736,34 @@ loader.inflector.inflect "html_parser" => "HTMLParser"
 loader.inflector.inflect "mysql_adapter" => "MySQLAdapter"
 ```
 
+Overrides have to match exactly directory or file (without extension) _basenames_. For example, if you configure
+
+```ruby
+loader.inflector.inflect("xml" => "XML")
+```
+
+then the following constants are expected:
+
+```
+xml.rb         -> XML
+foo/xml        -> Foo::XML
+foo/bar/xml.rb -> Foo::Bar::XML
+```
+
+As you see, any directory whose basename is exactly `xml`, and any file whose basename is exactly `xml.rb` are expected to define the constant `XML` in the corresponding namespace. On the other hand, partial matches are ignored. For example, `xml_parser.rb` would be inflected as `XmlParser` because `xml_parser` is not equal to `xml`. You'd need an additional override:
+
+```ruby
+loader.inflector.inflect(
+  "xml"        => "XML",
+  "xml_parser" => "XMLParser"
+)
+```
+
+If you need more flexibility, you can define a custom inflector, as explained down below.
+
 Overrides need to be configured before calling `setup`.
 
- The inflectors of different loaders are independent of each other. There are no global inflection rules or global configuration that can affect this inflector. It is deterministic.
+The inflectors of different loaders are independent of each other. There are no global inflection rules or global configuration that can affect this inflector. It is deterministic.
 
 <a id="markdown-zeitwerkgeminflector" name="zeitwerkgeminflector"></a>
 #### Zeitwerk::GemInflector
@@ -1214,6 +1242,9 @@ With that, when Zeitwerk scans the file system and reaches the gem directories `
 <a id="markdown-introspection" name="introspection"></a>
 ### Introspection
 
+<a id="markdown-zeitwerkloaderdirs" name="zeitwerkloaderdirs"></a>
+#### `Zeitwerk::Loader#dirs`
+
 The method `Zeitwerk::Loader#dirs` returns an array with the absolute paths of the root directories as strings:
 
 ```ruby
@@ -1235,6 +1266,44 @@ By default, ignored root directories are filtered out. If you want them included
 
 These collections are read-only. Please add to them with `Zeitwerk::Loader#push_dir`.
 
+<a id="markdown-zeitwerkloadercpath_expected_at" name="zeitwerkloadercpath_expected_at"></a>
+#### `Zeitwerk::Loader#cpath_expected_at`
+
+Given a path as a string or `Pathname` object, `Zeitwerk::Loader#cpath_expected_at` returns a string with the corresponding expected constant path.
+
+Some examples, assuming that `app/models` is a root directory:
+
+```ruby
+loader.cpath_expected_at("app/models")                  # => "Object"
+loader.cpath_expected_at("app/models/user.rb")          # => "User"
+loader.cpath_expected_at("app/models/hotel")            # => "Hotel"
+loader.cpath_expected_at("app/models/hotel/billing.rb") # => "Hotel::Billing"
+```
+
+If `collapsed` is a collapsed directory:
+
+```ruby
+loader.cpath_expected_at("a/b/collapsed/c") # => "A::B::C"
+loader.cpath_expected_at("a/b/collapsed")   # => "A::B", edge case
+loader.cpath_expected_at("a/b")             # => "A::B"
+```
+
+If the argument corresponds to an [ignored file or directory](#ignoring-parts-of-the-project), the method returns `nil`. Same if the argument is not managed by the loader.
+
+`Zeitwerk::Error` is raised if the given path does not exist:
+
+```ruby
+loader.cpath_expected_at("non_existing_file.rb") # => Zeitwerk::Error
+```
+
+`Zeitwerk::NameError` is raised if a constant path cannot be derived from it:
+
+```ruby
+loader.cpath_expected_at("8.rb") # => Zeitwerk::NameError
+```
+
+This method does not parse file contents and does not guarantee files define the returned constant path. It just says which is the _expected_ one.
+
 <a id="markdown-encodings" name="encodings"></a>
 ### Encodings
 
@@ -1265,9 +1334,11 @@ The test suite passes on Windows with codepage `Windows-1252` if all the involve
 <a id="markdown-debuggers" name="debuggers"></a>
 ### Debuggers
 
-Zeitwerk works fine with [debug.rb](https://github.com/ruby/debug) and [Break](https://github.com/gsamokovarov/break).
+Zeitwerk and [debug.rb](https://github.com/ruby/debug) are fully compatible if CRuby is ≥ 3.1 (see [ruby/debug#558](https://github.com/ruby/debug/pull/558)).
+
+[Byebug](https://github.com/deivid-rodriguez/byebug) is compatible except for an edge case explained in [deivid-rodriguez/byebug#564](https://github.com/deivid-rodriguez/byebug/issues/564). Prior to CRuby 3.1, `debug.rb` has a similar edge incompatibility.
 
-[Byebug](https://github.com/deivid-rodriguez/byebug) is compatible except for an edge case explained in [deivid-rodriguez/byebug#564](https://github.com/deivid-rodriguez/byebug/issues/564).
+[Break](https://github.com/gsamokovarov/break) is fully compatible.
 
 <a id="markdown-pronunciation" name="pronunciation"></a>
 ## Pronunciation

data/lib/zeitwerk/loader/eager_load.rb

@@ -45,8 +45,10 @@ module Zeitwerk::Loader::EagerLoad
 
       break if root_namespace = roots[dir]
 
+      basename = File.basename(dir)
+      return if hidden?(basename)
+
       unless collapse?(dir)
-        basename = File.basename(dir)
         cnames << inflector.camelize(basename, dir).to_sym
       end
     end
@@ -119,6 +121,8 @@ module Zeitwerk::Loader::EagerLoad
     raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_path?(abspath)
 
     basename = File.basename(abspath, ".rb")
+    raise Zeitwerk::Error.new("#{abspath} is ignored") if hidden?(basename)
+
     base_cname = inflector.camelize(basename, abspath).to_sym
 
     root_namespace = nil
@@ -129,8 +133,10 @@ module Zeitwerk::Loader::EagerLoad
 
       break if root_namespace = roots[dir]
 
+      basename = File.basename(dir)
+      raise Zeitwerk::Error.new("#{abspath} is ignored") if hidden?(basename)
+
       unless collapse?(dir)
-        basename = File.basename(dir)
         cnames << inflector.camelize(basename, dir).to_sym
       end
     end

data/lib/zeitwerk/loader/helpers.rb

@@ -140,4 +140,48 @@ module Zeitwerk::Loader::Helpers
   private def crem(parent, cname)
     parent.__send__(:remove_const, cname)
   end
+
+  CNAME_VALIDATOR = Module.new
+  private_constant :CNAME_VALIDATOR
+
+  # @raise [Zeitwerk::NameError]
+  # @sig (String, String) -> Symbol
+  private def cname_for(basename, abspath)
+    cname = inflector.camelize(basename, abspath)
+
+    unless cname.is_a?(String)
+      raise TypeError, "#{inflector.class}#camelize must return a String, received #{cname.inspect}"
+    end
+
+    if cname.include?("::")
+      raise Zeitwerk::NameError.new(<<~MESSAGE, cname)
+        wrong constant name #{cname} inferred by #{inflector.class} from
+
+          #{abspath}
+
+        #{inflector.class}#camelize should return a simple constant name without "::"
+      MESSAGE
+    end
+
+    begin
+      CNAME_VALIDATOR.const_defined?(cname, false)
+    rescue ::NameError => error
+      path_type = ruby?(abspath) ? "file" : "directory"
+
+      raise Zeitwerk::NameError.new(<<~MESSAGE, error.name)
+        #{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
+
+    cname.to_sym
+  end
 end

data/lib/zeitwerk/loader.rb

@@ -228,6 +228,54 @@ module Zeitwerk
       setup
     end
 
+  # @sig (String | Pathname) -> String?
+  def cpath_expected_at(path)
+    abspath = File.expand_path(path)
+
+    raise Zeitwerk::Error.new("#{abspath} does not exist") unless File.exist?(abspath)
+
+    return unless dir?(abspath) || ruby?(abspath)
+    return if ignored_path?(abspath)
+
+    paths = []
+
+    if ruby?(abspath)
+      basename = File.basename(abspath, ".rb")
+      return if hidden?(basename)
+
+      paths << [basename, abspath]
+      walk_up_from = File.dirname(abspath)
+    else
+      walk_up_from = abspath
+    end
+
+    root_namespace = nil
+
+    walk_up(walk_up_from) do |dir|
+      break if root_namespace = roots[dir]
+      return if ignored_path?(dir)
+
+      basename = File.basename(dir)
+      return if hidden?(basename)
+
+      paths << [basename, abspath] unless collapse?(dir)
+    end
+
+    return unless root_namespace
+
+    if paths.empty?
+      real_mod_name(root_namespace)
+    else
+      cnames = paths.reverse_each.map { |b, a| cname_for(b, a) }
+
+      if root_namespace == Object
+        cnames.join("::")
+      else
+        "#{real_mod_name(root_namespace)}::#{cnames.join("::")}"
+      end
+    end
+  end
+
     # Says if the given constant path would be unloaded on reload. This
     # predicate returns `false` if reloading is disabled.
     #
@@ -359,34 +407,15 @@ module Zeitwerk
     # @sig (String, Module) -> void
     private def set_autoloads_in_dir(dir, parent)
       ls(dir) do |basename, abspath|
-        begin
-          if ruby?(basename)
-            basename.delete_suffix!(".rb")
-            cname = inflector.camelize(basename, abspath).to_sym
-            autoload_file(parent, cname, abspath)
+        if ruby?(basename)
+          basename.delete_suffix!(".rb")
+          autoload_file(parent, cname_for(basename, abspath), abspath)
+        else
+          if collapse?(abspath)
+            set_autoloads_in_dir(abspath, parent)
           else
-            if collapse?(abspath)
-              set_autoloads_in_dir(abspath, parent)
-            else
-              cname = inflector.camelize(basename, abspath).to_sym
-              autoload_subdir(parent, cname, abspath)
-            end
+            autoload_subdir(parent, cname_for(basename, abspath), abspath)
           end
-        rescue ::NameError => error
-          path_type = ruby?(abspath) ? "file" : "directory"
-
-          raise NameError.new(<<~MESSAGE, error.name)
-            #{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
@@ -511,7 +540,6 @@ module Zeitwerk
               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/version.rb

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

metadata

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