boxwerk 0.1.0

data/lib/boxwerk/loader.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module Boxwerk
+  # Loader handles the creation and initialization of isolated package boxes
+  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
+        registry.register(package.name, package)
+
+        package
+      end
+
+      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)
+
+        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}"
+        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
+          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")
+          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(/::/, '/')
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .tr('-', '_')
+          .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
+
+          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
+
+          wire_import_strategy(box, package, path, config, dependency)
+        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)
+        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)
+          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)
+          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)
+        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)
+          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)
+        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)
+      end
+
+      # Simple camelization (underscore to CamelCase)
+      def camelize(string)
+        string.split('_').map(&:capitalize).join
+      end
+    end
+  end
+end

data/lib/boxwerk/package.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Boxwerk
+  # Represents a package loaded from package.yml
+  class Package
+    attr_reader :name, :path, :exports, :imports, :box, :loaded_exports
+
+    def initialize(name, path)
+      @name = name
+      @path = path
+      @box = nil
+      @exports = []
+      @imports = []
+      @loaded_exports = {}
+
+      load_config
+    end
+
+    def booted?
+      !@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
+    end
+
+    private
+
+    def load_config
+      config_path = File.join(@path, 'package.yml')
+      return unless File.exist?(config_path)
+
+      config = YAML.load_file(config_path)
+
+      @exports = config['exports'] || []
+      @imports = config['imports'] || []
+    end
+  end
+end

data/lib/boxwerk/registry.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Boxwerk
+  # Registry for tracking booted package instances
+  # This allows packages to be booted once and reused
+  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
+  end
+end

data/lib/boxwerk/setup.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Boxwerk
+  # Setup orchestrates the Boxwerk boot 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
+
+        # 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
+      end
+
+      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)
+
+          parent = File.dirname(current)
+          break if parent == current # reached filesystem root
+
+          current = parent
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/boxwerk/version.rb

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

data/lib/boxwerk.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'boxwerk/cli'
+require_relative 'boxwerk/graph'
+require_relative 'boxwerk/loader'
+require_relative 'boxwerk/package'
+require_relative 'boxwerk/registry'
+require_relative 'boxwerk/setup'
+require_relative 'boxwerk/version'
+
+module Boxwerk
+  class Error < StandardError
+  end
+end

data/sig/boxwerk.rbs

@@ -0,0 +1,4 @@
+module Boxwerk
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: boxwerk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Cristofaro
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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.
+email:
+- david@dtcristo.com
+executables:
+- boxwerk
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- 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
+- lib/boxwerk/graph.rb
+- lib/boxwerk/loader.rb
+- lib/boxwerk/package.rb
+- lib/boxwerk/registry.rb
+- lib/boxwerk/setup.rb
+- lib/boxwerk/version.rb
+- sig/boxwerk.rbs
+homepage: https://github.com/dtcristo/boxwerk
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/dtcristo/boxwerk
+  source_code_uri: https://github.com/dtcristo/boxwerk
+  changelog_uri: https://github.com/dtcristo/boxwerk/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Ruby package system with Box-powered constant isolation
+test_files: []