zeitwerk 2.7.5 → 2.8.2

data/lib/zeitwerk/loader/config.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
-require "set"
-require "securerandom"
+require 'set'
+require 'securerandom'
 
 module Zeitwerk::Loader::Config
   extend Zeitwerk::Internal
   include Zeitwerk::RealModName
 
+  UNDEFINED = Object.new.freeze
+  private_constant :UNDEFINED
+
   #: camelize(String, String) -> String
   attr_accessor :inflector
 
@@ -15,8 +18,8 @@ module Zeitwerk::Loader::Config
 
   # Absolute paths of the root directories, mapped to their respective root namespaces:
   #
-  #   "/Users/fxn/blog/app/channels" => Object,
-  #   "/Users/fxn/blog/app/adapters" => ActiveJob::QueueAdapters,
+  #   '/Users/fxn/blog/app/channels' => Object,
+  #   '/Users/fxn/blog/app/adapters' => ActiveJob::QueueAdapters,
   #   ...
   #
   # Stored in a hash to preserve order, easily handle duplicates, and have a
@@ -29,6 +32,12 @@ module Zeitwerk::Loader::Config
   attr_reader :roots
   internal :roots
 
+  # Basename of files that define namespaces. For example, if `nsfile` is
+  # 'ns.rb', then `foo/ns.rb` defines the `Foo` namespace.
+  #
+  #: String?
+  attr_reader :nsfile
+
   # Absolute paths of files, directories, or glob patterns to be ignored.
   #
   #: Set[String]
@@ -50,12 +59,20 @@ module Zeitwerk::Loader::Config
   private :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.
+  # glob patterns were expanded. Computed on setup and recomputed on reload.
   #
   #: Set[String]
   attr_reader :collapse_dirs
   private :collapse_dirs
 
+  # Absolute paths of directories that are parents of collapsed directories.
+  # This is a cache to optimize some tree walks. Computed on setup and
+  # recomputed on reload.
+  #
+  #: Set[String]
+  attr_reader :collapse_parents
+  private :collapse_parents
+
   # Absolute paths of files or directories not to be eager loaded.
   #
   #: Set[String]
@@ -82,16 +99,19 @@ module Zeitwerk::Loader::Config
   attr_reader :on_unload_callbacks
   private :on_unload_callbacks
 
+  #: () -> void
   def initialize
     @inflector              = Zeitwerk::Inflector.new
     @logger                 = self.class.default_logger
     @tag                    = SecureRandom.hex(3)
     @initialized_at         = Time.now
     @roots                  = {}
+    @nsfile                 = nil
     @ignored_glob_patterns  = Set.new
     @ignored_paths          = Set.new
     @collapse_glob_patterns = Set.new
     @collapse_dirs          = Set.new
+    @collapse_parents       = Set.new
     @eager_load_exclusions  = Set.new
     @reloading_enabled      = false
     @on_setup_callbacks     = []
@@ -112,7 +132,7 @@ module Zeitwerk::Loader::Config
     end
 
     unless real_mod_name(namespace)
-      raise Zeitwerk::Error, "root namespaces cannot be anonymous"
+      raise Zeitwerk::Error, 'root namespaces cannot be anonymous'
     end
 
     abspath = File.expand_path(path)
@@ -141,6 +161,18 @@ module Zeitwerk::Loader::Config
     @tag = tag.to_s
   end
 
+  #: (String?) -> void ! TypeError, ArgumentError
+  def nsfile=(nsfile)
+    unless nsfile.nil?
+      raise TypeError,     'nsfiles must be strings'              unless nsfile.is_a?(String)
+      raise ArgumentError, 'nsfiles must have .rb extension'      unless @fs.rb_extension?(nsfile)
+      raise ArgumentError, 'nsfiles must be basenames, not paths' unless File.basename(nsfile) == nsfile
+      raise ArgumentError, 'nsfiles cannot be hidden'             if @fs.hidden?(nsfile)
+    end
+
+    @nsfile = nsfile
+  end
+
   # If `namespaces` is falsey (default), returns an array with the absolute
   # paths of the root directories as strings. If truthy, returns a hash table
   # instead. Keys are the absolute paths of the root directories as strings,
@@ -176,7 +208,7 @@ module Zeitwerk::Loader::Config
       break if @reloading_enabled
 
       if @setup
-        raise Zeitwerk::Error, "cannot enable reloading after setup"
+        raise Zeitwerk::Error, 'cannot enable reloading after setup'
       else
         @reloading_enabled = true
       end
