carton 0.2.0 → 0.3.0

data/lib/carton/gem_activation.rb

@@ -15,9 +15,10 @@ module Carton
   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.
+    # The gem in `loaded_specs` that owns `feature`, plus its activated
+    # runtime dependencies, dependencies first. Default gems count: a new Box
+    # would otherwise load the newest installed version, not the caller's.
+    # Empty when no activated gem owns the file.
     def closure(feature, loaded_specs)
       owner = owner_of(feature, loaded_specs.values)
       return [] unless owner
@@ -34,21 +35,52 @@ module Carton
       loaded_specs.values.select { |spec| shareable?(spec) }
     end
 
+    # The specs that own at least one of `features`, by require path. Sorted
+    # features let each directory check be a binary search, so a large bundle
+    # stays cheap.
+    def owning(specs, features)
+      sorted = features.sort
+      specs.select do |spec|
+        spec.full_require_paths.any? do |dir|
+          prefix = "#{dir}/"
+          sorted.bsearch { |feature| feature >= prefix }&.start_with?(prefix)
+        end
+      end
+    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.
+    #
+    # Default gems come first, from this Box's own default specs: the YAML
+    # round trip loads Psych, whose requires (date, for one) would otherwise
+    # activate the newest installed version before the caller's.
     def activate(specs, locked = nil)
-      rebuilt = (locked || specs).map { |source| rebuild(source) }
+      defaults, others = (locked || specs).partition(&:default_gem?)
+      defaults.each { |source| activate_spec(default_spec(source)) }
+
+      rebuilt = others.map { |source| rebuild(source) }
       restrict_to(rebuilt) if locked
+      rebuilt.each { |spec| activate_spec(spec) }
+    end
 
-      rebuilt.each do |spec|
-        loaded = Gem.loaded_specs[spec.name]
-        spec.activate unless loaded && loaded.version == spec.version
-      end
+    def activate_spec(spec)
+      loaded = Gem.loaded_specs[spec.name]
+      spec.activate unless loaded && loaded.version == spec.version
+    end
+    private_class_method :activate_spec
+
+    def default_spec(source)
+      stub =
+        Gem::Specification.default_stubs(
+          "#{source.name}-#{source.version}.gemspec",
+        ).first
+      stub ? stub.to_spec : rebuild(source)
     end
+    private_class_method :default_spec
 
     def rebuild(source)
       spec = Gem::Specification.from_yaml(source.to_spec.to_yaml)
@@ -80,7 +112,7 @@ module Carton
 
     def owner_of(feature, specs)
       specs
-        .select { |spec| shareable?(spec) }
+        .select { |spec| activatable?(spec) }
         .filter_map do |spec|
           dir =
             spec.full_require_paths.find do |path|
@@ -94,7 +126,7 @@ module Carton
     private_class_method :owner_of
 
     def visit(spec, loaded_specs, ordered, seen)
-      return ordered if seen[spec.name] || !shareable?(spec)
+      return ordered if seen[spec.name] || !activatable?(spec)
 
       seen[spec.name] = true
       spec.runtime_dependencies.each do |dependency|
@@ -105,13 +137,15 @@ module Carton
     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
+    # Bundler is never shared: 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 activatable?(spec) = spec.name != 'bundler'
+    private_class_method :activatable?
+
+    # Bundler's restriction already lets default gems load, so the locked set
+    # leaves them out.
+    def shareable?(spec) = activatable?(spec) && !spec.default_gem?
     private_class_method :shareable?
   end
 end

data/lib/carton/import_cache.rb

@@ -10,61 +10,96 @@ module Carton
   # value or `Carton::Exports` from the Main Box regardless of which
   # Carton imported it first.
   class ImportCache
+    # Returned by `claim` when the calling thread should load the Entrypoint.
+    LOAD = Object.new.freeze
+    private_constant :LOAD
+
     def initialize(&loader)
       @loader = loader
       @values = {}
-      @gem_versions = {}
+      @gem_usage = {}
+      # The thread loading each Entrypoint, while it loads.
       @loading = {}
       @lock = Thread::Mutex.new
+      @loaded = Thread::ConditionVariable.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.
+    # path are loaded uncached.
+    #
+    # The lock only guards this bookkeeping and is never held while an
+    # Entrypoint runs, so an Entrypoint can start threads that import other
+    # Cartons. An import of an Entrypoint another thread is loading waits
+    # for that load; one the same thread is loading is a cycle.
     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?
+      cached = claim(key)
+      return load_entry(key, target) if cached.equal?(LOAD)
 
