carton 0.1.0 → 0.3.0

data/lib/carton/runtime.rb

@@ -4,79 +4,94 @@ 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)
-    end
+    # Load the target feature in a new box and return the exported value, or
+    # 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`, 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
 
-    def export(args, kwargs)
-      if args.any? || kwargs.empty?
-        raise ArgumentError,
-              'export takes keyword arguments; use export_default for a single export'
+      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
+      begin
+        import_cache.import(target)
+      rescue LoadError => e
+        raise unless e.path == target.feature && base_dir.nil?
 
-      current_import_box.__send__(:set_export, kwargs)
+        raise LoadError, missing_name_message(path, e.message, from)
+      end
     end
 
-    def export_default(value)
-      current_import_box.__send__(:set_export, value)
-    end
+    # 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 takes the value to export, not a name like #{value.inspect}: " \
+                'export a module, or keywords for a Hash'
+      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:,
-      )
-      box
+      entrypoint_box(file)&.__send__(:declare_export, value)
+      value
     end
-    private_class_method :build_import_box
-
-    def extract_export(box)
-      return box unless box.__send__(:export_set?)
 
-      value = box.__send__(:export_value)
-      value.is_a?(Hash) ? Carton::Exports.new(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 :extract_export
-
-    def current_import_box
-      box = Ruby::Box.current
-
-      unless box.respond_to?(:set_export, true)
-        raise RuntimeError,
-              'export/export_default must be called from inside Carton.import/import_relative'
-      end
-
-      box
+    private_class_method :missing_name_message
+
+    def load_import(target)
+      Box
+        .new
+        .__send__(
+          :import_target,
+          target,
+          carton_entrypoint: ENTRYPOINT,
+          import_cache: IMPORT_CACHE,
+        ) { |methods, constants| Namespace.new(methods, constants) }
     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)
-
-      expanded_rb = "#{expanded}.rb"
-      return expanded_rb if File.file?(expanded_rb)
+    private_class_method :load_import
 
-      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)
-
-      path
+    def import_cache
+      box = Box.for(Ruby::Box.current)
+      box ? box.__send__(:import_cache) : IMPORT_CACHE
+    end
+    private_class_method :import_cache
+
+    # 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 = Box.for(Ruby::Box.current)
+      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.3.0'
 end

data/lib/carton.rb

@@ -1,31 +1,22 @@
 # frozen_string_literal: true
 
-raise 'Ruby 4.0+ is required for Carton' if RUBY_VERSION.to_f < 4.0
-
-module Carton
-  module_function
-
-  def with_bundle(gemfile)
-    previous = ENV['BUNDLE_GEMFILE']
-    ENV['BUNDLE_GEMFILE'] = gemfile
-    yield
-  ensure
-    if previous
-      ENV['BUNDLE_GEMFILE'] = previous
-    else
-      ENV.delete 'BUNDLE_GEMFILE'
-    end
-  end
-end
-
-require_relative 'carton/export_methods'
-require_relative 'carton/exports'
+require_relative 'carton/error'
+require_relative 'carton/bundler'
+require_relative 'carton/namespace_methods'
+require_relative 'carton/namespace'
 require_relative 'carton/box'
+require_relative 'carton/gem_activation'
+require_relative 'carton/import_cache'
+require_relative 'carton/resolver'
 require_relative 'carton/runtime'
 require_relative 'carton/kernel_patch'
 
 module Carton
-  private_constant :ExportMethods
-  private_constant :Runtime
+  private_constant :Box
+  private_constant :GemActivation
+  private_constant :ImportCache
   private_constant :KernelPatch
+  private_constant :NamespaceMethods
+  private_constant :Resolver
+  private_constant :Runtime
 end

data/sig/carton.rbs

