boxwerk 0.2.0 → 0.3.0

data/lib/boxwerk/package.rb

@@ -1,42 +1,94 @@
 # frozen_string_literal: true
 
-require 'yaml'
-
 module Boxwerk
-  # Package represents a single package loaded from package.yml.
-  # Tracks exports, imports, dependencies, and the isolated Ruby::Box instance.
+  # Data class representing a package. Reads the standard package.yml format.
   class Package
-    attr_reader :name, :path, :exports, :imports, :loaded_exports
-    attr_accessor :box
+    attr_reader :name, :config
 
-    def initialize(name, path)
+    def initialize(name:, config: {})
       @name = name
-      @path = path
-      @box = nil
-      @exports = []
-      @imports = []
-      @loaded_exports = {}
-
-      load_config
+      @config = config
     end
 
-    def booted?
-      !@box.nil?
+    def root?
+      @name == '.'
     end
 
     def dependencies
-      @imports.map { |item| item.is_a?(String) ? item : item.keys.first }
+      @config['dependencies'] || []
+    end
+
+    def enforce_dependencies?
+      @config['enforce_dependencies'] == true
+    end
+
+    def ==(other)
+      other.is_a?(Package) && name == other.name
     end
 
-    private
+    alias eql? ==
+
+    def hash
+      name.hash
+    end
+
+    def to_s
+      name
+    end
 
-    def load_config
-      config_path = File.join(@path, 'package.yml')
-      return unless File.exist?(config_path)
+    def inspect
+      "#<Boxwerk::Package #{name}>"
+    end
+
+    # Loads a Package from a package.yml file.
+    # The name is the relative path from root_path to the package directory.
+    def self.from_yml(yml_path, root_path:)
+      config = YAML.safe_load_file(yml_path) || {}
+      pkg_dir = File.dirname(yml_path)
+      name =
+        if File.expand_path(pkg_dir) == File.expand_path(root_path)
+          '.'
+        else
+          relative_path(pkg_dir, root_path)
+        end
+
+      # Normalize dependency names declared in the package.yml
+      if config['dependencies']
+        config = config.dup
+        config['dependencies'] = config['dependencies'].map { |d| normalize(d) }
+      end
+
+      new(name: name, config: config)
+    end
+
+    # Creates an implicit root package that depends on all other packages.
+    # No enforcement is enabled.
+    def self.implicit_root(all_package_names)
+      new(
+        name: '.',
+        config: {
+          'enforce_dependencies' => false,
+          'enforce_privacy' => false,
+          'dependencies' => all_package_names.reject { |n| n == '.' },
+        },
+      )
+    end
+
+    # Normalizes a package name: strips leading ./ and trailing /.
+    # Allows users to write packs/loyalty/, ./packs/loyalty, or packs/loyalty
+    # interchangeably in package.yml dependencies and CLI --package flag.
+    def self.normalize(name)
+      name = name.to_s.strip
+      name = name.sub(%r{\A\./}, '')
+      name = name.sub(%r{/\z}, '')
+      name
+    end
 
-      config = YAML.load_file(config_path)
-      @exports = config['exports'] || []
-      @imports = config['imports'] || []
+    def self.relative_path(path, base)
+      Pathname
+        .new(File.expand_path(path))
+        .relative_path_from(Pathname.new(File.expand_path(base)))
+        .to_s
     end
   end
 end

