zeitwerk 2.6.12 → 2.6.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a9048a5ba05f448e5406080995aab9709a3dd7c8dd32aad3aa0ba4f544b69c4
-  data.tar.gz: 581cf27f70c82b754a1baadf7a41f6c87c069ae2e78bd26b4ec6e02cfa2795b9
+  metadata.gz: 8177bcca0fd5895bbe28b19dc5fd04a810e2905f21f33924786a33a317c96207
+  data.tar.gz: 7e441521285fe28230dadfb4c5c9d40564e376dd651ddae043190c5fdd3ee526
 SHA512:
-  metadata.gz: 45327b148bab210d941ffeae022b70e5c2f2be4372f2192a08859faeed81d2cc5702b05d6e4efcf676a8fb7b451c46200ac372051c68ba84cfc31ed9339f3ede
-  data.tar.gz: 8e3266d7641f58b6a8f74abfa913c14ae4a79d4efd177578de4e7e144a21adc33d33279b7d2771cdc57937cfedfb1f5e193bb9e57c18ea90956b342b516e9bd9
+  metadata.gz: 57e0e401c952a13d1b96a8993bbee930132f2b63252ff7cd6646ceeeb5a3de886d1c36a8cdbc06e9add3e16e76bacd08cc8e32b58289fa01e9eabea4dad25581
+  data.tar.gz: e56116c8325ab38f751b8497f8270544543e950f92624c755b5d3d7bb296b48ce4afa668e1b4daae546561ddfa344fd9c650c7114c9cd2c637a514f0ebd38c98

data/README.md

