carton 0.1.0 → 0.2.0

data/lib/carton/export_declaration.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Carton
+  # What an Entrypoint exports: an Export Namespace built from one or more
+  # `export` calls, or a single Default Export from `export_default`. The two
+  # forms are exclusive, and a name may be exported only once.
+  class ExportDeclaration
+    COMBINED =
+      'export_default cannot be combined with export; ' \
+        'put the other names inside the default value'
+    private_constant :COMBINED
+
+    NO_DEFAULT = Object.new.freeze
+    private_constant :NO_DEFAULT
+
+    def self.absent
+      new({}, {}, NO_DEFAULT)
+    end
+
+    def initialize(methods, values, default)
+      @methods = methods.freeze
+      @values = values.freeze
+      @default = default
+      freeze
+    end
+
+    def add(methods, values)
+      raise ExportError, COMBINED if default?
+
+      duplicate =
+        (methods.keys + values.keys).find do |name|
+          @methods.key?(name) || @values.key?(name)
+        end
+      if duplicate
+        raise ExportError, "export name given more than once: #{duplicate}"
+      end
+
+      self.class.__send__(
+        :new,
+        @methods.merge(methods),
+        @values.merge(values),
+        NO_DEFAULT,
+      )
+    end
+
+    def default(value)
+      if default?
+        raise ExportError, 'export_default may be called only once per file'
+      end
+      raise ExportError, COMBINED if namespace?
+
+      self.class.__send__(:new, @methods, @values, value)
+    end
+
+    # The Default Export, or yields methods and values for the Export
+    # Namespace, or for a Bare Carton's surface, which `bare` computes lazily,
+    # when nothing was exported.
+    def public_surface(bare:)
+      return @default if default?
+
+      namespace? ? yield(@methods, @values) : yield(*bare.call)
+    end
+
+    private_class_method :new
+
+    private
+
+    def default? = !NO_DEFAULT.equal?(@default)
+
+    def namespace? = !(@methods.empty? && @values.empty?)
+  end
+end

data/lib/carton/export_methods.rb

@@ -1,27 +1,30 @@
 # frozen_string_literal: true
 
 module Carton
+  # Hash-like lookup helpers for `Carton::Exports`.
   module ExportMethods
+    # Support destructuring like `import('math') => { add: }`.
     def deconstruct_keys(keys)
-      return {} unless keys
-
       keys.each_with_object({}) do |key, hash|
         found, value = lookup_entry(key)
         hash[key] = value if found
       end
     end
 
+    # Return the exported value or `nil`.
     def [](key)
       found, value = lookup_entry(key)
       found ? value : nil
     end
 
+    # Check whether the export lookup will succeed.
     def key?(key)
       lookup_entry(key).first
     end
 
     alias has_key? key?
 
+    # Fetch an exported value with the same default/block semantics as `Hash#fetch`.
     def fetch(key, *default)
       if default.size > 1
         raise ArgumentError,
@@ -36,10 +39,12 @@ module Carton
       raise KeyError, "key not found: #{key.inspect}"
     end
 
+    # Fetch several exported values and raise if any are missing.
     def fetch_values(*keys)
       keys.map { |key| fetch(key) }
     end
 
+    # Return several exported values, using `nil` for missing keys.
     def values_at(*keys)
       keys.map { |key| self[key] }
     end

data/lib/carton/exports.rb

@@ -1,28 +1,47 @@
 # frozen_string_literal: true
 
 module Carton
+  # Module-like wrapper returned from named exports.
+  #
+  # Exported methods become singleton methods that forward to the carton's
+  # method. Capitalized value keys become constants; lowercase value keys become
+  # readers that return the value as-is. Lookup helpers return the `Method`
+  # object or the value.
   class Exports < ::Module
     include ExportMethods
 
-    def initialize(values = {})
+    def initialize(methods = {}, values = {})
       super()
-      @values = values
       @lookup = {}
