config-merge 7.1.13

data/lib/config/merge/flag_file/three_way_merger.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+require_relative "result"
+
+module Config
+  module Merge
+    module FlagFile
+      # Merges option records using base-aware per-flag policy.
+      #
+      # The conventional roles are base, ours (the destination/current side), and
+      # theirs (the incoming side). Rules compare normalized values while output
+      # retains original option spelling, argument text, comments, and blank lines.
+      class ThreeWayMerger
+        attr_reader :base, :ours, :theirs, :policy
+
+        def initialize(base:, ours:, theirs:, policy:)
+          @parser = Parser.new
+          @base = parse(base)
+          @ours = parse(ours)
+          @theirs = parse(theirs)
+          @policy = policy
+        end
+
+        def merge
+          decisions = merge_decisions
+          partial = render(decisions.fetch(:selected))
+          conflicts = decisions.fetch(:conflicts)
+          Result.new(output: conflicts.empty? ? partial : nil, conflicts: conflicts, partial_output: partial)
+        end
+
+        private
+
+        def merge_decisions
+          DecisionEngine.new(base: base, ours: ours, theirs: theirs, policy: policy).merge
+        end
+
+        def render(selected)
+          output = OutputRenderer.new(selected, base: base, ours: ours, theirs: theirs, policy: policy).render
+          output += "\n" if !output.empty? && trailing_newline?
+          output
+        end
+
+        def parse(value)
+          value.is_a?(Document) ? value : @parser.parse(value)
+        end
+
+        def trailing_newline?
+          return ours.trailing_newline if ours.trailing_newline == theirs.trailing_newline
+          return theirs.trailing_newline if ours.trailing_newline == base.trailing_newline
+
+          ours.trailing_newline
+        end
+      end
+
+      # Makes per-flag base/ours/theirs decisions.
+      class DecisionEngine
+        def initialize(base:, ours:, theirs:, policy:)
+          @base = base
+          @ours = ours
+          @theirs = theirs
+          @policy = policy
+        end
+
+        def merge
+          selected = {}
+          conflicts = []
+          flags.each do |flag|
+            chosen, conflict = choose(flag, options(@base, flag), options(@ours, flag), options(@theirs, flag))
+            selected[flag] = chosen if chosen
+            conflicts << conflict if conflict
+          end
+          { selected: selected, conflicts: conflicts }
+        end
+
+        private
+
+        def flags
+          (@base.options + @ours.options + @theirs.options).map(&:flag).uniq
+        end
+
+        def options(document, flag)
+          document.options.select { |option| option.flag == flag }
+        end
+
+        def choose(flag, base, ours, theirs)
+          rule = @policy.rule_for(flag)
+          base_key = semantic_options(base, rule)
+          ours_key = semantic_options(ours, rule)
+          theirs_key = semantic_options(theirs, rule)
+          return [sourced(ours, :ours), nil] if ours_key == theirs_key || theirs_key == base_key
+          return [sourced(theirs, :theirs), nil] if ours_key == base_key
+          if rule.cardinality == :repeatable && rule.on_conflict == :union
+            return [merge_repeatable(base, ours, theirs, rule), nil]
+          end
+
+          resolve_conflict(flag, base, ours, theirs, rule)
+        end
+
+        def resolve_conflict(flag, base, ours, theirs, rule)
+          case rule.on_conflict
+          when :ours then [sourced(ours, :ours), nil]
+          when :theirs then [sourced(theirs, :theirs), nil]
+          when :base then [sourced(base, :base), nil]
+          when :union then [stable_union(ours, theirs, rule), nil]
+          when :conflict then [nil, Conflict.new(flag: flag, base: base, ours: ours, theirs: theirs)]
+          end
+        end
+
+        def merge_repeatable(base, ours, theirs, rule)
+          counts = [base, ours, theirs].map { |options| option_counts(options, rule) }
+          keys = counts.flat_map(&:keys).uniq
+          targets = keys.to_h { |key| [key, target_count(key, counts)] }
+          select_records(targets, [[ours, :ours], [theirs, :theirs], [base, :base]], rule)
+        end
+
+        def target_count(key, counts)
+          base_count, ours_count, theirs_count = counts.map { |count| count.fetch(key, 0) }
+          removed = [base_count - ours_count, base_count - theirs_count, 0].max
+          added = [ours_count - base_count, theirs_count - base_count, 0].max
+          [base_count - removed, 0].max + added
+        end
+
+        def stable_union(ours, theirs, rule)
+          seen = {}
+          sourced(ours, :ours).concat(sourced(theirs, :theirs)).each_with_object([]) do |(option, source), selected|
+            key = semantic_key(option, rule)
+            next if seen[key]
+
+            seen[key] = true
+            selected << [option, source]
+          end
+        end
+
+        def select_records(targets, sources, rule)
+          remaining = targets.dup
+          sources.each_with_object([]) do |(options, source), selected|
+            options.each do |option|
+              key = semantic_key(option, rule)
+              next unless remaining.fetch(key, 0).positive?
+
+              selected << [option, source]
+              remaining[key] -= 1
+            end
+          end
+        end
+
+        def sourced(options, source)
+          options.map { |option| [option, source] }
+        end
+
+        def option_counts(options, rule)
+          options.each_with_object(Hash.new(0)) { |option, counts| counts[semantic_key(option, rule)] += 1 }
+        end
+
+        def semantic_options(options, rule)
+          options.map { |option| semantic_key(option, rule) }
+        end
+
+        def semantic_key(option, rule)
+          [option.flag, NormalizerRegistry.normalize(rule.normalizer, option.value)]
+        end
+      end
+
+      # Renders selected records in destination order and retains opaque source lines.
+      class OutputRenderer
+        def initialize(selected, base:, ours:, theirs:, policy:)
+          @selected = selected
+          @documents = [[ours, 0], [theirs, 1], [base, 2]]
+          @policy = policy
+        end
+
+        def render
+          records.sort_by do |line_number, source_rank, position, sequence, _raw|
+            [line_number, source_rank, position, sequence]
+          end
+                 .map(&:last).join("\n")
+        end
+
+        private
+
+        def records
+          @opaque_remaining = opaque_counts
+          @sequence = 0
+          selected_records + @documents.flat_map do |document, source_rank|
+            opaque_records(document, source_rank)
+          end
+        end
+
+        def selected_records
+          @selected.flat_map do |_flag, entries|
+            entries.map do |option, source|
+              record(option.line_number, source_rank(source), option.position, option.raw)
+            end
+          end
+        end
+
+        def source_rank(source)
+          { ours: 0, theirs: 1, base: 2 }.fetch(source)
+        end
+
+        def opaque_records(document, source_rank)
+          document.opaque_lines.filter_map do |line_number, position, raw|
+            next unless @opaque_remaining.fetch(raw, 0).positive?
+
+            @opaque_remaining[raw] -= 1
+            record(line_number, source_rank, position, raw)
+          end
+        end
+
+        def record(line_number, source_rank, position, raw)
+          value = [line_number, source_rank, position, @sequence, raw]
+          @sequence += 1
+          value
+        end
+
+        def opaque_counts
+          base_counts = line_counts(@documents[2].first)
+          ours_counts = line_counts(@documents[0].first)
+          theirs_counts = line_counts(@documents[1].first)
+          keys = base_counts.keys | ours_counts.keys | theirs_counts.keys
+          keys.to_h { |raw| [raw, merged_line_count(raw, base_counts, ours_counts, theirs_counts)] }
+        end
+
+        def line_counts(document)
+          document.opaque_lines.each_with_object(Hash.new(0)) do |(_line, _position, raw), result|
+            result[raw] += 1
+          end
+        end
+
+        def merged_line_count(raw, base_counts, ours_counts, theirs_counts)
+          base_count = base_counts.fetch(raw, 0)
+          ours_count = ours_counts.fetch(raw, 0)
+          theirs_count = theirs_counts.fetch(raw, 0)
+          return ours_count if ours_count == theirs_count
+          return theirs_count if ours_count == base_count
+          return ours_count if theirs_count == base_count
+
+          [ours_count, theirs_count].max
+        end
+      end
+    end
+  end
+end

