myway_config 0.1.1

data/lib/myway_config/base.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+require 'anyway_config'
+require 'yaml'
+
+module MywayConfig
+  # Base configuration class that extends Anyway::Config with additional features
+  #
+  # Provides:
+  # - ConfigSection coercion for nested configuration
+  # - XDG config file loading
+  # - Bundled defaults loading with environment overrides
+  # - Environment detection helpers
+  # - Deep merge utilities
+  #
+  # @example Define a configuration class (recommended)
+  #   class MyApp::Config < MywayConfig::Base
+  #     config_name :myapp
+  #     env_prefix :myapp
+  #     defaults_path File.expand_path('config/defaults.yml', __dir__)
+  #     auto_configure!
+  #   end
+  #
+  # @example Manual configuration (when custom coercions are needed)
+  #   class MyApp::Config < MywayConfig::Base
+  #     config_name :myapp
+  #     env_prefix :myapp
+  #     defaults_path File.expand_path('config/defaults.yml', __dir__)
+  #
+  #     attr_config :database, :api, :log_level
+  #
+  #     coerce_types(
+  #       database: config_section_coercion(:database),
+  #       api: config_section_coercion(:api),
+  #       log_level: ->(v) { v.to_s.upcase.to_sym }
+  #     )
+  #   end
+  #
+  class Base < Anyway::Config
+    class << self
+      # Register a defaults file path for this config class
+      #
+      # @param path [String] absolute path to the defaults.yml file
+      # @raise [ConfigurationError] if the file does not exist
+      def defaults_path(path = nil)
+        if path
+          raise ConfigurationError, "Defaults file not found: #{path}" unless File.exist?(path)
+          @defaults_path = path
+          # Register with the loader
+          MywayConfig::Loaders::DefaultsLoader.register(config_name, path)
+        end
+        @defaults_path
+      end
+
+      # Load and cache the schema from defaults file
+      #
+      # @return [Hash] the defaults section from the YAML file
+      def schema
+        @schema ||= begin
+          return {} unless @defaults_path && File.exist?(@defaults_path)
+
+          content = File.read(@defaults_path)
+          raw = YAML.safe_load(
+            content,
+            permitted_classes: [Symbol],
+            symbolize_names: true,
+            aliases: true
+          ) || {}
+          raw[:defaults] || {}
+        end
+      end
+
+      # Create a coercion that merges incoming value with schema defaults for a section
+      #
+      # This ensures environment variables don't lose other defaults.
+      #
+      # @param section_key [Symbol] the section key in the schema
+      # @return [Proc] coercion proc for use with coerce_types
+      def config_section_coercion(section_key)
+        defaults = schema[section_key] || {}
+        ->(v) {
+          return v if v.is_a?(MywayConfig::ConfigSection)
+
+          incoming = v || {}
+          # Deep merge: defaults first, then overlay incoming values
+          merged = deep_merge_hashes(defaults.dup, incoming)
+          MywayConfig::ConfigSection.new(merged)
+        }
+      end
+
+      # Simple ConfigSection coercion without schema defaults
+      #
+      # @return [Proc] coercion proc for use with coerce_types
+      def config_section
+        ->(v) {
+          return v if v.is_a?(MywayConfig::ConfigSection)
+          MywayConfig::ConfigSection.new(v || {})
+        }
+      end
+
+      # Symbol coercion helper
+      #
+      # @return [Proc] coercion proc that converts to symbol
+      def to_symbol
+        ->(v) { v.nil? ? nil : v.to_s.to_sym }
+      end
+
+      # Deep merge helper for coercion
+      #
+      # @param base [Hash] base hash
+      # @param overlay [Hash] overlay hash (takes precedence)
+      # @return [Hash] merged hash
+      def deep_merge_hashes(base, overlay)
+        base.merge(overlay) do |_key, old_val, new_val|
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            deep_merge_hashes(old_val, new_val)
+          else
+            new_val.nil? ? old_val : new_val
+          end
+        end
+      end
+
+      # Get the current environment
+      #
+      # Override this method to customize environment detection.
+      # Default priority: RAILS_ENV > RACK_ENV > 'development'
+      #
+      # @return [String] current environment name
+      def env
+        Anyway::Settings.current_environment ||
+          ENV['RAILS_ENV'] ||
+          ENV['RACK_ENV'] ||
+          'development'
+      end
+
+      # Returns list of valid environment names from bundled defaults
+      #
+      # @return [Array<Symbol>] valid environment names
+      def valid_environments
+        MywayConfig::Loaders::DefaultsLoader.valid_environments(config_name)
+      end
+
+      # Check if current environment is valid
+      #
+      # @return [Boolean] true if environment has a config section
+      def valid_environment?
+        MywayConfig::Loaders::DefaultsLoader.valid_environment?(config_name, env)
+      end
+
+      # Define predicate methods for each environment in the config
+      #
+      # Generates instance methods like `development?`, `production?`, `staging?`
+      # based on the environment names found in the YAML config file.
+      #
+      # @return [Array<Symbol>] list of defined method names
+      def define_environment_predicates
+        valid_environments.map do |env_name|
+          method_name = "#{env_name}?"
+          define_method(method_name) do
+            self.class.env == env_name.to_s
+          end
+          method_name.to_sym
+        end
+      end
+
+      # Auto-configure attributes and coercions from the YAML schema
+      #
+      # This method reads the defaults section from the YAML file and
+      # automatically generates attr_config declarations and coercions.
+      # Hash values become ConfigSection objects with method-style access.
+      #
+      # @example Minimal config class
+      #   class Xyzzy::Config < MywayConfig::Base
+      #     config_name :xyzzy
+      #     env_prefix  :xyzzy
+      #     defaults_path File.expand_path('config/defaults.yml', __dir__)
+      #     auto_configure!
+      #   end
+      #
+      def auto_configure!
+        raise ConfigurationError, 'defaults_path must be set before auto_configure!' unless @defaults_path
+
+        coercions = {}
+
+        schema.each do |key, value|
+          # Pass boolean defaults to attr_config so anyway_config creates predicate methods
+          if boolean?(value)
+            attr_config key => value
+          else
+            attr_config key
+          end
+
+          coercions[key] = if value.is_a?(Hash)
+                             config_section_coercion(key)
+                           elsif value.is_a?(Symbol)
+                             to_symbol
+                           end
+        end
+
+        coerce_types(coercions.compact)
+        define_environment_predicates
+        validate_environment!
+      end
+
+      # Check if a value is a boolean
+      #
+      # @param value [Object] the value to check
+      # @return [Boolean] true if value is true or false
+      def boolean?(value)
+        value.is_a?(TrueClass) || value.is_a?(FalseClass)
+      end
+
+      # Validate that the current environment is defined in the config
+      #
+      # @raise [ConfigurationError] if environment is not valid
+      # @return [void]
+      def validate_environment!
+        return unless @defaults_path
+        return if valid_environment?
+
+        raise ConfigurationError,
+              "Invalid environment '#{env}'. Valid environments: #{valid_environments.join(', ')}"
+      end
+    end
+
+    # ==========================================================================
+    # Instance Methods
+    # ==========================================================================
+
+    # Initialize configuration from defaults, a file path, or a Hash
+    #
+    # @param source [nil, String, Pathname, Hash] configuration source
+    #   - nil: use defaults and environment overrides
+    #   - String/Pathname: path to a YAML config file
+    #   - Hash: direct configuration overrides
+    #
+    # @example Standard usage (defaults + environment)
+    #   config = MyConfig.new
+    #
+    # @example Load from a custom file path
+    #   config = MyConfig.new('/path/to/custom.yml')
+    #   config = MyConfig.new(Pathname.new('/path/to/custom.yml'))
+    #
+    # @example With Hash overrides
+    #   config = MyConfig.new(database: { host: 'custom.local' })
+    #
+    def initialize(source = nil)
+      overrides = case source
+                  when String, Pathname
+                    load_from_file(source.to_s)
+                  when Hash
+                    source
+                  when nil
+                    nil
+                  else
+                    raise ConfigurationError, "Invalid source: expected String, Pathname, Hash, or nil"
+                  end
+
+      self.class.validate_environment!
+      super(overrides)
+    end
+
+    private
+
+    def load_from_file(path)
+      raise ConfigurationError, "Config file not found: #{path}" unless File.exist?(path)
+
+      content = File.read(path)
+      raw = YAML.safe_load(
+        content,
+        permitted_classes: [Symbol],
+        symbolize_names: true,
+        aliases: true
+      ) || {}
+
+      environment = self.class.env
+
+      if raw.key?(:defaults)
+        base = raw[:defaults] || {}
+        env_key = environment.to_sym
+        env_overrides = raw[env_key] || {}
+        self.class.deep_merge_hashes(base, env_overrides)
+      else
+        raw
+      end
+    end
+
+    public
+
+    # Get the current environment name
+    #
+    # @return [String]
+    def environment
+      self.class.env
+    end
+
+    # Check if environment is valid
+    #
+    # @return [Boolean]
+    def valid_environment?
+      self.class.valid_environment?
+    end
+  end
+end