-      define_exports
+      define_methods(methods)
+      define_values(values)
+    end
+
+    def deconstruct_keys(keys)
+      return super if keys
+
+      @lookup.to_h { |key, value| [key.to_sym, value] }
     end
 
     private
 
-    def define_exports
-      @values.each do |key, value|
+    def define_methods(methods)
+      methods.each do |name, method|
+        @lookup[name.to_s] = method
+        define_singleton_method(name) do |*args, **kwargs, &block|
+          method.call(*args, **kwargs, &block)
+        end
+      end
+    end
+
+    def define_values(values)
+      values.each do |key, value|
         @lookup[key.to_s] = value
 
         if key.to_s.match?(/\A[A-Z]/)
           const_set(key, value)
         else
-          define_singleton_method(
-            key,
-          ) { |*args, **kwargs, &block| value.respond_to?(:call) ? value.call(*args, **kwargs, &block) : value }
+          define_singleton_method(key) { value }
         end
       end
     end

data/lib/carton/gem_activation.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Carton
+  # Carries the caller's activated gems into a Carton Box.
+  #
+  # Optional Boxes copy Master, so they start with clean RubyGems state and
+  # would auto-activate the newest installed version of any dependency. When
+  # an Import resolves inside an activated gem, Carton activates that gem and
+  # its runtime dependencies in the new Box at the caller's versions, so the
+  # caller's lockfile (or plain `gem` calls) decides what the Carton sees.
+  #
+  # When the caller ran Bundler setup, the Box is also restricted to the
+  # caller's locked gems, as `Bundler.setup` restricts Main: every locked gem
+  # is activated at its locked version and anything else fails to load.
+  module GemActivation
+    module_function
+
+    # The non-default gem in `loaded_specs` that owns `feature`, plus its
+    # activated runtime dependencies, dependencies first. Empty when no
+    # activated gem owns the file.
+    def closure(feature, loaded_specs)
+      owner = owner_of(feature, loaded_specs.values)
+      return [] unless owner
+
+      visit(owner, loaded_specs, [], {})
+    end
+
+    # The caller's locked gems when `box` ran Bundler setup, otherwise nil.
+    # Bundler marks every locked spec as loaded, so these are the shareable
+    # entries of its `Gem.loaded_specs`.
+    def locked(box, loaded_specs)
+      return unless bundled?(box)
+
+      loaded_specs.values.select { |spec| shareable?(spec) }
+    end
+
+    # Rebuild specs in the current Box and activate them. With `locked`, the
+    # Box is restricted to those specs and all of them are activated, as
+    # `Bundler.setup` does, since RubyGems does not auto-activate under
+    # Bundler's restricted view. Spec objects come from another Box, so their
+    # own `activate` would update that Box; a YAML round trip builds this Box's
+    # `Gem::Specification` without re-evaluating gemspec files.
+    def activate(specs, locked = nil)
+      rebuilt = (locked || specs).map { |source| rebuild(source) }
+      restrict_to(rebuilt) if locked
+
+      rebuilt.each do |spec|
+        loaded = Gem.loaded_specs[spec.name]
+        spec.activate unless loaded && loaded.version == spec.version
+      end
+    end
+
+    def rebuild(source)
+      spec = Gem::Specification.from_yaml(source.to_spec.to_yaml)
+      spec.loaded_from = source.loaded_from
+      spec.full_gem_path = source.full_gem_path
+      spec
+    end
+    private_class_method :rebuild
+
+    # Bundler has no public API for "restrict this Box to these specs", so the
+    # two Bundler internals Carton relies on live here. `@replaced_methods`
+    # is non-empty once `Bundler.setup` has replaced RubyGems entrypoints.
+    # `replace_entrypoints` is the strict half of `Bundler::Runtime#setup`,
+    # without resolution, `ENV` exports, or lockfile writes. See
+    # docs/internals/upstream.md.
+    def bundled?(box)
+      box.eval(
+        'defined?(Bundler.rubygems) && ' \
+          'Bundler.rubygems.instance_variable_get(:@replaced_methods)&.any?',
+      )
+    end
+    private_class_method :bundled?
+
+    def restrict_to(specs)
+      require 'bundler'
+      Bundler.rubygems.replace_entrypoints(specs)
+    end
+    private_class_method :restrict_to
+
+    def owner_of(feature, specs)
+      specs
+        .select { |spec| shareable?(spec) }
+        .filter_map do |spec|
+          dir =
+            spec.full_require_paths.find do |path|
+              feature.start_with?("#{path}/")
+            end
+          [dir.length, spec] if dir
+        end
+        .max_by(&:first)
+        &.last
+    end
+    private_class_method :owner_of
+
+    def visit(spec, loaded_specs, ordered, seen)
+      return ordered if seen[spec.name] || !shareable?(spec)
+
+      seen[spec.name] = true
+      spec.runtime_dependencies.each do |dependency|
+        dependency_spec = loaded_specs[dependency.name]
+        visit(dependency_spec, loaded_specs, ordered, seen) if dependency_spec
+      end
+      ordered << spec
+    end
+    private_class_method :visit
+
+    # Default gems already load in every Box. Bundler is left out too: each
+    # Box loads its own copy to apply the restriction, possibly a different
+    # version than the caller's, and activating the caller's on top of it
+    # raises Gem::LoadError.
+    def shareable?(spec)
+      !spec.default_gem? && spec.name != 'bundler'
+    end
+    private_class_method :shareable?
+  end
+end

