boxwerk 0.2.0 → 0.3.0

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,9 +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 << 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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - David Cristofaro
@@ -9,23 +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 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.
+        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:
@@ -33,19 +64,30 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
+- ARCHITECTURE.md
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- 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
+- lib/boxwerk/zeitwerk_scanner.rb
 homepage: https://github.com/dtcristo/boxwerk
 licenses:
 - MIT
@@ -54,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
@@ -61,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:
   - - ">="
@@ -70,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/lib/boxwerk/graph.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-module Boxwerk
-  # 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
-
-    def initialize(root_path)
-      @root_path = root_path
-      @packages = {}
-      @root = load_package('root', root_path)
-      resolve_dependencies(@root, [])
-    end
-
-    def topological_order
-      visited = {}
-      order = []
-      @packages.each_value { |pkg| visit(pkg, visited, order, []) }
-      order
-    end
-
-    private
-
-    def load_package(name, path)
-      return @packages[name] if @packages[name]
-
-      @packages[name] = Package.new(name, path)
-    end
-
-    def resolve_dependencies(package, path)
-      raise "Circular dependency: #{(path + [package.name]).join(' -> ')}" if path.include?(package.name)
-
-      package.dependencies.each do |dep_path|
-        full_path = File.join(@root_path, dep_path)
-        raise "Package not found: #{dep_path}" unless File.directory?(full_path)
-
-        resolve_dependencies(load_package(File.basename(dep_path), full_path), path + [package.name])
-      end
-    end
-
-    def visit(package, visited, order, path)
-      return if visited[package.name]
-
-      visited[package.name] = true
-      package.dependencies.each do |dep_path|
-        dep_package = @packages[File.basename(dep_path)]
-        visit(dep_package, visited, order, path + [package.name]) if dep_package
-      end
-      order << package
-    end
-  end
-end

data/lib/boxwerk/loader.rb

@@ -1,149 +0,0 @@
-# frozen_string_literal: true
-
-module Boxwerk
-  # 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
-      def boot_all(graph, registry)
-        order = graph.topological_order
-
-        order.each { |package| boot(package, graph, registry) }
-      end
-
-      def boot(package, graph, registry)
-        return package if package.booted?
-
-        package.box = Ruby::Box.new
-        wire_imports(package.box, package, graph)
-        registry.register(package.name, package)
-
-        package
-      end
-
-      private
-
-      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)
-
-        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}'"
-        end
-
-        package.box.require(file_path)
-        package.loaded_exports[const_name] = file_path
-      end
-
-      def find_file_for_constant(lib_path, const_name)
-        if const_name.include?('::')
-          nested_path = File.join(lib_path, "#{underscore(const_name)}.rb")
-          return nested_path if File.exist?(nested_path)
-
-          parts = const_name.split('::')
-          parent_name = parts[0..-2].join('::')
-          parent_file = File.join(lib_path, "#{underscore(parent_name)}.rb")
-          return parent_file if File.exist?(parent_file)
-        else
-          conventional_path =
-            File.join(lib_path, "#{underscore(const_name)}.rb")
-          return conventional_path if File.exist?(conventional_path)
-        end
-
-        nil
-      end
-
-      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
-
-      def wire_imports(box, package, graph)
-        package.imports.each do |import_item|
-          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
-
-          wire_import_strategy(box, package, path, config, dependency)
-        end
-      end
-
-      def wire_import_strategy(box, package, path, config, dependency)
-        case config
-        when nil
-          create_namespace(package, camelize(File.basename(path)), dependency)
-        when String
-          create_namespace(package, config, dependency)
-        when Array
-          config.each do |name|
-            set_constant(package, name, get_constant(dependency, name))
-          end
-        when Hash
-          config.each do |remote, local|
-            set_constant(package, local, get_constant(dependency, remote))
-          end
-        end
-      end
-
-      def create_namespace(package, namespace_name, dependency)
-        if dependency.exports.size == 1
-          set_constant(
-            package,
-            namespace_name,
-            get_constant(dependency, dependency.exports.first),
-          )
-        else
-          mod = create_module(package.box, namespace_name)
-          dependency.exports.each do |name|
-            mod.const_set(name.to_sym, get_constant(dependency, name))
-          end
-        end
-      end
-
-      def get_constant(package, name)
-        load_export(package, name)
-        package.box.const_get(name.to_sym)
-      end
-
-      def set_constant(package, name, value)
-        package.box.const_set(name.to_sym, value)
-      end
-
-      def create_module(box, name)
-        if box.const_defined?(name.to_sym, false)
-          return box.const_get(name.to_sym)
-        end
-
-        mod = Module.new
-        box.const_set(name.to_sym, mod)
-        mod
-      end
-
-      def camelize(string)
-        string.split('_').map(&:capitalize).join
-      end
-    end
-  end
-end

data/lib/boxwerk/registry.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-module Boxwerk
-  # Registry tracks booted package instances to ensure each package boots only once.
-  class Registry
-    def initialize
-      @registry = {}
-    end
-
-    def register(name, instance)
-      @registry[name] = instance
-    end
-
-    def get(name)
-      @registry[name]
-    end
-
-    def registered?(name)
-      @registry.key?(name)
-    end
-
-    def clear!
-      @registry = {}
-    end
-  end
-end