boxwerk 0.1.0 → 0.3.0

data/lib/boxwerk/package.rb

@@ -1,51 +1,94 @@
 # frozen_string_literal: true
 
-require 'yaml'
-
 module Boxwerk
-  # Represents a package loaded from package.yml
+  # Data class representing a package. Reads the standard package.yml format.
   class Package
-    attr_reader :name, :path, :exports, :imports, :box, :loaded_exports
+    attr_reader :name, :config
 
-    def initialize(name, path)
+    def initialize(name:, config: {})
       @name = name
-      @path = path
-      @box = nil
-      @exports = []
-      @imports = []
-      @loaded_exports = {}
+      @config = config
+    end
 
-      load_config
+    def root?
+      @name == '.'
     end
 
-    def booted?
-      !@box.nil?
+    def dependencies
+      @config['dependencies'] || []
     end
 
-    def box=(box_instance)
-      @box = box_instance
+    def enforce_dependencies?
+      @config['enforce_dependencies'] == true
     end
 
-    def dependencies
-      @imports.map do |item|
-        if item.is_a?(String)
-          item
+    def ==(other)
+      other.is_a?(Package) && name == other.name
+    end
+
+    alias eql? ==
+
+    def hash
+      name.hash
+    end
+
+    def to_s
+      name
+    end
+
+    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
-          item.keys.first
+          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
-    end
 
-    private
+      new(name: name, config: config)
+    end
 
-    def load_config
-      config_path = File.join(@path, 'package.yml')
-      return unless File.exist?(config_path)
+    # 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
 
-      config = YAML.load_file(config_path)
+    # 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
 
-      @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