boxwerk 0.2.0 → 0.3.0

data/lib/boxwerk/constant_resolver.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module Boxwerk
+  # Resolves constants from dependency packages without namespace wrapping.
+  #
+  # When package A depends on package B, B's constants are accessible
+  # directly in A (e.g. Invoice, not Finance::Invoice). A const_missing
+  # handler searches all direct dependencies in order and resolves the
+  # first match. Privacy enforcement is applied per-dependency.
+  module ConstantResolver
+    # Installs a const_missing handler on the box that searches all
+    # dependency boxes for the requested constant. Each dependency entry
+    # contains: :box, :file_index, :public_constants, :private_constants,
+    # :package_name.
+    #
+    # +all_packages_ref+ is an optional hash with lazy references to
+    # :file_indexes, :packages, :root_path, :dep_names, and :self_name
+    # for producing helpful NameError hints.
+    # +package_name+ is the name of the current package (for error messages).
+    def self.install_dependency_resolver(
+      box,
+      deps_config,
+      all_packages_ref: nil,
+      package_name: nil
+    )
+      resolver =
+        build_resolver(
+          deps_config,
+          all_packages_ref: all_packages_ref,
+          package_name: package_name,
+        )
+      box.const_set(:BOXWERK_DEPENDENCY_RESOLVER, resolver)
+
+      # Define const_missing on Object within the box so that top-level
+      # constant lookups (e.g. Invoice) trigger the dependency search.
+      box.eval(<<~RUBY)
+        class Object
+          def self.const_missing(const_name)
+            BOXWERK_DEPENDENCY_RESOLVER.call(const_name)
+          end
+        end
+      RUBY
+    end
+
+    # Builds a resolver proc that searches dependencies for a constant.
+    def self.build_resolver(
+      deps_config,
+      all_packages_ref: nil,
+      package_name: nil
+    )
+      proc do |const_name|
+        name_str = const_name.to_s
+        found = false
+        value = nil
+
+        deps_config.each do |dep|
+          dep_box = dep[:box]
+          file_index = dep[:file_index]
+          public_constants = dep[:public_constants]
+          private_constants = dep[:private_constants]
+          pkg_name = dep[:package_name]
+
+          # Check if this dependency has the constant or a namespace
+          # matching it (e.g. "Menu" when file_index has "Menu::Item")
+          has_constant =
+            file_index.key?(name_str) ||
+              file_index.any? { |k, _| k.start_with?("#{name_str}::") } ||
+              (
+                begin
+                  dep_box.const_get(const_name)
+                  true
+                rescue NameError
+                  false
+                end
+              )
+
+          next unless has_constant
+
+          # Check explicitly private constants
+          if private_constants && !private_constants.empty?
+            if private_constants.include?(name_str) ||
+                 private_constants.any? { |pc| name_str.start_with?("#{pc}::") }
+              from = package_name ? " referenced from '#{package_name}'" : ''
+              raise NameError.new(
+                "private constant #{name_str}#{from} — #{name_str} is private to '#{pkg_name}'",
+                const_name,
+              )
+            end
+          end
+
+          # Check public constants whitelist (privacy enforcement).
+          # A namespace module (e.g. Menu) is allowed if any public
+          # constant lives under it (e.g. Menu::Item).
+          if public_constants
+            direct_match = public_constants.include?(name_str)
+            namespace_match =
+              public_constants.any? { |pc| pc.start_with?("#{name_str}::") }
+            unless direct_match || namespace_match
+              from = package_name ? " referenced from '#{package_name}'" : ''
+              raise NameError.new(
+                "private constant #{name_str}#{from} — #{name_str} is private to '#{pkg_name}'",
+                const_name,
+              )
+            end
+          end
+
+          # Resolve the constant from the dependency box
+          value =
+            begin
+              dep_box.const_get(const_name)
+            rescue NameError
+              file = file_index[name_str]
+              if file
+                dep_box.require(file)
+                dep_box.const_get(const_name)
+              else
+                # Namespace module — trigger autoload of a child constant
+                # so the module gets defined in the dependency box.
+                child_key =
+                  file_index.keys.find { |k| k.start_with?("#{name_str}::") }
+                if child_key
+                  child_file = file_index[child_key]
+                  dep_box.require(child_file)
+                  dep_box.const_get(const_name)
+                else
+                  raise NameError.new(
+                    "uninitialized constant #{name_str}",
+                    const_name,
+                  )
+                end
+              end
+            end
+
+          found = true
+          break
+        end
+
+        unless found
+          hint = find_hint(name_str, all_packages_ref)
+          msg =
+            if hint
+              visibility = hint[:private] ? 'private in' : 'defined in'
+              from = package_name ? ", not a dependency of '#{package_name}'" : ''
+              "uninitialized constant #{name_str} (#{visibility} '#{hint[:package_name]}'#{from})"
+            else
+              "uninitialized constant #{name_str}"
+            end
+          raise NameError.new(msg, const_name)
+        end
+
+        value
+      end
+    end
+
+    # Searches all packages (via lazy ref) for one whose file_index
+    # contains the given constant name. Returns a hash with :package_name
+    # and :private (boolean), or nil if not found.
+    #
+    # For packages that weren't booted (not in file_indexes), does a
+    # lightweight file-system scan so hints work with selective booting.
+    def self.find_hint(name_str, all_packages_ref)
+      return nil unless all_packages_ref
+
+      file_indexes = all_packages_ref[:file_indexes]
+      packages = all_packages_ref[:packages]
+      root_path = all_packages_ref[:root_path]
+      dep_names = all_packages_ref[:dep_names]
+      self_name = all_packages_ref[:self_name]
+
+      packages.each_value do |pkg|
+        next if pkg.name == self_name
+        next if dep_names.include?(pkg.name)
+
+        pkg_file_index = file_indexes[pkg.name]
+
+        if pkg_file_index
+          # Package was booted — use its file index directly
+          next unless pkg_file_index.key?(name_str) ||
+            pkg_file_index.any? { |k, _| k.start_with?("#{name_str}::") }
+        else
+          # Package was not booted — do a lightweight file-system scan
+          pkg_file_index = scan_package_for_hint(pkg, root_path)
+          next unless pkg_file_index.key?(name_str) ||
+            pkg_file_index.any? { |k, _| k.start_with?("#{name_str}::") }
+        end
+
+        pub_consts = PrivacyChecker.public_constants(pkg, root_path)
+        is_private =
+          if pub_consts
+            !pub_consts.include?(name_str) &&
+              !pub_consts.any? { |pc| pc.start_with?("#{name_str}::") }
+          else
+            false
+          end
+
+        return { package_name: pkg.name, private: is_private }
+      end
+      nil
+    end
+
+    # Lightweight file-system scan to build a constant → file map for a
+    # package without booting its box. Used for NameError hints.
+    #
+    # Does NOT use Zeitwerk::Loader (which registers dirs globally and
+    # would conflict if called twice for the same dir). Instead performs
+    # a plain Dir.glob walk with Zeitwerk::Inflector for naming.
+    def self.scan_package_for_hint(pkg, root_path)
+      pkg_dir =
+        if pkg.root?
+          root_path
+        else
+          File.join(root_path, pkg.name)
+        end
+
+      lib_dir = pkg.root? ? nil : File.join(pkg_dir, 'lib')
+      pub_dir = PrivacyChecker.public_path_for(pkg, root_path)
+
+      inflector = Zeitwerk::Inflector.new
+      result = {}
+
+      [lib_dir, pub_dir].compact.each do |dir|
+        next unless File.directory?(dir)
+
+        Dir.glob(File.join(dir, '**', '*.rb')).sort.each do |abspath|
+          relative = abspath.delete_prefix("#{dir}/").delete_suffix('.rb')
+          parts = relative.split('/')
+          cnames = parts.map { |part| inflector.camelize(part, abspath) }
+          full_path = cnames.join('::')
+          result[full_path] ||= abspath
+        end
+      end
+
+      result
+    end
+  end
+end