data/lib/config/merge/normalizer_registry.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Config
+  module Merge
+    # Thread-safe registry of named value normalizers used for semantic comparison.
+    # Normalizers change comparison values only; rendering keeps the original text.
+    class NormalizerRegistry
+      class UnknownNormalizerError < ArgumentError; end
+
+      @monitor = Monitor.new
+      @normalizers = {
+        identity: ->(value) { value },
+        strip: ->(value) { value&.strip },
+        downcase: ->(value) { value&.downcase }
+      }
+
+      class << self
+        def register(name, callable = nil, replace: false, &block)
+          normalizer = callable || block
+          raise ArgumentError, "normalizer must respond to #call" unless normalizer.respond_to?(:call)
+
+          key = normalize_name(name)
+          @monitor.synchronize do
+            raise ArgumentError, "Normalizer already registered: #{key}" if @normalizers.key?(key) && !replace
+
+            @normalizers[key] = normalizer
+          end
+          key
+        end
+
+        def normalize(name, value)
+          key = normalize_name(name)
+          normalizer = @monitor.synchronize { @normalizers[key] }
+          raise UnknownNormalizerError, "Unknown normalizer: #{key}" unless normalizer
+
+          normalizer.call(value)
+        end
+
+        def registered?(name)
+          @monitor.synchronize { @normalizers.key?(normalize_name(name)) }
+        end
+
+        def names
+          @monitor.synchronize { @normalizers.keys.sort.freeze }
+        end
+
+        private
+
+        def normalize_name(name)
+          name.to_s.downcase.tr("-", "_").to_sym
+        end
+      end
+    end
+  end
+end

