ace-support-config 0.9.0

data/lib/ace/support/config/atoms/yaml_parser.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "date"
+
+module Ace
+  module Support
+    module Config
+      module Atoms
+        # Pure YAML parsing functions
+        module YamlParser
+          module_function
+
+          # Parse YAML string into Ruby hash
+          # @param yaml_string [String] YAML content to parse
+          # @return [Hash] Parsed YAML content
+          # @raise [YamlParseError] if parsing fails
+          def parse(yaml_string)
+            return {} if yaml_string.nil? || yaml_string.strip.empty?
+
+            YAML.safe_load(yaml_string, permitted_classes: [Symbol, Date], aliases: true)
+          rescue Psych::SyntaxError => e
+            raise YamlParseError, "Failed to parse YAML: #{e.message}"
+          rescue Encoding::CompatibilityError, Encoding::InvalidByteSequenceError => e
+            raise YamlParseError, "Failed to parse YAML (encoding error): #{e.message}"
+          end
+
+          # Convert Ruby hash to YAML string
+          # @param data [Hash] Data to convert
+          # @return [String] YAML representation
+          def dump(data)
+            return "" if data.nil? || data.empty?
+
+            YAML.dump(data)
+          end
+
+          # Check if string is valid YAML
+          # @param yaml_string [String] YAML content to validate
+          # @return [Boolean] true if valid YAML
+          def valid?(yaml_string)
+            parse(yaml_string)
+            true
+          rescue YamlParseError
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/config/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "ace/support/fs"
+
+module Ace
+  module Support
+    module Config
+      # Base error class for all ace-support-config errors
+      class Error < StandardError; end
+
+      # Raised when configuration file is not found
+      class ConfigNotFoundError < Error; end
+
+      # Raised when YAML parsing fails
+      class YamlParseError < Error; end
+
+      # Raised when a path cannot be resolved
+      class PathError < Error; end
+
+      # Raised when merge strategy is invalid
+      class MergeStrategyError < Error; end
+    end
+  end
+end

