zeitwerk 1.0.0.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b8109591e515376b3aa028f266d2d354be134aa38cc7b062f7130afc1640f91d
+  data.tar.gz: b9c0118d2cbd8aa5dba6bf22be756f3c7ad448c7320958f76e53fc898ad55b76
+SHA512:
+  metadata.gz: 51bc3e2567f0ef5c6199e56799ab0d851ba7006e35ccf3813d4dde949fe44d9af6848ac4da219e359a017275d86b0fae7fc4657660c8a0c0737ffb02ac78f614
+  data.tar.gz: 4d7051b8d27fc70fd45aaff66c78e00881e758b1d7db1c551026233874f837351aaa72336c1b8fa083b6a83fbc6987f16f0687e9fcf92df8a41f36812d5fad2d

data/README.md

@@ -0,0 +1,326 @@
+# WIP — NOT PUBLISHED — API AND DOCS IN FLUX
+
+# Zeitwerk
+
+[![Build Status](https://travis-ci.com/fxn/zeitwerk.svg?branch=master)](https://travis-ci.com/fxn/zeitwerk)
+
+## Introduction
+
+Zeitwerk is an efficient and thread-safe code loader for Ruby.
+
+Given a conventional file structure, Zeitwerk loads the project classes and modules on demand. 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.
+
+The library is designed so that each gem and application can have their own loader, independent of each other. Each loader has its own configuration, inflector, and optional logger.
+
+Zeitwerk is also able to reload code, which may be handy for web applications. Coordination is needed to reload in a thread-safe manner. The documentation below explains how to do this.
+
+Finally, in some production setups it may be interesting to be able to eager load all code upfront. Zeitwerk is able to do that too.
+
+## Synopsis
+
+Main interface for gems:
+
+```ruby
+# lib/my_gem.rb (main file)
+
+require "zeitwerk"
+Zeitwerk::Loader.for_gem.setup
+
+module MyGem
+  # ...
+end
+```
+
+Main generic interface:
+
+```ruby
+loader = Zeitwerk::Loader.new
+loader.push_dir(...)
+loader.setup
+```
+
+Zeitwerk is ready to right after the `setup` call.
+
+Later, you can reload if you want to:
+
+```ruby
+loader.reload
+```
+
+and you can also eager load:
+
+```ruby
+loader.eager_load
+```
+
+Broadcast `eager_load` to all loaders:
+
+```
+Zeitwerk::Loader.eager_load_all
+```
+
+## Compatible file structure
+
+To have a file structure compatible with Zeitwerk, just name files and directories after the name of the classes and modules they define:
+
+```
+lib/my_gem.rb         -> MyGem
+lib/my_gem/foo.rb     -> MyGem::Foo
+lib/my_gem/bar_baz.rb -> MyGem::BarBaz
+lib/my_gem/woo/zoo.rb -> MyGem::Woo::Zoo
+```
+
+Every directory configured with `push_dir` acts as root namespace. There can be several of them. For example, given
+
+```ruby
+loader.push_dir(Rails.root.join("app/models"))
+loader.push_dir(Rails.root.join("app/controllers"))
+```
+
+you get the mappings
+
+```
+app/models/user.rb                        -> User
+app/controllers/admin/users_controller.rb -> Admin::UsersController
+```
+
+### Implicit namespaces
+
+Directories without a matching Ruby file get modules autovivified automatically by Zeitwerk. For example, in
+
+```
+app/controllers/admin/users_controller.rb -> Admin::UsersController
+```
+
+`Admin` is autovivified as a module on demand, you do not need to define an `Admin` class or module in an `admin.rb` file explicitly.
+
+### Explicit namespaces
+
+Classes and modules that act as namespaces can also be explictly defined, though. For instance, consider
+
+```
+app/models/hotel.rb      -> Hotel
+app/models/hotel/pricing -> Hotel::Pricing
+```
+
+Zeitwerk does not autovivify a `Hotel` module in that case. The file `app/models/hotel.rb` explictly defines `Hotel` and Zeitwerk loads it as needed before going for `Hotel::Pricing`.
+
+## Synopsis
+
+
+
+The autoloading semantics provided by Zeitwerk match Ruby's. Zeitwerk bases autoloading on `Kernel#autoload`, which has builtin support in the interpreter in constant lookup algorithms and related APIs.
+
+Autoloadable files can be required. The idea is to _not_ use `require` at all with a gem managed by Zeitwerk, but support for this exists in case your users have `require` calls already in place and upgrade, for example.
+
+## Use case: Gems
+
+To use Zeitwerk in a gem just throw these couple of lines in the main file:
+
+```ruby
+# lib/my_gem.rb
+
+require "zeitwerk"
+Zeitwerk::Loader.for_gem.setup
+
+module MyGem
+  # ...
+end
+```
+
+The loader of your gem is exclusive, it has its own configuration, inflector, and logger.
+
+## Use case: Generic interface
+
+The generic interface to use Zeitwerk in a different context is
+
+```ruby
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.new
+loader.push_dir("...")
+loader.setup
+```
+
+A loader instantiated that way is independent of other loaders. It has its own configuration, inflector, and logger.
+
+The variable used to setup the loader can get out of scope. The instance won't be garbage collected because Zeitwerk keeps a registry of them.
+
+## Inflection
+
+Each individual loader needs an inflector to figure out which constant path would a given file or directory map to. Zeitwerk ships with two basic inflectors.
+
+### Zeitwerk::Inflector
+
+This is a super basic inflector that converts snake case to camel case preserving upper case letters:
+
+```
+user             -> User
+users_controller -> UsersController
+html_parser      -> HtmlParser
+HTML_parser      -> HTMLParser
+```
+
+This is the default inflector.
+
+### Zeitwerk::GemInflector
+
+The loader instantiated behind the scenes by `Zeitwerk::Loader.for_gem` gets assigned by default an inflector that is like the basic one, except it expects `lib/my_gem/version.rb` to define `MyGem::VERSION`.
+
+### Custom inflector
+
+The inflectors that ship with Zeitwerk are deterministic and simple. But you can configure your own:
+
+```ruby
+# frozen_string_literal: true
+
+class MyInflector < Zeitwerk::Inflector
+  def camelize(basename, _abspath)
+    case basename
+    when "api"
+      "API"
+    when "mysql_adapter"
+      "MySQLAdapter"
+    else
+      super
+    end
+  end
+end
+```
+
+The first argument, `basename`, is a string with the basename of the file or directory to be inflected. In the case of a file, without extension. The inflector needs to return this basename inflected. Therefore, a simple constant name without colons.
+
+The second argument, `abspath`, is a string with the absolute path to the file or directory in case you need it to decide how to inflect the basename.
+
+Then, assign the inflector before calling `setup`:
+
+```
+loader = Zeitwerk::Loader.new
+loader.inflector = MyInflector.new
+loader.setup
+```
+
+## Logging
+
+Zeitwerk is silent by default, but you can configure a callable as logger.
+
+In the case of gems, for example:
+
+```ruby
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.logger = method(:puts)
+loader.setup
+```
+
+If there is a logger configured, the the loader is going to print traces when autoloads are set, files preloaded, files autoloaded, and modules autovivified from directories.
+
+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 be lazy and avoid unnecessary tree walks. It sets autoloads one depth level at a time, and only on demand.
+
+## Reloading
+
+In order to reload code, unload and setup:
+
+```ruby
+loader.unload
+loader.setup
+```
+
+It is important to highlight that these are instance methods. Therefore, reloading the project managed by your autoloader does _not_ reload the code of other gems using Zeitwerk.
+
+Generally speaking, reloading is useful for services, servers, web applications, etc. Gems that implement regular libraries, so to speak, won't normally have a use case for reloading.
+
+## Eager loading
+
+Zeitwerk instances are able to eager load their managed files:
+
+```ruby
+loader.eager_load
+```
+
+You can opt-out of eager loading individual files or directories:
+
+```ruby
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+
+db_adapters = File.expand_path("my_gem/db_adapters", __dir__)
+cache_adapters = File.expand_path("my_gem/cache_adapters", __dir__)
+loader.do_not_eager_load(db_adapters, cache_adapters)
+loader.eager_load # won't go into the directories with db/cache adapters
+```
+
+Files and directories excluded from eager loading can still be autoloaded, so a technique like this is possible:
+
+```ruby
+db_adapter = Object.const_get("MyGem::DbAdapters::#{config[:db_adapter]}")
+```
+
+You can even opt-out from eager loading entirely:
+
+```ruby
+require "zeitwerk"
+loader = Zeitwerk::Loader.for_gem
+loader.do_not_eager_load(__dir__)
+loader.setup
+```
+
+If you want to eager load yourself and all dependencies using Zeitwerk, you can broadcast the `eager_load` call to all registered instances:
+
+```ruby
+Zeitwerk::Loader.eager_load_all
+```
+
+In that case, exclusions are per autoloader, and so will apply to each of them accordingly.
+
+This may be handy in top-level services, like web applications.
+
+## Preloading
+
+Zeitwerk instances are able to preload files and directories.
+
+```ruby
+loader.preload("app/models/videogame.rb")
+loader.preload("app/models/book.rb")
+```
+
+The example above depicts several calls are supported, but `preload` accepts multiple arguments and arrays of strings as well.
+
+The call can happen after `setup` (preloads on the spot), or before `setup` (executes during setup).
+
+If you're using reloading, preloads run on each reload too.
+
+This is a feature specifically thought for STIs in Rails, preloading the leafs of an STI tree ensures all classes are known when doing a query.
+
+Instead of preloading, gems can issue regular requires in the main file:
+
+```ruby
+require "zeitwerk"
+Zeitwerk::Loader.for_gem.setup
+
+module MyGem
+  require "preload_me"
+end
+```
+
+## Supported Ruby versions
+
+Zeitwerk works with MRI 2.4.4 and above.
+
+## Motivation
+
+Since `require` has global side-effects, and there is no static way to verify that you have issued the `require` calls for code that your file depends on, in practice it is very easy to forget some. That introduces bugs that depend on the load order. Zeitwerk provides a way to forget about `require` in your own code, just name things following conventions and done.
+
+On the other hand, autoloading in Rails is based on `const_missing`, which lacks fundamental information like the nesting and the resolution algorithm that was being used. Because of that, Rails autoloading is not able to match Ruby's semantics and that introduces a series of gotchas. The original goal of this project was to bring a better autoloading mechanism for Rails 6.
+
+## Thanks
+
+I'd like to thank [@matthewd](https://github.com/matthewd) for the discussions we've had about this topic in the past years, I learned a couple of tricks used in Zeitwerk from him.
+
+Also would like to thank [@Shopify](https://github.com/Shopify), [@rafaelfranca](https://github.com/rafaelfranca), and [@dylanahsmith](https://github.com/dylanahsmith), for sharing [this PoC](https://github.com/Shopify/autoload_reloader). The technique Zeitwerk uses to support explicit namespaces was copied from that project.
+
+## License
+
+Released under the MIT License, Copyright (c) 2019–<i>ω</i> Xavier Noria.

data/lib/zeitwerk.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Zeitwerk
+  require_relative "zeitwerk/loader"
+  require_relative "zeitwerk/registry"
+  require_relative "zeitwerk/inflector"
+  require_relative "zeitwerk/gem_inflector"
+  require_relative "zeitwerk/kernel"
+end

data/lib/zeitwerk/gem_inflector.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Zeitwerk
+  class GemInflector < Inflector
+    # @param gem_entry_point [String]
+    def initialize(root_file)
+      namespace = File.basename(root_file, ".rb")
+      @version_file = File.join(namespace, "version.rb")
+    end
+
+    # @param basename [String]
+    # @param abspath [String]
+    # @return [String]
+    def camelize(basename, abspath)
+      basename == "version" && abspath.end_with?(@version_file) ? "VERSION" : super
+    end
+  end
+end

data/lib/zeitwerk/inflector.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Zeitwerk
+  class Inflector # :nodoc:
+    # Given a basename without extension, returns the name of the constant
+    # expected to be defined in such file or directory.
+    #
+    #   Zeitwerk::Inflector.camelize("post", ...)             # => "Post"
+    #   Zeitwerk::Inflector.camelize("users_controller", ...) # => "UsersController"
+    #   Zeitwerk::Inflector.camelize("api", ...)              # => "Api"
+    #   Zeitwerk::Inflector.camelize("HTML", ...)             # => "HTML"
+    #
+    # @param basename [String]
+    # @param _abspath [String]
+    # @return [String]
+    def camelize(basename, _abspath)
+      basename.gsub(/(?:\A|_)(\w)/) { $1.capitalize }
+    end
+  end
+end

data/lib/zeitwerk/kernel.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Kernel
+  module_function
+
+  # 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.
+  alias_method :zeitwerk_original_require, :require
+
+  # @param path [String]
+  # @return [Boolean]
+  def require(path)
+    if loader = Zeitwerk::Registry.loader_for(path)
+      if path.end_with?(".rb")
+        zeitwerk_original_require(path).tap do |required|
+          loader.on_file_loaded(path) if required
+        end
+      else
+        loader.on_dir_loaded(path)
+      end
+    else
+      zeitwerk_original_require(path).tap do |required|
+        if required
+          realpath = $LOADED_FEATURES.last
+          if loader = Zeitwerk::Registry.loader_for(realpath)
+            loader.on_file_loaded(realpath)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zeitwerk/loader.rb

@@ -0,0 +1,480 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Zeitwerk
+  class Loader
+    # Object used to infer the constant name from a basename without extension.
+    # Default is an instance of Zeitwerk::Inflector.
+    #
+    #   inflector.camelize("users_controller", realname) # => "UsersController"
+    #
+    # For context, it receives also the absolute path to the file or directory
+    # name.
+    #
+    # @return [#camelize]
+    attr_accessor :inflector
+
+    # An optional callable to log when a constant is loaded, `nil` by default.
+    #
+    # @return [nil, #call]
+    attr_accessor :logger
+
+    # Absolute paths of directories from which you want to load constants. This
+    # is a private attribute, client code should use `push_dir`.
+    #
+    # Stored in a hash to preserve order, easily handle duplicates, and also be
+    # able to have a fast lookup, needed for detecting nested paths.
+    #
+    #   {
+    #     "/Users/fxn/blog/app/assets"   => true,
+    #     "/Users/fxn/blog/app/channels" => true,
+    #     ...
+    #   }
+    #
+    # @private
+    # @return [{String => true}]
+    attr_reader :dirs
+
+    # Absolute paths of files or directories that have to be preloaded.
+    #
+    # @private
+    # @return [<String>]
+    attr_reader :preloads
+
+    # Absolute paths of files or directories to be totally ignored.
+    #
+    # @private
+    # @return [String]
+    attr_reader :ignored
+
+    # Maps real absolute paths for which an autoload has been set to their
+    # corresponding parent class or module and constant name.
+    #
+    #   "/Users/fxn/blog/app/models/user.rb"          => [Object, "User"]
+    #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, "Pricing"]
+    #
+    # @private
+    # @return [{String => (Module, String)}]
+    attr_reader :autoloads
+
+    # Maps constant paths of namespaces to arrays of corresponding directories.
+    #
+    # For example, given this mapping:
+    #
+    #   "Admin" => [
+    #     "/Users/fxn/blog/app/controllers/admin",
+    #     "/Users/fxn/blog/app/models/admin",
+    #     ...
+    #   ]
+    #
+    # when `Admin` gets defined we know that it plays the role of a namespace and
+    # that its children are spread over those directories. We'll visit them to set
+    # up the corresponding autoloads.
+    #
+    # @private
+    # @return [{String => <String>}]
+    attr_reader :lazy_subdirs
+
+    # @private
+    # @return [Set]
+    attr_reader :eager_load_exclusions
+
+    # @private
+    # @return [Mutex]
+    attr_reader :mutex
+
+    # @private
+    # @return [TracePoint]
+    attr_reader :tracer
+
+    def initialize
+      self.inflector = Inflector.new
+
+      @dirs                  = {}
+      @autoloads             = {}
+      @preloads              = []
+      @lazy_subdirs          = {}
+      @ignored               = Set.new
+      @eager_load_exclusions = Set.new
+      @mutex                 = Mutex.new
+      @setup                 = false
+      @eager_loaded          = false
+
+      # We have run several benchmarks that have shown having a trace point for
+      # the :class event does not impact performance in any measurable way.
+      @tracer = TracePoint.trace(:class) do |tp|
+        unless lazy_subdirs.empty? # do not even compute the hash key if not needed
+          if subdirs = lazy_subdirs.delete(tp.self.name)
+            subdirs.each { |subdir| set_autoloads_in_dir(subdir, tp.self) }
+          end
+        end
+      end
+
+      Registry.register_loader(self)
+    end
+
+    # Pushes `paths` to the list of root directories.
+    #
+    # @param path [<String, Pathname>]
+    # @return [void]
+    def push_dir(path)
+      abspath = File.expand_path(path)
+      mutex.synchronize do
+        if dir?(abspath)
+          dirs[abspath] = true
+        else
+          raise ArgumentError, "the root directory #{abspath} does not exist"
+        end
+      end
+    end
+
+    # Files or directories to be preloaded instead of lazy loaded.
+    #
+    # @param paths [<String, Pathname, <String, Pathname>>]
+    # @return [void]
+    def preload(*paths)
+      mutex.synchronize do
+        expand_paths(paths).each do |abspath|
+          preloads << abspath
+          if @setup
+            if ruby?(abspath)
+              do_preload_file(abspath)
+            elsif dir?(abspath)
+              do_preload_dir(abspath)
+            end
+          end
+        end
+      end
+    end
+
+    # Files or directories to be totally ignored by Zeitwerk.
+    #
+    # @param paths [<String, Pathname, <String, Pathname>>]
+    # @return [void]
+    def ignore(*paths)
+      mutex.synchronize { ignored.merge(expand_paths(paths)) }
+    end
+
+    # Sets autoloads in the root namespace and preloads files if any.
+    #
+    # Once started, this instance is ready to trace loaded constants if logging
+    # is enabled, to autovivify modules on demand, and to descend further
+    # directory levels to lazily set more autoloads.
+    #
+    # @return [void]
+    def setup
+      mutex.synchronize do
+        unless @setup
+          actual_dirs.each { |dir| set_autoloads_in_dir(dir, Object) }
+          tracer.enable
+          do_preload
+          @setup = true
+        end
+      end
+    end
+
+    # Removes loaded constants and configured autoloads.
+    #
+    # The objects the constants stored are no longer reachable through them. In
+    # addition, since said objects are normally not referenced from anywhere
+    # else, they are eligible for garbage collection, which would effectively
+    # unload them.
+    #
+    # @return [void]
+    def unload
+      mutex.synchronize do
+        autoloads.each do |path, (parent, cname)|
+          # If the constant was loaded, we unload it. Otherwise, this removes
+          # the autoload in the parent, which is something we want to do anyway.
+          parent.send(:remove_const, cname) rescue :user_removed_it_by_hand_that_is_fine
+
+          # Let Kernel#require load the same path later again by removing it
+          # from $LOADED_FEATURES. We check the extension to avoid unnecessary
+          # array lookups, since directories are not stored in $LOADED_FEATURES.
+          $LOADED_FEATURES.delete(path) if ruby?(path)
+        end
+        autoloads.clear
+        lazy_subdirs.clear
+
+        Registry.on_unload(self)
+
+        tracer.disable
+        @setup = false
+      end
+    end
+
+    # Docs pending.
+    #
+    # @return [void]
+    def reload
+      unload
+      setup
+    end
+
+    # Eager loads in the root directories, recursively. Files do not need to be
+    # in `$LOAD_PATH`, absolute file names are used.
+    #
+    # @return [void]
+    def eager_load
+      mutex.synchronize do
+        unless @eager_loaded
+          actual_dirs.each do |dir|
+            eager_load_dir(dir) unless eager_load_exclusions.member?(dir)
+          end
+          tracer.disable if eager_load_exclusions.empty?
+          @eager_loaded = true
+        end
+      end
+    end
+
+    # Let eager load ignore the given files or directories.
+    #
+    # @param paths [<String, Pathname, <String, Pathname>>]
+    # @return [void]
+    def do_not_eager_load(*paths)
+      mutex.synchronize { eager_load_exclusions.merge(expand_paths(paths)) }
+    end
+
+    # --- Class methods -----------------------------------------------------------------------------
+
+    # This is a shortcut for
+    #
+    #   require "zeitwerk"
+    #   loader = Zeitwerk::Loader.new
+    #   loader.inflector = Zeitwerk::GemInflector.new
+    #   loader.push_dir(__dir__)
+    #
+    # except that this method returns the same object in subsequent calls from
+    # the same file, in the unlikely case the gem wants to be able to reload.
+    #
+    # `Zeitwerk::GemInflector` is a subclass of `Zeitwerk::Inflector` that
+    # camelizes "lib/my_gem/version.rb" as "MyGem::VERSION".
+    #
+    # @return [Zeitwerk::Loader]
+    def self.for_gem
+      called_from = caller[0].split(':')[0]
+      Registry.loader_for_gem(called_from)
+    end
+
+    # Broadcasts `eager_load` to all instances.
+    #
+    # @return [void]
+    def self.eager_load_all
+      Registry.loaders.each(&:eager_load)
+    end
+
+    # --- Calbacks ----------------------------------------------------------------------------------
+
+    # Callback invoked from Kernel when a managed file is loaded.
+    #
+    # @private
+    # @param file [String]
+    # @return [void]
+    def on_file_loaded(file)
+      if logger
+        parent, cname = autoloads[file]
+        logger.call("constant #{cpath(parent, cname)} loaded from file #{file}")
+      end
+    end
+
+    # Callback invoked from Kernel when a managed directory is loaded.
+    #
+    # @private
+    # @param dir [String]
+    # @return [void]
+    def on_dir_loaded(dir)
+      parent, cname = autoloads[dir]
+      autovivified = parent.const_set(cname, Module.new)
+      logger.call("module #{cpath(parent, cname)} autovivified from directory #{dir}") if logger
+
+      if subdirs = lazy_subdirs[cpath(parent, cname)]
+        subdirs.each { |subdir| set_autoloads_in_dir(subdir, autovivified) }
+      end
+    end
+
+    private # ---------------------------------------------------------------------------------------
+
+    # @private
+    # @return [<String>]
+    def actual_dirs
+      dirs.each_key.reject { |dir| ignored.member?(dir) }
+    end
+
+    # @param dir [String]
+    # @param parent [Module]
+    def set_autoloads_in_dir(dir, parent)
+      each_abspath(dir) do |abspath|
+        cname = inflector.camelize(File.basename(abspath, ".rb"), abspath)
+        if ruby?(abspath)
+          autoload_file(parent, cname, abspath)
+        elsif dir?(abspath)
+          # In a Rails application, `app/models/concerns` is a subdirectory of
+          # `app/models`, but both of them are root directories.
+          #
+          # To resolve the ambiguity file name -> constant path this introduces,
+          # the `app/models/concerns` directory is totally ignored as a namespace,
+          # it counts only as root. The guard checks that.
+          autoload_subdir(parent, cname, abspath) unless dirs.key?(abspath)
+        end
+      end
+    end
+
+    # @param subdir [String]
+    # @param parent [Module]
+    # @paran cname [String]
+    # @return [void]
+    def autoload_subdir(parent, cname, subdir)
+      if autoload_for?(parent, cname)
+        # If there is already an autoload for this cname, maybe there are multiple
+        # directories defining the namespace, or the cname is going to be defined
+        # in a file (not autovivified). In either case, we do not need to issue
+        # another autoload, the existing one is fine.
+        (lazy_subdirs[cpath(parent, cname)] ||= []) << subdir
+      elsif !parent.const_defined?(cname, false)
+        # First time we find this namespace, set an autoload for it.
+        (lazy_subdirs[cpath(parent, cname)] ||= []) << subdir
+        set_autoload(parent, cname, subdir)
+      else
+        # For whatever reason the constant that corresponds to this namespace has
+        # already been defined, we have to recurse.
+        set_autoloads_in_dir(subdir, parent.const_get(cname))
+      end
+    end
+
+    # @param file [String]
+    # @param parent [Module]
+    # @paran cname [String]
+    # @return [void]
+    def autoload_file(parent, cname, file)
+      if autoload_path = autoload_for?(parent, cname)
+        # First autoload for a Ruby file wins, just ignore subsequent ones.
+        return if ruby?(autoload_path)
+
+        # Override autovivification, we want the namespace to become the
+        # class/module defined in this file.
+        autoloads.delete(autoload_path)
+        Registry.unregister_autoload(autoload_path)
+        set_autoload(parent, cname, file)
+      elsif !parent.const_defined?(cname, false)
+        set_autoload(parent, cname, file)
+      end
+    end
+
+    # @param parent [Module]
+    # @param cname [String]
+    # @param abspath [String]
+    # @return [void]
+    def set_autoload(parent, cname, abspath)
+      # $LOADED_FEATURES stores real paths since Ruby 2.4.4. We set and save the
+      # real path to be able to delete it from $LOADED_FEATURES on unload, and to
+      # be able to do a lookup later in Kernel#require for manual require calls.
+      realpath = File.realpath(abspath)
+      parent.autoload(cname, realpath)
+      if logger
+        if ruby?(realpath)
+          logger.call("autoload set for #{cpath(parent, cname)}, to be loaded from #{realpath}")
+        else
+          logger.call("autoload set for #{cpath(parent, cname)}, to be autovivified from #{realpath}")
+        end
+      end
+
+      autoloads[realpath] = [parent, cname]
+      Registry.register_autoload(self, realpath)
+
+      # See why in the documentation of Zeitwerk::Registry.inceptions.
+      unless parent.autoload?(cname)
+        Registry.register_inception(cpath(parent, cname), realpath, self)
+      end
+    end
+
+    # @param parent [Module]
+    # @param cname [String]
+    # @return [nil, String]
+    def autoload_for?(parent, cname)
+      parent.autoload?(cname) || Registry.inception?(cpath(parent, cname))
+    end
+
+    # @param dir [String]
+    def eager_load_dir(dir)
+      each_abspath(dir) do |abspath|
+        next if eager_load_exclusions.member?(abspath)
+
+        if ruby?(abspath)
+          require abspath
+        elsif dir?(abspath)
+          eager_load_dir(abspath)
+        end
+      end
+    end
+
+    # This method is called this way because I prefer `preload` to be the method
+    # name to configure preloads in the public interface.
+    #
+    # @return [void]
+    def do_preload
+      preloads.each do |abspath|
+        if ruby?(abspath)
+          do_preload_file(abspath)
+        elsif dir?(abspath)
+          do_preload_dir(abspath)
+        end
+      end
+    end
+
+    # @param dir [String]
+    # @return [void]
+    def do_preload_dir(dir)
+      each_abspath(dir) do |abspath|
+        if ruby?(abspath)
+          do_preload_file(abspath)
+        elsif dir?(abspath)
+          do_preload_dir(abspath)
+        end
+      end
+    end
+
+    # @param file [String]
+    # @return [Boolean]
+    def do_preload_file(file)
+      logger.call("preloading #{file}") if logger
+      require file
+    end
+
+    # @param parent [Module]
+    # @param cname [String]
+    # @return [String]
+    def cpath(parent, cname)
+      parent.equal?(Object) ? cname : "#{parent}::#{cname}"
+    end
+
+    # @param dir [String]
+    # @yieldparam path [String]
+    # @return [void]
+    def each_abspath(dir)
+      Dir.foreach(dir) do |entry|
+        next if entry.start_with?(".")
+        abspath = File.join(dir, entry)
+        yield abspath unless ignored.member?(abspath)
+      end
+    end
+
+    # @param path [String]
+    # @return [Boolean]
+    def ruby?(path)
+      path.end_with?(".rb")
+    end
+
+    # @param path [String]
+    # @return [Boolean]
+    def dir?(path)
+      File.directory?(path)
+    end
+
+    # @param paths [<String, Pathname, <String, Pathname>>]
+    # @return [<String>]
+    def expand_paths(paths)
+      Array(paths).flatten.map { |path| File.expand_path(path) }
+    end
+  end
+end

data/lib/zeitwerk/registry.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Zeitwerk
+  module Registry # :nodoc: all
+    class << self
+      # Keeps track of all loaders. Useful to broadcast messages and to prevent
+      # them from being garbage collected.
+      #
+      # @private
+      # @return [<Zeitwerk::Loader>]
+      attr_reader :loaders
+
+      # Registers loaders created with `for_gem` to make the method idempotent
+      # in case of reload.
+      #
+      # @private
+      # @return [{String => Zeitwerk::Loader}]
+      attr_reader :loaders_managing_gems
+
+      # Maps real paths to the loaders responsible for them.
+      #
+      # This information is used by our decorated Kernel#require to be able to
+      # invoke callbacks.
+      #
+      # @private
+      # @return [{String => Zeitwerk::Loader}]
+      attr_reader :autoloads
+
+      # This hash table addresses an edge case in which an autoload is ignored:
+      #
+      #   Object.autoload(:MyGem, path)
+      #   Object.autoload?(:MyGem) # => nil (!!!!)
+      #
+      # For example, let's suppose we want to autoload in a gem like this:
+      #
+      #   # lib/my_gem.rb
+      #   loader = Zeitwerk::Loader.new
+      #   loader.push_dir(__dir__)
+      #   loader.setup
+      #
+      #   module MyGem
+      #   end
+      #
+      # if you require "my_gem", this happens while setting up autoloads:
+      #
+      #   1. Object.autoload?(:MyGem) returns `nil`.
+      #   2. The constant `MyGem` is undefined while setup runs.
+      #
+      # Therefore, a directory `lib/my_gem` would autovivify a module according to
+      # the existing information. But that would be wrong.
+      #
+      # To overcome this fundamental limitation, we keep track of the constant
+      # paths that are in this situation ---in the example above "MyGem"---, and
+      # take this collection into account for the autovivification logic.
+      #
+      # Note that you cannot generally address this by moving the setup code
+      # below the constant definition, because we want libraries to be able to
+      # use managed constants in the module body:
+      #
+      #   module MyGem
+      #     include MyConcern
+      #   end
+      #
+      # and it would be inelegant to ask users to split that into
+      #
+      #   # NO WAY WE ARE GOING TO ASK PEOPLE TO DO THIS.
+      #   module MyGem
+      #   end
+      #   loader.setup
+      #   module MyGem
+      #     include MyConcern
+      #   end
+      #
+      # @private
+      # @return [{String => (String, Zeitwerk::Loader)}]
+      attr_reader :inceptions
+
+      # Registers a loader.
+      #
+      # @private
+      # @param loader [Zeitwerk::Loader]
+      def register_loader(loader)
+        loaders << loader
+      end
+
+      # This method returns always a loader, and it returns the same instance
+      # for the same root file. That is how Zeitwerk.start is idempotent.
+      #
+      # @private
+      # @param root_file [String]
+      # @return [Zeitwerk::Loader]
+      def loader_for_gem(root_file)
+        loaders_managing_gems[root_file] ||= begin
+          Loader.new.tap do |loader|
+            loader.inflector = Zeitwerk::GemInflector.new(root_file)
+            loader.push_dir(File.dirname(root_file))
+          end
+        end
+      end
+
+      # @private
+      # @param loader [Zeitwerk::Loader]
+      # @param realpath [String]
+      def register_autoload(loader, realpath)
+        autoloads[realpath] = loader
+      end
+
+      # @private
+      # @param realpath [String]
+      def unregister_autoload(realpath)
+        autoloads.delete(realpath)
+      end
+
+      # @private
+      # @param cpath [String]
+      # @param realpath [String]
+      # @param loader [Zeitwerk::Loader]
+      def register_inception(cpath, realpath, loader)
+        inceptions[cpath] = [realpath, loader]
+      end
+
+      # @private
+      # @param cpath [String]
+      # @return [String, nil]
+      def inception?(cpath)
+        if pair = inceptions[cpath]
+          pair.first
+        end
+      end
+
+      # @private
+      # @param path [String]
+      # @return [Zeitwerk::Loader, nil]
+      def loader_for(path)
+        autoloads[path]
+      end
+
+      # @private
+      # @param loader [Zeitwerk::Loader]
+      def on_unload(loader)
+        autoloads.delete_if { |_path, object| object == loader }
+        inceptions.delete_if { |_cpath, (_path, object)| object == loader }
+      end
+    end
+
+    @loaders               = []
+    @loaders_managing_gems = {}
+    @autoloads             = {}
+    @inceptions            = {}
+  end
+end

data/lib/zeitwerk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Zeitwerk
+  VERSION = "1.0.0.alpha"
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: zeitwerk
+version: !ruby/object:Gem::Version
+  version: 1.0.0.alpha
+platform: ruby
+authors:
+- Xavier Noria
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-01-18 00:00:00.000000000 Z
+dependencies: []
+description: |2
+      Zeitwerk implements constant autoloading with Ruby semantics. Each gem
+      and application may have their own independent autoloader, with its own
+      configuration, inflector, and logger. Supports autoloading, preloading,
+      reloading, and eager loading.
+email: fxn@hashref.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/zeitwerk.rb
+- lib/zeitwerk/gem_inflector.rb
+- lib/zeitwerk/inflector.rb
+- lib/zeitwerk/kernel.rb
+- lib/zeitwerk/loader.rb
+- lib/zeitwerk/registry.rb
+- lib/zeitwerk/version.rb
+homepage: https://github.com/fxn/zeitwerk
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.4
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.0.1
+signing_key: 
+specification_version: 4
+summary: Efficient and thread-safe constant autoloader
+test_files: []