data/lib/myway_config/config_section.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module MywayConfig
+  # ConfigSection provides method access to nested configuration hashes
+  #
+  # This allows configuration values to be accessed using method syntax
+  # instead of hash bracket notation, making config access more readable.
+  # Includes Enumerable for full Hash-like iteration support.
+  #
+  # @example Basic usage
+  #   section = ConfigSection.new(host: 'localhost', port: 5432)
+  #   section.host        # => 'localhost'
+  #   section[:host]      # => 'localhost'
+  #   section['host']     # => 'localhost'
+  #
+  # @example Nested sections
+  #   section = ConfigSection.new(database: { host: 'localhost', port: 5432 })
+  #   section.database.host  # => 'localhost'
+  #
+  # @example Hash-like behavior
+  #   section.keys           # => [:host, :port]
+  #   section.values         # => ['localhost', 5432]
+  #   section.fetch(:host)   # => 'localhost'
+  #   section.map { |k, v| "#{k}=#{v}" }  # => ['host=localhost', 'port=5432']
+  #
+  class ConfigSection
+    include Enumerable
+    def initialize(hash = {})
+      @data = {}
+      (hash || {}).each do |key, value|
+        @data[key.to_sym] = value.is_a?(Hash) ? ConfigSection.new(value) : value
+      end
+    end
+
+    def method_missing(method, *args, &block)
+      key = method.to_s
+      if key.end_with?('=')
+        @data[key.chomp('=').to_sym] = args.first
+      elsif @data.key?(method)
+        @data[method]
+      else
+        nil
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      key = method.to_s.chomp('=').to_sym
+      @data.key?(key) || super
+    end
+
+    # Convert to a plain Ruby hash
+    #
+    # @return [Hash] the configuration as a hash
+    def to_h
+      @data.transform_values do |v|
+        v.is_a?(ConfigSection) ? v.to_h : v
+      end
+    end
+
+    # Access a value by key
+    #
+    # @param key [Symbol, String] the key to access
+    # @return [Object] the value
+    def [](key)
+      @data[key.to_sym]
+    end
+
+    # Set a value by key
+    #
+    # @param key [Symbol, String] the key to set
+    # @param value [Object] the value to set
+    def []=(key, value)
+      @data[key.to_sym] = value
+    end
+
+    # Merge with another ConfigSection or hash
+    #
+    # @param other [ConfigSection, Hash] the other config to merge
+    # @return [ConfigSection] a new merged ConfigSection
+    def merge(other)
+      other_hash = other.is_a?(ConfigSection) ? other.to_h : other
+      ConfigSection.new(deep_merge(to_h, other_hash || {}))
+    end
+
+    # Get all keys
+    #
+    # @return [Array<Symbol>] the keys
+    def keys
+      @data.keys
+    end
+
+    # Iterate over key-value pairs
+    #
+    # @yield [key, value] each key-value pair
+    def each(&block)
+      @data.each(&block)
+    end
+
+    # Check if a key exists
+    #
+    # @param key [Symbol, String] the key to check
+    # @return [Boolean] true if the key exists
+    def key?(key)
+      @data.key?(key.to_sym)
+    end
+
+    # Check if the section is empty
+    #
+    # @return [Boolean] true if no keys are present
+    def empty?
+      @data.empty?
+    end
+
+    # Get all values
+    #
+    # @return [Array] the values
+    def values
+      @data.values
+    end
+
+    # Get the number of keys
+    #
+    # @return [Integer] the number of keys
+    def size
+      @data.size
+    end
+    alias length size
+
+    # Fetch a value with optional default
+    #
+    # @param key [Symbol, String] the key to fetch
+    # @param default [Object] optional default value
+    # @yield optional block for default value
+    # @return [Object] the value or default
+    # @raise [KeyError] if key not found and no default given
+    def fetch(key, *args, &block)
+      @data.fetch(key.to_sym, *args, &block)
+    end
+
+    # Dig into nested values
+    #
+    # @param keys [Array<Symbol, String>] the keys to dig through
+    # @return [Object, nil] the value or nil if not found
+    def dig(*keys)
+      keys.reduce(self) do |obj, key|
+        return nil unless obj.respond_to?(:[])
+        obj[key]
+      end
+    end
+
+    # Alias for key? to match Hash interface
+    alias has_key? key?
+    alias include? key?
+    alias member? key?
+
+    private
+
+    def deep_merge(base, overlay)
+      base.merge(overlay) do |_key, old_val, new_val|
+        if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+          deep_merge(old_val, new_val)
+        else
+          new_val
+        end
+      end
+    end
+  end
+end