data/lib/carton/import_cache.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Carton
+  # Process-wide record of loaded Cartons, keyed by Entrypoint path.
+  #
+  # The Main Box creates one instance and every Carton Box receives that same
+  # object, so each Entrypoint loads once no matter which Carton imports it.
+  # Ruby objects are shared across Boxes; only definitions are Box-local, so
+  # the Main Box's loader builds every Carton. A cached value is then a
+  # value or `Carton::Exports` from the Main Box regardless of which
+  # Carton imported it first.
+  class ImportCache
+    def initialize(&loader)
+      @loader = loader
+      @values = {}
+      @gem_versions = {}
+      @loading = {}
+      @lock = Thread::Mutex.new
+    end
+
+    # Load `target` once per Entrypoint path. Targets without an absolute
+    # path are loaded uncached. Nested imports on the owning thread re-enter
+    # without waiting on the lock.
+    def import(target)
+      return @loader.call(target) unless File.absolute_path?(target.feature)
+
+      key = File.realpath(target.feature)
+      return fetch(key, target) if @lock.owned?
+
+      @lock.synchronize { fetch(key, target) }
+    end
+
+    private
+
+    def fetch(key, target)
+      if @values.key?(key)
+        check_gem_versions(key, target)
+        return @values[key]
+      end
+      raise ImportError, "circular import: #{key}" if @loading.key?(key)
+
+      @loading[key] = true
+      begin
+        @values[key] = @loader.call(target)
+        @gem_versions[key] = gem_versions(target)
+        @values[key]
+      ensure
+        @loading.delete(key)
+      end
+    end
+
+    # A cached Carton keeps the gem versions its first importer activated.
+    # Raise instead of silently sharing it with an importer that locks a
+    # different version of one of those gems.
+    def check_gem_versions(key, target)
+      cached = @gem_versions.fetch(key)
+      gem_versions(target).each do |name, version|
+        next if cached.fetch(name, version) == version
+
+        raise ImportError,
+              "#{key} was imported with #{name} #{cached[name]}, " \
+                "but this import activates #{name} #{version}"
+      end
+    end
+
+    def gem_versions(target)
+      (target.gems || []).to_h { |spec| [spec.name, spec.version.to_s] }
+    end
+  end
+end

data/lib/carton/kernel_patch.rb

@@ -2,24 +2,34 @@
 
 module Carton
   module KernelPatch
