boxwerk 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45cabb7d61d5029a494703a95c1b974f1af7ee1286001d457ea7aaf8b870496c
-  data.tar.gz: fb14ec2556787d19618ee3599685a06a06a4d1ed40a3113c47f61420f84fb202
+  metadata.gz: 6fbe46b469b3c4c08b56abcf734d26d26edf383161e3c2bc7e345c930ec4db13
+  data.tar.gz: 69b8f826fa921007beae2b32b4fa2e053f2c9109a0095a5813431cb4cc6447e8
 SHA512:
-  metadata.gz: 8e11bee2fd442bc29b537d4e7099e4380b19bed851f4f40bd42e119c35f139ee680866bd0f6189334e46652881c224559e10c6ab4dcf722c4d50c455fccdf16e
-  data.tar.gz: 0c69bf3a342d8fd502d6e64d085edfa9d1a2864b60d8f3f683addc680080f5762246f9901926c81667c40ddad82fdae7ead6e939ea3f297c0f907c983e21622f
+  metadata.gz: 48649f22d3db03be484e78dbf42234b9a1bc13b6616d20a3dae31d0ea8e7542c559d315aa572e5f1f9ffca2cbc8639cf944e95569dc4e122028ccf3a87772702
+  data.tar.gz: 1a211414af0a486e1df289b1b12f84cc51eada906bad50fa047e3d9a38ef93c51a19871593844268a8ef14ab9fd36540698cb8ca7dafd57f42e6f6dc0ab844f4

data/CHANGELOG.md

@@ -1,8 +1,31 @@
 # Changelog
 
-## [0.1.0] - 2026-01-05
+## [Unreleased]
+
+## [v0.2.0] - 2026-01-06
+
+### Changed
+- Simplified implementation (~370 lines removed)
+- Consolidated cycle detection in Graph (removed redundant methods)
+- Removed unused Loader methods
+- Streamlined all module implementations
+- Added class-level documentation to all modules
+- Simplified example application
+
+### Removed
+- Removed `Gemfile.lock` from git (library best practice)
+- Removed `sig/boxwerk.rbs` 
+- Excluded `example/` from gem package
+
+### Tests
+- Reduced test suite from 62 to 46 tests
+- Removed redundant unit tests (275 lines)
+- Maintained full integration test coverage
+
+## [v0.1.0] - 2026-01-05
 
 Initial release.
 
-[unreleased]: https://github.com/dtcristo/boxwerk/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/dtcristo/boxwerk/releases/tag/v0.1.0
+[Unreleased]: https://github.com/dtcristo/boxwerk/compare/v0.2.0...HEAD
+[v0.2.0]: https://github.com/dtcristo/boxwerk/releases/tag/v0.2.0
+[v0.1.0]: https://github.com/dtcristo/boxwerk/releases/tag/v0.1.0

data/README.md

@@ -1,24 +1,30 @@
-# Boxwerk
+<div align="center">
+  <h1>
+    📦 Boxwerk
+  </h1>
+</div>
 
-Boxwerk is a runtime package system for Ruby with strict isolation of constants using Ruby 4.0's [`Ruby::Box`](https://docs.ruby-lang.org/en/master/Ruby/Box.html). It is used to organize code into packages with explicit dependency graphs and strict access to constants between packages. It is inspired by [Packwerk](https://github.com/Shopify/packwerk), a static package system.
+Boxwerk is an **experimental** Ruby package system with Box-powered constant isolation. It is used at runtime to organize code into packages with explicit dependencies and strict constant access using [`Ruby::Box`](https://docs.ruby-lang.org/en/master/Ruby/Box.html). Inspired by [Packwerk](https://github.com/Shopify/packwerk).
 
 ## Features
 
-- **Strict Isolation**: Each package runs in its own `Ruby::Box`, preventing constants from leaking without explicit imports or exports.
-- **Explicit Dependencies**: Dependencies are declared in `package.yml` files, forming a validated DAG.
-- **Ergonomic Imports**: Flexible import strategies (namespaced, aliased, selective, renamed).
+- **Strict Isolation**: Each package runs in its own `Ruby::Box`, preventing constant leakage
+- **Explicit Dependencies**: Dependencies declared in `package.yml`, validated as a DAG
+- **Controlled Exports**: Only declared constants are accessible to importers
+- **Flexible Imports**: Multiple strategies (namespaced, aliased, selective, renamed)
+- **Lazy Loading**: Exports loaded on-demand when imported
 
-## Limtations
+## Current Limitations
 
-- There is no isolation of gems.
-- Gems are required to be eager loaded in the root box to be accessible in packages.
-- No support for reloading of constants.
-- Exported constants must follow Zeitwerk naming conventions for their source location.
+- No gem isolation—all gems are global across packages
+- No constant reloading support
+- Exported constants must follow [Zeitwerk naming conventions](https://github.com/fxn/zeitwerk#file-structure)
+- Console runs in root box, not root package box (due to IRB loading issues)
+- `Ruby::Box` itself is experimental in Ruby 4.0
 
 ## Requirements
 
-- Ruby 4.0+ with [`Ruby::Box`](https://docs.ruby-lang.org/en/master/Ruby/Box.html) support
-- `RUBY_BOX=1` environment variable must be set at process startup
+- Ruby 4.0+ with `RUBY_BOX=1` environment variable set.
 
 ## Quick Start
 
@@ -26,14 +32,15 @@ Boxwerk is a runtime package system for Ruby with strict isolation of constants
 
 ```
 my_app/
-├── Gemfile                  # Your gem dependencies
-├── package.yml              # Root package
+├── Gemfile
+├── package.yml              # Root package manifest
 ├── app.rb                   # Your application entrypoint
 └── packages/
-    └── billing/
+    └── finance/
         ├── package.yml      # Package manifest
         └── lib/
-            └── invoice.rb   # Package code
+            ├── invoice.rb        # Defines Invoice
+            └── tax_calculator.rb # Defines TaxCalculator
 ```
 
 ### 2. Define Your Gemfile
@@ -61,27 +68,6 @@ exports:
   - TaxCalculator
 ```
 
-**`packages/finance/lib/invoice.rb`:**
-```ruby
-class Invoice
-  def initialize(amount_cents)
-    # Money gem is accessible because it's in the Gemfile
-    @amount = Money.new(amount_cents, 'USD')
-  end
-
-  def total
-    @amount
-  end
-end
-```
-
-**`packages/finance/lib/tax_calculator.rb`:**
-```ruby
-class TaxCalculator
-  # ...
-end
-```
-
 ### 4. Use in Your Application
 
 **`app.rb`:**
@@ -97,40 +83,30 @@ puts invoice.total  # => #<Money fractional:10000 currency:USD>
 RUBY_BOX=1 boxwerk run app.rb
 ```
 
-Boxwerk automatically:
-1. Sets up Bundler
-2. Requires all gems from your Gemfile in the root box
-3. Loads and wires all packages
-4. Executes your script in the root package context
+Boxwerk handles Bundler setup, gem loading, package wiring, and script execution automatically.
 
-## Usage
-
-### Running Scripts
+## Example
 
-Execute a Ruby script in the root package context:
+See the [example/](example/) directory for a working multi-package application:
 
 ```bash
-boxwerk run script.rb [args...]
+cd example
+RUBY_BOX=1 boxwerk run app.rb
 ```
 
-The script has access to:
-- All gems from your Gemfile (automatically required)
-- All imports defined in the root `package.yml`
-
-### Interactive Console
+## CLI Usage
 
-TODO: This feature is currenly broken and will run IRB from the root box, not the root package as desired.
-
-Start an IRB session in the root package context:
+**Run a script:**
+```bash
+boxwerk run script.rb [args...]
+```
 
+**Interactive console** (currently runs in root box, not root package):
 ```bash
 boxwerk console [irb-args...]
 ```
 
-All imports and gems are available for interactive exploration.
-
-### Help
-
+**Help:**
 ```bash
 boxwerk help
 ```
@@ -151,211 +127,79 @@ imports:
 
 ### Exports
 
-Constants that should be visible to packages that import this one.
+Constants that should be visible to packages that import this one. Exports are lazily loaded during boot; only those actually imported by dependent packages are loaded.
 
 ### Imports
 
-Dependencies this package needs. **Note**: Dependencies are NOT transitive. If package A imports B, and B imports C, then A cannot access C unless it explicitly imports it.
+Package dependencies that are wired as new constants in the importing package's box. Default and aliased namespace imports create a module to hold the exports. **Not transitive**: if A imports B and B imports C, A cannot access C without explicitly importing it.
 
 ## Import Strategies
 
-Boxwerk supports four import strategies in `package.yml`:
-
-### 1. Default Namespace
-
-Import all exports under a module named after the package:
-
+**Default namespace** (all exports under package name):
 ```yaml
 imports:
   - packages/finance
+# Result: Finance::Invoice, Finance::TaxCalculator
 ```
 
-Result: `Finance::Invoice`, `Finance::TaxCalculator`
-
-### 2. Aliased Namespace
-
-Import under a custom module name:
-
+**Aliased namespace** (custom module name):
 ```yaml
 imports:
   - packages/finance: Billing
+# Result: Billing::Invoice, Billing::TaxCalculator
 ```
+*Note: Single exports import directly without namespace*
 
-Result: `Billing::Invoice`, `Billing::TaxCalculator`
-
-**Single Export Optimization**: If a package exports only one constant, it's imported directly (not wrapped in a module):
-
-```yaml
-# util exports only Calculator
-imports:
-  - packages/util: Calc
-```
-
-Result: `Calc` (not `Calc::Calculator`)
-
-### 3. Selective Import
-
-Import specific constants directly:
-
+**Selective import** (specific constants):
 ```yaml
 imports:
   - packages/finance:
     - Invoice
     - TaxCalculator
+# Result: Invoice, TaxCalculator (no namespace)
 ```
 
-Result: `Invoice`, `TaxCalculator` (no namespace)
-
-### 4. Selective Rename
-
-Import specific constants with custom names:
-
+**Selective rename** (custom names):
 ```yaml
 imports:
   - packages/finance:
       Invoice: Bill
       TaxCalculator: Calculator
+# Result: Bill, Calculator
 ```
 
-Result: `Bill`, `Calculator`
-
-## Gems and Packages
-
-### How Gems Work in Boxwerk
-
-When you run `boxwerk`, all gems in your `Gemfile` are:
-1. Automatically loaded via Bundler in the root box
-2. Accessible globally in all package boxes (gems are not isolated)
+## Gem Handling
 
-This means:
-- You can use any gem from your Gemfile in any package.
-- Gems don't need to be declared in `package.yml`.
-- You do not `require` gems manually.
-
-### Isolation Model
-
-- **Root Box**: The box where Ruby bootstraps and all builtin classes/modules are defined. In Boxwerk, the root box performs all setup operations (Bundler setup, gem loading, dependency graph building, package box creation, and import wiring).
-- **Main Box**: The first user box created automatically by Ruby (copied from root box). In Boxwerk, it only runs the `exe/boxwerk` executable file, which then calls into the root box to execute the setup. The main box has no other purpose.
-- **Package Boxes**: Each package (including root package) runs in its own isolated `Ruby::Box` (created by copying from root box after gems are loaded).
-- **Box Inheritance**: All boxes are created via copy-on-write from the root box, inheriting builtin classes and loaded gems.
-- **Gems are Global**: All gems from Gemfile are accessible in all boxes (loaded in root box before package boxes are created).
-- **Package Exports are Isolated**: Only explicit imports from packages are accessible.
-- **No Transitive Access**: Packages can only see their explicit imports.
-
-For more details on how Ruby::Box works, see the [official Ruby::Box documentation](https://docs.ruby-lang.org/en/master/Ruby/Box.html).
+All gems in your `Gemfile` are:
+- Automatically loaded in the root box via Bundler
+- Accessible globally in all packages (no gem isolation)
+- No manual `require` or `package.yml` declaration needed
 
 ## Known Issues
 
-These issues are related to the current state of Ruby::Box in Ruby 4.0+. See the [Ruby::Box documentation](https://docs.ruby-lang.org/en/master/Ruby/Box.html) for known issues with the feature itself.
-
-### Gem Requiring in Boxes
-
-Requiring any gem from within a box (after boot) currently crashes the Ruby VM. This is likely an issue with Ruby::Box itself. As a workaround, Boxwerk automatically requires all gems from the Gemfile in the root box before creating package boxes, so gems are already loaded and accessible everywhere.
-
-### Console Context
-
-The console does not correctly run in the root package box—it runs in the context of the root box instead. It should run in the root package box. However, if we attempt to `require 'irb'` in the root package box, the Ruby VM crashes due to the gem requiring issue described above.
-
-### IRB Autocomplete
+Related to Ruby::Box in Ruby 4.0+. See [Ruby::Box documentation](https://docs.ruby-lang.org/en/master/Ruby/Box.html) for details.
 
-Autocomplete is disabled for the console/IRB by default. When enabled, the Ruby VM crashes as soon as any key is pressed. This appears to be an issue with Ruby::Box and IRB's autocomplete feature interacting poorly.
+- **Gem requiring**: Crashes VM when requiring gems inside boxes after boot (workaround: gems pre-loaded in root box)
+- **Console context**: Runs in root box instead of root package box due to IRB loading limitation
+- **IRB autocomplete**: Disabled by since it currently crashes VMpe
 
 ## Architecture
 
-### Boot Process
-
-1. Setup Bundler and require all gems in the root box
-2. Find root `package.yml` (searches up from current directory)
-3. Build dependency graph from package manifests
-4. Validate dependency graph (no circular dependencies)
-5. Boot packages in topological order
-6. Wire imports into each package box
-7. Execute command in root package context
-
-### Internal Components
-
-Boxwerk consists of several internal components that work together to provide package isolation:
-
-#### `Boxwerk::CLI`
-
-The command-line interface handler that:
-- Parses commands (`run`, `console`, `help`)
-- Validates the Ruby environment (checks for `RUBY_BOX=1` and Ruby::Box support)
-- Delegates to `Boxwerk::Setup` for the boot process
-- Executes the requested command in the root package's box context
-
-#### `Boxwerk::Setup`
-
-The setup orchestrator that:
-- Searches up the directory tree to find the root `package.yml`
-- Creates a `Boxwerk::Graph` instance to build and validate the dependency graph
-- Creates a `Boxwerk::Registry` instance to track booted packages
-- Calls `Boxwerk::Loader.boot_all` to boot all packages in topological order
-- Returns the loaded graph for introspection
-
-#### `Boxwerk::Graph`
-
-The dependency graph builder that:
-- Parses the root `package.yml` and recursively discovers all package dependencies
-- Builds a directed acyclic graph (DAG) of package relationships
-- Validates that there are no circular dependencies
-- Performs topological sorting to determine boot order (dependencies before consumers)
-- Provides access to all packages in the graph
-
-#### `Boxwerk::Package`
-
-The package manifest parser that:
-- Represents a single package with its configuration
-- Parses `package.yml` files to extract exports and imports
-- Normalizes the polymorphic import syntax (String, Array, Hash)
-- Stores the package path, name, exports, imports, and box reference
-- Tracks which exports have been loaded via `loaded_exports` hash (export name → file path)
-- Tracks whether the package has been booted
-
-#### `Boxwerk::Loader`
-
-The package loader that:
-- Creates a new `Ruby::Box` for each package (including the root package)
-- Loads exported constants lazily on-demand when they are imported by other packages
-- Uses Zeitwerk naming conventions to discover file locations for exported constants
-- Caches loaded exports in `package.loaded_exports` to avoid redundant file loading
-- Wires imports by injecting constants from dependency boxes into consumer boxes
-- Implements all four import strategies (default namespace, aliased namespace, selective import, selective rename)
-- Handles the single-export optimization for namespace imports
-- Registers each booted package in the registry
-- Only loads files that define exported constants, never loading non-exported code
-
-#### `Boxwerk::Registry`
-
-The package registry that:
-- Tracks all booted package instances
-- Allows packages to be retrieved by name during the wiring phase
-- Ensures each package is only booted once
-- Provides a clean interface for package lookup
-
-## Example
-
-See the [example/](example/) directory for a complete working example with:
-
-- Multi-package application
-- Gem usage
-- Transitive dependency demonstration
-- Isolation verification
-- Console usage examples
-
-Run it with:
-
-```bash
-cd example
-RUBY_BOX=1 boxwerk run app.rb
-```
-
-Or explore interactively:
-
-```bash
-cd example
-RUBY_BOX=1 boxwerk console
-```
+**Boot process:**
+1. Setup Bundler and require all gems in root box
+2. Find root `package.yml` by searching up from current directory
+3. Build and validate dependency graph (DAG)
+4. Boot packages in topological order, creating isolated boxes
+5. Wire imports by lazily loading exports and injecting constants
+6. Execute command in root package context
+
+**Components:**
+- **CLI**: Parses commands, validates environment, delegates to Setup
+- **Setup**: Finds root package, builds graph, creates registry, boots packages
+- **Graph**: Builds DAG, validates no cycles, performs topological sort
+- **Package**: Parses `package.yml`, tracks exports/imports/box
+- **Loader**: Creates boxes, loads exports lazily (Zeitwerk conventions), wires imports
+- **Registry**: Tracks booted packages, ensures single boot per package
 
 ## Development
 

data/exe/boxwerk

@@ -1,28 +1,20 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Boxwerk CLI
-# Usage: boxwerk <command> [args...]
-
-# Check if Ruby::Box is available and enabled
 unless ENV['RUBY_BOX'] == '1'
   puts "Error: Boxwerk requires Ruby::Box to be enabled"
   puts "Please set RUBY_BOX=1 environment variable"
   exit 1
 end
 
-# Verify Ruby::Box is actually available in this Ruby version
 unless defined?(Ruby::Box)
   puts "Error: Ruby::Box is not available in this Ruby version"
   puts "Boxwerk requires Ruby 4.0 or later with Box support"
   exit 1
 end
 
-# Setup Bundler, require any gems and run Boxwerk - all in the root box
 Ruby::Box.root.eval(<<~RUBY)
   require 'bundler/setup'
-  # Application gems need to be required in the root box to be accessible in package boxes
   Bundler.require
-  # Run the CLI to handle the invocation
   Boxwerk::CLI.run(ARGV)
 RUBY

data/lib/boxwerk/cli.rb

@@ -1,20 +1,17 @@
 # frozen_string_literal: true
 
 module Boxwerk
-  # CLI handles command-line execution of Boxwerk applications
+  # CLI parses commands and delegates to Setup for package management.
+  # Handles run, console, and help commands.
   module CLI
     class << self
-      # Main entry point for CLI
-      # @param argv [Array<String>] Command line arguments
       def run(argv)
         if argv.empty?
           print_usage
           exit 1
         end
 
-        command = argv[0]
-
-        case command
+        case argv[0]
         when 'run'
           run_command(argv[1..-1])
         when 'console'
@@ -23,7 +20,7 @@ module Boxwerk
           print_usage
           exit 0
         else
-          puts "Error: Unknown command '#{command}'"
+          puts "Error: Unknown command '#{argv[0]}'"
           puts ''
           print_usage
           exit 1
@@ -41,8 +38,6 @@ module Boxwerk
         puts '  run <script.rb> [args...]    Run a script in the root package context'
         puts '  console [irb-args...]        Start an IRB console in the root package context'
         puts '  help                         Show this help message'
-        puts ''
-        puts 'All packages are loaded and wired before the command executes.'
       end
 
       def run_command(args)
@@ -54,50 +49,31 @@ module Boxwerk
         end
 
         script_path = args[0]
-        script_args = args[1..-1] || []
-
-        # Verify script exists
         unless File.exist?(script_path)
           puts "Error: Script not found: #{script_path}"
           exit 1
         end
 
-        # Perform Boxwerk setup (find package.yml, build graph, boot packages)
         graph = perform_setup
-
-        # Execute the script in the root package's box
-        root_package = graph.root
-        execute_in_box(root_package.box, script_path, script_args)
+        execute_in_box(graph.root.box, script_path, args[1..-1] || [])
       end
 
       def console_command(args)
-        # Require IRB while we're still in root box context
         require 'irb'
-
-        # Perform Boxwerk setup
         graph = perform_setup
-
-        # Start IRB in the root package's box with provided args
-        root_package = graph.root
-        start_console_in_box(root_package.box, args)
+        start_console_in_box(graph.root.box, args)
       end
 
       def perform_setup
-        begin
-          Boxwerk::Setup.run!(start_dir: Dir.pwd)
-        rescue => e
-          puts "Error: #{e.message}"
-          exit 1
-        end
+        Boxwerk::Setup.run!(start_dir: Dir.pwd)
+      rescue => e
+        puts "Error: #{e.message}"
+        exit 1
       end
 
       def execute_in_box(box, script_path, script_args)
-        # Set ARGV for the script using eval
         box.eval("ARGV.replace(#{script_args.inspect})")
-
-        # Run the script in the isolated box
-        absolute_script_path = File.expand_path(script_path)
-        box.require(absolute_script_path)
+        box.require(File.expand_path(script_path))
       end
 
       def start_console_in_box(box, irb_args = [])
@@ -112,16 +88,8 @@ module Boxwerk
         puts '=' * 70
         puts ''
 
-        # Start IRB in the box context.
-        # TODO: This is currently broken. IRB runs the in the root box context.
-        # This should be fixed by calling `require 'irb'` inside the box, but
-        # that currently crashes the VM.
-        # Set ARGV to the provided IRB args so they can be processed by IRB.
-        # Always add --noautocomplete to disable autocomplete (currently broken with Ruby::Box)
-        # TODO: Enable autocomplete when it's not broken.
-        irb_args_with_noautocomplete = ['--noautocomplete'] + irb_args
         box.eval(<<~RUBY)
-          ARGV.replace(#{irb_args_with_noautocomplete.inspect})
+          ARGV.replace(#{(['--noautocomplete'] + irb_args).inspect})
           IRB.start
         RUBY
       end