data/lib/boxwerk/gem_resolver.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require 'bundler'
+
+module Boxwerk
+  # Resolves per-package gem dependencies from lockfiles.
+  #
+  # Parses lockfiles with Bundler::LockfileParser and resolves gem load paths
+  # for $LOAD_PATH isolation per box. Unlike Bundler itself, this resolver can
+  # find gems outside the current bundle by searching all gem directories.
+  #
+  # Gems are fully isolated per box — they do not leak across package
+  # boundaries. Cross-package version conflicts are harmless because each box
+  # has its own $LOAD_PATH and $LOADED_FEATURES snapshot. The only situation
+  # worth flagging is when a package defines a gem that is also in the root
+  # Gemfile at a different version: both versions end up in memory (the global
+  # version inherited at box creation, the package version loaded on demand).
+  class GemResolver
+    # Represents a resolved gem for a package: name, version, load paths,
+    # and autorequire directives from the Gemfile.
+    #   autorequire: nil      → transitive dependency (not in Gemfile)
+    #   autorequire: :default → require the gem name (Gemfile entry, no require option)
+    #   autorequire: []       → skip (require: false)
+    #   autorequire: ["x/y"]  → require each listed path
+    GemInfo = Struct.new(:name, :version, :load_paths, :autorequire, keyword_init: true)
+
+    attr_reader :root_path
+
+    def initialize(root_path)
+      @root_path = root_path
+      @all_specs = nil
+      @package_gems = {} # package name -> [GemInfo]
+    end
+
+    # Returns an array of load paths for a package's gem dependencies.
+    # Returns nil if the package has no gems.rb/Gemfile.
+    def resolve_for(package)
+      gems = gems_for(package)
+      return nil unless gems&.any?
+
+      gems.flat_map(&:load_paths).uniq
+    end
+
+    # Returns [GemInfo] for a package, cached after first resolution.
+    # Merges lockfile resolution with Gemfile autorequire directives.
+    def gems_for(package)
+      return @package_gems[package.name] if @package_gems.key?(package.name)
+
+      gemfile_path = find_gemfile(package)
+      unless gemfile_path
+        @package_gems[package.name] = nil
+        return nil
+      end
+
+      lockfile_path = find_lockfile(gemfile_path)
+      unless lockfile_path && File.exist?(lockfile_path)
+        pkg_label = package.root? ? '.' : package.name
+        warn "Boxwerk: No lockfile found for #{pkg_label}. Run 'boxwerk install' to install gems."
+        @package_gems[package.name] = nil
+        return nil
+      end
+
+      requires = parse_gemfile_requires(gemfile_path)
+      gems = resolve_gems_from_lockfile(lockfile_path)
+      gems.each do |g|
+        next unless requires.key?(g.name)
+        # :default means "require the gem name" (Gemfile entry with no require option).
+        # nil means transitive dependency (not in Gemfile) — skip auto-require.
+        g.autorequire = requires[g.name] || :default
+      end
+      @package_gems[package.name] = gems
+      gems
+    end
+
+    # Parses the Gemfile to extract autorequire directives.
+    # Returns { gem_name => autorequire_value } where value is:
+    #   nil      → require the gem name (default)
+    #   []       → skip (require: false)
+    #   ["path"] → require the listed paths
+    #
+    # Uses a lightweight DSL evaluator to avoid Bundler::Dsl side-effects.
+    def parse_gemfile_requires(gemfile_path)
+      parser = GemfileRequireParser.new
+      parser.eval_gemfile(gemfile_path)
+      parser.requires
+    end
+
+    # Checks for gem version conflicts between global and per-package gems.
+    # Returns an array of conflict descriptions (empty if none).
+    #
+    # Cross-package conflicts are NOT checked because gems are fully isolated
+    # per box — each box has its own $LOAD_PATH and $LOADED_FEATURES snapshot.
+    # Package A can safely use gem Z v2 while package B uses gem Z v1, even if
+    # A depends on B.
+    #
+    # The only conflict worth flagging is a **global override**: a package
+    # defines a gem that is also in the root Gemfile at a different version.
+    # Both versions load into memory (global inherited at box creation,
+    # package version loaded on demand), which wastes memory but is
+    # functionally correct.
+    def check_conflicts(package_resolver)
+      conflicts = []
+
+      root_gems = gems_for(package_resolver.root)
+      return conflicts unless root_gems&.any?
+
+      root_gem_map = root_gems.each_with_object({}) { |g, h| h[g.name] = g }
+
+      package_resolver.packages.each_value do |pkg|
+        next if pkg.root?
+
+        pkg_gems = gems_for(pkg)
+        next unless pkg_gems
+
+        pkg_gems.each do |gem_info|
+          root_gem = root_gem_map[gem_info.name]
+          next unless root_gem
+          next if root_gem.version == gem_info.version
+
+          conflicts << {
+            type: :global_override,
+            gem_name: gem_info.name,
+            package: pkg.name,
+            package_version: gem_info.version,
+            global_version: root_gem.version,
+          }
+        end
+      end
+
+      conflicts
+    end
+
+    private
+
+    def package_dir(package)
+      if package.root?
+        @root_path
+      else
+        File.join(@root_path, package.name)
+      end
+    end
+
+    def find_gemfile(package)
+      dir = package_dir(package)
+
+      gemfile = File.join(dir, 'gems.rb')
+      return gemfile if File.exist?(gemfile)
+
+      gemfile = File.join(dir, 'Gemfile')
+      return gemfile if File.exist?(gemfile)
+
+      nil
+    end
+
+    def find_lockfile(gemfile_path)
+      if gemfile_path.end_with?('gems.rb')
+        gemfile_path.sub('gems.rb', 'gems.locked')
+      else
+        "#{gemfile_path}.lock"
+      end
+    end
+
+    # Parses a lockfile and returns [GemInfo] with resolved load paths.
+    # Path gems (like `boxwerk`) that can't be found in gem dirs are included
+    # with empty load_paths so they appear in display output.
+    def resolve_gems_from_lockfile(lockfile_path)
+      lockfile_content = File.read(lockfile_path)
+      parser = Bundler::LockfileParser.new(lockfile_content)
+
+      seen = Set.new
+      gems = []
+      parser.specs.each do |spec|
+        # Deduplicate by name — lockfiles can have multiple platform-specific
+        # variants of the same gem (e.g. sqlite3 for x86_64-linux and arm64-darwin).
+        next unless seen.add?(spec.name)
+
+        paths = resolve_gem_paths(spec.name, spec.version.to_s)
+        gems << GemInfo.new(
+          name: spec.name,
+          version: spec.version.to_s,
+          load_paths: paths || [],
+        )
+      end
+
+      gems
+    end
+
+    # Resolves load paths for a specific gem version.
+    def resolve_gem_paths(name, version)
+      spec = find_gem_spec(name, version)
+      unless spec
+        unless name == 'boxwerk'
+          warn "Boxwerk: gem '#{name}' (#{version}) not installed, skipping"
+        end
+        return nil
+      end
+      collect_paths(spec)
+    end
+
+    # Finds a gem specification by searching all gem directories.
+    def find_gem_spec(name, version)
+      all_gem_specs.find { |s| s.name == name && s.version.to_s == version } ||
+        all_gem_specs.find { |s| s.name == name }
+    end
+
+    # Loads all gem specifications from all gem directories.
+    # Cached for the lifetime of this resolver.
+    def all_gem_specs
+      @all_specs ||=
+        begin
+          dirs =
+            Gem.path.flat_map do |p|
+              Dir.glob(File.join(p, 'specifications', '*.gemspec'))
+            end
+          dirs.map { |path| Gem::Specification.load(path) }.compact
+        end
+    end
+
+    # Recursively collects load paths for a gem and its runtime dependencies.
+    def collect_paths(spec, resolved = Set.new)
+      return [] if resolved.include?(spec.name)
+
+      resolved.add(spec.name)
+      paths = spec.full_require_paths.dup
+
+      spec.runtime_dependencies.each do |dep|
+        dep_spec = find_gem_spec(dep.name, dep.requirement.to_s.delete('= '))
+        dep_spec ||= all_gem_specs.find { |s| s.name == dep.name }
+        paths.concat(collect_paths(dep_spec, resolved)) if dep_spec
+      end
+
+      paths
+    end
+  end
+end