-      @lock.synchronize { fetch(key, target) }
+      check_gem_versions(key, target)
+      cached
     end
 
     private
 
-    def fetch(key, target)
-      if @values.key?(key)
-        check_gem_versions(key, target)
-        return @values[key]
+    # The cached value, or LOAD once this thread owns loading `key`.
+    def claim(key)
+      @lock.synchronize do
+        loop do
+          return @values[key] if @values.key?(key)
+
+          owner = @loading[key]
+          if owner.nil?
+            @loading[key] = Thread.current
+            return LOAD
+          end
+          if owner == Thread.current
+            raise ImportError, "circular import: #{key}"
+          end
+
+          @loaded.wait(@lock)
+        end
       end
-      raise ImportError, "circular import: #{key}" if @loading.key?(key)
+    end
 
-      @loading[key] = true
-      begin
-        @values[key] = @loader.call(target)
-        @gem_versions[key] = gem_versions(target)
-        @values[key]
-      ensure
+    # A failed load is not cached: the next import, or a thread waiting on
+    # this one, tries again.
+    def load_entry(key, target)
+      value = @loader.call(target)
+      @lock.synchronize do
+        @values[key] = value
+        @gem_usage[key] = target.gem_usage || -> { target.gems }
+      end
+      value
+    ensure
+      @lock.synchronize do
         @loading.delete(key)
+        @loaded.broadcast
       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.
+    # A cached Carton keeps the gem versions its first importer gave it: its
+    # closure and the locked gems it has loaded, including any loaded lazily
+    # since. Raise instead of silently sharing it with an importer that
+    # activates or locks another version of one.
     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
+      wanted = versions([*target.locked_gems, *target.gems])
+      return if wanted.empty?
+
+      usage = @lock.synchronize { @gem_usage.fetch(key) }
+      versions(usage.call).each do |name, version|
+        next if wanted.fetch(name, version) == version
 
         raise ImportError,
-              "#{key} was imported with #{name} #{cached[name]}, " \
-                "but this import activates #{name} #{version}"
+              "#{key} was imported with #{name} #{version}, " \
+                "but this import activates #{name} #{wanted[name]}"
       end
     end
 
-    def gem_versions(target)
-      (target.gems || []).to_h { |spec| [spec.name, spec.version.to_s] }
+    def versions(specs)
+      (specs || []).to_h { |spec| [spec.name, spec.version.to_s] }
     end
   end
 end

data/lib/carton/kernel_patch.rb

@@ -7,7 +7,7 @@ module Carton
     # Import a carton by absolute path or by feature name from the caller box's
     # current `$LOAD_PATH`.
     def import(path)
-      Runtime.import(path)
+      Runtime.import(path, from: caller_locations(1, 1).first.path)
     end
 
     # Import a carton relative to the calling file, like `require_relative`.
@@ -16,17 +16,11 @@ module Carton
       Runtime.import(path, base_dir: caller_dir)
     end
 
-    # 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)
+    # Export one value from the current carton; `import` returns it as is.
+    # Keywords export a Hash, as in `export version: '1.0'`.
+    def export(value)
       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)
-      file = caller_locations(1, 1).first.absolute_path
-      Runtime.export_default(value, file:)
+      Runtime.export(value, file:)
     end
   end
 end

data/lib/carton/loaded_features.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Loaded inside a Carton Box by `Carton::Box#loaded_features`. Like
+# `$LOAD_PATH`, `$LOADED_FEATURES` resolves to the Box of the file being
+# loaded, so this file sees the Carton's own features even while another
+# Carton is importing it.
+Carton
+  .const_get(:Box)
+  .for(Ruby::Box.current)
+  .__send__(:receive_loaded_features, $LOADED_FEATURES.to_a)

