carton 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3d0c8755a90c3eb40d7ee29a16a174a89f1c678e43ba08275fab4502b298fae
-  data.tar.gz: 582512d0d84c6e3dfa2b49c9d95b5e77e4fac4a25a45b63b17bf9ed6087d65c1
+  metadata.gz: 0a0f0305abe746709cf0b95c29f1f5d94d4ae4d794698205a4aa64fded37780b
+  data.tar.gz: 262c64943c2e73831507b95a8dde3e3e8f2ea712f6844e25fa02de178e292bd3
 SHA512:
-  metadata.gz: f48e9cdd2c5c64d12f323de0acc65498f7e0c0aa7f230decdf5fae538337e268c07686e9f2b5017b4d38dd1b4c22bb2120bc5c54b5ce6884f59d7b319779b0e5
-  data.tar.gz: 1470bb044aaacf574535228f1bc9f12a84f0654651c3fbaa52fe52bcde0f215c9262eb0d603c6cc98239c29f4f44854b07534ff608af0bc206e701f2498f1cc0
+  metadata.gz: b20c31a54f13d1a25296779c7bfc9b03adb4a6a2df8fb22cf6ebf7fa714f29b0d497ea8ddf7ca5a96e3e83cb76484d5687dfe7a9d9cb7563e5ab7d482d83f054
+  data.tar.gz: c0db95029ee083e52ab39b535f03a89bd8cc9ad5b9cf1d0741c90d65fb919e64a1ba369377a62ec17615e6e42a69d5969ec550093adebdba527caf79e12e0fe4

data/CHANGELOG.md