data/lib/boxwerk/gemfile_require_parser.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Boxwerk
+  # Lightweight Gemfile parser that extracts autorequire directives.
+  #
+  # Evaluates a Gemfile in a sandbox that only captures `gem` calls,
+  # avoiding Bundler::Dsl side-effects. Handles:
+  #   gem 'name'                → nil   (require the gem name)
+  #   gem 'name', require: false → []   (skip)
+  #   gem 'name', require: 'x'  → ["x"] (require specific paths)
+  class GemfileRequireParser
+    attr_reader :requires
+
+    def initialize
+      @requires = {}
+    end
+
+    def eval_gemfile(path)
+      instance_eval(File.read(path), path)
+    end
+
+    private
+
+    def source(*); end
+    def ruby(*); end
+    def git_source(*); end
+    def platform(*); end
+    def platforms(*); end
+    def group(*); end
+    def install_if(*); end
+    def plugin(*); end
+
+    def gem(name, *args)
+      opts = args.last.is_a?(Hash) ? args.last : {}
+
+      if opts.key?(:require)
+        val = opts[:require]
+        @requires[name] =
+          case val
+          when false then []
+          when String then [val]
+          when Array then val
+          else nil
+          end
+      else
+        @requires[name] = nil
+      end
+    end
+  end
+end