data/lib/carton/namespace.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Carton
+  # What importing a Bare Carton returns: a module of the constants and
+  # top-level helpers its Entrypoint defined. Helpers become singleton
+  # methods that forward to the Carton's method, and lookup helpers return
+  # the `Method` object or the constant.
+  class Namespace < ::Module
+    include NamespaceMethods
+
+    # A helper becomes a singleton method, so one named like a method every
+    # `Carton::Namespace` has, such as `fetch` or `name`, would hide it.
+    # Constants are capitalized and never collide.
+    def self.reserved?(name)
+      name = name.to_s
+      !name.match?(/\A[A-Z]/) && RESERVED.include?(name)
+    end
+
+    # Raise for the first reserved name in `names`.
+    def self.check_names(names)
+      name = names.find { |n| reserved?(n) } or return
+
+      raise ExportError,
+            "a top-level method named #{name} would hide " \
+              "Carton::Namespace##{name}: rename it, or export a module"
+    end
+
+    def initialize(methods = {}, constants = {})
+      super()
+      Namespace.check_names(methods.keys)
+      @lookup = {}
+      define_methods(methods)
+      define_constants(constants)
+    end
+
+    def deconstruct_keys(keys)
+      return super if keys
+
+      to_h
+    end
+
+    # `#<Carton::Namespace PI, add>`: its names, so a namespace is
+    # recognizable in a console.
+    def inspect
+      names = @lookup.keys.join(', ')
+      names.empty? ? '#<Carton::Namespace>' : "#<Carton::Namespace #{names}>"
+    end
+    alias to_s inspect
+
+    private
+
+    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_constants(constants)
+      constants.each do |name, value|
+        @lookup[name.to_s] = value
+        const_set(name, value)
+      end
+    end
+
+    def lookup_entry(key)
+      name = key.to_s
+      @lookup.key?(name) ? [true, @lookup[name]] : [false, nil]
+    end
+
+    def lookup_names = @lookup.keys
+
+    RESERVED = public_instance_methods.map(&:to_s).freeze
+    private_constant :RESERVED
+  end
+end

data/lib/carton/{export_methods.rb → namespace_methods.rb}

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Carton
-  # Hash-like lookup helpers for `Carton::Exports`.
-  module ExportMethods
+  # Hash-like lookup helpers for `Carton::Namespace`.
+  module NamespaceMethods
     # Support destructuring like `import('math') => { add: }`.
     def deconstruct_keys(keys)
       keys.each_with_object({}) do |key, hash|
@@ -11,20 +11,20 @@ module Carton
       end
     end
 
-    # Return the exported value or `nil`.
+    # Return the member or `nil`.
     def [](key)
       found, value = lookup_entry(key)
       found ? value : nil
     end
 
-    # Check whether the export lookup will succeed.
+    # Check whether the 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`.
+    # Fetch a member with the same default/block semantics as `Hash#fetch`.
     def fetch(key, *default)
       if default.size > 1
         raise ArgumentError,
@@ -39,12 +39,18 @@ module Carton
       raise KeyError, "key not found: #{key.inspect}"
     end
 
-    # Fetch several exported values and raise if any are missing.
+    # Member names as Symbols: helpers first, then constants.
+    def keys = lookup_names.map(&:to_sym)
+
+    # Every member by name: helpers as `Method` objects, constants as set.
+    def to_h = keys.to_h { |key| [key, self[key]] }
+
+    # Fetch several members 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.
+    # Return several members, using `nil` for missing keys.
     def values_at(*keys)
       keys.map { |key| self[key] }
     end

data/lib/carton/resolver.rb

@@ -9,8 +9,18 @@ module Carton
     # 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.
+    # After loading, the Carton Box sets `gem_usage`, a callable returning the
+    # gems the Carton depends on at that moment: its closure plus every locked
+    # gem whose files it has loaded so far.
     Target =
-      Struct.new(:feature, :load_path, :gems, :locked_gems, keyword_init: true)
+      Struct.new(
+        :feature,
+        :load_path,
+        :gems,
+        :locked_gems,
+        :gem_usage,
+        keyword_init: true,
+      )
 
     EXTENSIONS = ['.rb', ".#{RbConfig::CONFIG['DLEXT']}"].freeze
     private_constant :EXTENSIONS
@@ -24,17 +34,22 @@ module Carton
     # 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 = locate(path, load_path:, base_dir:)
+      reject_inside_carton(path.to_s, target)
       target
     end
 
+    # Like `resolve`, but a file inside a Carton comes back as is, as
+    # `require` would load it. `carton check` uses this for `require` calls.
+    def locate(path, load_path:, base_dir: nil)
+      path = path.to_s
+      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
+    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
@@ -87,10 +102,24 @@ module Carton
         return Target.new(feature: entrypoint, load_path: lib)
       end
 
-      raise LoadError, "cannot load such file -- #{expanded}"
+      raise LoadError, missing_file_message(expanded)
     end
     private_class_method :resolve_file
 