@@ -214,7 +246,11 @@ module Zeitwerk::Loader::Config
     glob_patterns = expand_paths(glob_patterns)
     mutex.synchronize do
       collapse_glob_patterns.merge(glob_patterns)
-      collapse_dirs.merge(expand_glob_patterns(glob_patterns))
+      new_collapse_dirs = expand_glob_patterns(glob_patterns)
+      collapse_dirs.merge(new_collapse_dirs)
+      new_collapse_dirs.each do |dir|
+        collapse_parents << File.dirname(dir)
+      end
     end
   end
 
@@ -233,8 +269,8 @@ module Zeitwerk::Loader::Config
   # Supports multiple callbacks, and if there are many, they are executed in
   # the order in which they were defined.
   #
-  #   loader.on_load("SomeApiClient") do |klass, _abspath|
-  #     klass.endpoint = "https://api.dev"
+  #   loader.on_load('SomeApiClient') do |klass, _abspath|
+  #     klass.endpoint = 'https://api.dev'
   #   end
   #
   # Can also be configured for any constant loaded:
@@ -243,12 +279,19 @@ module Zeitwerk::Loader::Config
   #     # ...
   #   end
   #
-  #: (String?) { (top, String) -> void } -> void ! TypeError
-  def on_load(cpath = :ANY, &block)
-    raise TypeError, "on_load only accepts strings" unless cpath.is_a?(String) || cpath == :ANY
+  #: (String) { (top, String) -> void } -> void ! TypeError | NameError
+  #| { (String, top, String) -> void } -> void
+  def on_load(cpath = UNDEFINED, &block)
+    key = if cpath.equal?(UNDEFINED)
+      :ANY
+    elsif !cpath.is_a?(String)
+      raise TypeError, 'on_load only accepts strings'
+    else
+      @cpv.validate!(cpath)
+    end
 
     mutex.synchronize do
-      (on_load_callbacks[cpath] ||= []) << block
+      (on_load_callbacks[key] ||= []) << block
     end
   end
 
@@ -256,7 +299,7 @@ module Zeitwerk::Loader::Config
   # Supports multiple callbacks, and if there are many, they are executed in the
   # order in which they were defined.
   #
-  #   loader.on_unload("Country") do |klass, _abspath|
+  #   loader.on_unload('Country') do |klass, _abspath|
   #     klass.clear_cache
   #   end
   #
@@ -266,12 +309,19 @@ module Zeitwerk::Loader::Config
   #     # ...
   #   end
   #
-  #: (String?) { (top, String) -> void } -> void ! TypeError
-  def on_unload(cpath = :ANY, &block)
-    raise TypeError, "on_unload only accepts strings" unless cpath.is_a?(String) || cpath == :ANY
+  #: (String) { (top, String) -> void } -> void ! TypeError | NameError
+  #| { (String, top, String) -> void } -> void
+  def on_unload(cpath = UNDEFINED, &block)
+    key = if cpath.equal?(UNDEFINED)
+      :ANY
+    elsif !cpath.is_a?(String)
+      raise TypeError, 'on_unload only accepts strings'
+    else
+      @cpv.validate!(cpath)
+    end
 
     mutex.synchronize do
-      (on_unload_callbacks[cpath] ||= []) << block
+      (on_unload_callbacks[key] ||= []) << block
     end
   end
 
@@ -315,6 +365,16 @@ module Zeitwerk::Loader::Config
     roots.key?(dir)
   end
 
+  #: (String) -> bool
+  internal def collapse?(dir)
+    collapse_dirs.member?(dir)
+  end
+
+  #: (String) -> bool
+  internal def collapse_parent?(dir)
+    collapse_parents.member?(dir)
+  end
+
   #: (String) -> bool
   private def excluded_from_eager_load?(abspath)
     # Optimize this common use case.
@@ -328,11 +388,6 @@ module Zeitwerk::Loader::Config
     false
   end
 
-  #: (String) -> bool
-  private def collapse?(dir)
-    collapse_dirs.member?(dir)
-  end
-
   #: (String | Pathname | Array[String | Pathname]) -> Array[String]
   private def expand_paths(paths)
     paths.flatten.map! { |path| File.expand_path(path) }
@@ -354,4 +409,12 @@ module Zeitwerk::Loader::Config
   private def recompute_collapse_dirs
     collapse_dirs.replace(expand_glob_patterns(collapse_glob_patterns))
   end
+
+  #: () -> void
+  private def recompute_collapse_parents
+    collapse_parents.clear
+    collapse_dirs.each do |dir|
+      collapse_parents << File.dirname(dir)
+    end
+  end
 end