@@ -0,0 +1,49 @@
+module Kernel
+  private
+
+  def import: (::String path) -> untyped
+  def import_relative: (::String path) -> untyped
+  def export: [T] (T value) -> T
+end
+
+module Carton
+  VERSION: ::String
+
+  def self.setup_bundle: (*::Symbol groups, ?gemfile: ::String?) -> untyped
+end
+
+class Carton::Error < ::StandardError
+end
+
+class Carton::ImportError < Carton::Error
+end
+
+class Carton::ExportError < Carton::Error
+end
+
+class Carton::GemfileNotFound < Carton::Error
+end
+
+# Lookup helpers on every `Carton::Namespace`. `carton rbs` extends its
+# generated `Carton::Namespace::*` modules with these.
+module Carton::NamespaceMethods
+  type key = ::String | ::Symbol
+
+  # Helpers come back as Method objects; constants as set.
+  def []: (key key) -> untyped
+  def deconstruct_keys: (nil keys) -> ::Hash[::Symbol, untyped]
+                      | (::Array[::Symbol] keys) -> ::Hash[::Symbol, untyped]
+  def fetch: (key key) -> untyped
+           | (key key, untyped default) -> untyped
+           | [T] (key key) { (key key) -> T } -> (untyped | T)
+  def fetch_values: (*key keys) -> ::Array[untyped]
+  def keys: () -> ::Array[::Symbol]
+  def to_h: () -> ::Hash[::Symbol, untyped]
+  def has_key?: (key key) -> bool
+  def key?: (key key) -> bool
+  def values_at: (*key keys) -> ::Array[untyped]
+end
+
+class Carton::Namespace < ::Module
+  include ::Carton::NamespaceMethods
+end

metadata

@@ -1,63 +1,49 @@
 --- !ruby/object:Gem::Specification
 name: carton
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - David Cristofaro
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Carton is a thin wrapper around Ruby::Box for safe, ergonomic modularization
-  in Ruby 4+. It gives you imports and exports that feel like ES Modules while still
-  reading like Ruby. Each carton can isolate constants, gems, and monkey patches behind
-  a small public API, so large apps can keep clear boundaries.
+description: The package system Ruby has been missing. Split code into Cartons that
+  import and export like modules. Each Carton runs in its own Ruby::Box, so only what
+  it exports is reachable, monkey patches stay where they are made, and two Cartons
+  can use different versions of the same gem. No manifest needed. Requires Ruby 4.0.7+.
 email:
 - david@dtcristo.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- AGENTS.md
 - CHANGELOG.md
-- DESIGN.md
 - LICENSE.txt
 - README.md
-- Rakefile
-- TODO.md
-- USAGE.md
-- examples/complex/README.md
-- examples/complex/cartons/adventure/.env
-- examples/complex/cartons/adventure/Gemfile
-- examples/complex/cartons/adventure/Gemfile.lock
-- examples/complex/cartons/adventure/lib/adventure.rb
-- examples/complex/cartons/loot/.env
-- examples/complex/cartons/loot/Gemfile
-- examples/complex/cartons/loot/Gemfile.lock
-- examples/complex/cartons/loot/lib/loot.rb
-- examples/complex/cartons/quest/lib/quest.rb
-- examples/complex/main.rb
-- examples/minimal/README.md
-- examples/minimal/bar.rb
-- examples/minimal/baz.rb
-- examples/minimal/foo.rb
-- examples/minimal/main.rb
-- images/carton.png
 - lib/carton.rb
+- lib/carton/activate_gems.rb
 - lib/carton/box.rb
-- lib/carton/export_methods.rb
-- lib/carton/exports.rb
+- lib/carton/bundler.rb
+- lib/carton/error.rb
+- lib/carton/gem_activation.rb
+- lib/carton/import_cache.rb
 - lib/carton/kernel_patch.rb
+- lib/carton/loaded_features.rb
+- lib/carton/namespace.rb
+- lib/carton/namespace_methods.rb
+- lib/carton/resolver.rb
 - lib/carton/runtime.rb
 - lib/carton/version.rb
+- sig/carton.rbs
 homepage: https://github.com/dtcristo/carton
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/dtcristo/carton
-  source_code_uri: https://github.com/dtcristo/carton
   changelog_uri: https://github.com/dtcristo/carton/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
@@ -66,14 +52,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 4.0.1
+      version: 4.0.7
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Easily box your Ruby
+summary: Real boundaries for Ruby
 test_files: []

data/AGENTS.md