data/lib/boxwerk/package_context.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Boxwerk
+  # Runtime context for the current package, accessible via +Boxwerk.package+.
+  # Available during +boot.rb+ execution and throughout the application.
+  class PackageContext
+    # @return [String] The package name (e.g. +"packs/orders"+ or +"."+ for root).
+    attr_reader :name
+
+    # @return [String] Absolute path to the package directory.
+    attr_reader :root_path
+
+    # @return [PackageContext::Autoloader] Autoloader configuration for this package.
+    attr_reader :autoloader
+
+    def initialize(name:, root_path:, config:, autoloader:)
+      @name = name
+      @root_path = root_path
+      @config = config.freeze
+      @autoloader = autoloader
+    end
+
+    # @return [Boolean] Whether this is the root package.
+    def root?
+      @name == '.'
+    end
+
+    # @return [Hash] Frozen package configuration from +package.yml+.
+    def config
+      @config
+    end
+
+    # Autoload configuration for a package box. Provides {AutoloaderMixin}'s
+    # +push_dir+, +collapse+, +ignore+, and +setup+ in +boot.rb+.
+    #
+    # Registration happens immediately when +push_dir+ or +collapse+ is called,
+    # making constants available for the rest of the boot script without an
+    # explicit +setup+ call.
+    class Autoloader
+      include AutoloaderMixin
+
+      def initialize(root_path, box:, default_autoload_dirs: [])
+        init_dirs
+        @root_path = root_path
+        @box = box
+        @default_autoload_dirs = default_autoload_dirs
+      end
+
+      private
+
+      def do_setup(new_push, new_collapse)
+        return unless @box
+
+        all_entries = []
+
+        new_push.each do |dir|
+          abs_dir = File.expand_path(dir, @root_path)
+          next unless File.directory?(abs_dir)
+          all_entries.concat(ZeitwerkScanner.scan(abs_dir))
+        end
+
+        new_collapse.each do |dir|
+          abs_dir = File.expand_path(dir, @root_path)
+          next unless File.directory?(abs_dir)
+          root_dir = find_root_for(abs_dir)
+          all_entries.concat(ZeitwerkScanner.scan_files_only(abs_dir, root_dir: root_dir))
+        end
+
+        return if all_entries.empty?
+
+        ZeitwerkScanner.register_autoloads(@box, all_entries)
+        file_index = ZeitwerkScanner.build_file_index(all_entries)
+        @accumulated_file_index ||= {}
+        @accumulated_file_index.merge!(file_index)
+      end
+
+      # Returns the absolute root autoload dir that contains abs_dir, or nil.
+      def find_root_for(abs_dir)
+        (@default_autoload_dirs + @push_dirs)
+          .map { |d| File.expand_path(d, @root_path) }
+          .find { |root| abs_dir.start_with?("#{root}/") }
+      end
+
+      # All user-configured collapse dirs (for BoxManager namespace cleanup).
+      def all_collapse_dirs = @collapse_dirs.dup
+
+      # All user-configured ignore dirs (for BoxManager namespace cleanup).
+      def ignore_dirs = @ignore_dirs.dup
+
+      # File index accumulated from all auto-setup calls (for BoxManager).
+      def accumulated_file_index = @accumulated_file_index || {}
+
+      # Dir info for BoxManager#record_package_dirs (used by info command).
+      def dir_info
+        {
+          autoload: @default_autoload_dirs + @push_dirs,
+          collapse: @collapse_dirs.dup,
+          ignore: @ignore_dirs.dup,
+        }
+      end
+    end
+  end
+end