data/lib/zeitwerk/loader/constant_path_validator.rb

@@ -0,0 +1,17 @@
+# @private
+class Zeitwerk::Loader::ConstantPathValidator # :nodoc
+  CNAME_VALIDATOR = Module.new.freeze #: Module
+  private_constant :CNAME_VALIDATOR
+
+  # Technically, this validation works with symbols, but API boundary restricts
+  # input to strings, so we assume strings, and we test strings.
+  #
+  #: (String) -> String ! NameError
+  def validate!(possible_cpath)
+    # We do this before validating because as of this writing, TruffleRuby
+    # raises TypeError if the argument has leading colons.
+    possible_cpath = possible_cpath.delete_prefix('::')
+    CNAME_VALIDATOR.const_defined?(possible_cpath, false)
+    possible_cpath
+  end
+end

data/lib/zeitwerk/loader/eager_load.rb

@@ -1,9 +1,10 @@
 module Zeitwerk::Loader::EagerLoad
   # Eager loads all files in the root directories, recursively. Files do not
-  # need to be in `$LOAD_PATH`, absolute file names are used. Ignored and
-  # shadowed files are not eager loaded. You can opt-out specifically in
-  # specific files and directories with `do_not_eager_load`, and that can be
-  # overridden passing `force: true`.
+  # need to be in `$LOAD_PATH`, absolute file names are used.
+  #
+  # Ignored files are not eager loaded. You can opt-out specifically in specific
+  # files and directories with `do_not_eager_load`, and that can be overridden
+  # passing `force: true`.
   #
   #: (?force: boolish) -> void
   def eager_load(force: false)
@@ -11,7 +12,7 @@ module Zeitwerk::Loader::EagerLoad
       break if @eager_loaded
       raise Zeitwerk::SetupRequired unless @setup
 
-      log { "eager load start" }
+      log { 'eager load start' }
 
       actual_roots.each do |root_dir, root_namespace|
         actual_eager_load_dir(root_dir, root_namespace, force: force)
@@ -24,7 +25,7 @@ module Zeitwerk::Loader::EagerLoad
 
       @eager_loaded = true
 
-      log { "eager load end" }
+      log { 'eager load end' }
     end
   end
 
@@ -91,11 +92,11 @@ module Zeitwerk::Loader::EagerLoad
         eager_load_child_namespace(mod, mod_name, root_dir, root_namespace)
       else
         root_namespace_name = real_mod_name(root_namespace)
-        if root_namespace_name.start_with?(mod_name + "::")
+        if root_namespace_name.start_with?(mod_name + '::')
           actual_eager_load_dir(root_dir, root_namespace)
         elsif mod_name == root_namespace_name
           actual_eager_load_dir(root_dir, root_namespace)
-        elsif mod_name.start_with?(root_namespace_name + "::")
+        elsif mod_name.start_with?(root_namespace_name + '::')
           eager_load_child_namespace(mod, mod_name, root_dir, root_namespace)
         else
           # Unrelated constant hierarchies, do nothing.
@@ -119,7 +120,7 @@ module Zeitwerk::Loader::EagerLoad
     raise Zeitwerk::Error.new("#{abspath} is not a Ruby file") if !@fs.rb_extension?(abspath)
     raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_path?(abspath)
 
-    file_basename = File.basename(abspath, ".rb")
+    file_basename = File.basename(abspath)
     raise Zeitwerk::Error.new("#{abspath} is ignored") if @fs.hidden?(file_basename)
 
     root_namespace = nil
@@ -138,17 +139,20 @@ module Zeitwerk::Loader::EagerLoad
 
     raise Zeitwerk::Error.new("I do not manage #{abspath}") unless root_namespace
 
-    base_cname = cname_for(file_basename, abspath)
-
     namespace = root_namespace
     paths.reverse_each do |basename, dir|
       cname = cname_for(basename, dir)
       namespace = namespace.const_get(cname, false)
     end
 
-    raise Zeitwerk::Error.new("#{abspath} is shadowed") if shadowed_file?(abspath)
-
-    namespace.const_get(base_cname, false)
+    if file_basename == @nsfile
+      namespace
+    elsif shadowed_file?(abspath)
+      raise Zeitwerk::Error.new("#{abspath} is shadowed")
+    else
+      cname = cname_for(file_basename.delete_suffix('.rb'), abspath)
+      namespace.const_get(cname, false)
+    end
   end
 
   # The caller is responsible for making sure `namespace` is the namespace that