+    private # like `require` and `require_relative`
+
+    # Import a carton by absolute path or by feature name from the caller box's
+    # current `$LOAD_PATH`.
     def import(path)
-      Runtime.import(path, base_dir: Dir.pwd)
+      Runtime.import(path)
     end
 
+    # Import a carton relative to the calling file, like `require_relative`.
     def import_relative(path)
       caller_dir = File.dirname(caller_locations(1, 1).first.path)
       Runtime.import(path, base_dir: caller_dir)
     end
 
-    def export(*args, **kwargs)
-      Runtime.export(args, kwargs)
+    # Export top-level methods by name plus keyword values from the current
+    # carton. `self` is the carton's top-level object, which owns its methods.
+    def export(*names, **values)
+      file = caller_locations(1, 1).first.absolute_path
+      Runtime.export(names, values, owner: self, file:)
     end
 
+    # Export a single value that `import` returns as is.
     def export_default(value)
-      Runtime.export_default(value)
+      file = caller_locations(1, 1).first.absolute_path
+      Runtime.export_default(value, file:)
     end
   end
 end
 
 # Inject only the Kernel patch module into Kernel.
-::Kernel.prepend(Carton::KernelPatch)
+Kernel.prepend(Carton::KernelPatch)

data/lib/carton/resolver.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Carton
+  # Maps an Import path to the file that should load, without evaluating any
+  # code or reading Box state. The runtime passes the caller Box's
+  # `$LOAD_PATH`; a static analyzer can pass any load path it has computed.
+  module Resolver
+    # `feature` is what the new Box requires. `load_path` is the single caller
+    # load-path entry that matched a name-based Import, if any. The runtime
+    # fills `gems` with the caller specs to activate in the new Box, and
+    # `locked_gems` with the caller's locked specs when it ran Bundler setup.
+    Target =
+      Struct.new(:feature, :load_path, :gems, :locked_gems, keyword_init: true)
+
+    EXTENSIONS = ['.rb', ".#{RbConfig::CONFIG['DLEXT']}"].freeze
+    private_constant :EXTENSIONS
+
+    module_function
+
+    # Resolve `path` like `require_relative` when `base_dir` is given, like
+    # `require` with an absolute path, or by searching `load_path` in order.
+    # A missing relative or absolute target raises LoadError, as
+    # `require_relative` does. A name that matches no Ruby source file, such
+    # as a native extension, comes back as the bare `path`. A file inside a
+    # Carton raises ImportError: only its Entrypoint can be imported.
+    def resolve(path, load_path:, base_dir: nil)
+      path = path.to_s
+      target =
+        if base_dir || File.absolute_path?(path)
+          resolve_file(File.expand_path(path, base_dir))
+        else
+          resolve_name(path, load_path) || Target.new(feature: path)
+        end
+      reject_inside_carton(path, target)
+      target
+    end
+
+    # A Carton is its Entrypoint `x.rb` plus the `x/` directory beside it,
+    # the shape of a gem's `lib/` and of a Zeitwerk explicit namespace.
+    # Directories without their own `.rb` file, like Zeitwerk implicit
+    # namespaces, stay inside the Carton above them. Returns the outermost
+    # Entrypoint whose directory holds `file`, or `file` itself.
+    def entrypoint_for(file)
+      entrypoint = file
+      dir = File.dirname(file)
+      until dir == File.dirname(dir)
+        entrypoint = "#{dir}.rb" if File.file?("#{dir}.rb")
+        dir = File.dirname(dir)
+      end
+      entrypoint
+    end
+
+    def reject_inside_carton(path, target)
+      return unless File.absolute_path?(target.feature)
+
+      entrypoint = entrypoint_for(target.feature)
+      return if entrypoint == target.feature
+
+      raise ImportError, inside_carton_message(path, target, entrypoint)
+    end
+    private_class_method :reject_inside_carton
+
+    def inside_carton_message(path, target, entrypoint)
+      prefix = "#{target.load_path}/"
+      fix =
+        if target.load_path && entrypoint.start_with?(prefix)
+          name = entrypoint.delete_prefix(prefix).delete_suffix('.rb')
+          "#{path} is inside the #{name} Carton: import '#{name}'"
+        else
+          "#{target.feature} is inside the Carton #{entrypoint}: " \
+            'import that file'
+        end
+      "#{fix}, or require it from inside that Carton"
+    end
+    private_class_method :inside_carton_message
+
+    # A directory laid out like a gem, `billing/lib/billing.rb`, resolves to
+    # that Entrypoint with its `lib/` on the Carton's load path, so the
+    # Carton can `require 'billing/invoice'` as a gem would.
+    def resolve_file(expanded)
+      [expanded, "#{expanded}.rb"].each do |candidate|
+        return Target.new(feature: candidate) if File.file?(candidate)
+      end
+      lib = File.join(expanded, 'lib')
+      entrypoint = File.join(lib, "#{File.basename(expanded)}.rb")
+      if File.file?(entrypoint)
+        return Target.new(feature: entrypoint, load_path: lib)
+      end
+
+      raise LoadError, "cannot load such file -- #{expanded}"
+    end
+    private_class_method :resolve_file
+
+    # Like Ruby, check each load-path entry in order and try each extension
+    # within it, so an earlier native extension shadows a later `.rb`.
+    def resolve_name(path, load_path)
+      candidates = feature_candidates(path)
+
+      load_path.each do |entry|
+        dir = File.expand_path(entry.to_s)
+        candidates.each do |candidate|
+          file = File.join(dir, candidate)
+          next unless File.file?(file)
+          return nil unless file.end_with?('.rb')
+
+          return Target.new(feature: file, load_path: dir)
+        end
+      end
+      nil
+    end
+    private_class_method :resolve_name
+
+    def feature_candidates(path)
+      return [path] if EXTENSIONS.include?(File.extname(path))
+
+      EXTENSIONS.map { |ext| "#{path}#{ext}" }
+    end
+    private_class_method :feature_candidates
+  end
+end

