boxwerk 0.1.0 → 0.3.0

data/lib/boxwerk/setup.rb

@@ -1,70 +1,157 @@
 # 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
+      def run(start_dir: Dir.pwd, packages: nil, config: {})
+        root_path = find_root(start_dir)
+
+        resolver = Boxwerk::PackageResolver.new(root_path, config_overrides: config)
+        config = resolver.boxwerk_config
+        eager_load_global = config.fetch('eager_load_global', true)
+        eager_load_packages = config.fetch('eager_load_packages', false)
 
-        # Build and validate dependency graph (happens automatically in constructor)
-        graph = Boxwerk::Graph.new(root_path)
+        # Create GlobalContext and expose it as Boxwerk.global before boot.rb runs
+        global_context = GlobalContext.new(root_path)
+        root_box = Ruby::Box.root
+        root_box.__send__(:remove_const, :BOXWERK_GLOBAL) if root_box.const_defined?(:BOXWERK_GLOBAL, false)
+        root_box.const_set(:BOXWERK_GLOBAL, global_context)
 
-        # Create a registry instance for tracking booted packages
-        registry = Boxwerk::Registry.new
+        # Run global boot in root box (after gems, before package boxes).
+        run_global_boot(root_path, eager_load: eager_load_global, global_context: global_context)
 
-        # Boot all packages in topological order (all in isolated boxes)
-        Boxwerk::Loader.boot_all(graph, registry)
+        # Eager-load all Zeitwerk-managed constants in root box so child
+        # boxes inherit fully resolved constants (not pending autoloads).
+        eager_load_zeitwerk if eager_load_global
+
+        @box_manager = Boxwerk::BoxManager.new(root_path)
+        if packages
+          packages.each do |pkg|
+            @box_manager.boot_package(
+              pkg,
+              resolver,
+              eager_load_packages: eager_load_packages,
+            )
+          end
+        else
+          @box_manager.boot_all(
+            resolver,
+            eager_load_packages: eager_load_packages,
+          )
+        end
 
-        # Store graph for introspection
-        @graph = graph
+        check_gem_conflicts(@box_manager.gem_resolver, resolver)
+
+        @resolver = resolver
         @booted = true
 
-        graph
+        { resolver: resolver, box_manager: @box_manager, root_path: root_path }
+      end
+
+      def resolver
+        @resolver
       end
 
-      # Returns the loaded graph (for introspection)
-      # @return [Boxwerk::Graph, nil]
-      def graph
-        @graph
+      def box_manager
+        @box_manager
       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
+      def root_box
+        return nil unless @box_manager && @resolver&.root
+
+        @box_manager.boxes[@resolver.root.name]
+      end
+
+      def reset
+        @resolver = nil
+        @box_manager = nil
         @booted = false
+        if defined?(Ruby::Box)
+          root_box = Ruby::Box.root
+          root_box.__send__(:remove_const, :BOXWERK_GLOBAL) if root_box.const_defined?(:BOXWERK_GLOBAL, false)
+        end
       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)