data/lib/myway_config/loaders/defaults_loader.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'anyway_config'
+require 'yaml'
+
+module MywayConfig
+  module Loaders
+    # Bundled Defaults Loader for Anyway Config
+    #
+    # Loads default configuration values from a YAML file bundled with a gem.
+    # This ensures defaults are always available regardless of where the gem is installed.
+    #
+    # The defaults.yml file structure:
+    #   defaults:      # Base values for all environments
+    #     database:
+    #       host: localhost
+    #       port: 5432
+    #   development:   # Overrides for development
+    #     database:
+    #       name: myapp_development
+    #   test:          # Overrides for test
+    #     database:
+    #       name: myapp_test
+    #   production:    # Overrides for production
+    #     database:
+    #       sslmode: require
+    #
+    # This loader deep-merges `defaults` with the current environment's overrides.
+    #
+    # Loading priority (lowest to highest):
+    # 1. Bundled defaults (this loader)
+    # 2. XDG user config (~/.config/app/app.yml)
+    # 3. Project config (./config/app.yml)
+    # 4. Local overrides (./config/app.local.yml)
+    # 5. Environment variables (APP_*)
+    # 6. Programmatic (configure block)
+    #
+    class DefaultsLoader < Anyway::Loaders::Base
+      # Registry of defaults paths keyed by config name
+      @defaults_paths = {}
+
+      class << self
+        attr_reader :defaults_paths
+
+        # Register a defaults file path for a config name
+        #
+        # @param name [Symbol, String] the config name
+        # @param path [String] absolute path to the defaults.yml file
+        def register(name, path)
+          @defaults_paths[name.to_sym] = path
+        end
+
+        # Get the registered defaults path for a config name
+        #
+        # @param name [Symbol, String] the config name
+        # @return [String, nil] the path or nil if not registered
+        def defaults_path(name)
+          @defaults_paths[name.to_sym]
+        end
+
+        # Check if defaults file exists for a config name
+        #
+        # @param name [Symbol, String] the config name
+        # @return [Boolean]
+        def defaults_exist?(name)
+          path = defaults_path(name)
+          path && File.exist?(path)
+        end
+
+        # Load and parse the raw YAML content
+        #
+        # @param name [Symbol, String] the config name
+        # @return [Hash] parsed YAML with symbolized keys
+        def load_raw_yaml(name)
+          path = defaults_path(name)
+          return {} unless path && File.exist?(path)
+
+          content = File.read(path)
+          YAML.safe_load(
+            content,
+            permitted_classes: [Symbol],
+            symbolize_names: true,
+            aliases: true
+          ) || {}
+        rescue Psych::SyntaxError => e
+          warn "MywayConfig: Failed to parse bundled defaults #{path}: #{e.message}"
+          {}
+        end
+
+        # Extract the schema (attribute names) from the defaults section
+        #
+        # @param name [Symbol, String] the config name
+        # @return [Hash] the defaults section containing all attribute definitions
+        def schema(name)
+          raw = load_raw_yaml(name)
+          raw[:defaults] || {}
+        end
+
+        # Returns valid environment names from the config file
+        #
+        # Valid environments are top-level keys excluding 'defaults'.
+        #
+        # @param name [Symbol, String] the config name
+        # @return [Array<Symbol>] list of valid environment names
+        def valid_environments(name)
+          raw = load_raw_yaml(name)
+          raw.keys.reject { |k| k == :defaults }.sort
+        end
+
+        # Check if a given environment name is valid
+        #
+        # @param name [Symbol, String] the config name
+        # @param env [String, Symbol] environment name to check
+        # @return [Boolean] true if environment is valid
+        def valid_environment?(name, env)
+          return false if env.nil? || env.to_s.empty?
+          return false if env.to_s == 'defaults'
+
+          valid_environments(name).include?(env.to_sym)
+        end
+      end
+
+      def call(name:, **_options)
+        return {} unless self.class.defaults_exist?(name)
+
+        path = self.class.defaults_path(name)
+        trace!(:bundled_defaults, path: path) do
+          load_and_merge_for_environment(name)
+        end
+      end
+
+      private
+
+      # Load defaults and deep merge with environment-specific overrides
+      #
+      # @param name [Symbol, String] the config name
+      # @return [Hash] merged configuration for current environment
+      def load_and_merge_for_environment(name)
+        raw = self.class.load_raw_yaml(name)
+        return {} if raw.empty?
+
+        # Start with the defaults section
+        defaults = raw[:defaults] || {}
+
+        # Deep merge with environment-specific overrides
+        env = current_environment
+        env_overrides = raw[env.to_sym] || {}
+
+        deep_merge(defaults, env_overrides)
+      end
+
+      # Deep merge two hashes, with overlay taking precedence
+      #
+      # @param base [Hash] base configuration
+      # @param overlay [Hash] overlay configuration (takes precedence)
+      # @return [Hash] merged result
+      def deep_merge(base, overlay)
+        base.merge(overlay) do |_key, old_val, new_val|
+          if old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            deep_merge(old_val, new_val)
+          else
+            new_val
+          end
+        end
+      end
+
+      # Determine the current environment
+      #
+      # @return [String] current environment name
+      def current_environment
+        Anyway::Settings.current_environment ||
+          ENV['RAILS_ENV'] ||
+          ENV['RACK_ENV'] ||
+          'development'
+      end
+    end
+  end
+end