ast-merge 1.0.0

data/lib/ast/merge/rspec/shared_examples/merger_config.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+# Shared examples for validating MergerConfig usage
+#
+# Usage in your spec:
+#   require "ast/merge/rspec/shared_examples/merger_config"
+#
+#   RSpec.describe Ast::Merge::MergerConfig do
+#     it_behaves_like "Ast::Merge::MergerConfig" do
+#       let(:merger_config_class) { Ast::Merge::MergerConfig }
+#       # Factory to create merger config instance
+#       let(:build_merger_config) { ->(**opts) { merger_config_class.new(**opts) } }
+#     end
+#   end
+#
+# @note This is for testing the MergerConfig class itself or custom subclasses
+
+RSpec.shared_examples("Ast::Merge::MergerConfig") do
+  # Required let blocks:
+  # - merger_config_class: The class under test (usually Ast::Merge::MergerConfig)
+  # - build_merger_config: Lambda that creates a merger config instance
+
+  describe "constants" do
+    it "has VALID_PREFERENCES" do
+      expect(merger_config_class::VALID_PREFERENCES).to(eq(%i[destination template]))
+    end
+  end
+
+  describe "default configuration" do
+    let(:config) { build_merger_config.call }
+
+    it "defaults preference to :destination" do
+      expect(config.preference).to(eq(:destination))
+    end
+
+    it "defaults add_template_only_nodes to false" do
+      expect(config.add_template_only_nodes).to(eq(false))
+    end
+
+    it "defaults freeze_token to nil" do
+      expect(config.freeze_token).to(be_nil)
+    end
+
+    it "defaults signature_generator to nil" do
+      expect(config.signature_generator).to(be_nil)
+    end
+  end
+
+  describe "custom configuration" do
+    it "accepts preference: :template" do
+      config = build_merger_config.call(preference: :template)
+      expect(config.preference).to(eq(:template))
+    end
+
+    it "accepts add_template_only_nodes: true" do
+      config = build_merger_config.call(add_template_only_nodes: true)
+      expect(config.add_template_only_nodes).to(eq(true))
+    end
+
+    it "accepts freeze_token option" do
+      config = build_merger_config.call(freeze_token: "my-token")
+      expect(config.freeze_token).to(eq("my-token"))
+    end
+
+    it "accepts signature_generator proc" do
+      generator = ->(node) { [:custom, node] }
+      config = build_merger_config.call(signature_generator: generator)
+      expect(config.signature_generator).to(eq(generator))
+    end
+  end
+
+  describe "validation" do
+    it "raises ArgumentError for invalid preference" do
+      expect { build_merger_config.call(preference: :invalid) }
+        .to(raise_error(ArgumentError, /invalid.*preference/i))
+    end
+
+    it "accepts :destination preference" do
+      expect { build_merger_config.call(preference: :destination) }
+        .not_to(raise_error)
+    end
+
+    it "accepts :template preference" do
+      expect { build_merger_config.call(preference: :template) }
+        .not_to(raise_error)
+    end
+
+    it "accepts Hash preference" do
+      expect { build_merger_config.call(preference: {default: :destination}) }
+        .not_to(raise_error)
+    end
+
+    it "validates node_typing if provided" do
+      expect { build_merger_config.call(node_typing: "not a hash") }
+        .to(raise_error(ArgumentError, /must be a Hash/))
+    end
+  end
+
+  describe "#prefer_destination?" do
+    it "returns true when preference is :destination" do
+      config = build_merger_config.call(preference: :destination)
+      expect(config.prefer_destination?).to(be(true))
+    end
+
+    it "returns false when preference is :template" do
+      config = build_merger_config.call(preference: :template)
+      expect(config.prefer_destination?).to(be(false))
+    end
+  end
+
+  describe "#prefer_template?" do
+    it "returns true when preference is :template" do
+      config = build_merger_config.call(preference: :template)
+      expect(config.prefer_template?).to(be(true))
+    end
+
+    it "returns false when preference is :destination" do
+      config = build_merger_config.call(preference: :destination)
+      expect(config.prefer_template?).to(be(false))
+    end
+  end
+
+  describe "#to_h" do
+    it "returns a hash with configuration options" do
+      config = build_merger_config.call(
+        preference: :template,
+        add_template_only_nodes: true,
+      )
+      hash = config.to_h
+
+      expect(hash).to(be_a(Hash))
+      expect(hash[:preference]).to(eq(:template))
+      expect(hash[:add_template_only_nodes]).to(eq(true))
+    end
+
+    it "includes freeze_token when set" do
+      config = build_merger_config.call(freeze_token: "my-token")
+      hash = config.to_h
+
+      expect(hash[:freeze_token]).to(eq("my-token"))
+    end
+
+    it "uses default_freeze_token when none specified" do
+      config = build_merger_config.call
+      hash = config.to_h(default_freeze_token: "default-token")
+
+      expect(hash[:freeze_token]).to(eq("default-token"))
+    end
+
+    it "includes signature_generator when set" do
+      generator = ->(_node) { [:custom] }
+      config = build_merger_config.call(signature_generator: generator)
+      hash = config.to_h
+
+      expect(hash[:signature_generator]).to(eq(generator))
+    end
+
+    it "includes node_typing when set" do
+      typing = {CallNode: ->(_node) { nil }}
+      config = build_merger_config.call(node_typing: typing)
+      hash = config.to_h
+
+      expect(hash[:node_typing]).to(eq(typing))
+    end
+  end
+
+  describe "#with" do
+    it "creates a new config with updated values" do
+      original = build_merger_config.call(preference: :destination)
+      updated = original.with(preference: :template)
+
+      expect(original.preference).to(eq(:destination))
+      expect(updated.preference).to(eq(:template))
+    end
+
+    it "preserves unmodified values" do
+      original = build_merger_config.call(
+        preference: :destination,
+        add_template_only_nodes: true,
+      )
+      updated = original.with(preference: :template)
+
+      expect(updated.add_template_only_nodes).to(eq(true))
+    end
+
+    it "preserves node_typing" do
+      typing = {CallNode: ->(_node) { nil }}
+      original = build_merger_config.call(node_typing: typing)
+      updated = original.with(preference: :template)
+
+      expect(updated.node_typing).to(eq(typing))
+    end
+  end
+
+  describe "#inspect" do
+    it "returns a string representation" do
+      config = build_merger_config.call
+      expect(config.inspect).to(be_a(String))
+      expect(config.inspect).to(include("MergerConfig"))
+    end
+  end
+end