@@ -1,47 +0,0 @@
-# Agents
-
-Guidance and memory for agents working on this repo.
-
-## Memory bank
-
-- Goal: make Carton feel like part of Ruby: built-in, simple, streamlined, and not verbose.
-- Prefer simpler implementation over complexity.
-- Keep the public API small and Ruby-like.
-- The project should work with or without Bundler.
-- A package in this system is called a carton, though docs can still use "package" in plain English when it reads better.
-- Current reliable bundled-carton pattern: use `Carton.with_bundle(gemfile) { import ... }` for the entry import that should activate a carton-local bundle.
-- Conflicting bundles still need a subprocess workaround today.
-- Ruby::Box boxes start from root-box load paths/loaded features, so Carton must copy parent non-gem load paths forward itself.
-- `$LOAD_PATH` is box-local, but `Gem.loaded_specs` is shared across boxes in practice, so conflicting bundle activation still collides there.
-- Duplicating `Gem.loaded_specs` inside a box isolates a single bundled import from root state, but conflicting bundles still fail because Bundler also rewrites shared RubyGems entrypoints/spec state such as `Gem::Specification.all`.
-- Never push. Make local commits only; the user handles pushes.
-
-## Working rules
-
-- Everything should have tests. Write tests for new behaviour, run targeted tests as you go, and `RUBY_BOX=1 bundle exec rake` before finishing.
-- If you only changed an example, run that example during iteration and the full suite before finishing.
-- Run `bundle exec rake format` after every change.
-- Keep implementation and docs concise.
-- Do not over-engineer.
-- Never use thread local variables in implementation.
-- Always review https://docs.ruby-lang.org/en/4.0/Ruby/Box.html on how `Ruby::Box` works.
-- Never bump the version or publish the gem.
-- When multiple implementation choices are viable, present a menu with your recommendation.
-- Commit as you go with descriptive messages and the required Co-authored-by trailer.
-- Never push; the user will do that.
-
-## Docs
-
-- Keep `README.md`, `USAGE.md`, `DESIGN.md`, `TODO.md`, `AGENTS.md`, and example READMEs up to date when behavior, workflow, or plans change.
-- Keep the root `README.md` minimal; move detail into focused docs.
-- Put future work, open questions, and upstream ideas in `TODO.md`.
-- Update `AGENTS.md` whenever the user gives durable project guidance or you discover stable context worth remembering.
-- Use `AGENTS.md` as a concise memory bank, not a changelog.
-
-## Commands
-
-- `RUBY_BOX=1 bundle exec rake` - full suite
-- `RUBY_BOX=1 bundle exec rake test` - unit tests only
-- `RUBY_BOX=1 bundle exec rake example:minimal` - minimal example
-- `RUBY_BOX=1 bundle exec rake example:complex` - complex example
-- `bundle exec rake format` - format code

data/DESIGN.md