data/lib/boxwerk/package_resolver.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'pathname'
+
+module Boxwerk
+  # Discovers packages by scanning for package.yml files and provides
+  # ordering for boot. Supports boxwerk.yml configuration for package_paths.
+  class PackageResolver
+    attr_reader :packages, :root
+
+    def initialize(root_path, config_overrides: {})
+      @root_path = File.expand_path(root_path)
+      @packages = {}
+      @config = load_boxwerk_config.merge(config_overrides)
+
+      discover_packages
+    end
+
+    # Returns packages in boot order. Dependencies come before dependents
+    # when possible. Circular dependencies are allowed — strongly connected
+    # components are grouped together. Packages with enforce_dependencies
+    # disabled are treated as depending on all other packages for ordering.
+    def topological_order
+      visited = {}
+      order = []
+      @packages.each_value { |pkg| visit(pkg, visited, order, Set.new) }
+      order
+    end
+
+    # Returns the direct dependency Package objects for a given package.
+    def direct_dependencies(package)
+      package.dependencies.filter_map { |dep_name| @packages[dep_name] }
+    end
+
+    # Returns all packages except the given one.
+    def all_except(package)
+      @packages.values.reject { |p| p.name == package.name }
+    end
+
+    # Boxwerk configuration from boxwerk.yml.
+    def boxwerk_config
+      @config
+    end
+
+    private
+
+    def load_boxwerk_config
+      yml_path = File.join(@root_path, 'boxwerk.yml')
+      if File.exist?(yml_path)
+        YAML.safe_load_file(yml_path) || {}
+      else
+        {}
+      end
+    end
+
+    def discover_packages
+      yml_paths = find_package_ymls
+
+      yml_paths.each do |yml_path|
+        package = Package.from_yml(yml_path, root_path: @root_path)
+        @packages[package.name] = package
+        @root = package if package.root?
+      end
+
+      # Implicit root package if no package.yml at root
+      unless @root
+        @root = Package.implicit_root(@packages.keys)
+        @packages['.'] = @root
+      end
+    end
+
+    def find_package_ymls
+      ymls = []
+
+      # Check for root package.yml
+      root_yml = File.join(@root_path, 'package.yml')
+      ymls << root_yml if File.exist?(root_yml)
+
+      # Use package_paths from boxwerk.yml (default: ["**/"])
+      package_paths = @config['package_paths'] || ['**/']
+
+      package_paths.each do |pattern|
+        glob = File.join(@root_path, pattern, 'package.yml')
+        Dir
+          .glob(glob)
+          .each do |path|
+            next if path == root_yml
+            ymls << path
+          end
+      end
+
+      ymls.uniq
+    end
+
+    def visit(package, visited, order, in_stack)
+      return if visited[package.name]
+
+      visited[package.name] = true
+      in_stack.add(package.name)
+
+      # When enforce_dependencies is false, treat as depending on all
+      # other packages for boot ordering purposes.
+      deps =
+        if package.enforce_dependencies?
+          package.dependencies
+        else
+          @packages.keys.reject { |n| n == package.name }
+        end
+
+      deps.each do |dep_name|
+        dep = @packages[dep_name]
+        next unless dep
+        next if in_stack.include?(dep_name)
+        visit(dep, visited, order, in_stack)
+      end
+
+      in_stack.delete(package.name)
+      order << package
+    end
+  end
+end