@@ -2,9 +2,127 @@
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-17
+
+Cartons are now gem-sized or domain-sized units: a file plus the directory
+named after it. This release also redesigns exports, shares imports across
+the process, adds gem and Bundler support, and requires Ruby 4.0.7.
+
+### Breaking
+
+- A Carton is now a file plus the directory named after it, the shape of a
+  gem's `lib/`: `billing.rb` and everything under `billing/`, including
+  Zeitwerk implicit-namespace directories. Importing a file inside a Carton,
+  such as `import 'billing/invoice'`, raises `Carton::ImportError` naming the
+  import to use. It used to load a second copy of the file in its own Box, so
+  its classes did not match the Carton's.
+- Carton now requires Ruby 4.0.7 or later, enforced by the gemspec, and
+  Bundler support needs Bundler 4.0.23 or later.
+- `export` can be called many times per file, and each call adds to one
+  Export Namespace. A capitalized Symbol exports a constant (`export :Money`),
+  other Symbols export methods (`export :add`, or `export def add ...`), and
+  keywords export plain values. Replace `export add: method(:add)` with
+  `export :add`. A missing name raises `NameError`, and a name exported twice
+  raises `Carton::ExportError`.
+- Exported methods forward when called (`exports.add(...)`), while `[]`,
+  `fetch`, and destructuring return the `Method` object. Keyword values are no
+  longer invoked: `export handler: -> {}` makes `exports.handler` return the
+  lambda.
+- `export_default` may be called only once per file and cannot be combined
+  with `export`; both raise `Carton::ExportError`. Put other names inside the
+  default value.
+- Importing a file with no exports (a Bare Carton) returns a `Carton::Exports`
+  of the constants and top-level helpers it defines, instead of its
+  `Carton::Box`. Importers can no longer `eval`, `require`, or read
+  `load_path` inside another Carton. Helpers are callable directly
+  (`toolbox.helper`), lookups return their `Method` object
+  (`toolbox.fetch(:helper).call`), and constants are read when the import
+  finishes. `Carton::Box` is now a private constant.
+- Imports are shared across the process. Each Carton file loads once, and
+  every later `import` or `import_relative` of it returns the same value, so
+  sibling Cartons share classes and Carton state no longer resets per import.
+  A Carton that imports itself raises `Carton::ImportError`.
+- `import 'name'` no longer checks the current directory before `$LOAD_PATH`,
+  so results no longer depend on where the app was started. Use an absolute
+  path, `import_relative`, or add the directory to `$LOAD_PATH`.
+- `Carton.with_bundle { require 'bundler/setup' }` is replaced by
+  `Carton.setup_bundle`. Pass groups as with `Bundler.setup`
+  (`Carton.setup_bundle(:default, :test)`) and choose a Gemfile with
+  `gemfile:`. Bundler errors raise instead of exiting the process.
+
+### Added
+
+- `import_relative` and absolute `import` accept a gem-shaped directory:
+  `import_relative 'components/billing'` loads
+  `components/billing/lib/billing.rb` with that `lib/` on the Carton's load
+  path.
+- `Carton::Error`, the base class of every error Carton raises itself, with
+  `Carton::ImportError` (circular imports, gem version mismatches) and
+  `Carton::ExportError` (repeated or conflicting exports). They replace plain
+  `RuntimeError`s and `ArgumentError`s, and are the same classes in every
+  Box. `Carton::GemfileNotFound` is now a `Carton::Error`.
+- `Carton.setup_bundle(*groups, gemfile: nil)` sets up a Carton's own bundle.
+  Without `gemfile:` it searches upward from the calling file for `gems.rb`
+  or `Gemfile`. It clears any stale `BUNDLE_LOCKFILE` and restores all of
+  `ENV` after setup, so a Carton's bundle variables never reach the rest of
+  the process. `Carton::GemfileNotFound` is raised when there is no Gemfile.
+- Public RBS signatures in `sig/carton.rbs`.
+- `examples/monorepo`: packages as path gems in one Gemfile, imported by gem
+  name.
+- `examples/rails_in_main`: a Rails API app whose domain logic is a
+  Zeitwerk-loaded path-gem Carton.
+- `examples/rails_in_cartons`: Rails loaded once in a framework Carton, with
+  models and controllers spread across domain Cartons. The Main Box runs only
+  Rack.
+- `examples/master_prelude`: an optional, unsupported hack that loads Active
+  Support's core extensions into Ruby's Master Box so every Carton inherits
+  them.
+
+### Changed
+
+- `export` and `export_default` only declare exports from the imported
+  Entrypoint. Under plain `require`, or in other files a Carton requires, they
+  validate their arguments and do nothing, so Carton-aware files and gems also
+  load with `require`.
+- Importing a file from an activated gem activates that gem and its runtime
+  dependencies in the Carton's Box at the caller's versions. When the caller
+  ran Bundler setup, the Box is also restricted to the caller's bundle: every
+  locked gem loads at its locked version, and gems outside the lockfile raise
+  `LoadError`.
+- `import`, `import_relative`, `export`, and `export_default` are private
+  Kernel methods, like `require`, so `"str".import(...)` raises
+  `NoMethodError` and objects no longer `respond_to?` them.
+- `import 'name'` resolves the feature in the caller's Box and carries only
+  the matching load-path entry into the imported Box, instead of copying the
+  caller's whole `$LOAD_PATH`.
+- `RUBY_BOX=1 bundle exec` works, including Gemfiles that evaluate a gemspec.
+  Carton no longer patches RubyGems or Bundler.
+
+### Fixed
+
+- Importing without `RUBY_BOX=1` raises `Carton::ImportError` explaining how to
+  enable Boxes, instead of `NoMethodError` on `nil`.
+- A missing `import_relative` target raises `LoadError` instead of loading a
+  same-named feature from the load path (such as the stdlib `json`), and a
+  missing absolute `import` raises `LoadError` instead of `Errno::ENOENT`.
+- `export_default` keeps Hash, `nil`, and `false` values as Default Exports
+  instead of treating a Hash as an Export Namespace.
+- A gem Carton imported from another Carton's Box gets its dependencies.
+  Activation used to write to the importing Carton's `$LOAD_PATH`, so the
+  gem's `require` of a dependency raised `LoadError`.
+- A gem Carton's dependencies load at the caller's versions instead of the
+  newest installed ones. A later import whose caller has different versions
+  activated raises instead of reusing the cached Carton.
+- Bare Carton lookup only finds constants and helpers the Entrypoint defines.
+  Keys are no longer evaluated as Ruby expressions, and `key?` no longer calls
+  helpers.
+- Hash-rest patterns (`=> { **rest }`) return every Named Export, or every
+  member of a Bare Carton's Public Surface, instead of an empty hash.
+
 ## [0.1.0] - 2026-04-16
 
 Initial release.
 
-[Unreleased]: https://github.com/dtcristo/carton/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/dtcristo/carton/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/dtcristo/carton/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/dtcristo/carton/releases/tag/v0.1.0

data/README.md

@@ -1,8 +1,8 @@
 <div align="center">
+  <img src="images/carton.png" alt="Carton logo" width="200" />
   <h1>
     Carton
   </h1>
-  <img src="images/carton.png" alt="Carton logo" width="200" />
   <p>
     <strong>
       Easily box your Ruby
@@ -10,56 +10,128 @@
   </p>
 </div>
 