data/lib/config/merge/policies/rspec.yml

@@ -0,0 +1,24 @@
+name: rspec
+format: flag_file
+defaults:
+  cardinality: repeatable
+  on_conflict: conflict
+flags:
+  --require:
+    cardinality: single
+    on_conflict: ours
+  --order:
+    cardinality: single
+    on_conflict: ours
+  --out:
+    cardinality: single
+    on_conflict: ours
+  --format:
+    cardinality: repeatable
+    on_conflict: union
+  --exclude-pattern:
+    cardinality: repeatable
+    on_conflict: union
+  --env:
+    cardinality: repeatable
+    on_conflict: union

data/lib/config/merge/policy.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "normalizer_registry"
+
+module Config
+  module Merge
+    # Immutable policy for resolving conflicts in a line-oriented flag file.
+    class Policy
+      Rule = Struct.new(:cardinality, :on_conflict, :normalizer, keyword_init: true) do
+        def initialize(cardinality:, on_conflict:, normalizer:)
+          super(cardinality: cardinality.to_sym, on_conflict: on_conflict.to_sym, normalizer: normalizer.to_sym)
+          freeze
+        end
+      end
+
+      CARDINALITIES = %i[single repeatable].freeze
+      CONFLICT_ACTIONS = %i[conflict ours theirs base union].freeze
+      ROOT_KEYS = %w[name format defaults flags].freeze
+      RULE_KEYS = %w[cardinality on_conflict normalizer].freeze
+
+      attr_reader :name, :format, :defaults, :flags
+
+      def self.load(path)
+        raise ArgumentError, "Policy file not found: #{path}" unless File.file?(path)
+
+        new(YAML.safe_load_file(path, permitted_classes: [], aliases: false))
+      end
+
+      def initialize(config)
+        normalized = validate_config(config)
+        @name = normalized["name"]&.to_s
+        @format = normalized["format"]&.to_s || "flag_file"
+        validate_format!
+        @defaults = build_rule(normalized["defaults"] || {}, default: true)
+        @flags = parse_flags(normalized["flags"] || {}).freeze
+        freeze
+      end
+
+      def rule_for(flag)
+        flags.fetch(normalize_flag(flag), defaults)
+      end
+
+      private
+
+      def validate_config(config)
+        normalized = stringify_keys(config)
+        reject_unknown_keys!(normalized, ROOT_KEYS, "policy")
+        normalized
+      end
+
+      def validate_format!
+        return if format == "flag_file"
+
+        raise ArgumentError, "unsupported policy format: #{format}"
+      end
+
+      def parse_flags(config)
+        raise ArgumentError, "flags must be a mapping" unless config.is_a?(Hash)
+
+        config.to_h do |flag, values|
+          raise ArgumentError, "flag policy for #{flag.inspect} must be a mapping" unless values.is_a?(Hash)
+
+          [normalize_flag(flag), build_rule(stringify_keys(values), default: false)]
+        end
+      end
+
+      def build_rule(values, default:)
+        values = stringify_keys(values)
+        reject_unknown_keys!(values, RULE_KEYS, "rule")
+        cardinality = rule_value(values, "cardinality", default ? "repeatable" : "single").to_sym
+        on_conflict = rule_value(values, "on_conflict", "conflict").to_sym
+        normalizer = rule_value(values, "normalizer", "identity").to_sym
+        validate_rule!(cardinality, on_conflict, normalizer)
+        Rule.new(cardinality: cardinality, on_conflict: on_conflict, normalizer: normalizer)
+      end
+
+      def rule_value(values, key, fallback)
+        values.fetch(key, fallback)
+      end
+
+      def validate_rule!(cardinality, on_conflict, normalizer)
+        raise ArgumentError, "invalid cardinality: #{cardinality}" unless CARDINALITIES.include?(cardinality)
+        raise ArgumentError, "invalid conflict action: #{on_conflict}" unless CONFLICT_ACTIONS.include?(on_conflict)
+        if cardinality == :single && on_conflict == :union
+          raise ArgumentError, "single-valued flags cannot use the union conflict action"
+        end
+        raise ArgumentError, "unknown normalizer: #{normalizer}" unless NormalizerRegistry.registered?(normalizer)
+      end
+
+      def reject_unknown_keys!(hash, allowed, context)
+        unknown = hash.keys - allowed
+        raise ArgumentError, "unknown #{context} key(s): #{unknown.join(", ")}" unless unknown.empty?
+      end
+
+      def stringify_keys(hash)
+        raise ArgumentError, "expected a mapping" unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) { |(key, value), result| result[key.to_s] = value }
+      end
+
+      def normalize_flag(flag)
+        value = flag.to_s
+        raise ArgumentError, "flag names must not be empty" if value.empty?
+
+        value
+      end
+    end
+  end
+end