@@ -1,84 +0,0 @@
-# Design
-
-## Goal
-
-Keep the library small: a thin wrapper around `Ruby::Box` that makes isolated file-to-file imports feel like part of Ruby.
-
-## Main pieces
-
-| File | Role |
-| --- | --- |
-| `lib/carton.rb` | Entry point, version guard, `Carton.with_bundle`, and internal wiring |
-| `lib/carton/kernel_patch.rb` | Adds global `import`, `import_relative`, `export_default`, and `export` |
-| `lib/carton/runtime.rb` | Builds boxes, resolves targets, runs imports, and extracts exports |
-| `lib/carton/box.rb` | Box-specific helpers for requiring files, managing export state, and inheriting safe load paths |
-| `lib/carton/exports.rb` | Wraps named exports in a module-like namespace |
-| `lib/carton/export_methods.rb` | Shared `[]`, `fetch`, `fetch_values`, `values_at`, `key?`, and destructuring support |
-
-## Import flow
-
-1. `import` or `import_relative` delegates to `Carton::Runtime.import`.
-2. A fresh `Carton::Box` is created for that import.
-3. The carton entrypoint (`lib/carton.rb`) is required inside the box so the box has `export`, `import`, and `import_relative`.
-4. The target file is resolved either from the caller's base directory or from the current box's `$LOAD_PATH`.
-5. The target file is required inside the box.
-6. If the file called `export_default` or `export`, the exported value is returned.
-7. If the export was a hash, it is wrapped in `Carton::Exports`.
-8. If there was no export, the box itself is returned.
-
-Every import creates a fresh box. There is no module cache at the Carton layer.
-
-## Export model
-
-There are three return shapes:
-
-- single export: the exported object itself
-- named exports: `Carton::Exports`
-- no export: `Carton::Box`
-
-`export_default` is the explicit single-export form. `export` is the named-export form and only accepts keyword arguments. `Carton::Exports` exposes capitalized keys as constants and lowercase keys as singleton methods. Both `Carton::Exports` and `Carton::Box` share the same small fetch/deconstruction API through `ExportMethods`.
-
-## Load path model
-
-Ruby::Box creates new user boxes from the root box, not from the current caller box. In `box.c`, each new box starts by duplicating the root box's `load_path` and `loaded_features`, and `require` resolves against the loading box's local `$LOAD_PATH` / `$LOADED_FEATURES`.
-
-Carton therefore re-inherits the parent box's non-gem load paths manually so local carton directories can still be resolved by name across nested imports.
-
-The current filter deliberately tries to avoid leaking gem paths from a parent import chain into child boxes:
-
-- RubyGems paths are filtered
-- common Bundler vendor paths are filtered
-- local, non-gem carton paths are preserved
-
-This is why the examples add sibling `lib/` directories to `$LOAD_PATH` explicitly before using `import 'name'`.
-
-## Bundler model
-
-The current implementation works best when a carton bundle is selected before its entry file is evaluated. In practice that means selecting `BUNDLE_GEMFILE` around the `import` call for that carton; `Carton.with_bundle` is the small wrapper for that handoff.
-
-This keeps one carton-local bundle isolated from the caller, but current limitations remain:
-
-- a parent already running under Bundler is not a reliable place to import a child carton with its own bundle
-- switching between conflicting bundles in one process is not reliable today
-- the complex example uses a subprocess for the conflicting `loot` bundle for that reason
-
-The problem is not that Bundler has special C code mutating every box at once. Bundler and RubyGems do their activation work in Ruby:
-
-- `Bundler::SharedHelpers#find_gemfile` reads `ENV['BUNDLE_GEMFILE']`
-- `Bundler::Runtime#setup` calls `clean_load_path`, `replace_entrypoints`, `mark_loaded`, and `Gem.add_to_load_path`
-- RubyGems activation checks and writes `Gem.loaded_specs`
-
-What matters under `Ruby::Box` is which of those pieces are box-local. In practice:
-
-- `$LOAD_PATH` stays box-local; activating a bundle in an imported box does not inject its gem lib paths into the caller box
-- `Gem.loaded_specs` is still shared across boxes in practice unless it is explicitly replaced inside the box
-
-Duplicating `Gem.loaded_specs` inside an imported box was enough to keep a single bundled import from leaking back into the caller box, but it was still not enough to make two conflicting bundles coexist. Bundler also rewrites RubyGems entrypoints and spec state through code paths such as `replace_entrypoints`, `stub_rubygems`, `Gem::Specification.all = ...`, and `Gem.clear_paths`.
-
-That shared activation state is why a second box can see a gem version activated by the first one even though its own `$LOAD_PATH` is separate. In local probes, activating `dotenv 3.2.0` in one box caused a second box targeting `dotenv ~> 2.0` to fail its Bundler activation and then crash under Ruby 4.0 + `Ruby::Box`.
-
-See [TODO.md](TODO.md) for the upstream work that would help.
-
-## Why the complex example stays explicit
-
-The complex example keeps load-path setup and bundled imports visible in `main.rb` on purpose. It is meant to demonstrate Carton directly, not hide the mechanics behind another layer.

data/Rakefile