+    # Name the files tried, relative to the directory they were tried in.
+    def missing_file_message(expanded)
+      name = File.basename(expanded)
+      tried =
+        if EXTENSIONS.include?(File.extname(name))
+          [name]
+        else
+          ["#{name}.rb", "#{name}/lib/#{name}.rb"]
+        end
+      "cannot load such file -- #{expanded} " \
+        "(tried #{tried.join(' and ')} in #{File.dirname(expanded)})"
+    end
+    private_class_method :missing_file_message
+
     # 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)

data/lib/carton/runtime.rb

@@ -12,11 +12,12 @@ module Carton
     module_function
 
     # 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
+    # a `Carton::Namespace` of its definitions if it exports nothing. 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)
+    # caller Box's `$LOAD_PATH`, and `from` names the calling file for its
+    # error message.
+    def import(path, base_dir: nil, from: nil)
       unless Ruby::Box.enabled?
         raise ImportError, 'Carton needs Ruby::Box: run Ruby with RUBY_BOX=1'
       end
@@ -29,45 +30,42 @@ module Carton
       unless target.gems.empty?
         target.locked_gems = GemActivation.locked(caller_box, loaded_specs)
       end
-      import_cache.import(target)
-    end
+      begin
+        import_cache.import(target)
+      rescue LoadError => e
+        raise unless e.path == target.feature && base_dir.nil?
 
-    # 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 Symbols naming methods or constants, and keyword values'
+        raise LoadError, missing_name_message(path, e.message, from)
       end
+    end
 
-      duplicate = (names + values.keys).tally.find { |_, count| count > 1 }
-      if duplicate
+    # Make `value` the current carton's export, which `import` returns as
+    # is. A Symbol is refused even outside the Entrypoint: `export def name`
+    # and `export :Name` would export the Symbol itself.
+    def export(value, file:)
+      if value.is_a?(Symbol)
         raise ExportError,
-              "export name given more than once: #{duplicate.first}"
+              "export takes the value to export, not a name like #{value.inspect}: " \
+                'export a module, or keywords for a Hash'
       end
 
-      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),
-      )
-      names.first if names.size == 1 && values.empty?
+      entrypoint_box(file)&.__send__(:declare_export, value)
+      value
     end
 
-    # 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
+    # A name not on `$LOAD_PATH` is the usual mistake of `import` for a file
+    # beside the caller, so point at `import_relative` when one is there.
+    def missing_name_message(path, message, from)
+      message = "#{message}: import searches $LOAD_PATH, like require"
+      dir = from && File.dirname(File.expand_path(from))
+      return message unless dir
+
+      file = Resolver.locate(path, load_path: [], base_dir: dir).feature
+      "#{message}; use import_relative #{path.to_s.inspect} for #{file}"
+    rescue LoadError
+      message
     end
+    private_class_method :missing_name_message
 
     def load_import(target)
       Box
@@ -77,15 +75,13 @@ module Carton
           target,
           carton_entrypoint: ENTRYPOINT,
           import_cache: IMPORT_CACHE,
-        ) { |methods, values| Exports.new(methods, values) }
+        ) { |methods, constants| Namespace.new(methods, constants) }
     end
     private_class_method :load_import
 
     def import_cache
-      box = Ruby::Box.current
-      return IMPORT_CACHE unless box.respond_to?(:import_cache, true)
-
-      box.__send__(:import_cache)
+      box = Box.for(Ruby::Box.current)
+      box ? box.__send__(:import_cache) : IMPORT_CACHE
     end
     private_class_method :import_cache
 
@@ -93,10 +89,8 @@ module Carton
     # 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)
-
-      box if box.__send__(:entrypoint?, file)
+      box = Box.for(Ruby::Box.current)
+      box if box&.__send__(:entrypoint?, file)
     end
     private_class_method :entrypoint_box
   end

data/lib/carton/version.rb

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

data/lib/carton.rb

@@ -2,9 +2,8 @@
 
 require_relative 'carton/error'
 require_relative 'carton/bundler'
-require_relative 'carton/export_methods'
-require_relative 'carton/exports'
-require_relative 'carton/export_declaration'
+require_relative 'carton/namespace_methods'
+require_relative 'carton/namespace'
 require_relative 'carton/box'
 require_relative 'carton/gem_activation'
 require_relative 'carton/import_cache'
@@ -14,11 +13,10 @@ require_relative 'carton/kernel_patch'
 
 module Carton
   private_constant :Box
-  private_constant :ExportDeclaration
-  private_constant :ExportMethods
   private_constant :GemActivation
   private_constant :ImportCache
   private_constant :KernelPatch
+  private_constant :NamespaceMethods
   private_constant :Resolver
   private_constant :Runtime
 end