@@ -171,12 +175,8 @@ module Zeitwerk::Loader::EagerLoad
             cref.get
           end
         else
-          if collapse?(abspath)
-            queue << [abspath, namespace]
-          else
-            cname = cname_for(basename, abspath)
-            queue << [abspath, namespace.const_get(cname, false)]
-          end
+          cname = cname_for(basename, abspath)
+          queue << [abspath, namespace.const_get(cname, false)]
         end
       end
     end
@@ -191,7 +191,7 @@ module Zeitwerk::Loader::EagerLoad
   private def eager_load_child_namespace(child, child_name, root_dir, root_namespace)
     suffix = child_name
     unless root_namespace.equal?(Object)
-      suffix = suffix.delete_prefix(real_mod_name(root_namespace) + "::")
+      suffix = suffix.delete_prefix(real_mod_name(root_namespace) + '::')
     end
 
     # These directories are at the same namespace level, there may be more if
@@ -204,14 +204,10 @@ module Zeitwerk::Loader::EagerLoad
     dirs = [root_dir]
     next_dirs = []
 
-    suffix.split("::").each do |segment|
+    suffix.split('::').each do |segment|
       while (dir = dirs.shift)
         @fs.ls(dir) do |basename, abspath, ftype|
-          next unless ftype == :directory
-
-          if collapse?(abspath)
-            dirs << abspath
-          elsif segment == cname_for(basename, abspath).to_s
+          if ftype == :directory && segment == cname_for(basename, abspath).to_s
             next_dirs << abspath
           end
         end

data/lib/zeitwerk/loader/file_system.rb

@@ -12,8 +12,22 @@ class Zeitwerk::Loader::FileSystem # :nodoc:
     @loader = loader
   end
 
+  # This method lists directories, filtering out the following:
+  #
+  # - Hidden entries.
+  # - Ignored entries.
+  # - Files whose extension is not `.rb`.
+  # - Nested root directories, since they represent separate trees.
+  # - Subdirectories that (recursively) contain no Ruby files.
+  #
+  # If `collapse` is true, collapsed directories are not yielded, instead, the
+  # method recurses so that the caller gets a conceptually flat listing.
+  #
+  # For every entry that is not excluded, `ls` yields its basename, absolute
+  # path, and file type, which can only be :file or :directory.
+  #
   #: (String) { (String, String, Symbol) -> void } -> void
-  def ls(dir)
+  def ls(dir, collapse: true, &block)
     children = relevant_dir_entries(dir)
 
     # The order in which a directory is listed depends on the file system.
@@ -24,9 +38,14 @@ class Zeitwerk::Loader::FileSystem # :nodoc:
     children.sort_by!(&:first)
 
     children.each do |basename, abspath, ftype|
-      if :directory == ftype && !has_at_least_one_ruby_file?(abspath)
-        @loader.__log { "directory #{abspath} is ignored because it has no Ruby files" }
-        next
+      if ftype == :directory
+        if !has_at_least_one_ruby_file?(abspath)
+          @loader.__log { "directory #{abspath} is ignored because it has no Ruby files" }
+          next
+        elsif collapse && @loader.__collapse?(abspath)
+          ls(abspath, collapse: collapse, &block)
+          next
+        end
       end
 
       yield basename, abspath, ftype
@@ -38,8 +57,47 @@ class Zeitwerk::Loader::FileSystem # :nodoc:
     loop do
       yield abspath
       abspath, basename = File.split(abspath)
-      break if basename == "/"
+      break if basename == '/'
+    end
+  end
+
+  # Returns the absolute path to an nsfile in `dir`, if there is exactly one. If
+  # there is none, it returns `nil`.
+  #
+  # This method accounts for collapsed directories, which conceptually allow for
+  # multiple nsfiles. If two are found, Zeitwerk::ConflictingNamespaceDefinitionError is raised.
+  #
+  #: (Zeitwerk::Cref, String) -> String? ! Zeitwerk::ConflictingNamespaceDefinitionError
+  def has_exactly_one_nsfile?(cref, dir)
+    return unless @loader.nsfile
+
+    # When `dir` does not have any collapsed directories a simple lookup
+    # suffices. This is a common case worth optimizing.
+    unless @loader.__collapse_parent?(dir)
+      nsfile_abspath = File.join(dir, @loader.nsfile)
+      if File.exist?(nsfile_abspath) && !@loader.__ignored_path?(nsfile_abspath)
+        return nsfile_abspath
+      end
+      return
+    end
+
+    nsfile = nil
+
+    to_visit = [dir]
+    while (dir = to_visit.shift)
+      relevant_dir_entries(dir) do |basename, abspath, ftype|
+        if ftype == :file && basename == @loader.nsfile
+          if nsfile
+            raise Zeitwerk::ConflictingNamespaceDefinitionError.new(cref.path, location: nsfile, conflicting_file: abspath)
+          end
+          nsfile = abspath
+        elsif ftype == :directory && @loader.__collapse?(abspath)
+          to_visit << abspath
+        end
+      end
     end