data/lib/boxwerk/global_context.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Boxwerk
+  # Runtime context for the root box, accessible via +Boxwerk.global+ from
+  # any box context (global boot, package boot, or application code).
+  class GlobalContext
+    # @return [GlobalContext::Autoloader] Autoloader configuration for the root box.
+    attr_reader :autoloader
+
+    def initialize(root_path)
+      @root_path = root_path
+      @autoloader = Autoloader.new(root_path)
+      @default_dirs = []
+    end
+
+    # Autoload configuration for the root box. Provides {AutoloaderMixin}'s
+    # +push_dir+, +collapse+, +ignore+, and +setup+ in +global/boot.rb+.
+    #
+    # Registrations are lazy (autoload entries only) until the framework
+    # eager-loads them after +global/boot.rb+ completes.
+    class Autoloader
+      include AutoloaderMixin
+
+      def initialize(root_path)
+        init_dirs
+        @root_path = root_path
+        @accumulated_entries = []
+      end
+
+      private
+
+      def do_setup(new_push, new_collapse)
+        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)
+          all_entries.concat(ZeitwerkScanner.scan_files_only(abs_dir))
+        end
+
+        return if all_entries.empty?
+
+        ZeitwerkScanner.register_autoloads(Ruby::Box.root, all_entries)
+        @accumulated_entries.concat(all_entries)
+      end
+
+      # Eagerly requires all registered files so child boxes inherit constants.
+      # Called by Setup after global/boot.rb when eager_load_global is true.
+      def eager_load!
+        return if @accumulated_entries.empty?
+
+        root_box = Ruby::Box.root
+        @accumulated_entries.each { |e| root_box.require(e.file) if e.file }
+      end
+
+      # Dir info for the info command (accessed via GlobalContext#dir_info).
+      def dir_info
+        { autoload: @push_dirs.dup, collapse: @collapse_dirs.dup, ignore: @ignore_dirs.dup }
+      end
+    end
+
+    private
+
+    # Records a directory scanned by Setup (e.g. global/) for the info command.
+    def record_scanned_dir(rel_path)
+      @default_dirs << rel_path
+    end
+
+    # Returns combined dir info for the info command.
+    def dir_info
+      al_info = @autoloader.__send__(:dir_info)
+      {
+        autoload: @default_dirs + al_info[:autoload],
+        collapse: al_info[:collapse],
+        ignore: al_info[:ignore],
+      }
+    end
+  end
+end