data/lib/ast/merge/rspec/shared_examples/reproducible_merge.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# Shared example for testing merge scenarios with idempotency
+#
+# This example tests that:
+# 1. Merging template + destination produces the expected result
+# 2. The merge is idempotent (merging again produces the same result)
+#
+# Required let blocks that must be defined by the including spec:
+# - fixtures_path: Path to the fixtures directory
+# - merger_class: The SmartMerger class to use (e.g., Ast::Merge::Text::SmartMerger)
+#
+# Optional let blocks:
+# - file_extension: File extension for fixtures (default: "" for no extension)
+#                   Set to "rb" for Ruby, "txt" for text, etc.
+#
+# The shared example accepts:
+# - scenario: Name of the fixture subdirectory (e.g., "01_top_level_removed")
+# - options: Hash of merge options to pass to the merger (default: {})
+#
+# Fixture directory structure:
+#   fixtures_path/
+#     scenario/
+#       template.{ext}    - The template file
+#       destination.{ext} - The destination file
+#       result.{ext}      - The expected merge result
+#
+# @example Basic usage with .txt files
+#   let(:fixtures_path) { File.expand_path("../fixtures/text", __dir__) }
+#   let(:merger_class) { Ast::Merge::Text::SmartMerger }
+#
+#   context "when a top-level node is removed in destination" do
+#     it_behaves_like "a reproducible merge", "01_top_level_removed"
+#   end
+#
+# @example With Ruby files
+#   let(:fixtures_path) { File.expand_path("../fixtures/ruby", __dir__) }
+#   let(:merger_class) { Prism::Merge::SmartMerger }
+#   let(:file_extension) { "rb" }
+#
+# @example With no extension
+#   let(:file_extension) { "" }
+#
+# @example With merge options
+#   context "with preference: :template" do
+#     it_behaves_like "a reproducible merge", "config_preference_template", {
+#       preference: :template
+#     }
+#   end
+#
+RSpec.shared_examples("a reproducible merge") do |scenario, options = {}|
+  let(:scenario_name) { scenario }
+  let(:merge_options) { options }
+  # file_extension should be defined by the including spec
+  # Default: "" (no extension). Override with let(:file_extension) { "rb" } etc.
+  let(:file_extension) do
+    super()
+  rescue NoMethodError
+    ""
+  end
+  let(:fixture_filename) do
+    ->(name) { file_extension.to_s.empty? ? name : "#{name}.#{file_extension}" }
+  end
+  let(:fixture) do
+    template = File.read(File.join(fixtures_path, scenario_name, fixture_filename.call("template")))
+    destination = File.read(File.join(fixtures_path, scenario_name, fixture_filename.call("destination")))
+    expected_result = File.read(File.join(fixtures_path, scenario_name, fixture_filename.call("result")))
+    {template: template, destination: destination, expected: expected_result}
+  end
+
+  it "produces the expected result" do
+    merger = merger_class.new(
+      fixture[:template],
+      fixture[:destination],
+      **merge_options,
+    )
+    result = merger.merge
+
+    # Normalize trailing newlines for comparison
+    expected = fixture[:expected]
+    actual = result.to_s
+
+    expect(actual).to(
+      eq(expected),
+      "Merge result did not match expected.\n" \
+        "Expected:\n#{expected.inspect}\n" \
+        "Got:\n#{actual.inspect}",
+    )
+  end
+
+  it "is idempotent (merging again produces same result)" do
+    # First merge
+    merger1 = merger_class.new(
+      fixture[:template],
+      fixture[:destination],
+      **merge_options,
+    )
+    result1 = merger1.merge
+
+    # Second merge: use result1 as new destination
+    merger2 = merger_class.new(
+      fixture[:template],
+      result1,
+      **merge_options,
+    )
+    result2 = merger2.merge
+
+    expect(result2).to(
+      eq(result1),
+      "Merge is not idempotent!\n" \
+        "First merge:\n#{result1.inspect}\n" \
+        "Second merge:\n#{result2.inspect}",
+    )
+  end
+end