data/lib/carton/runtime.rb

@@ -4,79 +4,100 @@ module Carton
   module Runtime
     ENTRYPOINT = File.expand_path('../carton.rb', __dir__)
     private_constant :ENTRYPOINT
+    # Used only when this Box is the Main Box. Carton Boxes reuse the Main
+    # Box cache, so every Carton is built by the Main Box loader.
+    IMPORT_CACHE = ImportCache.new { |target| load_import(target) }
+    private_constant :IMPORT_CACHE
 
     module_function
 
-    def import(path, base_dir:)
-      box = build_import_box
-      target = resolve_import_target(box, path, base_dir:)
-      box.__send__(:activate_bundle_if_configured) if target == path
-      box.__send__(:require_in_box, target)
-      extract_export(box)
+    # Load the target feature in a new box and return the exported value, or
+    # the box itself if the target does not export anything. Each Entrypoint
+    # loads once per process; later imports return the same value.
+    # `base_dir` is given for `import_relative`; plain `import` searches the
+    # caller Box's `$LOAD_PATH`.
+    def import(path, base_dir: nil)
+      unless Ruby::Box.enabled?
+        raise ImportError, 'Carton needs Ruby::Box: run Ruby with RUBY_BOX=1'
+      end
+
+      caller_box = Ruby::Box.current
+      load_path = caller_box.eval('$LOAD_PATH.to_a')
+      target = Resolver.resolve(path, load_path:, base_dir:)
+      loaded_specs = caller_box.eval('defined?(Gem) ? Gem.loaded_specs : {}')
+      target.gems = GemActivation.closure(target.feature, loaded_specs)
+      unless target.gems.empty?
+        target.locked_gems = GemActivation.locked(caller_box, loaded_specs)
+      end
+      import_cache.import(target)
     end
 
