zeitwerk 2.7.4 → 2.8.0

data/lib/zeitwerk/inflector.rb

@@ -5,9 +5,9 @@ module Zeitwerk
     # Very basic snake case -> camel case conversion.
     #
     #   inflector = Zeitwerk::Inflector.new
-    #   inflector.camelize("post", ...)             # => "Post"
-    #   inflector.camelize("users_controller", ...) # => "UsersController"
-    #   inflector.camelize("api", ...)              # => "Api"
+    #   inflector.camelize('post', ...)             # => 'Post'
+    #   inflector.camelize('users_controller', ...) # => 'UsersController'
+    #   inflector.camelize('api', ...)              # => 'Api'
     #
     # Takes into account hard-coded mappings configured with `inflect`.
     #
@@ -20,13 +20,13 @@ module Zeitwerk
     #
     #   inflector = Zeitwerk::Inflector.new
     #   inflector.inflect(
-    #     "html_parser"   => "HTMLParser",
-    #     "mysql_adapter" => "MySQLAdapter"
+    #     'html_parser'   => 'HTMLParser',
+    #     'mysql_adapter' => 'MySQLAdapter'
     #   )
     #
-    #   inflector.camelize("html_parser", abspath)      # => "HTMLParser"
-    #   inflector.camelize("mysql_adapter", abspath)    # => "MySQLAdapter"
-    #   inflector.camelize("users_controller", abspath) # => "UsersController"
+    #   inflector.camelize('html_parser', abspath)      # => 'HTMLParser'
+    #   inflector.camelize('mysql_adapter', abspath)    # => 'MySQLAdapter'
+    #   inflector.camelize('users_controller', abspath) # => 'UsersController'
     #
     #: (Hash[String, String]) -> void
     def inflect(inflections)

data/lib/zeitwerk/loader/callbacks.rb

@@ -12,12 +12,12 @@ module Zeitwerk::Loader::Callbacks # :nodoc: all
     Zeitwerk::Registry.autoloads.unregister(file)
 
     if cref.defined?
-      log("constant #{cref} loaded from file #{file}") if logger
+      log { "constant #{cref} loaded from file #{file}" }
       to_unload[file] = cref if reloading_enabled?
       run_on_load_callbacks(cref.path, cref.get, file) unless on_load_callbacks.empty?
     else
       msg = "expected file #{file} to define constant #{cref}, but didn't"
-      log(msg) if logger
+      log { msg }
 
       # Ruby still keeps the autoload defined, but we remove it because the
       # contract in Zeitwerk is more strict.
@@ -52,7 +52,7 @@ module Zeitwerk::Loader::Callbacks # :nodoc: all
     dirs_autoload_monitor.synchronize do
       if cref = autoloads.delete(dir)
         implicit_namespace = cref.set(Module.new)
-        log("module #{cref} autovivified from directory #{dir}") if logger
+        log { "module #{cref} autovivified from directory #{dir}" }
 
         to_unload[dir] = cref if reloading_enabled?
 
@@ -77,7 +77,7 @@ module Zeitwerk::Loader::Callbacks # :nodoc: all
   internal def on_namespace_loaded(cref, namespace)
     if dirs = namespace_dirs.delete(cref)
       dirs.each do |dir|
-        define_autoloads_for_dir(dir, namespace)
+        define_autoloads_for_dir(dir, namespace, external: false)
       end
     end
   end

data/lib/zeitwerk/loader/config.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require "set"
-require "securerandom"
+require 'set'
+require 'securerandom'
 
 module Zeitwerk::Loader::Config
   extend Zeitwerk::Internal
@@ -15,8 +15,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 +29,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 +56,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 +96,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,12 +129,12 @@ 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)
-    if dir?(abspath)
-      raise_if_conflicting_directory(abspath)
+    if @fs.dir?(abspath)
+      raise_if_conflicting_root_dir(abspath)
       roots[abspath] = namespace
     else
       raise Zeitwerk::Error, "the root directory #{abspath} does not exist"
@@ -141,6 +158,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 +205,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 +243,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 +266,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:
@@ -245,7 +278,7 @@ module Zeitwerk::Loader::Config
   #
   #: (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
+    raise TypeError, 'on_load only accepts strings' unless cpath.is_a?(String) || cpath == :ANY
 
     mutex.synchronize do
       (on_load_callbacks[cpath] ||= []) << block
@@ -256,7 +289,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
   #
@@ -268,7 +301,7 @@ module Zeitwerk::Loader::Config
   #
   #: (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
+    raise TypeError, 'on_unload only accepts strings' unless cpath.is_a?(String) || cpath == :ANY
 
     mutex.synchronize do
       (on_unload_callbacks[cpath] ||= []) << block
@@ -290,49 +323,54 @@ module Zeitwerk::Loader::Config
     # Common use case.
     return false if ignored_paths.empty?
 
-    walk_up(abspath) do |path|
+    @fs.walk_up(abspath) do |path|
       return true  if ignored_path?(path)
-      return false if roots.key?(path)
+      return false if root_dir?(path)
     end
 
     false
   end
 
   #: (String) -> bool
-  private def ignored_path?(abspath)
+  internal def ignored_path?(abspath)
     ignored_paths.member?(abspath)
   end
 
   #: () -> Array[String]
   private def actual_roots
     roots.reject do |root_dir, _root_namespace|
-      !dir?(root_dir) || ignored_path?(root_dir)
+      !@fs.dir?(root_dir) || ignored_path?(root_dir)
     end
   end
 
   #: (String) -> bool
