carton 0.1.0 → 0.3.0

data/lib/carton/bundler.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Carton
+  class << self
+    # Set up the current carton's bundle, like `Bundler.setup(*groups)`.
+    #
+    # Bundler finds its Gemfile through process-global `ENV["BUNDLE_GEMFILE"]`
+    # or the real process cwd. Carton resolves the Gemfile from the calling
+    # file (or `gemfile:`, relative to it), points Bundler at it, and clears any
+    # stale `BUNDLE_LOCKFILE` so Bundler derives the matching lockfile. All of
+    # `ENV` is restored afterwards; Bundler keeps the selected Gemfile.
+    def setup_bundle(*groups, gemfile: nil)
+      path = resolve_bundle_gemfile(gemfile, caller_locations(1, 1).first)
+
+      with_bundle_env(path) do
+        require 'bundler'
+        Bundler.ui.silence { Bundler.setup(*groups) }
+      end
+    end
+
+    private
+
+    # `ENV` is process-global. Bundler reads the Gemfile from it and exports
+    # subprocess variables such as `RUBYOPT` into it, so restore all of it.
+    def with_bundle_env(gemfile)
+      previous_env = ENV.to_h
+      ENV['BUNDLE_GEMFILE'] = gemfile
+      ENV.delete 'BUNDLE_LOCKFILE'
+      yield
+    ensure
+      ENV.replace(previous_env)
+    end
+
+    def resolve_bundle_gemfile(gemfile, call_site)
+      caller_dir = caller_directory(call_site)
+      return resolve_explicit_bundle_gemfile(gemfile, caller_dir) if gemfile
+
+      current = caller_dir
+
+      loop do
+        bundle_gemfile_names.each do |name|
+          candidate = File.join(current, name)
+          return candidate if File.file?(candidate)
+        end
+
+        parent = File.dirname(current)
+        break if parent == current
+
+        current = parent
+      end
+
+      raise GemfileNotFound, "Gemfile not found from #{caller_dir}"
+    end
+
+    def resolve_explicit_bundle_gemfile(gemfile, caller_dir)
+      resolved = File.expand_path(gemfile, caller_dir)
+      return resolved if File.file?(resolved)
+
+      raise GemfileNotFound, "Gemfile not found: #{resolved}"
+    end
+
+    def caller_directory(call_site)
+      path = call_site&.absolute_path || call_site&.path
+      return Dir.pwd unless path && !path.start_with?('(')
+
+      File.dirname(File.expand_path(path))
+    end
+
+    def bundle_gemfile_names
+      %w[gems.rb Gemfile]
+    end
+  end
+end

data/lib/carton/error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Carton
+  # Base class for every error Carton raises itself. A missing Import target
+  # raises `LoadError`, as `require` does, and a missing exported name raises
+  # `NameError`.
+  class Error < StandardError
+  end
+
+  # An Import that cannot go ahead: Boxes are disabled, a Carton imports
+  # itself, or a cached Carton was built against other gem versions.
+  class ImportError < Error
+  end
+
+  # An `export` that breaks the rules: called twice in one Entrypoint, given
+  # a Symbol, or a Bare Carton helper that would hide a `Carton::Namespace`
+  # method.
+  class ExportError < Error
+  end
+
+  # Raised when Carton cannot find the bundle file for `setup_bundle`.
+  class GemfileNotFound < Error
+  end
+end

data/lib/carton/gem_activation.rb

@@ -0,0 +1,151 @@
+# 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 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
+
+      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
+
+    # 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)
+      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
+
+    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)
+      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| activatable?(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] || !activatable?(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
+
+    # 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

@@ -0,0 +1,105 @@
+# 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
+    # 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_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.
+    #
+    # 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)
+      cached = claim(key)
+      return load_entry(key, target) if cached.equal?(LOAD)
+
+      check_gem_versions(key, target)
+      cached
+    end
+
+    private
+
+    # 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
+    end
+
+    # 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 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)
+      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} #{version}, " \
+                "but this import activates #{name} #{wanted[name]}"
+      end
+    end
+
+    def versions(specs)
+      (specs || []).to_h { |spec| [spec.name, spec.version.to_s] }
+    end
+  end
+end

data/lib/carton/kernel_patch.rb

@@ -2,24 +2,28 @@
 
 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, from: caller_locations(1, 1).first.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)
-    end
-
-    def export_default(value)
-      Runtime.export_default(value)
+    # 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(value, file:)
     end
   end
 end
 
 # Inject only the Kernel patch module into Kernel.
-::Kernel.prepend(Carton::KernelPatch)
+Kernel.prepend(Carton::KernelPatch)

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,27 +1,30 @@
 # frozen_string_literal: true
 
 module Carton
-  module ExportMethods
+  # Hash-like lookup helpers for `Carton::Namespace`.
+  module NamespaceMethods
+    # 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 member or `nil`.
     def [](key)
       found, value = lookup_entry(key)
       found ? value : nil
     end
 
+    # Check whether the lookup will succeed.
     def key?(key)
       lookup_entry(key).first
     end
 
     alias has_key? key?
 
+    # Fetch a member with the same default/block semantics as `Hash#fetch`.
     def fetch(key, *default)
       if default.size > 1
         raise ArgumentError,
@@ -36,10 +39,18 @@ module Carton
       raise KeyError, "key not found: #{key.inspect}"
     end
 
+    # 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 members, using `nil` for missing keys.
     def values_at(*keys)
       keys.map { |key| self[key] }
     end

data/lib/carton/resolver.rb

@@ -0,0 +1,149 @@
+# 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.
+    # 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,
+        :gem_usage,
+        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)
+      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
+    # 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, 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)
+      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