-    def export(args, kwargs)
-      if args.any? || kwargs.empty?
+    # Add to the current carton's Export Namespace. A capitalized Symbol names
+    # a top-level constant, any other Symbol a top-level method; keyword
+    # arguments are plain values. Like `private`, a single Symbol is returned
+    # so `export def name ...` works.
+    def export(names, values, owner:, file:)
+      if (names.empty? && values.empty?) ||
+           names.any? { |name| !name.is_a?(Symbol) }
         raise ArgumentError,
-              'export takes keyword arguments; use export_default for a single export'
+              'export takes Symbols naming methods or constants, and keyword values'
       end
 
-      current_import_box.__send__(:set_export, kwargs)
-    end
-
-    def export_default(value)
-      current_import_box.__send__(:set_export, value)
-    end
+      duplicate = (names + values.keys).tally.find { |_, count| count > 1 }
+      if duplicate
+        raise ExportError,
+              "export name given more than once: #{duplicate.first}"
+      end
 
-    def build_import_box
-      parent_box = Ruby::Box.current
-      box = Carton::Box.new
-      bundle_gemfile = parent_box.eval("ENV['BUNDLE_GEMFILE']")
-      box.__send__(
-        :configure_for_import,
-        parent_box:,
-        entrypoint: ENTRYPOINT,
-        bundle_gemfile:,
+      constants, method_names =
+        names.partition { |name| name.match?(/\A[A-Z]/) }
+      methods = method_names.to_h { |name| [name, owner.method(name)] }
+      constants =
+        constants.to_h { |name| [name, Object.const_get(name, false)] }
+      entrypoint_box(file)&.__send__(
+        :declare_export,
+        methods,
+        values.merge(constants),
       )
-      box
+      names.first if names.size == 1 && values.empty?
     end
-    private_class_method :build_import_box
 
-    def extract_export(box)
-      return box unless box.__send__(:export_set?)
+    # Make `value` the current carton's Default Export, which `import`
+    # returns as is. It cannot be combined with `export`.
+    def export_default(value, file:)
+      entrypoint_box(file)&.__send__(:declare_default, value)
+      value
+    end
 
-      value = box.__send__(:export_value)
-      value.is_a?(Hash) ? Carton::Exports.new(value) : value
+    def load_import(target)
+      Box
+        .new
+        .__send__(
+          :import_target,
+          target,
+          carton_entrypoint: ENTRYPOINT,
+          import_cache: IMPORT_CACHE,
+        ) { |methods, values| Exports.new(methods, values) }
     end
-    private_class_method :extract_export
+    private_class_method :load_import
 
-    def current_import_box
+    def import_cache
       box = Ruby::Box.current
+      return IMPORT_CACHE unless box.respond_to?(:import_cache, true)
 
-      unless box.respond_to?(:set_export, true)
-        raise RuntimeError,
-              'export/export_default must be called from inside Carton.import/import_relative'
-      end
-
-      box
+      box.__send__(:import_cache)
     end
-    private_class_method :current_import_box
-
-    def resolve_import_target(box, path, base_dir:)
-      expanded = File.expand_path(path, base_dir)
-      return expanded if File.file?(expanded)
+    private_class_method :import_cache
 
-      expanded_rb = "#{expanded}.rb"
-      return expanded_rb if File.file?(expanded_rb)
-
-      resolved = box.__send__(:resolve_feature_path_in_box, path)
-      return path unless resolved
-
-      type, resolved_path = resolved
-      return resolved_path if type == :rb && File.file?(resolved_path)
+    # The Carton Box whose Entrypoint is `file`, or nil. Outside that file,
+    # such as under a plain `require`, `export` is inert, so Carton-aware
+    # files and gems still load the ordinary way.
+    def entrypoint_box(file)
+      box = Ruby::Box.current
+      return unless box.respond_to?(:entrypoint?, true)
 
-      path
+      box if box.__send__(:entrypoint?, file)
     end
-    private_class_method :resolve_import_target
+    private_class_method :entrypoint_box
   end
 end

data/lib/carton/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Carton
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end