data/lib/ace/support/config/models/cascade_path.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Config
+      module Models
+        # Represents a configuration cascade path
+        class CascadePath
+          attr_reader :path, :priority, :exists, :type
+
+          # Initialize cascade path
+          # @param path [String] File system path
+          # @param priority [Integer] Priority (lower = higher priority)
+          # @param exists [Boolean] Whether path exists
+          # @param type [Symbol] Type of path (:local, :home, :gem)
+          def initialize(path:, priority: 100, exists: false, type: :local)
+            @path = path.to_s.freeze
+            @priority = priority
+            @exists = exists
+            @type = type
+            freeze
+          end
+
+          # Compare paths by priority
+          # @param other [CascadePath] Other path to compare
+          # @return [Integer] Comparison result
+          def <=>(other)
+            return nil unless other.is_a?(CascadePath)
+
+            priority <=> other.priority
+          end
+
+          # Check if this path should override another
+          # @param other [CascadePath] Other path
+          # @return [Boolean] true if this path has higher priority
+          def overrides?(other)
+            return false unless other.is_a?(CascadePath)
+
+            priority < other.priority
+          end
+
+          # Convert to string
+          # @return [String] The file path
+          def to_s
+            path
+          end
+
+          # Get path as Pathname
+          # @return [Pathname] Path object
+          def pathname
+            require "pathname"
+            Pathname.new(path)
+          end
+
+          # Check if path is absolute
+          # @return [Boolean] true if absolute path
+          def absolute?
+            pathname.absolute?
+          end
+
+          # Check if path is relative
+          # @return [Boolean] true if relative path
+          def relative?
+            !absolute?
+          end
+
+          def ==(other)
+            other.is_a?(self.class) &&
+              other.path == path &&
+              other.priority == priority &&
+              other.type == type
+          end
+
+          def hash
+            [path, priority, type].hash
+          end
+
+          alias_method :eql?, :==
+
+          def inspect
+            attrs = [
+              "path=#{path.inspect}",
+              "type=#{type}",
+              "priority=#{priority}",
+              exists ? "exists" : "missing"
+            ].join(" ")
+
+            "#<#{self.class.name} #{attrs}>"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/config/models/config.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Config
+      module Models
+        # Configuration data structure
+        class Config
+          attr_reader :data, :source, :merge_strategy
+
+          # Initialize configuration
+          # @param data [Hash] Configuration data
+          # @param source [String] Source file or identifier
+          # @param merge_strategy [Symbol] How to merge with other configs
+          def initialize(data = {}, source: nil, merge_strategy: :replace)
+            @data = data || {}
+            @source = source
+            @merge_strategy = merge_strategy
+            freeze
+          end
+
+          # Get configuration value by key path
+          # @param keys [Array<String,Symbol>] Path to value
+          # @return [Object] Value at path or nil
+          def get(*keys)
+            keys = keys.flatten.map(&:to_s)
+            keys.reduce(data) do |current, key|
+              return nil unless current.is_a?(Hash)
+
+              current[key]
+            end
+          end
+
+          # Check if configuration has key path
+          # @param keys [Array<String,Symbol>] Path to check
+          # @return [Boolean] true if path exists
+          def key?(*keys)
+            !get(*keys).nil?
+          end
+
+          # Convert to hash
+          # @return [Hash] Configuration data
+          def to_h
+            data.dup
+          end
+
+          # Get all keys at root level
+          # @return [Array<String>] Root level keys
+          def keys
+            data.keys
+          end
+
+          # Check if configuration is empty
+          # @return [Boolean] true if no configuration data
+          def empty?
+            data.empty?
+          end
+
+          # Iterate over root level key-value pairs
+          def each(&block)
+            data.each(&block)
+          end
+
+          # Create new config with additional data merged in
+          # @param other_data [Hash] Data to merge
+          # @return [Config] New configuration instance
+          def merge(other_data)
+            merged_data = Atoms::DeepMerger.merge(
+              data,
+              other_data,
+              array_strategy: merge_strategy
+            )
+
+            self.class.new(
+              merged_data,
+              source: "#{source}+merged",
+              merge_strategy: merge_strategy
+            )
+          end
+
+          # Alias for backward compatibility
+          alias_method :with, :merge
+
+          # Factory method to wrap a hash and merge additional data, returning a hash
+          # Provides a convenient one-liner for the common pattern:
+          #   Config.new(base, source: "...").merge(overrides).to_h
+          #
+          # @param base [Hash, nil] Base configuration data (nil coerced to empty hash)
+          # @param overrides [Hash, nil] Data to merge on top of base (default: {}, nil coerced to empty hash)
+          # @param source [String] Source identifier for debugging (default: "wrap")
+          # @param merge_strategy [Symbol] How to merge arrays (default: :replace)
+          # @return [Hash] Merged configuration as a plain hash
+          #
+          # @example Single hash wrapping
+          #   Config.wrap(defaults)
+          #   # => { "key" => "default_value" }
+          #
+          # @example Merge two hashes
+          #   Config.wrap(defaults, overrides)
+          #   # => { "key" => "override_value", "other" => "default" }
+          #
+          # @example With options
+          #   Config.wrap(defaults, overrides, source: "git_config", merge_strategy: :union)
+          #
+          # @example Handling nil inputs (type coercion)
+          #   Config.wrap(nil)           # => {}
+          #   Config.wrap({}, nil)       # => {}
+          #   Config.wrap(nil, nil)      # => {}
+          #
+          def self.wrap(base, overrides = {}, source: "wrap", merge_strategy: :replace)
+            # Type coercion: ensure base and overrides are hashes to prevent unexpected behavior
+            base_hash = base.is_a?(Hash) ? base : {}
+            overrides_hash = overrides.is_a?(Hash) ? overrides : {}
+
+            new(base_hash, source: source, merge_strategy: merge_strategy)
+              .merge(overrides_hash)
+              .to_h
+          end
+
+          def ==(other)
+            other.is_a?(self.class) &&
+              other.data == data &&
+              other.source == source &&
+              other.merge_strategy == merge_strategy
+          end
+
+          def inspect
+            "#<#{self.class.name} source=#{source.inspect} keys=#{keys.inspect}>"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/config/models/config_group.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Config
+      module Models
+        # ConfigGroup represents a set of files sharing the same effective config
+        class ConfigGroup
+          # Default scope name when no path rule matches and no distributed config is found
+          DEFAULT_SCOPE_NAME = "project default"
+
+          # rule_config: Original path rule config (before cascade merge), used for grouping
+          #   - When a path rule matches, this contains only the rule's own overrides
+          #   - nil for distributed config matches or project default
+          #   - Separates grouping (use rule_config) from message generation (use config)
+          attr_reader :name, :source, :config, :rule_config, :files
+
+          def initialize(name:, source:, config:, files: [], rule_config: nil)
+            @name = name
+            @source = source
+            @config = config || {}
+            @rule_config = rule_config
+            @files = Array(files)
+            freeze
+          end
+
+          def add_file(file)
+            self.class.new(
+              name: name,
+              source: source,
+              config: config,
+              rule_config: rule_config,
+              files: files + [file]
+            )
+          end
+
+          def file_count
+            files.length
+          end
+
+          def ==(other)
+            other.is_a?(self.class) &&
+              other.name == name &&
+              other.source == source &&
+              other.config == config &&
+              other.rule_config == rule_config &&
+              other.files == files
+          end
+
+          def inspect
+            "#<#{self.class.name} name=#{name.inspect} files=#{files.length}>"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/config/molecules/config_finder.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Ace
+  module Support
+    module Config
+      module Molecules
+        # Find configuration files in cascade paths
+        class ConfigFinder
+          # Common config file patterns
+          DEFAULT_FILE_PATTERNS = %w[
+            settings.yml
+            settings.yaml
+            config.yml
+            config.yaml
+          ].freeze
+
+          attr_reader :config_dir, :defaults_dir, :gem_path, :file_patterns, :start_path
+
+          # Initialize finder with configurable paths
+          # @param config_dir [String] User config folder name (default: ".ace")
+          # @param defaults_dir [String] Gem defaults folder name (default: ".ace-defaults")
+          # @param gem_path [String, nil] Gem root path for defaults
+          # @param file_patterns [Array<String>] File patterns to look for
+          # @param use_traversal [Boolean] Whether to use directory traversal (default: true)
+          # @param start_path [String, nil] Starting path for traversal (default: Dir.pwd)
+          def initialize(
+            config_dir: ".ace",
+            defaults_dir: ".ace-defaults",
+            gem_path: nil,
+            file_patterns: DEFAULT_FILE_PATTERNS,
+            use_traversal: true,
+            start_path: nil
+          )
+            @config_dir = config_dir
+            @defaults_dir = defaults_dir
+            @gem_path = gem_path
+            @file_patterns = file_patterns
+            @use_traversal = use_traversal
+            @start_path = start_path ? Ace::Support::Fs::Atoms::PathExpander.expand(start_path) : Dir.pwd
+            @search_paths = build_search_paths
+          end
+
+          # Find all config files in cascade order
+          # @return [Array<Models::CascadePath>] Found config paths
+          def find_all
+            paths = []
+
+            @search_paths.each_with_index do |base_path, index|
+              priority = index * 10 # Lower index = higher priority
+
+              @file_patterns.each do |pattern|
+                found = find_in_path(base_path, pattern, priority)
+                paths.concat(found)
+              end
+            end
+
+            # Add gem defaults with lowest priority
+            gem_config = find_gem_defaults
+            paths.concat(gem_config) if gem_config
+
+            paths.sort
+          end
+
+          # Find first existing config file
+          # @return [Models::CascadePath, nil] First found config path
+          def find_first
+            find_all.find(&:exists)
+          end
+
+          # Find configs by type
+          # @param type [Symbol] Type to filter (:local, :home, :gem)
+          # @return [Array<Models::CascadePath>] Configs of given type
+          def find_by_type(type)
+            find_all.select { |path| path.type == type }
+          end
+
+          # Find a specific config file using the cascade
+          # @param filename [String] Specific filename to find
+          # @return [String, nil] Path to the first found config file
+          def find_file(filename)
+            # Use pre-built search_paths (respects @use_traversal setting)
+            @search_paths.each do |dir|
+              file_path = File.join(dir, filename)
+              return file_path if File.exist?(file_path)
+            end
+
+            # Check gem defaults if available
+            if @gem_path
+              gem_default_path = File.join(@gem_path, @defaults_dir, filename)
+              return gem_default_path if File.exist?(gem_default_path)
+            end
+
+            nil
+          end
+
+          # Find all instances of a config file in the cascade
+          # @param filename [String] Specific filename to find
+          # @return [Array<String>] All found file paths in cascade order
+          def find_all_files(filename)
+            files = []
+
+            # Use pre-built search_paths (respects @use_traversal setting)
+            @search_paths.each do |dir|
+              file_path = File.join(dir, filename)
+              files << file_path if File.exist?(file_path)
+            end
+
+            # Check gem defaults if available
+            if @gem_path
+              gem_default_path = File.join(@gem_path, @defaults_dir, filename)
+              files << gem_default_path if File.exist?(gem_default_path)
+            end
+
+            files
+          end
+
+          # Get the search paths being used
+          # @return [Array<String>] Ordered list of search paths
+          attr_reader :search_paths
+
+          private
+
+          # Build search paths using directory traversal
+          # @return [Array<String>] Expanded search paths
+          def build_search_paths
+            if @use_traversal
+              traverser = Ace::Support::Fs::Molecules::DirectoryTraverser.new(
+                config_dir: @config_dir,
+                start_path: @start_path
+              )
+              paths = traverser.find_config_directories
+
+              # Add home directory if not already included
+              home_config = File.expand_path("~/#{@config_dir}")
+              paths << home_config unless paths.include?(home_config)
+
+              paths
+            else
+              # Simple default paths
+              [
+                File.join(@start_path, @config_dir),
+                File.expand_path("~/#{@config_dir}")
+              ]
+            end
+          end
+
+          # Find config files in a specific path with pattern
+          # @param base_path [String] Base path to search
+          # @param pattern [String] File pattern
+          # @param base_priority [Integer] Base priority for found files
+          # @return [Array<Models::CascadePath>] Found paths
+          def find_in_path(base_path, pattern, base_priority)
+            paths = []
+            full_pattern = File.join(base_path, pattern)
+
+            # Determine type based on path
+            type = determine_type(base_path)
+
+            Dir.glob(full_pattern).each_with_index do |file, index|
+              next unless File.file?(file)
+
+              paths << Models::CascadePath.new(
+                path: file,
+                priority: base_priority + index,
+                exists: true,
+                type: type
+              )
+            end
+
+            # If no files found but we're looking for a specific file, add as missing
+            if paths.empty? && !pattern.include?("*")
+              file_path = File.join(base_path, pattern)
+              paths << Models::CascadePath.new(
+                path: file_path,
+                priority: base_priority,
+                exists: false,
+                type: type
+              )
+            end
+
+            paths
+          end
+
+          # Find gem's default configs
+          # @return [Array<Models::CascadePath>] Gem default paths
+          def find_gem_defaults
+            return nil unless @gem_path
+
+            defaults_path = File.join(@gem_path, @defaults_dir)
+            return nil unless Dir.exist?(defaults_path)
+
+            paths = []
+
+            @file_patterns.each_with_index do |pattern, index|
+              Dir.glob(File.join(defaults_path, pattern)).each do |file|
+                next unless File.file?(file)
+
+                paths << Models::CascadePath.new(
+                  path: file,
+                  priority: 2000 + index, # Very low priority for gem defaults
+                  exists: true,
+                  type: :gem
+                )
+              end
+            end
+
+            paths.empty? ? nil : paths
+          end
+
+          # Determine config type from path
+          # @param path [String] Path to check
+          # @return [Symbol] Config type
+          def determine_type(path)
+            expanded = Ace::Support::Fs::Atoms::PathExpander.expand(path)
+            home = Ace::Support::Fs::Atoms::PathExpander.expand("~")
+
+            # Use @start_path (stable) instead of Dir.pwd (mutable)
+            if expanded.start_with?(@start_path)
+              :local
+            elsif expanded.start_with?(home)
+              :home
+            else
+              :gem
+            end
+          end
+        end
+      end
+    end
+  end
+end