data/lib/config/merge/provider_adapter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Config
+  module Merge
+    # Reuses an ast-merge provider for formats with an existing structural parser.
+    #
+    # The provider result is returned unchanged, including diagnostics,
+    # verification details, and source-preserving output.
+    class ProviderAdapter
+      def initialize(family:, dialect: nil, backend: nil, profile_id: nil, provider_id: nil)
+        @selectors = {
+          family: family,
+          dialect: dialect,
+          backend: backend,
+          profile_id: profile_id,
+          provider_id: provider_id
+        }.compact.freeze
+      end
+
+      # Dispatches a base-aware structural merge to the selected provider.
+      #
+      # @param base [String] common ancestor source
+      # @param ours [String] current or destination source
+      # @param theirs [String] incoming source
+      # @param metadata [Hash, nil] provider-specific request metadata
+      # @return [Hash] validated ast-merge provider result
+      def merge3(base:, ours:, theirs:, metadata: nil)
+        request = @selectors.merge(
+          base_source: base,
+          ours_source: ours,
+          theirs_source: theirs
+        )
+        request[:metadata] = metadata if metadata
+
+        Ast::Merge.dispatch_provider(:merge3, request)
+      end
+    end
+  end
+end

data/lib/config/merge/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Config
+  module Merge
+    # Version namespace for this gem.
+    module Version
+      # Current gem version.
+      VERSION = "7.1.13"
+    end
+    # Current gem version exposed at the traditional constant location.
+    VERSION = Version::VERSION # Traditional Constant Location
+  end
+end