@@ -40,6 +40,7 @@
   - [Inflection](#inflection)
     - [Zeitwerk::Inflector](#zeitwerkinflector)
     - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
+    - [Zeitwerk::NullInflector](#zeitwerknullinflector)
     - [Custom inflector](#custom-inflector)
   - [Callbacks](#callbacks)
     - [The on_setup callback](#the-on_setup-callback)
@@ -59,6 +60,7 @@
   - [Introspection](#introspection)
     - [`Zeitwerk::Loader#dirs`](#zeitwerkloaderdirs)
     - [`Zeitwerk::Loader#cpath_expected_at`](#zeitwerkloadercpath_expected_at)
+    - [`Zeitwerk::Loader#all_expected_cpaths`](#zeitwerkloaderall_expected_cpaths)
   - [Encodings](#encodings)
   - [Rules of thumb](#rules-of-thumb)
   - [Debuggers](#debuggers)
@@ -258,7 +260,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.
 
-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.
+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
@@ -373,7 +375,7 @@ require "zeitwerk"
 loader = Zeitwerk::Loader.new
 loader.tag = File.basename(__FILE__, ".rb")
 loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
-loader.push_dir(__dir__)
+loader.push_dir(File.dirname(__FILE__))
 ```
 
 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:
@@ -579,7 +581,7 @@ root_dir2/my_app/routes
 root_dir3/my_app/routes
 ```
 
-where `root_directory{1,2,3}` are root directories, eager loading `MyApp::Routes` will eager load the contents of the three corresponding directories.
+where `root_dir{1,2,3}` are root directories, eager loading `MyApp::Routes` will eager load the contents of the three corresponding directories.
 
 There might exist external source trees implementing part of the namespace. This happens routinely, because top-level constants are stored in the globally shared `Object`. It happens also when deliberately [reopening third-party namespaces](#reopening-third-party-namespaces). Such external code is not eager loaded, the implementation is carefully scoped to what the receiver manages to avoid side-effects elsewhere.
 
@@ -774,6 +776,31 @@ This inflector is like the basic one, except it expects `lib/my_gem/version.rb`
 
 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-zeitwerknullinflector" name="zeitwerknullinflector"></a>
+#### Zeitwerk::NullInflector
+
+This is an experimental inflector that simply returns its input unchanged.
+
+```ruby
+loader.inflector = Zeitwerk::NullInflector.new
+```
+
+In a project using this inflector, the names of files and directories are equal to the constants they define:
+
+```
+User.rb       -> User
+HTMLParser.rb -> HTMLParser
+Admin/Role.rb -> Admin::Role
+```
+
+Point is, you think less. Names that typically need custom configuration like acronyms no longer require your attention. What you see is what you get, simple.
+
+This inflector is experimental since Ruby usually goes for snake case in files and directories. But hey, if you fancy giving it a whirl, go for it!
+
+The null inflector cannot be used in Rails applications because the `main` autoloader also manages engines. However, you could subclass the default inflector and override `camelize` to return the basename untouched if it starts with an uppercase letter. Generators would not create the expected file names, but you could still experiment to see how far this approach takes you.
+
+In case-insensitive file systems, this inflector works as long as directory listings return the expected strings. Zeitwerk lists directories using Ruby APIs like `Dir.children` or `Dir.entries`.
+
 <a id="markdown-custom-inflector" name="custom-inflector"></a>
 #### Custom inflector
 
@@ -1006,7 +1033,7 @@ Zeitwerk::Loader.default_logger = method(:puts)
 
 If there is a logger configured, you'll see traces when autoloads are set, files loaded, and modules autovivified. While reloading, removed autoloads and unloaded objects are also traced.
 
-As a curiosity, if your project has namespaces you'll notice in the traces Zeitwerk sets autoloads for _directories_. That's a technique used to be able to descend into subdirectories on demand, avoiding that way unnecessary tree walks.
+As a curiosity, if your project has namespaces you'll notice in the traces Zeitwerk sets autoloads for _directories_. This allows descending into subdirectories on demand, thus avoiding unnecessary tree walks.
 
 <a id="markdown-loader-tag" name="loader-tag"></a>
 #### Loader tag
@@ -1032,7 +1059,7 @@ Zeitwerk@my_gem: constant MyGem::Foo loaded from ...
 <a id="markdown-ignoring-parts-of-the-project" name="ignoring-parts-of-the-project"></a>
 ### Ignoring parts of the project
 
-Zeitwerk ignores automatically any file or directory whose name starts with a dot, and any files that do not have extension ".rb".
+Zeitwerk ignores automatically any file or directory whose name starts with a dot, and any files that do not have the extension ".rb".
 
 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.
 
@@ -1304,6 +1331,54 @@ 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.
 
+`Zeitwerk::Loader#cpath_expected_at` is designed to be used with individual paths. If you want to know all the expected constant paths in the project, please use `Zeitwerk::Loader#all_expected_cpaths`, documented next.
+
+<a id="markdown-zeitwerkloaderall_expected_cpaths" name="zeitwerkloaderall_expected_cpaths"></a>
+#### `Zeitwerk::Loader#all_expected_cpaths`
+
+The method `Zeitwerk::Loader#all_expected_cpaths` returns a hash that maps the absolute paths of the files and directories managed by the receiver to their expected constant paths.
+
+Ignored files, hidden files, and files whose extension is not ".rb" are not included in the result. Same for directories, hidden or ignored directories are not included in the result. Additionally, directories that contain no files with extension ".rb" (recursively) are also excluded, since those are not considered to represent Ruby namespaces.
+
+For example, if `lib` is the root directory of a gem with the following contents:
+
+```
+lib/.DS_Store
+lib/my_gem.rb
+lib/my_gem/version.rb
+lib/my_gem/ignored.rb
+lib/my_gem/drivers/unix.rb
+lib/my_gem/drivers/windows.rb
+lib/my_gem/collapsed/foo.rb
+lib/tasks/my_gem.rake
+```
+
+`Zeitwerk::Loader#all_expected_cpaths` would return (maybe in a different order):
+
+```ruby
+{
+  "/.../lib"                           => "Object",
+  "/.../lib/my_gem.rb"                 => "MyGem",
+  "/.../lib/my_gem"                    => "MyGem",
+  "/.../lib/my_gem/version.rb"         => "MyGem::VERSION",
+  "/.../lib/my_gem/drivers"            => "MyGem::Drivers",
+  "/.../lib/my_gem/drivers/unix.rb"    => "MyGem::Drivers::Unix",
+  "/.../lib/my_gem/drivers/windows.rb" => "MyGem::Drivers::Windows",
+  "/.../lib/my_gem/collapsed"          => "MyGem"
+  "/.../lib/my_gem/collapsed/foo.rb"   => "MyGem::Foo"
+}
+```
+
+In the previous example we assume `lib/my_gem/ignored.rb` is ignored, and therefore it is not present in the returned hash. Also, `lib/my_gem/collapsed` is a collapsed directory, so the expected namespace at that level is still `MyGem` (this is an edge case).
+
+The file `lib/.DS_Store` is hidden, hence excluded. The directory `lib/tasks` is also not present because it contains no files with extension ".rb".
+
+Directory paths do not have trailing slashes.
+
+The order of the hash entries is undefined.
+
+This method does not parse or execute file contents and does not guarantee files define the corresponding constant paths. It just says which are the _expected_ ones.
+
 <a id="markdown-encodings" name="encodings"></a>
 ### Encodings
 
@@ -1325,7 +1400,7 @@ The test suite passes on Windows with codepage `Windows-1252` if all the involve
 
 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.
+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 defines, the namespace. This is often accomplished by loading (e.g., `require`-ing) 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.
 

data/lib/zeitwerk/gem_loader.rb

@@ -42,13 +42,12 @@ module Zeitwerk
     def warn_on_extra_files
       expected_namespace_dir = @root_file.delete_suffix(".rb")
 
-      ls(@root_dir) do |basename, abspath|
+      ls(@root_dir) do |basename, abspath, ftype|
         next if abspath == @root_file
         next if abspath == expected_namespace_dir
 
         basename_without_ext = basename.delete_suffix(".rb")
         cname = inflector.camelize(basename_without_ext, abspath).to_sym
-        ftype = dir?(abspath) ? "directory" : "file"
 
         warn(<<~EOS)
           WARNING: Zeitwerk defines the constant #{cname} after the #{ftype}

data/lib/zeitwerk/kernel.rb

@@ -14,10 +14,6 @@ module Kernel
   # should not require anything. But if someone has legacy require calls around,
   # they will work as expected, and in a compatible way. This feature is by now
   # EXPERIMENTAL and UNDOCUMENTED.
-  #
-  # 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 on Ruby < 3.0.
   alias_method :zeitwerk_original_require, :require
   class << self
     alias_method :zeitwerk_original_require, :require

data/lib/zeitwerk/loader/eager_load.rb

@@ -164,13 +164,13 @@ module Zeitwerk::Loader::EagerLoad
     log("eager load directory #{dir} start") if logger
 
     queue = [[dir, namespace]]
-    while to_eager_load = queue.shift
-      dir, namespace = to_eager_load
+    until queue.empty?
+      dir, namespace = queue.shift
 
-      ls(dir) do |basename, abspath|
+      ls(dir) do |basename, abspath, ftype|
         next if honour_exclusions && eager_load_exclusions.member?(abspath)
 
-        if ruby?(abspath)
+        if ftype == :file
           if (cref = autoloads[abspath])
             cget(*cref)
           end
@@ -209,9 +209,9 @@ module Zeitwerk::Loader::EagerLoad
     next_dirs = []
 
     suffix.split("::").each do |segment|
-      while dir = dirs.shift
-        ls(dir) do |basename, abspath|
-          next unless dir?(abspath)
+      while (dir = dirs.shift)
+        ls(dir) do |basename, abspath, ftype|
+          next unless ftype == :directory
 
           if collapse?(abspath)
             dirs << abspath

data/lib/zeitwerk/loader/helpers.rb

@@ -31,26 +31,39 @@ module Zeitwerk::Loader::Helpers
       if dir?(abspath)
         next if roots.key?(abspath)
         next if !has_at_least_one_ruby_file?(abspath)
+        ftype = :directory
       else
         next unless ruby?(abspath)
+        ftype = :file
       end
 
       # We freeze abspath because that saves allocations when passed later to
       # File methods. See #125.
-      yield basename, abspath.freeze
+      yield basename, abspath.freeze, ftype
     end
   end
 
+  # Looks for a Ruby file using breadth-first search. This type of search is
+  # important to list as less directories as possible and return fast in the
+  # common case in which there are Ruby files.
+  #
   # @sig (String) -> bool
   private def has_at_least_one_ruby_file?(dir)
     to_visit = [dir]
 
-    while dir = to_visit.shift
-      ls(dir) do |_basename, abspath|
+    while (dir = to_visit.shift)
+      children = Dir.children(dir)
+
+      children.each do |basename|
+        next if hidden?(basename)
+
+        abspath = File.join(dir, basename)
+        next if ignored_path?(abspath)
+
         if dir?(abspath)
-          to_visit << abspath
+          to_visit << abspath unless roots.key?(abspath)
         else
-          return true
+          return true if ruby?(abspath)
         end
       end
     end

data/lib/zeitwerk/loader.rb

@@ -230,53 +230,87 @@ module Zeitwerk
       setup
     end
 
-  # @sig (String | Pathname) -> String?
-  def cpath_expected_at(path)
-    abspath = File.expand_path(path)
+    # Returns a hash that maps the absolute paths of the managed files and
+    # directories to their respective expected constant paths.
+    #
+    # @sig () -> Hash[String, String]
+    def all_expected_cpaths
+      result = {}
 
-    raise Zeitwerk::Error.new("#{abspath} does not exist") unless File.exist?(abspath)
+      actual_roots.each do |root_dir, root_namespace|
+        queue = [[root_dir, real_mod_name(root_namespace)]]
 
-    return unless dir?(abspath) || ruby?(abspath)
-    return if ignored_path?(abspath)
+        until queue.empty?
+          dir, cpath = queue.shift
+          result[dir] = cpath
 
-    paths = []
+          prefix = cpath == "Object" ? "" : cpath + "::"
 
-    if ruby?(abspath)
-      basename = File.basename(abspath, ".rb")
-      return if hidden?(basename)
+          ls(dir) do |basename, abspath, ftype|
+            if ftype == :file
+              basename.delete_suffix!(".rb")
+              result[abspath] = prefix + inflector.camelize(basename, abspath)
+            else
+              if collapse?(abspath)
+                queue << [abspath, cpath]
+              else
+                queue << [abspath, prefix + inflector.camelize(basename, abspath)]
+              end
+            end
+          end
+        end
+      end
 
-      paths << [basename, abspath]
-      walk_up_from = File.dirname(abspath)
-    else
-      walk_up_from = abspath
+      result
     end
 
-    root_namespace = nil
+    # @sig (String | Pathname) -> String?
+    def cpath_expected_at(path)
+      abspath = File.expand_path(path)
 
-    walk_up(walk_up_from) do |dir|
-      break if root_namespace = roots[dir]
-      return if ignored_path?(dir)
+      raise Zeitwerk::Error.new("#{abspath} does not exist") unless File.exist?(abspath)
 
-      basename = File.basename(dir)
-      return if hidden?(basename)
+      return unless dir?(abspath) || ruby?(abspath)
+      return if ignored_path?(abspath)
 
-      paths << [basename, abspath] unless collapse?(dir)
-    end
+      paths = []
 
-    return unless root_namespace
+      if ruby?(abspath)
+        basename = File.basename(abspath, ".rb")
+        return if hidden?(basename)
 
-    if paths.empty?
-      real_mod_name(root_namespace)
-    else
-      cnames = paths.reverse_each.map { |b, a| cname_for(b, a) }
+        paths << [basename, abspath]
+        walk_up_from = File.dirname(abspath)
+      else
+        walk_up_from = abspath
+      end
 
-      if root_namespace == Object
-        cnames.join("::")
+      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
-        "#{real_mod_name(root_namespace)}::#{cnames.join("::")}"
+        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
-  end
 
     # Says if the given constant path would be unloaded on reload. This
     # predicate returns `false` if reloading is disabled.
@@ -408,8 +442,8 @@ module Zeitwerk
 
     # @sig (String, Module) -> void
     private def define_autoloads_for_dir(dir, parent)
-      ls(dir) do |basename, abspath|
-        if ruby?(basename)
+      ls(dir) do |basename, abspath, ftype|
+        if ftype == :file
           basename.delete_suffix!(".rb")
           autoload_file(parent, cname_for(basename, abspath), abspath)
         else

data/lib/zeitwerk/null_inflector.rb

@@ -0,0 +1,5 @@
+class Zeitwerk::NullInflector
+  def camelize(basename, _abspath)
+    basename
+  end
+end

data/lib/zeitwerk/version.rb

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

data/lib/zeitwerk.rb

@@ -9,6 +9,7 @@ module Zeitwerk
   require_relative "zeitwerk/explicit_namespace"
   require_relative "zeitwerk/inflector"
   require_relative "zeitwerk/gem_inflector"
+  require_relative "zeitwerk/null_inflector"
   require_relative "zeitwerk/kernel"
   require_relative "zeitwerk/error"
   require_relative "zeitwerk/version"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.12
+  version: 2.6.15
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-09-25 00:00:00.000000000 Z
+date: 2024-05-26 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem
@@ -35,6 +35,7 @@ files:
 - lib/zeitwerk/loader/config.rb
 - lib/zeitwerk/loader/eager_load.rb
 - lib/zeitwerk/loader/helpers.rb
+- lib/zeitwerk/null_inflector.rb
 - lib/zeitwerk/real_mod_name.rb
 - lib/zeitwerk/registry.rb
 - lib/zeitwerk/version.rb
@@ -61,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.16
+rubygems_version: 3.5.7
 signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader