boxwerk 0.1.0 → 0.2.0

data/lib/boxwerk/graph.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module Boxwerk
-  # Builds and validates the package dependency graph
+  # Graph builds a directed acyclic graph (DAG) of package dependencies.
+  # Validates no circular dependencies and provides topological ordering for boot sequence.
   class Graph
     attr_reader :packages, :root
 
@@ -10,102 +11,43 @@ module Boxwerk
       @packages = {}
       @root = load_package('root', root_path)
       resolve_dependencies(@root, [])
-      validate!
     end
 
-    # Returns packages in topological order (leaves first)
     def topological_order
       visited = {}
       order = []
-
-      @packages.each_value { |package| visit(package, visited, order, []) }
-
+      @packages.each_value { |pkg| visit(pkg, visited, order, []) }
       order
     end
 
     private
 
-    # Validate that the graph is acyclic
-    def validate!
-      visited = {}
-      rec_stack = {}
-
-      @packages.each_value do |package|
-        if has_cycle?(package, visited, rec_stack, [])
-          raise 'Circular dependency detected in package graph'
-        end
-      end
-
-      true
-    end
-
     def load_package(name, path)
       return @packages[name] if @packages[name]
 
-      package = Package.new(name, path)
-      @packages[name] = package
-      package
+      @packages[name] = Package.new(name, path)
     end
 
     def resolve_dependencies(package, path)
-      if path.include?(package.name)
-        cycle = (path + [package.name]).join(' -> ')
-        raise "Circular dependency detected: #{cycle}"
-      end
+      raise "Circular dependency: #{(path + [package.name]).join(' -> ')}" if path.include?(package.name)
 
       package.dependencies.each do |dep_path|
-        dep_name = File.basename(dep_path)
         full_path = File.join(@root_path, dep_path)
+        raise "Package not found: #{dep_path}" unless File.directory?(full_path)
 
-        unless File.directory?(full_path)
-          raise "Package not found: #{dep_path} (expected at #{full_path})"
-        end
-
-        dep_package = load_package(dep_name, full_path)
-        resolve_dependencies(dep_package, path + [package.name])
+        resolve_dependencies(load_package(File.basename(dep_path), full_path), path + [package.name])
       end
     end
 
-    # DFS for topological sort
     def visit(package, visited, order, path)
       return if visited[package.name]
 
-      if path.include?(package.name)
-        raise "Circular dependency: #{(path + [package.name]).join(' -> ')}"
-      end
-
       visited[package.name] = true
-
       package.dependencies.each do |dep_path|
-        dep_name = File.basename(dep_path)
-        dep_package = @packages[dep_name]
+        dep_package = @packages[File.basename(dep_path)]
         visit(dep_package, visited, order, path + [package.name]) if dep_package
       end
-
       order << package
     end
-
-    # Cycle detection
-    def has_cycle?(package, visited, rec_stack, path)
-      return false if visited[package.name]
-
-      return true if rec_stack[package.name]
-
-      visited[package.name] = true
-      rec_stack[package.name] = true
-
-      package.dependencies.each do |dep_path|
-        dep_name = File.basename(dep_path)
-        dep_package = @packages[dep_name]
-
-        if dep_package &&
-             has_cycle?(dep_package, visited, rec_stack, path + [package.name])
-          return true
-        end
-      end
-
-      rec_stack[package.name] = false
-      false
-    end
   end
 end

data/lib/boxwerk/loader.rb

@@ -1,45 +1,21 @@
 # frozen_string_literal: true
 
 module Boxwerk
-  # Loader handles the creation and initialization of isolated package boxes
+  # Loader creates isolated Ruby::Box instances for packages and wires imports.
+  # Lazily loads exports using Zeitwerk naming conventions and injects constants.
   class Loader
     class << self
-      # Boot all packages in topological order
-      # @param graph [Boxwerk::Graph] The dependency graph
-      # @param registry [Boxwerk::Registry] The registry instance
       def boot_all(graph, registry)
         order = graph.topological_order
 
         order.each { |package| boot(package, graph, registry) }
       end
 
-      # Boot a single package
-      # @param package [Boxwerk::Package] The package to boot
-      # @param graph [Boxwerk::Graph] The dependency graph
-      # @param registry [Boxwerk::Registry] The registry instance
       def boot(package, graph, registry)
         return package if package.booted?
 
-        # Check if RUBY_BOX environment variable is set
-        unless ENV['RUBY_BOX'] == '1'
-          raise 'Boxwerk requires RUBY_BOX=1 environment variable to enable Ruby::Box support'
-        end
-
-        # Check if we have Ruby::Box support
-        unless defined?(Ruby::Box)
-          raise 'Boxwerk requires Ruby 4.0+ with Ruby::Box support'
-        end
-
-        # All packages (including root) get their own isolated boxes
-        box = Ruby::Box.new
-
-        # Store the box reference first so it's available during wiring
-        package.box = box
-
-        # Wire imports based on configuration (exports loaded lazily on-demand)
-        wire_imports(box, package, graph)
-
-        # Register in the registry
+        package.box = Ruby::Box.new
+        wire_imports(package.box, package, graph)
         registry.register(package.name, package)
 
         package
@@ -47,10 +23,6 @@ module Boxwerk
 
       private
 
-      # Load a specific exported constant from package's lib directory using Zeitwerk conventions
-      # This enforces strict isolation - only requested exports are loaded, lazily
-      # @param package [Boxwerk::Package] The package
-      # @param const_name [String] The constant name to load
       def load_export(package, const_name)
         # Skip if already loaded (cached)
         return if package.loaded_exports.key?(const_name)
@@ -58,91 +30,33 @@ module Boxwerk
         lib_path = File.join(package.path, 'lib')
         return unless File.directory?(lib_path)
 
-        # Find the file path for this constant using Zeitwerk conventions
         file_path = find_file_for_constant(lib_path, const_name)
-
         unless file_path
-          raise "Cannot find file for exported constant '#{const_name}' in package '#{package.name}' at #{lib_path}"
+          raise "Cannot find file for exported constant '#{const_name}' in package '#{package.name}'"
         end
 
-        # Load the file in the package's box
         package.box.require(file_path)
-
-        # Cache the mapping AFTER successful load
         package.loaded_exports[const_name] = file_path
       end
 
-      # Load only exported constants from package's lib directory using Zeitwerk conventions
-      # @param box [Ruby::Box] The box instance
-      # @param package [Boxwerk::Package] The package
-      def load_exports(box, package)
-        lib_path = File.join(package.path, 'lib')
-        return unless File.directory?(lib_path)
-
-        # Find all files that might contain exported constants and map them to constants
-        files_to_load = {}  # file_path => [const_name, ...]
-
-        package.exports.each do |const_name|
-          # Skip if already loaded (cached)
-          next if package.loaded_exports.key?(const_name)
-
-          # Find the file path for this constant using Zeitwerk conventions
-          file_path = find_file_for_constant(lib_path, const_name)
-
-          unless file_path
-            raise "Cannot find file for exported constant '#{const_name}' in package '#{package.name}' at #{lib_path}"
-          end
-
-          files_to_load[file_path] ||= []
-          files_to_load[file_path] << const_name
-        end
-
-        # Load only the discovered files in the box (strict mode - no fallback)
-        files_to_load.keys.sort.each do |file|
-          box.require(file)
-
-          # Cache the mapping AFTER successful load
-          files_to_load[file].each do |const_name|
-            package.loaded_exports[const_name] = file
-          end
-        end
-      end
-
-      # Find the file that should define a constant using Zeitwerk's conventions
-      # Handles nested constants: Foo::Bar can be in lib/foo/bar.rb OR lib/foo.rb
-      # @param lib_path [String] The lib directory path
-      # @param const_name [String] The constant name (can include ::)
-      # @return [String, nil] The file path or nil if not found
       def find_file_for_constant(lib_path, const_name)
-        # For nested constants like Foo::Bar, try the nested path first
         if const_name.include?('::')
-          # Try conventional nested path: Foo::Bar -> lib/foo/bar.rb
           nested_path = File.join(lib_path, "#{underscore(const_name)}.rb")
           return nested_path if File.exist?(nested_path)
 
-          # Fall back to parent path: Foo::Bar -> lib/foo.rb
-          # The parent file might define the nested constant
           parts = const_name.split('::')
           parent_name = parts[0..-2].join('::')
-          parent_file = if parent_name.empty?
-            # Top-level nested constant (shouldn't happen, but handle it)
-            File.join(lib_path, "#{underscore(parts[-1])}.rb")
-          else
-            File.join(lib_path, "#{underscore(parent_name)}.rb")
-          end
+          parent_file = File.join(lib_path, "#{underscore(parent_name)}.rb")
           return parent_file if File.exist?(parent_file)
         else
-          # For top-level constants, try conventional path
-          conventional_path = File.join(lib_path, "#{underscore(const_name)}.rb")
+          conventional_path =
+            File.join(lib_path, "#{underscore(const_name)}.rb")
           return conventional_path if File.exist?(conventional_path)
         end
 
         nil
       end
 
-      # Convert CamelCase to snake_case (Zeitwerk-compatible)
-      # @param string [String] The string to convert
-      # @return [String] The underscored string
       def underscore(string)
         string
           .gsub(/::/, '/')
@@ -152,28 +66,22 @@ module Boxwerk
           .downcase
       end
 
-      # Wire imports according to YAML configuration (list format)
-      # @param box [Ruby::Box] The box instance
-      # @param package [Boxwerk::Package] The package being booted
-      # @param graph [Boxwerk::Graph] The dependency graph
       def wire_imports(box, package, graph)
         package.imports.each do |import_item|
-          # Normalize: String or Hash
-          if import_item.is_a?(String)
-            path = import_item
-            config = nil
-          else
-            path = import_item.keys.first
-            config = import_item.values.first
-          end
-
+          path, config =
+            (
+              if import_item.is_a?(String)
+                [import_item, nil]
+              else
+                [import_item.keys.first, import_item.values.first]
+              end
+            )
           dep_name = File.basename(path)
           dependency = graph.packages[dep_name]
 
           unless dependency
             raise "Cannot resolve dependency '#{path}' for package '#{package.name}'"
           end
-
           unless dependency.booted?
             raise "Dependency '#{dep_name}' not booted yet"
           end
@@ -182,93 +90,57 @@ module Boxwerk
         end
       end
 
-      # Execute the appropriate wiring strategy based on config type
-      # @param box [Ruby::Box] The box instance
-      # @param package [Boxwerk::Package] The current package being wired
-      # @param path [String] The dependency path
-      # @param config [nil, String, Array, Hash] The import configuration
-      # @param dependency [Boxwerk::Package] The dependency package
       def wire_import_strategy(box, package, path, config, dependency)
         case config
         when nil
-          # Strategy 1: Default Namespace ("packages/billing" -> "Billing")
-          name = camelize(File.basename(path))
-          create_namespace(package, name, dependency)
+          create_namespace(package, camelize(File.basename(path)), dependency)
         when String
-          # Strategy 2: Aliased Namespace ("packages/identity": "Auth")
           create_namespace(package, config, dependency)
         when Array
-          # Strategy 3: Selective List (["Log", "Metrics"])
-          config.each do |const_name|
-            value = get_constant(dependency, const_name)
-            set_constant(package, const_name, value)
+          config.each do |name|
+            set_constant(package, name, get_constant(dependency, name))
           end
         when Hash
-          # Strategy 4: Selective Rename ({Invoice: "Bill"})
-          config.each do |remote_name, local_alias|
-            value = get_constant(dependency, remote_name)
-            set_constant(package, local_alias, value)
+          config.each do |remote, local|
+            set_constant(package, local, get_constant(dependency, remote))
           end
         end
       end
 
-      # Create a namespace module and populate with all exports
-      # Or import directly if single export (optimization)
-      # @param package [Boxwerk::Package] The current package
-      # @param namespace_name [String] The module name to create
-      # @param dependency [Boxwerk::Package] The dependency package
       def create_namespace(package, namespace_name, dependency)
         if dependency.exports.size == 1
-          # Single export optimization: import directly
-          value = get_constant(dependency, dependency.exports.first)
-          set_constant(package, namespace_name, value)
+          set_constant(
+            package,
+            namespace_name,
+            get_constant(dependency, dependency.exports.first),
+          )
         else
-          # Multiple exports: create namespace module
           mod = create_module(package.box, namespace_name)
-          dependency.exports.each do |export_name|
-            value = get_constant(dependency, export_name)
-            mod.const_set(export_name.to_sym, value)
+          dependency.exports.each do |name|
+            mod.const_set(name.to_sym, get_constant(dependency, name))
           end
         end
       end
 
-      # Get a constant from a package's box, loading it lazily if needed
-      # @param package [Boxwerk::Package] The package to get the constant from
-      # @param name [String] The constant name
-      # @return [Object] The constant value
       def get_constant(package, name)
-        # Load the export lazily
         load_export(package, name)
-
         package.box.const_get(name.to_sym)
       end
 
-      # Set a constant in a package's box
-      # @param package [Boxwerk::Package] The package to set the constant in
-      # @param name [String] The constant name
-      # @param value [Object] The constant value
       def set_constant(package, name, value)
         package.box.const_set(name.to_sym, value)
       end
 
-      # Create a module in the box
       def create_module(box, name)
-        unless box.const_defined?(name.to_sym, false)
-          mod = Module.new
-          box.const_set(name.to_sym, mod)
-          mod
-        else
-          box.const_get(name.to_sym)
+        if box.const_defined?(name.to_sym, false)
+          return box.const_get(name.to_sym)
         end
-      end
 
-      # Set a constant within a module in the box
-      def set_const_in_module(box, module_name, const_name, value)
-        mod = box.const_get(module_name.to_sym, false)
-        mod.const_set(const_name.to_sym, value)
+        mod = Module.new
+        box.const_set(name.to_sym, mod)
+        mod
       end
 
-      # Simple camelization (underscore to CamelCase)
       def camelize(string)
         string.split('_').map(&:capitalize).join
       end

data/lib/boxwerk/package.rb

@@ -3,9 +3,11 @@
 require 'yaml'
 
 module Boxwerk
-  # Represents a package loaded from package.yml
+  # Package represents a single package loaded from package.yml.
+  # Tracks exports, imports, dependencies, and the isolated Ruby::Box instance.
   class Package
-    attr_reader :name, :path, :exports, :imports, :box, :loaded_exports
+    attr_reader :name, :path, :exports, :imports, :loaded_exports
+    attr_accessor :box
 
     def initialize(name, path)
       @name = name
@@ -22,18 +24,8 @@ module Boxwerk
       !@box.nil?
     end
 
-    def box=(box_instance)
-      @box = box_instance
-    end
-
     def dependencies
-      @imports.map do |item|
-        if item.is_a?(String)
-          item
-        else
-          item.keys.first
-        end
-      end
+      @imports.map { |item| item.is_a?(String) ? item : item.keys.first }
     end
 
     private
@@ -43,7 +35,6 @@ module Boxwerk
       return unless File.exist?(config_path)
 
       config = YAML.load_file(config_path)
-
       @exports = config['exports'] || []
       @imports = config['imports'] || []
     end

data/lib/boxwerk/registry.rb

@@ -1,35 +1,24 @@
 # frozen_string_literal: true
 
 module Boxwerk
-  # Registry for tracking booted package instances
-  # This allows packages to be booted once and reused
+  # Registry tracks booted package instances to ensure each package boots only once.
   class Registry
     def initialize
       @registry = {}
     end
 
-    # Register a booted package
-    # @param name [Symbol] Package name
-    # @param instance [Object] The booted package instance
     def register(name, instance)
       @registry[name] = instance
     end
 
-    # Retrieve a booted package
-    # @param name [Symbol] Package name
-    # @return [Object, nil] The package instance or nil
     def get(name)
       @registry[name]
     end
 
-    # Check if a package is registered
-    # @param name [Symbol] Package name
-    # @return [Boolean]
     def registered?(name)
       @registry.key?(name)
     end
 
-    # Clear the registry (useful for testing)
     def clear!
       @registry = {}
     end

data/lib/boxwerk/setup.rb

@@ -1,48 +1,31 @@
 # frozen_string_literal: true
 
 module Boxwerk
-  # Setup orchestrates the Boxwerk boot process
+  # Setup finds the root package, builds the dependency graph, and boots all packages.
+  # Orchestrates the entire Boxwerk initialization process.
   module Setup
     class << self
-      # Main entry point for setup
-      # @param start_dir [String] Directory to start searching for package.yml
-      # @return [Boxwerk::Graph] The loaded and validated graph
       def run!(start_dir: Dir.pwd)
-        # Find the root package.yml
         root_path = find_package_yml(start_dir)
-        unless root_path
-          raise 'Cannot find package.yml in current directory or ancestors'
-        end
+        raise 'Cannot find package.yml in current directory or ancestors' unless root_path
 
-        # Build and validate dependency graph (happens automatically in constructor)
         graph = Boxwerk::Graph.new(root_path)
-
-        # Create a registry instance for tracking booted packages
         registry = Boxwerk::Registry.new
-
-        # Boot all packages in topological order (all in isolated boxes)
         Boxwerk::Loader.boot_all(graph, registry)
 
-        # Store graph for introspection
         @graph = graph
         @booted = true
-
         graph
       end
 
-      # Returns the loaded graph (for introspection)
-      # @return [Boxwerk::Graph, nil]
       def graph
         @graph
       end
 
-      # Check if Boxwerk has been booted
-      # @return [Boolean]
       def booted?
         @booted || false
       end
 
-      # Reset the setup state (useful for testing)
       def reset!
         @graph = nil
         @booted = false
@@ -50,17 +33,13 @@ module Boxwerk
 
       private
 
-      # Find package.yml by searching up the directory tree
-      # @param start_dir [String] Directory to start searching from
-      # @return [String, nil] Path to directory containing package.yml, or nil
       def find_package_yml(start_dir)
         current = File.expand_path(start_dir)
         loop do
-          package_yml = File.join(current, 'package.yml')
-          return current if File.exist?(package_yml)
+          return current if File.exist?(File.join(current, 'package.yml'))
 
           parent = File.dirname(current)
-          break if parent == current # reached filesystem root
+          break if parent == current
 
           current = parent
         end

data/lib/boxwerk/version.rb

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

data/lib/boxwerk.rb

@@ -7,8 +7,3 @@ require_relative 'boxwerk/package'
 require_relative 'boxwerk/registry'
 require_relative 'boxwerk/setup'
 require_relative 'boxwerk/version'
-
-module Boxwerk
-  class Error < StandardError
-  end
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: boxwerk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - David Cristofaro
@@ -23,10 +23,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.16'
-description: Boxwerk provides strict package isolation for Ruby applications using
-  Ruby 4.0+ Box. It is used to organize code into packages with explicit dependency
-  graphs and strict access to constants between packages. It is inspired by Packwerk,
-  a static package system.
+description: 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. Inspired by Packwerk.
 email:
 - david@dtcristo.com
 executables:
@@ -38,17 +37,6 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- example/Gemfile
-- example/Gemfile.lock
-- example/README.md
-- example/app.rb
-- example/package.yml
-- example/packages/finance/lib/invoice.rb
-- example/packages/finance/lib/tax_calculator.rb
-- example/packages/finance/package.yml
-- example/packages/util/lib/calculator.rb
-- example/packages/util/lib/geometry.rb
-- example/packages/util/package.yml
 - exe/boxwerk
 - lib/boxwerk.rb
 - lib/boxwerk/cli.rb
@@ -58,7 +46,6 @@ files:
 - lib/boxwerk/registry.rb
 - lib/boxwerk/setup.rb
 - lib/boxwerk/version.rb
-- sig/boxwerk.rbs
 homepage: https://github.com/dtcristo/boxwerk
 licenses:
 - MIT

data/example/Gemfile

@@ -1,6 +0,0 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-
-gem 'boxwerk', path: '..'
-gem 'money'