data/lib/config/merge.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "ast/merge"
+require "version_gem"
+require_relative "merge/version"
+require_relative "merge/normalizer_registry"
+require_relative "merge/policy"
+require_relative "merge/built_in_policies"
+require_relative "merge/flag_file/option"
+require_relative "merge/flag_file/parser"
+require_relative "merge/flag_file/result"
+require_relative "merge/flag_file/three_way_merger"
+
+module Config
+  module Merge
+    # Base error class for config-merge.
+    class Error < Ast::Merge::Error; end
+  end
+end
+
+Config::Merge::Version.class_eval do
+  extend VersionGem::Basic
+end
+
+require_relative "merge/provider_adapter"

data/sig/config/merge.rbs

@@ -0,0 +1,90 @@
+module Config
+  module Merge
+    class Error < StandardError
+    end
+
+    class NormalizerRegistry
+      class UnknownNormalizerError < ArgumentError
+      end
+
+      def self.register: (String | Symbol name, ?Proc callable, ?replace: bool) -> Symbol
+                       | (String | Symbol name, ?replace: bool) { (untyped) -> untyped } -> Symbol
+      def self.normalize: (String | Symbol name, untyped value) -> untyped
+      def self.registered?: (String | Symbol name) -> bool
+      def self.names: () -> Array[Symbol]
+    end
+
+    class Policy
+      class Rule
+        attr_reader cardinality: Symbol
+        attr_reader on_conflict: Symbol
+        attr_reader normalizer: Symbol
+      end
+
+      attr_reader name: String?
+      attr_reader format: String
+      attr_reader defaults: Rule
+      attr_reader flags: Hash[String, Rule]
+
+      def self.load: (String path) -> Policy
+      def initialize: (Hash[String, untyped] config) -> void
+      def rule_for: (String flag) -> Rule
+    end
+
+    module BuiltInPolicies
+      def self.names: () -> Array[Symbol]
+      def self.fetch: (String | Symbol name) -> Policy
+    end
+
+    module FlagFile
+      class Option
+        attr_reader flag: String
+        attr_reader value: String?
+        attr_reader raw: String
+        attr_reader line_number: Integer
+        attr_reader position: Integer
+        attr_reader binding: Symbol
+      end
+
+      class Document
+        attr_reader options: Array[Option]
+        attr_reader opaque_lines: Array[[Integer, Integer, String]]
+        attr_reader trailing_newline: bool
+      end
+
+      class Parser
+        class ParseError < ArgumentError
+        end
+
+        def parse: (String source) -> Document
+      end
+
+      class Conflict
+        attr_reader flag: String
+        attr_reader base: Array[Option]
+        attr_reader ours: Array[Option]
+        attr_reader theirs: Array[Option]
+      end
+
+      class Result
+        attr_reader output: String?
+        attr_reader conflicts: Array[Conflict]
+        attr_reader partial_output: String
+        def clean?: () -> bool
+        def success?: () -> bool
+      end
+
+      class ThreeWayMerger
+        def initialize: (base: String | Document, ours: String | Document, theirs: String | Document, policy: Policy) -> void
+        def merge: () -> Result
+      end
+    end
+  end
+end
+
+module Config::Merge
+  class ProviderAdapter
+    def initialize: (family: String | Symbol, ?dialect: String | Symbol, ?backend: String | Symbol, ?profile_id: String | Symbol, ?provider_id: String | Symbol) -> void
+    def merge3: (base: String, ours: String, theirs: String, ?metadata: Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]
+  end
+end