-  private def root_dir?(dir)
+  internal def root_dir?(dir)
     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.
     return false if eager_load_exclusions.empty?
 
-    walk_up(abspath) do |path|
+    @fs.walk_up(abspath) do |path|
       return true  if eager_load_exclusions.member?(path)
-      return false if roots.key?(path)
+      return false if root_dir?(path)
     end
 
     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 +392,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/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") if logger
+      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") if logger
+      log { 'eager load end' }
     end
   end
 
@@ -34,23 +35,21 @@ module Zeitwerk::Loader::EagerLoad
 
     abspath = File.expand_path(path)
 
-    raise Zeitwerk::Error.new("#{abspath} is not a directory") unless dir?(abspath)
+    raise Zeitwerk::Error.new("#{abspath} is not a directory") unless @fs.dir?(abspath)
 
-    cnames = []
+    paths = []
 
     root_namespace = nil
-    walk_up(abspath) do |dir|
+    @fs.walk_up(abspath) do |dir|
       return if ignored_path?(dir)
       return if eager_load_exclusions.member?(dir)
 
       break if root_namespace = roots[dir]
 
       basename = File.basename(dir)
-      return if hidden?(basename)
+      return if @fs.hidden?(basename)
 
-      unless collapse?(dir)
-        cnames << inflector.camelize(basename, dir).to_sym
-      end
+      paths << [basename, dir] unless collapse?(dir)
     end
 
     raise Zeitwerk::Error.new("I do not manage #{abspath}") unless root_namespace
@@ -58,7 +57,8 @@ module Zeitwerk::Loader::EagerLoad
     return if @eager_loaded
 
     namespace = root_namespace
-    cnames.reverse_each do |cname|
+    paths.reverse_each do |basename, dir|
+      cname = cname_for(basename, dir)
       # Can happen if there are no Ruby files. This is not an error condition,
       # the directory is actually managed. Could have Ruby files later.
       return unless namespace.const_defined?(cname, false)
@@ -92,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.
@@ -117,40 +117,42 @@ module Zeitwerk::Loader::EagerLoad
     abspath = File.expand_path(path)
 
     raise Zeitwerk::Error.new("#{abspath} does not exist") unless File.exist?(abspath)
-    raise Zeitwerk::Error.new("#{abspath} is not a Ruby file") if dir?(abspath) || !ruby?(abspath)
+    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)
 
-    basename = File.basename(abspath, ".rb")
-    raise Zeitwerk::Error.new("#{abspath} is ignored") if hidden?(basename)
-
-    base_cname = inflector.camelize(basename, abspath).to_sym
+    file_basename = File.basename(abspath)
+    raise Zeitwerk::Error.new("#{abspath} is ignored") if @fs.hidden?(file_basename)
 
     root_namespace = nil
-    cnames = []
+    paths = []
 
-    walk_up(File.dirname(abspath)) do |dir|
+    @fs.walk_up(File.dirname(abspath)) do |dir|
       raise Zeitwerk::Error.new("#{abspath} is ignored") if ignored_path?(dir)
 
       break if root_namespace = roots[dir]
 
       basename = File.basename(dir)
-      raise Zeitwerk::Error.new("#{abspath} is ignored") if hidden?(basename)
+      raise Zeitwerk::Error.new("#{abspath} is ignored") if @fs.hidden?(basename)
 
-      unless collapse?(dir)
-        cnames << inflector.camelize(basename, dir).to_sym
-      end
+      paths << [basename, dir] unless collapse?(dir)
     end
 
     raise Zeitwerk::Error.new("I do not manage #{abspath}") unless root_namespace
 
     namespace = root_namespace
-    cnames.reverse_each do |cname|
+    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
@@ -161,11 +163,11 @@ module Zeitwerk::Loader::EagerLoad
     honour_exclusions = !force
     return if honour_exclusions && excluded_from_eager_load?(dir)
 
-    log("eager load directory #{dir} start") if logger
+    log { "eager load directory #{dir} start" }
 
     queue = [[dir, namespace]]
     while (current_dir, namespace = queue.shift)
-      ls(current_dir) do |basename, abspath, ftype|
+      @fs.ls(current_dir) do |basename, abspath, ftype|
         next if honour_exclusions && eager_load_exclusions.member?(abspath)
 
         if ftype == :file
@@ -173,17 +175,13 @@ module Zeitwerk::Loader::EagerLoad
             cref.get
           end
         else
-          if collapse?(abspath)
-            queue << [abspath, namespace]
-          else
-            cname = inflector.camelize(basename, abspath).to_sym
-            queue << [abspath, namespace.const_get(cname, false)]
-          end
+          cname = cname_for(basename, abspath)
+          queue << [abspath, namespace.const_get(cname, false)]
         end
       end
     end
 
-    log("eager load directory #{dir} end") if logger
+    log { "eager load directory #{dir} end" }
   end
 
   # In order to invoke this method, the caller has to ensure `child` is a
@@ -193,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
@@ -206,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)
-        ls(dir) do |basename, abspath, ftype|
-          next unless ftype == :directory
-
-          if collapse?(abspath)
-            dirs << abspath
-          elsif segment == inflector.camelize(basename, abspath)
+        @fs.ls(dir) do |basename, abspath, ftype|
+          if ftype == :directory && segment == cname_for(basename, abspath).to_s
             next_dirs << abspath
           end
         end