data/lib/ast/merge/rspec/shared_examples.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Load all Ast::Merge shared examples for RSpec
+#
+# Usage:
+#   require "ast/merge/rspec/shared_examples"
+#
+# This will load all shared examples provided by ast-merge,
+# making them available for use in any *-merge gem's test suite.
+#
+# Available shared examples:
+# - "Ast::Merge::ConflictResolverBase" - validates conflict resolver base implementation
+# - "Ast::Merge::DebugLogger" - validates debug logging integration
+# - "Ast::Merge::FileAnalyzable" - validates file analysis mixin integration
+# - "Ast::Merge::FreezeNodeBase" - validates freeze node base implementation
+# - "Ast::Merge::MergeResultBase" - validates merge result implementation
+# - "Ast::Merge::MergerConfig" - validates merger configuration
+# - "a reproducible merge" - validates merge scenarios with fixtures and idempotency
+
+require_relative "shared_examples/conflict_resolver_base"
+require_relative "shared_examples/debug_logger"
+require_relative "shared_examples/file_analyzable"
+require_relative "shared_examples/freeze_node_base"
+require_relative "shared_examples/merge_result_base"
+require_relative "shared_examples/merger_config"
+require_relative "shared_examples/reproducible_merge"

data/lib/ast/merge/rspec.rb

@@ -0,0 +1,4 @@
+# Ensure the main ast-merge library is loaded first
+require "ast/merge"
+
+require_relative "rspec/shared_examples"