@@ -1,52 +0,0 @@
-# frozen_string_literal: true
-
-STREE_FILES = '"**/*.{rb,rake,gemspec}" "**/Rakefile" "**/Gemfile"'
-EXAMPLES = %w[minimal complex].freeze
-
-desc 'Run all tests'
-task :test do
-  test_files =
-    Dir.glob('test/**/*_test.rb').sort.map { |f| File.expand_path(f) }
-  sh "RUBY_BOX=1 ruby -Ilib -Itest -e 'ARGV.each { |f| require f }' #{test_files.join(' ')}",
-     verbose: false
-end
-
-namespace :example do
-  EXAMPLES.each do |name|
-    desc "Run the #{name} example"
-    task name.to_sym do
-      dir = File.join('examples', name)
-
-      puts
-      puts "== Running example/#{name} =="
-      puts
-
-      Bundler.with_unbundled_env do
-        # Install gems for any carton/local example gemfile.
-        Dir
-          .glob(File.join(dir, '**/Gemfile'))
-          .each do |gemfile|
-            pkg_dir = File.dirname(gemfile)
-            sh(
-              "cd #{pkg_dir} && " \
-                'BUNDLE_GEMFILE=Gemfile bundle check >/dev/null 2>&1 || ' \
-                'BUNDLE_GEMFILE=Gemfile bundle install --quiet',
-              verbose: false,
-            )
-          end
-
-        sh "RUBY_BOX=1 ruby #{File.join(dir, 'main.rb')}", verbose: false
-      end
-    end
-  end
-end
-
-desc 'Run all examples'
-task examples: EXAMPLES.map { |n| "example:#{n}" }
-
-desc 'Format code'
-task :format do
-  sh "bundle exec stree write #{STREE_FILES}", verbose: false
-end
-
-task default: %i[test examples]

data/TODO.md

@@ -1,33 +0,0 @@
-# TODO
-
-## Bundler / upstream
-
-- Add a Bundler API that can activate a specific Gemfile explicitly instead of relying on process-global `ENV['BUNDLE_GEMFILE']` and `bundler/setup`.
-- Make multiple bundle contexts safer for embedded runtimes. Today one carton-local bundle can work, but importing a second conflicting bundle in the same process still resolves against the first bundle's shared RubyGems activation state and can crash under `Ruby::Box`.
-- Expose resolved bundle load paths without forcing full `Bundler.setup` and RubyGems entrypoint replacement.
-- Make `Bundler.reset!`, `with_original_env`, and `with_unbundled_env` sufficient for re-entering Bundler with another Gemfile, or add a supported replacement for that workflow.
-- Improve support for a parent process already running under Bundler importing a child carton that needs a different bundle.
-- Make RubyGems activation state such as `Gem.loaded_specs` safely box-local or otherwise explicitly isolateable so two conflicting bundles can coexist under `Ruby::Box` without a subprocess.
-- Investigate whether `Bundler.rubygems.replace_entrypoints`, `stub_rubygems`, `Gem::Specification.all`, and `Gem.clear_paths` can be made box-local. Duplicating `Gem.loaded_specs` inside the box isolated a single bundled import from the root box, but it was not enough to make a second conflicting bundle work.
-
-## Ruby::Box / upstream
-
-- Expose more public APIs or clearer guarantees around box-local `$LOAD_PATH`, `$LOADED_FEATURES`, and feature resolution so libraries like Carton do not need to manually copy parent load paths and call `resolve_feature_path`.
-- Investigate the crash path after conflicting bundled imports under Ruby 4.0 + `Ruby::Box`, even when the immediate conflict is already surfaced as a Bundler/RubyGems activation error.
-
-## Library
-
-- Revisit `Carton::Box#gem_path?`; it still relies partly on path heuristics.
-- Add targeted tests for bundled carton imports instead of covering that behavior only through the complex example.
-- Remove the targeted Minitest `object_id` warning suppression once Ruby::Box or Minitest no longer emits it under Ruby 4.0.
-- Revisit whether `import` should always return a `Carton::Exports` wrapper with a `default` accessor, or whether the current duck-typed return values are the better long-term fit.
-
-## Examples / docs
-
-- Keep the root README intentionally short and push detail into focused docs.
-- Keep documenting current Bundler constraints plainly until the runtime or Bundler story improves.
-
-## Tooling ideas
-
-- Explore a Prism-based strict mode/linter that enforces `import`/`export` calls at file root and can build a static dependency graph without evaluating code.
-- If that exists, add graph validation ideas such as cycle detection, missing import targets, dead imports, and unused exports.