+
+    nsfile
   end
 
   # Encodes the documented conventions.
@@ -55,7 +113,7 @@ class Zeitwerk::Loader::FileSystem # :nodoc:
 
   #: (String) -> bool
   def rb_extension?(path)
-    path.end_with?(".rb")
+    path.end_with?('.rb')
   end
 
   #: (String) -> bool
@@ -65,7 +123,7 @@ class Zeitwerk::Loader::FileSystem # :nodoc:
 
   #: (String) -> bool
   def hidden?(basename)
-    basename.start_with?(".")
+    basename.start_with?('.')
   end
 
   private
@@ -80,7 +138,7 @@ class Zeitwerk::Loader::FileSystem # :nodoc:
 
     while (dir = to_visit.shift)
       relevant_dir_entries(dir) do |_, abspath, ftype|
-        return true if :file == ftype
+        return true if ftype == :file
         to_visit << abspath
       end
     end
@@ -96,18 +154,9 @@ class Zeitwerk::Loader::FileSystem # :nodoc:
     each_ruby_file_or_directory(dir) do |basename, abspath, ftype|
       next if @loader.__ignored_path?(abspath)
 
-      if :link == ftype
-        begin
-          ftype = File.stat(abspath).ftype.to_sym
-        rescue Errno::ENOENT
-          warn "ignoring broken symlink #{abspath}"
-          next
-        end
-      end
-
-      if :file == ftype
-        yield basename, abspath, ftype if rb_extension?(basename)
-      elsif :directory == ftype
+      if ftype == :file
+        yield basename, abspath, ftype
+      else
         # Conceptually, root directories represent a separate project tree.
         yield basename, abspath, ftype unless @loader.__root_dir?(abspath)
       end
@@ -135,10 +184,10 @@ class Zeitwerk::Loader::FileSystem # :nodoc:
         if rb_extension?(basename)
           abspath = File.join(dir, basename).freeze
           yield basename, abspath, :file # By convention.
-        elsif :directory == ftype
+        elsif ftype == :directory
           abspath = File.join(dir, basename).freeze
           yield basename, abspath, :directory
-        elsif :link == ftype
+        elsif ftype == :link
           abspath = File.join(dir, basename).freeze
           yield basename, abspath, :directory if dir?(abspath)
         end
@@ -155,9 +204,7 @@ class Zeitwerk::Loader::FileSystem # :nodoc:
           yield basename, abspath, :file # By convention.
         else
           abspath = File.join(dir, basename).freeze
-          if dir?(abspath)
-            yield basename, abspath, :directory
-          end
+          yield basename, abspath, :directory if dir?(abspath)
         end
       end
     end

data/lib/zeitwerk/loader/helpers.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
 module Zeitwerk::Loader::Helpers
-  CNAME_VALIDATOR = Module.new #: Module
-  private_constant :CNAME_VALIDATOR
-
   #: (String, String) -> Symbol ! Zeitwerk::NameError
   private def cname_for(basename, abspath)
     cname = inflector.camelize(basename, abspath)
@@ -12,7 +9,7 @@ module Zeitwerk::Loader::Helpers
       raise TypeError, "#{inflector.class}#camelize must return a String, received #{cname.inspect}"
     end
 
-    if cname.include?("::")
+    if cname.include?('::')
       raise Zeitwerk::NameError.new(<<~MESSAGE, cname)
         wrong constant name #{cname} inferred by #{inflector.class} from
 
@@ -23,9 +20,9 @@ module Zeitwerk::Loader::Helpers
     end
 
     begin
-      CNAME_VALIDATOR.const_defined?(cname, false)
+      @cpv.validate!(cname)
     rescue ::NameError => error
-      path_type = @fs.rb_extension?(abspath) ? "file" : "directory"
+      path_type = @fs.rb_extension?(abspath) ? 'file' : 'directory'
 
       raise Zeitwerk::NameError.new(<<~MESSAGE, error.name)
         #{error.message} inferred by #{inflector.class} from #{path_type}