-Carton is a thin wrapper around [`Ruby::Box`](https://docs.ruby-lang.org/en/4.0/Ruby/Box.html) 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.
+Split a Ruby app into gem-sized units that import and export like modules.
+Each Carton runs in its own
+[`Ruby::Box`](https://docs.ruby-lang.org/en/4.0/Ruby/Box.html), so:
+
+- two parts of one app can use **different versions of the same gem**;
+- **monkey patches stay** in the Carton that makes them;
+- only what a Carton exports is reachable, so **boundaries hold at runtime**.
+
+A Carton is shaped like a gem: `billing.rb` plus the `billing/` directory, with
+no manifest. A gem, a path gem, a directory, or a single file can be one.
+
+## Quick start
+
+Carton needs Ruby 4.0.7+ with Boxes enabled (`RUBY_BOX=1`). Install it:
+
+```sh
+gem install carton   # or add `gem 'carton'` to your Gemfile
+```
 
-## Minimal usage
+A Carton's Entrypoint loads its own files and exports one value with
+`export_default`:
+
+```
+billing.rb          # the Entrypoint
+billing/invoice.rb  # inside the Carton
+```
 
 ```ruby
-# user.rb
-class User
-  def initialize(name) = @name = name
+# billing.rb
+require_relative 'billing/invoice'
+
+module Billing
+  def self.invoice(total) = Invoice.new(total)
 end
 
-export_default User
+export_default Billing
 ```
 
+Or it exports several names with `export`. Capitalized Symbols name
+constants, other Symbols name methods, and keywords are plain values:
+
+```ruby
+# math.rb
+export def add(a, b) = a + b
+export PI: 3.14159
+```
+
+Import them:
+
 ```ruby
 # main.rb
 require 'carton'
 
-User = import_relative 'user'
-alice = User.new('Alice')
+Billing = import_relative 'billing'
+Billing.invoice(42)
+
+MathTools = import_relative 'math'
+MathTools.add(2, 3) # => 5
+MathTools::PI       # => 3.14159
 ```
 
-Named exports return a namespace-like module:
+```sh
+RUBY_BOX=1 ruby main.rb
+```
 
-```ruby
-# math.rb
-def add(a, b) = a + b
+`import_relative 'billing/invoice'` raises `Carton::ImportError`: the file is
+inside the `billing` Carton, so only `billing` can be imported. `import 'name'`
+searches `$LOAD_PATH` like `require`, so gems and path gems import by name, and
+a gem-shaped directory (`components/billing/lib/billing.rb`) imports by its
+path. Each Carton loads once per process, and every later import returns the
+same value.
 
-export PI: 3.14159, add: method(:add)
-```
+## Gems and Bundler
+
+A Carton can set up its own bundle, isolated from the app's:
 
 ```ruby
-MathTools = import_relative 'math'
-MathTools::PI
-MathTools.add(2, 3)
+# cartons/reports/lib/reports.rb
+Carton.setup_bundle # uses cartons/reports/Gemfile
+require 'bigdecimal'
 ```
 
+A gem in the app's bundle imports as a Carton and gets its dependencies at the
+app's locked versions. For a monorepo, make each package a path gem in one
+Gemfile and import it by name; see [examples/monorepo](examples/monorepo/README.md).
+
+## Status
+
+Carton is experimental, and so is `Ruby::Box`. It targets Ruby 4.0.7+ and,
+with Bundler, Bundler 4.0.23+. Box is not a security boundary: it isolates
+definitions and load state, not objects. Classes a Carton defines are shared
+with every importer, so reopening one changes it everywhere; see
+[Sharing classes across Cartons](docs/usage.md#sharing-classes-across-cartons).
+
 ## Docs
 
-- [USAGE.md](USAGE.md) - detailed import/export, load path, and Bundler usage
-- [DESIGN.md](DESIGN.md) - implementation overview and constraints
-- [TODO.md](TODO.md) - future improvements and Bundler upstream ideas
-- [examples/minimal/README.md](examples/minimal/README.md) - smallest example
-- [examples/complex/README.md](examples/complex/README.md) - multi-carton example
+- [usage.md](docs/usage.md): exports, imports, Bundler, gem Cartons, and testing
+- [design.md](docs/design.md): how an import runs
+- [todo.md](docs/todo.md): planned work and open questions
+- [internals/](docs/internals/): how `Ruby::Box`, RubyGems, and Bundler work, and upstream plans
+- [CONTEXT.md](CONTEXT.md): the glossary
+
+Examples, each runnable with `RUBY_BOX=1 ruby examples/<name>/main.rb`:
+
+| Example | Shows |
+| --- | --- |
+| [minimal](examples/minimal/README.md) | A Carton with its own directory, a single-file Carton, and the error for importing a file inside a Carton |
+| [gems](examples/gems/README.md) | Two Cartons using different `bigdecimal` versions without Bundler |
+| [bundler](examples/bundler/README.md) | Cartons with their own Bundler setup, plus a path gem |
+| [monorepo](examples/monorepo/README.md) | Packages as path gems in one Gemfile, imported by gem name |
+| [rails_in_main](examples/rails_in_main/README.md) | Rails in the Main Box, domain logic in a Carton |
+| [rails_in_cartons](examples/rails_in_cartons/README.md) | Rails loaded once in a Carton, models and controllers in domain Cartons |
+| [master_prelude](examples/master_prelude/README.md) | An unsupported hack that shares Active Support with every Carton |
 
 ## Development
 
 ```sh
-bundle install                        # Install development deps
-RUBY_BOX=1 bundle exec rake           # Run all tests and examples
-bundle exec rake format               # Format code
+bundle install
+bundle exec rake                  # tests, RuboCop, and every example
+bundle exec rake test             # tests only
+bundle exec rake example:monorepo # one example
+bundle exec rake format           # format with Syntax Tree
 ```
 
 ## License

data/lib/carton/activate_gems.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Required inside a Carton Box by `Carton::Box#activate_gems`. `$LOAD_PATH`
+# resolves to the Box of the file being loaded, so activating from a file
+# required here updates this Box even during a nested Import.
+Carton.const_get(:GemActivation).activate(
+  *Ruby::Box.current.__send__(:pending_gems),
+)

data/lib/carton/box.rb

@@ -2,114 +2,141 @@
 
 module Carton
   class Box < Ruby::Box
-    include ExportMethods
-
-    UNSET_EXPORT = Object.new.freeze
-    private_constant :UNSET_EXPORT
+    ACTIVATE_GEMS = File.expand_path('activate_gems.rb', __dir__)
+    private_constant :ACTIVATE_GEMS
+    ERRORS = %i[Error ImportError ExportError GemfileNotFound].freeze
+    private_constant :ERRORS
 
     def initialize
       super
-      reset_export
+      reset_export_declaration
     end
 
     private
 
-    def configure_for_import(parent_box:, entrypoint:, bundle_gemfile:)
-      inherit_load_path(parent_box)
-      reset_export
+    # The whole Import lifecycle, in order: boot Carton in this Box, load the
+    # target, then build its public surface with `build`. Runtime calls only
+    # this, so the ordering lives here.
+    def import_target(target, carton_entrypoint:, import_cache:, &build)
+      configure_for_import(entrypoint: carton_entrypoint, import_cache:)
+      load_import(
+        target.feature,
+        load_path: target.load_path,
+        gems: target.gems || [],
+        locked_gems: target.locked_gems,
+      )
+      export_public_surface(&build)
+    end
+
+    # Fresh boxes copy Master, so they start without the caller's gems. Load
+    # Carton's own entrypoint so the imported file gets `import`,
+    # `import_relative`, and `export`. Nested imports reuse the caller's
+    # process-wide import cache.
+    def configure_for_import(entrypoint:, import_cache:)
+      @import_cache = import_cache
+      reset_export_declaration
+      add_import_load_path(File.dirname(entrypoint))
       require_in_box(entrypoint)
-      set_bundle_gemfile(bundle_gemfile)
+      share_error_classes
+      snapshot_import_support
       self
     end
 
-    def require_in_box(feature)
-      eval("require #{feature.inspect}")
-    end
+    # Activate the caller's gems for the target, then load it inside the box.
+    def load_import(feature, load_path: nil, gems: [], locked_gems: nil)
+      activate_gems(gems, locked_gems) unless gems.empty?
+      add_import_load_path(load_path) if load_path
 
-    def resolve_feature_path_in_box(feature)
-      eval("$LOAD_PATH.resolve_feature_path(#{feature.inspect})")
+      @entrypoint = real_path(feature)
+      result = require_in_box(feature)
+      discover_public_entries
+      result
     end
 
-    def activate_bundle_if_configured
-      gemfile = ENV['BUNDLE_GEMFILE']
-      return unless gemfile && File.file?(gemfile)
+    attr_reader :import_cache, :pending_gems
 
-      require_in_box('bundler/setup')
+    def require_in_box(feature)
+      eval("require #{feature.inspect}")
     end
 
-    def set_export(value)
-      if export_set?
-        raise RuntimeError, 'only one export is allowed per imported file'
+    # Box methods run in the Box that defined them, so this Box's own copy of
+    # Carton activates gems in this Box's RubyGems. `$LOAD_PATH` resolves to
+    # the Box of the file being loaded, which during a nested Import is the
+    # importing Carton, so activation runs from a file required here.
+    def activate_gems(gems, locked_gems)
+      @pending_gems = [gems, locked_gems]
+      require_in_box(ACTIVATE_GEMS)
+    ensure
+      @pending_gems = nil
+    end
+
+    # This Box just loaded its own copy of Carton, whose error classes are new
+    # objects that `rescue Carton::Error` in another Box would never match.
+    # Point them at the importer's classes, so one rescue catches errors
+    # raised in any Carton.
+    def share_error_classes
+      carton = const_get(:Carton, false)
+      ERRORS.each do |name|
+        carton.__send__(:remove_const, name)
+        carton.const_set(name, Carton.const_get(name, false))
       end
-
-      @export = value
-    end
-
-    def export_set?
-      !@export.equal?(UNSET_EXPORT)
     end
 
-    def export_value
-      @export
+    def add_import_load_path(path)
+      load_path.unshift(path) unless load_path.include?(path)
     end
 
-    def reset_export
-      @export = UNSET_EXPORT
+    # Only the imported Entrypoint declares this Carton's exports. Other files
+    # it requires may call `export` for their own imports; here it is inert.
+    def entrypoint?(file)
+      !@entrypoint.nil? && real_path(file) == @entrypoint
     end
 
-    def set_bundle_gemfile(path)
-      return unless path
+    def real_path(path)
+      return unless path && File.absolute_path?(path) && File.file?(path)
 
-      eval("ENV['BUNDLE_GEMFILE'] = #{path.inspect}")
+      File.realpath(path)
     end
 
-    def inherit_load_path(source_box)
-      return self unless source_box.respond_to?(:load_path)
-
-      source_box.load_path.each do |path|
-        next unless inherit_path?(path)
-
-        load_path << path unless load_path.include?(path)
-      end
+    def declare_export(methods, values)
+      @export_declaration = @export_declaration.add(methods, values)
+    end
 
-      self
+    def declare_default(value)
+      @export_declaration = @export_declaration.default(value)
     end
 
-    def inherit_path?(path)
-      expanded = File.expand_path(path)
-      !gem_path?(expanded)
+    # A Bare Carton's surface is the constants and top-level helpers its
+    # Entrypoint defined, so importers never receive the Box itself.
+    def export_public_surface(&)
+      @export_declaration.public_surface(bare: method(:bare_surface), &)
     end
 
-    def gem_path?(path)
-      gem_roots = Gem.path.map { |root| File.expand_path(root) }
-      gem_roots.any? { |root| path == root || path.start_with?("#{root}/") } ||
-        path.include?('/vendor/bundle/') || path.include?('/bundler/gems/')
+    def bare_surface
+      constants =
+        @public_constant_names.to_h { |name| [name, const_get(name, false)] }
+      [@public_method_entries, constants]
     end
 
-    def lookup_entry(key)
-      name = key.to_s
+    def reset_export_declaration
+      @export_declaration = ExportDeclaration.absent
+    end
 
-      if name.match?(/\A[A-Z]/)
-        lookup_constant_entry(name)
-      else
-        lookup_method_entry(name)
-      end
+    def snapshot_import_support
+      @import_constant_names = constants(false).map(&:to_s)
+      @import_method_names = top_level_methods.keys
     end
 
-    def lookup_constant_entry(name)
-      [true, const_get(name)]
-    rescue NameError
-      [false, nil]
+    def discover_public_entries
+      @public_constant_names =
+        constants(false).map(&:to_s) - @import_constant_names
+      @public_method_entries = top_level_methods.except(*@import_method_names)
     end
 
-    def lookup_method_entry(name)
-      [true, eval(name)]
-    rescue NameError, NoMethodError
-      begin
-        [true, __send__(name)]
-      rescue NoMethodError
-        [false, nil]
-      end
+    def top_level_methods
+      eval(
+        'Object.private_instance_methods(false).to_h { |name| [name.to_s, method(name)] }',
+      )
     end
   end
 end

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,23 @@
+# 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 Declaration that breaks the rules: a name exported twice,
+  # `export_default` called twice, or both forms in one Entrypoint.
+  class ExportError < Error
+  end
+
+  # Raised when Carton cannot find the bundle file for `setup_bundle`.
+  class GemfileNotFound < Error
+  end
+end