zeitwerk 2.6.13 → 2.6.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d4ce4eb7136dafe17130fc5d895e525d80ae947f02dd9420b5bc85a4d6f0dfd
-  data.tar.gz: edcac638955fef258ad36a358b78da6831a715ed46446848e39f9f1d8fb7de0b
+  metadata.gz: 8177bcca0fd5895bbe28b19dc5fd04a810e2905f21f33924786a33a317c96207
+  data.tar.gz: 7e441521285fe28230dadfb4c5c9d40564e376dd651ddae043190c5fdd3ee526
 SHA512:
-  metadata.gz: f0a6e64c56635c9c6a8c9b24bdeb7509e4a7f14489f32aae18b02221c23b95b34096184c78d2d1509130ce75031ed0f3a7751b78e43d9b72122440f07cf980bc
-  data.tar.gz: 06440147c101a95ac2c8b7dcd43920a3efc3da2f58b902c157730a449d57b6ef74e0d3db7f3d2735be816a74ceb774e2d4075741556c7e2ba7fa00b8130c1723
+  metadata.gz: 57e0e401c952a13d1b96a8993bbee930132f2b63252ff7cd6646ceeeb5a3de886d1c36a8cdbc06e9add3e16e76bacd08cc8e32b58289fa01e9eabea4dad25581
+  data.tar.gz: e56116c8325ab38f751b8497f8270544543e950f92624c755b5d3d7bb296b48ce4afa668e1b4daae546561ddfa344fd9c650c7114c9cd2c637a514f0ebd38c98

data/README.md

@@ -60,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)
@@ -259,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
@@ -1330,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
 

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/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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.6.13
+  version: 2.6.15
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-06 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
@@ -62,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.5
+rubygems_version: 3.5.7
 signing_key:
 specification_version: 4
 summary: Efficient and thread-safe constant autoloader