+      # Finds the project root directory. Walks up the directory tree
+      # looking for boxwerk.yml or package.yml. Falls back to start_dir
+      # if neither is found (implicit root).
+      def find_root(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, 'boxwerk.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
-        nil
+
+        # Fall back to CWD as implicit root
+        File.expand_path(start_dir)
+      end
+
+      # Runs the optional global boot in the root box. The global/
+      # directory is autoloaded and global/boot.rb is required in the root
+      # box. These run after global gems are loaded but before package
+      # boxes are created, so definitions here are inherited by all boxes.
+      #
+      # Root-level boot.rb is NOT handled here — it runs in the root
+      # package box via BoxManager (like any other package boot.rb).
+      def run_global_boot(root_path, eager_load: true, global_context: nil)
+        root_box = Ruby::Box.root
+        global_dir = File.join(root_path, 'global')
+        global_boot = File.join(global_dir, 'boot.rb')
+        global_entries = nil
+
+        # Always register lazy autoloads for global/ dir so constants are
+        # accessible in boot.rb (autoload fires on access in root box context).
+        # This works regardless of eager_load_global so global constants can
+        # be used in boot.rb even when eager loading is disabled.
+        if File.directory?(global_dir)
+          global_context&.__send__(:record_scanned_dir, 'global/')
+          entries = ZeitwerkScanner.scan(global_dir)
+          global_entries = entries.reject { |e| e.file == global_boot }
+          ZeitwerkScanner.register_autoloads(root_box, global_entries) if global_entries.any?
+        end
+
+        # Run global/boot.rb in root box (always, regardless of eager_load)
+        root_box.require(global_boot) if File.exist?(global_boot)
+
+        # After boot.rb, register lazy autoloads for any dirs added via
+        # Boxwerk.global.autoloader.push_dir during boot.
+        global_context&.autoloader&.setup
+
+        # Eager-load AFTER boot.rb so boot scripts run first.
+        if eager_load
+          global_entries&.each { |e| root_box.require(e.file) if e.file }
+          global_context&.autoloader&.__send__(:eager_load!)
+        end
+      end
+
+      def check_gem_conflicts(gem_resolver, package_resolver)
+        conflicts = gem_resolver.check_conflicts(package_resolver)
+        conflicts.each do |c|
+          warn "Boxwerk: gem '#{c[:gem_name]}' is #{c[:package_version]} in #{c[:package]} " \
+                 "but #{c[:global_version]} in global gems — both versions will be loaded into memory"
+        end
+      end
+
+      # Eager-load all Zeitwerk-managed constants (gem autoloads) in the root
+      # box. Child boxes created via Ruby::Box.new inherit a snapshot of the
+      # root box's constants. Zeitwerk autoloads are lazy — without eager
+      # loading, child boxes inherit pending autoload entries that may not
+      # resolve correctly across box boundaries.
+      def eager_load_zeitwerk
+        Ruby::Box.root.eval(<<~RUBY)
+          Zeitwerk::Loader.eager_load_all if defined?(Zeitwerk)
+        RUBY
       end
     end
   end

data/lib/boxwerk/version.rb

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

data/lib/boxwerk/zeitwerk_scanner.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+
+module Boxwerk
+  # Uses Zeitwerk's file system scanner and inflector to discover constants
+  # in a directory. Zeitwerk's autoload registration cannot be used directly
+  # inside Ruby::Box (autoloads register in the box where the code was
+  # defined, not where it's called), so we only use Zeitwerk for:
+  #
+  #   - File discovery (respecting Zeitwerk conventions: hidden dirs, etc.)
+  #   - Inflection (file names → constant names)
+  #
+  # The actual autoload registration is done by BoxManager using box.eval.
+  module ZeitwerkScanner
+    Entry = Data.define(:type, :cname, :full_path, :file, :parent, :dir)
+
+    # Scans a directory and returns an array of Entry structs describing
+    # the constants and namespaces found. Uses a temporary Zeitwerk::Loader
+    # for its FileSystem scanner and Inflector.
+    def self.scan(dir)
+      loader = Zeitwerk::Loader.new
+      loader.push_dir(dir)
+      inflector = loader.inflector
+      fs = Zeitwerk::Loader::FileSystem.new(loader)
+
+      entries = []
+      scan_dir(fs, inflector, dir, '', entries)
+      entries
+    end
+
+    # Registers autoloads in a Ruby::Box based on scan results.
+    # Implicit namespaces become Module.new, explicit namespaces are
+    # eagerly loaded so child autoloads can attach to them.
+    def self.register_autoloads(box, entries)
+      namespaces = entries.select { |e| e.type == :namespace }
+      files = entries.select { |e| e.type == :file }
+
+      # Deduplicate namespaces: when both lib/ and public/ contribute a
+      # namespace with the same full_path, prefer the explicit one (has a
+      # .rb file) so the module definition is loaded rather than replaced
+      # by an empty Module.new.
+      namespaces =
+        namespaces
+          .group_by(&:full_path)
+          .values
+          .map { |group| group.find { |ns| ns.file } || group.first }
+
+      # Phase 1: Set up namespaces
+      namespaces.each do |ns|
+        if ns.file
+          # Explicit namespace: autoload the .rb file
+          register_autoload(box, ns.parent, ns.cname, ns.file)
+        else
+          # Implicit namespace: create empty module
+          define_implicit_module(box, ns.parent, ns.cname, ns.full_path)
+        end
+      end
+
+      # Phase 2: Eagerly trigger explicit namespaces so children can attach
+      namespaces.each { |ns| box.eval(ns.full_path) if ns.file }
+
+      # Phase 3: Register file autoloads
+      files.each { |f| register_autoload(box, f.parent, f.cname, f.file) }
+    end
+
+    # Scans files in a collapsed directory, computing the parent namespace
+    # from the path between root_dir and the collapsed dir. E.g. if root_dir
+    # is lib/ and dir is lib/analytics/formatters/, files map to Analytics::*.
+    def self.scan_files_only(dir, root_dir: nil)
+      inflector = Zeitwerk::Inflector.new
+      entries = []
+
+      parent_cnames =
+        if root_dir && dir.start_with?("#{root_dir}/")
+          rel = dir.delete_prefix("#{root_dir}/")
+          rel.split('/')[0...-1].map { |p| inflector.camelize(p, root_dir) }
+        else
+          []
+        end
+
+      Dir
+        .glob(File.join(dir, '**', '*.rb'))
+        .sort
+        .each do |abspath|
+          relative = abspath.delete_prefix("#{dir}/").delete_suffix('.rb')
+          parts = relative.split('/')
+          file_cnames = parts.map { |part| inflector.camelize(part, dir) }
+          all_cnames = parent_cnames + file_cnames
+          full_path = all_cnames.join('::')
+          cname = all_cnames.last
+          parent = all_cnames[0...-1].join('::')
+
+          entries << Entry.new(
+            type: :file,
+            cname: cname,
+            full_path: full_path,
+            file: abspath,
+            parent: parent,
+            dir: nil,
+          )
+        end
+
+      entries
+    end
+
+    # Builds a file index (const_name → file_path) from scan entries.
+    # Used by ConstantResolver for dependency wiring.
+    def self.build_file_index(entries)
+      index = {}
+      entries.each { |e| index[e.full_path] = e.file if e.file }
+      index
+    end
+
+    class << self
+      private
+
+      def scan_dir(fs, inflector, dir, parent_path, entries)
+        fs.ls(dir) do |basename, abspath, ftype|
+          if ftype == :file
+            # Skip files that have a matching directory (explicit namespaces).
+            # These are already handled as namespace entries with their .rb file.
+            next if File.directory?(abspath.delete_suffix('.rb'))
+
+            cname = inflector.camelize(basename.delete_suffix('.rb'), dir)
+            full_path = parent_path.empty? ? cname : "#{parent_path}::#{cname}"
+            entries << Entry.new(
+              type: :file,
+              cname: cname,
+              full_path: full_path,
+              file: abspath,
+              parent: parent_path,
+              dir: nil,
+            )
+          elsif ftype == :directory
+            cname = inflector.camelize(basename, dir)
+            full_path = parent_path.empty? ? cname : "#{parent_path}::#{cname}"
+            rb_file = "#{abspath}.rb"
+            has_rb = File.exist?(rb_file)
+            entries << Entry.new(
+              type: :namespace,
+              cname: cname,
+              full_path: full_path,
+              file: has_rb ? rb_file : nil,
+              parent: parent_path,
+              dir: abspath,
+            )
+            scan_dir(fs, inflector, abspath, full_path, entries)
+          end
+        end
+      end
+
+      def register_autoload(box, parent, cname, file)
+        if parent.empty?
+          box.eval("autoload :#{cname}, #{file.inspect}")
+        else
+          box.eval("#{parent}.autoload(:#{cname}, #{file.inspect})")
+        end
+      end
+
+      def define_implicit_module(box, parent, cname, full_path)
+        if parent.empty?
+          box.eval("#{cname} = Module.new unless defined?(#{cname})")
+        else
+          box.eval(
+            "#{parent}.const_set(:#{cname}, Module.new) unless defined?(#{full_path})",
+          )
+        end
+      end
+    end
+  end
+end

data/lib/boxwerk.rb

@@ -1,14 +1,36 @@
 # frozen_string_literal: true
 
+require_relative 'boxwerk/autoloader_mixin'
+require_relative 'boxwerk/box_manager'
 require_relative 'boxwerk/cli'
-require_relative 'boxwerk/graph'
-require_relative 'boxwerk/loader'
+require_relative 'boxwerk/constant_resolver'
+require_relative 'boxwerk/gem_resolver'
+require_relative 'boxwerk/gemfile_require_parser'
+require_relative 'boxwerk/global_context'
 require_relative 'boxwerk/package'
-require_relative 'boxwerk/registry'
+require_relative 'boxwerk/package_context'
+require_relative 'boxwerk/package_resolver'
+require_relative 'boxwerk/privacy_checker'
 require_relative 'boxwerk/setup'
 require_relative 'boxwerk/version'
+require_relative 'boxwerk/zeitwerk_scanner'
 
+# Boxwerk is a package isolation system for Ruby applications built on
+# Ruby::Box. It loads each package in its own +Ruby::Box+, enforcing
+# dependency and privacy boundaries declared in +package.yml+ files.
 module Boxwerk
-  class Error < StandardError
+  class << self
+    # Returns the {PackageContext} for the currently executing package.
+    # Returns +nil+ in the root box.
+    # @return [PackageContext, nil]
+    def package
+      nil
+    end
+
+    # Returns the {GlobalContext}.
+    # @return [GlobalContext]
+    def global
+      Ruby::Box.root.const_get(:BOXWERK_GLOBAL)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: boxwerk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - David Cristofaro
@@ -9,24 +9,54 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: irb
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '1.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.17'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
   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.
+        version: '2.7'
+description: Boxwerk is a tool for creating modular Ruby and Rails applications. It
+  organizes code into packages with clear boundaries and explicit dependencies, enforcing
+  them at runtime using Ruby::Box constant isolation. It reads standard Packwerk package.yml
+  files (without requiring Packwerk), providing per-package gem isolation, Zeitwerk-based
+  autoloading, monkey patch isolation between packages, and a CLI for running, testing,
+  and inspecting your modular application.
 email:
 - david@dtcristo.com
 executables:
@@ -34,31 +64,30 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
+- ARCHITECTURE.md
 - 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
+- TODO.md
+- USAGE.md
 - exe/boxwerk
 - lib/boxwerk.rb
+- lib/boxwerk/autoloader_mixin.rb
+- lib/boxwerk/box_manager.rb
 - lib/boxwerk/cli.rb
-- lib/boxwerk/graph.rb
-- lib/boxwerk/loader.rb
+- lib/boxwerk/constant_resolver.rb
+- lib/boxwerk/gem_resolver.rb
+- lib/boxwerk/gemfile_require_parser.rb
+- lib/boxwerk/global_context.rb
 - lib/boxwerk/package.rb
-- lib/boxwerk/registry.rb
+- lib/boxwerk/package_context.rb
+- lib/boxwerk/package_resolver.rb
+- lib/boxwerk/privacy_checker.rb
 - lib/boxwerk/setup.rb
 - lib/boxwerk/version.rb
-- sig/boxwerk.rbs
+- lib/boxwerk/zeitwerk_scanner.rb
 homepage: https://github.com/dtcristo/boxwerk
 licenses:
 - MIT
@@ -67,6 +96,7 @@ metadata:
   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
+  documentation_uri: https://dtcristo.github.io/boxwerk/
 rdoc_options: []
 require_paths:
 - lib
@@ -74,7 +104,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 4.0.0
+      version: '4.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -83,5 +113,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Ruby package system with Box-powered constant isolation
+summary: Ruby package system with Box-powered boundary enforcement
 test_files: []

data/example/Gemfile

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

data/example/Gemfile.lock

@@ -1,66 +0,0 @@
-PATH
-  remote: ..
-  specs:
-    boxwerk (0.1.0)
-      irb (~> 1.16)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    bigdecimal (4.0.1)
-    concurrent-ruby (1.3.6)
-    date (3.5.1)
-    erb (6.0.1)
-    i18n (1.14.8)
-      concurrent-ruby (~> 1.0)
-    io-console (0.8.2)
-    irb (1.16.0)
-      pp (>= 0.6.0)
-      rdoc (>= 4.0.0)
-      reline (>= 0.4.2)
-    money (7.0.0)
-      bigdecimal
-      i18n (~> 1.9)
-    pp (0.6.3)
-      prettyprint
-    prettyprint (0.2.0)
-    psych (5.3.1)
-      date
-      stringio
-    rdoc (7.0.3)
-      erb
-      psych (>= 4.0.0)
-      tsort
-    reline (0.6.3)
-      io-console (~> 0.5)
-    stringio (3.2.0)
-    tsort (0.2.0)
-
-PLATFORMS
-  arm64-darwin-25
-  ruby
-
-DEPENDENCIES
-  boxwerk!
-  money
-
-CHECKSUMS
-  bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
-  boxwerk (0.1.0)
-  concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
-  date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
-  erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
-  i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
-  io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
-  irb (1.16.0) sha256=2abe56c9ac947cdcb2f150572904ba798c1e93c890c256f8429981a7675b0806
-  money (7.0.0) sha256=6de776ee00aced8b9a435d3aac25ce8c600566625809b3d69bbe0c319e941dd5
-  pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
-  prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
-  psych (5.3.1) sha256=eb7a57cef10c9d70173ff74e739d843ac3b2c019a003de48447b2963d81b1974
-  rdoc (7.0.3) sha256=dfe3d0981d19b7bba71d9dbaeb57c9f4e3a7a4103162148a559c4fc687ea81f9
-  reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
-  stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
-  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
-
-BUNDLED WITH
-  4.0.3