data/lib/boxwerk/privacy_checker.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+
+module Boxwerk
+  # Enforces privacy rules at runtime.
+  # Reads enforce_privacy, public_path, and private_constants from package.yml.
+  # Files with `# pack_public: true` sigil are treated as public.
+  module PrivacyChecker
+    DEFAULT_PUBLIC_PATH = 'public/'
+    PUBLICIZED_SIGIL_REGEX = /#.*pack_public:\s*true/
+
+    class << self
+      # Returns true if the package enforces privacy.
+      def enforces_privacy?(package)
+        setting = package.config['enforce_privacy']
+        [true, 'strict'].include?(setting)
+      end
+
+      # Returns the public path for a package (absolute).
+      def public_path_for(package, root_path)
+        user_path = package.config['public_path']
+        relative =
+          if user_path
+            user_path.end_with?('/') ? user_path : "#{user_path}/"
+          else
+            DEFAULT_PUBLIC_PATH
+          end
+
+        if package.root?
+          File.join(root_path, relative)
+        else
+          File.join(root_path, package.name, relative)
+        end
+      end
+
+      # Returns the set of public constant names for a package.
+      # These are derived from files in the public_path using Ruby naming conventions.
+      def public_constants(package, root_path)
+        return nil unless enforces_privacy?(package)
+
+        pub_path = public_path_for(package, root_path)
+        constants = Set.new
+
+        if File.directory?(pub_path)
+          Dir
+            .glob(File.join(pub_path, '**', '*.rb'))
+            .each do |file|
+              const_name = constant_name_from_path(file, pub_path)
+              constants.add(const_name) if const_name
+            end
+        end
+
+        # Also scan all package files for pack_public: true sigil
+        package_lib = package_lib_path(package, root_path)
+        if package_lib && File.directory?(package_lib)
+          Dir
+            .glob(File.join(package_lib, '**', '*.rb'))
+            .each do |file|
+              if publicized_file?(file)
+                const_name = constant_name_from_path(file, package_lib)
+                constants.add(const_name) if const_name
+              end
+            end
+        end
+
+        constants
+      end
+
+      # Returns the set of constants with pack_public: true sigil in package lib/.
+      # These are individual files opted-in to public access without a public_path dir.
+      def pack_public_constants(package, root_path)
+        lib = package_lib_path(package, root_path)
+        return nil unless lib && File.directory?(lib)
+
+        constants = Set.new
+        Dir
+          .glob(File.join(lib, '**', '*.rb'))
+          .each do |file|
+            if publicized_file?(file)
+              const_name = constant_name_from_path(file, lib)
+              constants.add(const_name) if const_name
+            end
+          end
+        constants.empty? ? nil : constants
+      end
+
+      # Returns the set of explicitly private constant names.
+      # Strips leading :: prefix.
+      def private_constants_list(package)
+        (package.config['private_constants'] || [])
+          .map { |name| name.start_with?('::') ? name[2..] : name }
+          .to_set
+      end
+
+      # Checks if a constant is accessible from outside the package.
+      # Returns true if accessible, false if blocked by privacy.
+      def accessible?(
+        const_name,
+        package,
+        root_path,
+        public_constants_cache: nil
+      )
+        return true unless enforces_privacy?(package)
+
+        # Check explicitly private constants
+        privates = private_constants_list(package)
+        return false if privates.include?(const_name.to_s)
+        if privates.any? { |pc| const_name.to_s.start_with?("#{pc}::") }
+          return false
+        end
+
+        # Check if constant is in the public set
+        pub_consts =
+          public_constants_cache || public_constants(package, root_path)
+        return true if pub_consts.nil? # privacy not enforced
+
+        # If public_path has files, check against them
+        # If public_path is empty/doesn't exist but enforce_privacy is on,
+        # all constants are private (no public API defined)
+        pub_consts.include?(const_name.to_s)
+      end
+
+      private
+
+      # Derives a constant name from a file path relative to a base directory.
+      # Uses Zeitwerk's inflector for Ruby naming conventions.
+      def constant_name_from_path(file_path, base_path)
+        normalized_base = base_path.end_with?('/') ? base_path : "#{base_path}/"
+        relative = file_path.delete_prefix(normalized_base).delete_suffix('.rb')
+        return nil if relative.empty?
+
+        inflector = Zeitwerk::Inflector.new
+        relative
+          .split('/')
+          .map { |part| inflector.camelize(part, base_path) }
+          .join('::')
+      end
+
+      # Checks if a file contains the pack_public: true sigil in first 5 lines.
+      def publicized_file?(file_path)
+        File
+          .foreach(file_path)
+          .first(5)
+          .any? { |line| line.match?(PUBLICIZED_SIGIL_REGEX) }
+      rescue Errno::ENOENT
+        false
+      end
+
+      def package_lib_path(package, root_path)
+        if package.root?
+          nil
+        else
+          File.join(root_path, package.name, 'lib')
+        end
+      end
+    end
+  end
+end

data/lib/boxwerk/setup.rb

@@ -1,41 +1,90 @@
 # frozen_string_literal: true
 
 module Boxwerk
-  # Setup finds the root package, builds the dependency graph, and boots all packages.
-  # Orchestrates the entire Boxwerk initialization process.
   module Setup
     class << self
-      def run!(start_dir: Dir.pwd)
-        root_path = find_package_yml(start_dir)
-        raise 'Cannot find package.yml in current directory or ancestors' unless root_path
+      def run(start_dir: Dir.pwd, packages: nil, config: {})
+        root_path = find_root(start_dir)
 
-        graph = Boxwerk::Graph.new(root_path)
-        registry = Boxwerk::Registry.new
-        Boxwerk::Loader.boot_all(graph, registry)
+        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)
 
-        @graph = graph
+        # 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)
+
+        # 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)
+
+        # 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
+
+        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 graph
-        @graph
+      def resolver
+        @resolver
+      end
+
+      def box_manager
+        @box_manager
       end
 
       def booted?
         @booted || false
       end
 
-      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
 
-      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
+          return current if File.exist?(File.join(current, 'boxwerk.yml'))
           return current if File.exist?(File.join(current, 'package.yml'))
 
           parent = File.dirname(current)
@@ -43,7 +92,66 @@ module Boxwerk
 
           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.2.0'
+  VERSION = '0.3.0'
 end