data/lib/ast/merge/section_typing.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # AST-aware section typing for identifying logical sections within parsed trees.
+    #
+    # Unlike text-based splitting (see `Ast::Merge::Text::SectionSplitter`), SectionTyping
+    # works with already-parsed AST nodes where the parser has already identified
+    # structural boundaries. This eliminates the need for regex pattern matching.
+    #
+    # ## Use Cases
+    #
+    # - Identifying `appraise` blocks in Appraisals files
+    # - Identifying `group` blocks in Gemfiles
+    # - Identifying method definitions in Ruby files
+    # - Any case where the AST parser provides structural information
+    #
+    # ## How It Works
+    #
+    # 1. **Classifier**: A callable that inspects an AST node and returns section info
+    # 2. **Typed Node**: The node wrapped with its section classification
+    # 3. **Merge Logic**: Section-aware merging based on classifications
+    #
+    # @example Defining an Appraisals block classifier
+    #   AppraisalClassifier = ->(node) do
+    #     return nil unless node.is_a?(Prism::CallNode)
+    #     return nil unless node.name == :appraise
+    #
+    #     # Extract the block name from the first argument
+    #     block_name = node.arguments&.arguments&.first
+    #     return nil unless block_name.is_a?(Prism::StringNode)
+    #
+    #     {
+    #       type: :appraise_block,
+    #       name: block_name.unescaped,
+    #       node: node
+    #     }
+    #   end
+    #
+    # @example Using the classifier
+    #   typing = SectionTyping.new(classifier: AppraisalClassifier)
+    #   sections = typing.classify_children(parsed_tree.statements)
+    #
+    #   sections.each do |section|
+    #     puts "#{section.type}: #{section.name}"
+    #   end
+    #
+    # @api public
+    module SectionTyping
+      # Represents a classified section from an AST node.
+      #
+      # Unlike `Text::Section` which is text-based, this wraps actual AST nodes
+      # with their classification information.
+      #
+      # @api public
+      TypedSection = Struct.new(
+        # @return [Symbol] The section type (e.g., :appraise_block, :gem_group)
+        :type,
+
+        # @return [String, Symbol] Unique identifier for matching (e.g., block name)
+        :name,
+
+        # @return [Object] The original AST node
+        :node,
+
+        # @return [Hash, nil] Additional metadata from classification
+        :metadata,
+        keyword_init: true,
+      ) do
+        # Normalize the section name for matching.
+        #
+        # @return [String] Normalized name
+        def normalized_name
+          return "" if name.nil?
+          return name.to_s if name.is_a?(Symbol)
+          name.to_s.strip.downcase
+        end
+
+        # Check if this is an unclassified/preamble section.
+        #
+        # @return [Boolean]
+        def unclassified?
+          type == :unclassified || type == :preamble
+        end
+      end
+
+      # Base class for AST-aware section classifiers.
+      #
+      # Subclasses implement `classify(node)` to identify section boundaries
+      # and extract section names from AST nodes.
+      #
+      # @abstract Subclass and implement {#classify}
+      # @api public
+      class Classifier
+        # Classify a single AST node.
+        #
+        # @param node [Object] An AST node to classify
+        # @return [TypedSection, nil] Section info if node starts a section, nil otherwise
+        # @abstract Subclasses must implement this method
+        def classify(node)
+          raise NotImplementedError, "#{self.class}#classify must be implemented"
+        end
+
+        # Classify all children of a parent node.
+        #
+        # Iterates through child nodes and classifies each, grouping consecutive
+        # unclassified nodes into preamble/interstitial sections.
+        #
+        # @param children [Array, Enumerable] Child nodes to classify
+        # @return [Array<TypedSection>] Classified sections
+        def classify_all(children)
+          sections = []
+          unclassified_buffer = []
+
+          children.each do |child|
+            if (section = classify(child))
+              # Flush unclassified buffer as preamble/interstitial
+              if unclassified_buffer.any?
+                sections << build_unclassified_section(unclassified_buffer)
+                unclassified_buffer = []
+              end
+              sections << section
+            else
+              unclassified_buffer << child
+            end
+          end
+
+          # Flush remaining unclassified nodes
+          if unclassified_buffer.any?
+            sections << build_unclassified_section(unclassified_buffer)
+          end
+
+          sections
+        end
+
+        # Check if a node can be classified by this classifier.
+        #
+        # @param node [Object] Node to check
+        # @return [Boolean]
+        def classifies?(node)
+          !classify(node).nil?
+        end
+
+        private
+
+        # Build a section for unclassified nodes.
+        #
+        # @param nodes [Array] Unclassified nodes
+        # @return [TypedSection]
+        def build_unclassified_section(nodes)
+          TypedSection.new(
+            type: :unclassified,
+            name: :unclassified,
+            node: (nodes.length == 1) ? nodes.first : nodes,
+            metadata: {node_count: nodes.length},
+          )
+        end
+      end
+
+      # A classifier that uses a callable (proc/lambda) for classification.
+      #
+      # This allows defining classifiers without creating a subclass.
+      #
+      # @example Using a lambda classifier
+      #   classifier = CallableClassifier.new(->(node) {
+      #     return nil unless node.respond_to?(:name) && node.name == :appraise
+      #     TypedSection.new(type: :appraise, name: extract_name(node), node: node)
+      #   })
+      #
+      class CallableClassifier < Classifier
+        # @return [#call] The callable used for classification
+        attr_reader :callable
+
+        # Initialize with a callable.
+        #
+        # @param callable [#call] A callable that takes a node and returns TypedSection or nil
+        def initialize(callable)
+          @callable = callable
+        end
+
+        # Classify using the callable.
+        #
+        # @param node [Object] Node to classify
+        # @return [TypedSection, nil]
+        def classify(node)
+          result = callable.call(node)
+          return if result.nil?
+
+          # Allow callable to return a Hash and convert to TypedSection
+          if result.is_a?(Hash)
+            TypedSection.new(**result)
+          else
+            result
+          end
+        end
+      end
+
+      # A composite classifier that tries multiple classifiers in order.
+      #
+      # Useful when a file may contain multiple types of sections
+      # (e.g., both `appraise` blocks and `group` blocks).
+      #
+      # @example Combining classifiers
+      #   composite = CompositeClassifier.new(
+      #     AppraisalClassifier.new,
+      #     GemGroupClassifier.new
+      #   )
+      #   sections = composite.classify_all(children)
+      #
+      class CompositeClassifier < Classifier
+        # @return [Array<Classifier>] Classifiers to try in order
+        attr_reader :classifiers
+
+        # Initialize with multiple classifiers.
+        #
+        # @param classifiers [Array<Classifier>] Classifiers to try
+        def initialize(*classifiers)
+          @classifiers = classifiers.flatten
+        end
+
+        # Try each classifier until one matches.
+        #
+        # @param node [Object] Node to classify
+        # @return [TypedSection, nil]
+        def classify(node)
+          classifiers.each do |classifier|
+            if (section = classifier.classify(node))
+              return section
+            end
+          end
+          nil
+        end
+      end
+
+      # Merge typed sections from template and destination.
+      #
+      # Similar to `Text::SectionSplitter#merge_section_lists` but works with
+      # TypedSection objects wrapping AST nodes.
+      #
+      # @param template_sections [Array<TypedSection>] Sections from template
+      # @param dest_sections [Array<TypedSection>] Sections from destination
+      # @param preference [Symbol, Hash] Merge preference (:template, :destination, or per-section Hash)
+      # @param add_template_only [Boolean] Whether to add sections only in template
+      # @return [Array<TypedSection>] Merged sections
+      def self.merge_sections(template_sections, dest_sections, preference: :destination, add_template_only: false)
+        dest_by_name = dest_sections.each_with_object({}) do |section, hash|
+          key = section.normalized_name
+          hash[key] = section unless section.unclassified?
+        end
+
+        merged = []
+        seen_names = Set.new
+
+        template_sections.each do |template_section|
+          if template_section.unclassified?
+            # Unclassified sections are typically kept as-is or merged specially
+            merged << template_section if add_template_only
+            next
+          end
+
+          key = template_section.normalized_name
+          seen_names << key
+
+          dest_section = dest_by_name[key]
+
+          if dest_section
+            # Section exists in both - choose based on preference
+            section_pref = preference_for(template_section.name, preference)
+            merged << ((section_pref == :template) ? template_section : dest_section)
+          elsif add_template_only
+            merged << template_section
+          end
+        end
+
+        # Append destination-only sections
+        dest_sections.each do |dest_section|
+          next if dest_section.unclassified?
+          key = dest_section.normalized_name
+          next if seen_names.include?(key)
+          merged << dest_section
+        end
+
+        merged
+      end
+
+      # Get preference for a specific section.
+      #
+      # @param section_name [String, Symbol] The section name
+      # @param preference [Symbol, Hash] Overall preference
+      # @return [Symbol] :template or :destination
+      def self.preference_for(section_name, preference)
+        return preference unless preference.is_a?(Hash)
+
+        normalized = section_name.to_s.strip.downcase
+        preference.each do |key, value|
+          return value if key.to_s.strip.downcase == normalized
+        end
+
+        preference.fetch(:default, :destination)
+      end
+    end
+  end
+end