ast-merge 1.0.0

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

@@ -0,0 +1,416 @@
+# frozen_string_literal: true
+
+# Shared examples for validating ConflictResolverBase integration
+#
+# Usage in your spec:
+#   require "ast/merge/rspec/shared_examples/conflict_resolver_base"
+#
+#   RSpec.describe MyMerge::ConflictResolver do
+#     it_behaves_like "Ast::Merge::ConflictResolverBase" do
+#       let(:conflict_resolver_class) { MyMerge::ConflictResolver }
+#       let(:strategy) { :node } # or :batch or :boundary
+#       # Factory to create a conflict resolver instance
+#       let(:build_conflict_resolver) do
+#         ->(preference:, template_analysis:, dest_analysis:, **opts) {
+#           conflict_resolver_class.new(
+#             preference: preference,
+#             template_analysis: template_analysis,
+#             dest_analysis: dest_analysis,
+#             **opts
+#           )
+#         }
+#       end
+#       # Factory to create mock analysis objects
+#       let(:build_mock_analysis) { -> { double("Analysis") } }
+#     end
+#   end
+#
+# @note The extending class should inherit from or behave like Ast::Merge::ConflictResolverBase
+
+RSpec.shared_examples("Ast::Merge::ConflictResolverBase") do
+  # Required let blocks:
+  # - conflict_resolver_class: The class under test
+  # - strategy: The resolution strategy (:node, :batch, or :boundary)
+  # - build_conflict_resolver: Lambda that creates a conflict resolver instance
+  # - build_mock_analysis: Lambda that creates mock analysis objects
+
+  describe "decision constants" do
+    it "has DECISION_DESTINATION" do
+      expect(conflict_resolver_class::DECISION_DESTINATION).to(eq(:destination))
+    end
+
+    it "has DECISION_TEMPLATE" do
+      expect(conflict_resolver_class::DECISION_TEMPLATE).to(eq(:template))
+    end
+
+    it "has DECISION_ADDED" do
+      expect(conflict_resolver_class::DECISION_ADDED).to(eq(:added))
+    end
+
+    it "has DECISION_FROZEN" do
+      expect(conflict_resolver_class::DECISION_FROZEN).to(eq(:frozen))
+    end
+
+    it "has DECISION_IDENTICAL" do
+      expect(conflict_resolver_class::DECISION_IDENTICAL).to(eq(:identical))
+    end
+
+    it "has DECISION_KEPT_DEST" do
+      expect(conflict_resolver_class::DECISION_KEPT_DEST).to(eq(:kept_destination))
+    end
+
+    it "has DECISION_KEPT_TEMPLATE" do
+      expect(conflict_resolver_class::DECISION_KEPT_TEMPLATE).to(eq(:kept_template))
+    end
+
+    it "has DECISION_APPENDED" do
+      expect(conflict_resolver_class::DECISION_APPENDED).to(eq(:appended))
+    end
+
+    it "has DECISION_FREEZE_BLOCK" do
+      expect(conflict_resolver_class::DECISION_FREEZE_BLOCK).to(eq(:freeze_block))
+    end
+
+    it "has DECISION_RECURSIVE" do
+      expect(conflict_resolver_class::DECISION_RECURSIVE).to(eq(:recursive))
+    end
+
+    it "has DECISION_REPLACED" do
+      expect(conflict_resolver_class::DECISION_REPLACED).to(eq(:replaced))
+    end
+  end
+
+  describe "initialization" do
+    let(:template_analysis) { build_mock_analysis.call }
+    let(:dest_analysis) { build_mock_analysis.call }
+
+    context "with :destination preference" do
+      let(:resolver) do
+        build_conflict_resolver.call(
+          preference: :destination,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+        )
+      end
+
+      it "sets preference to :destination" do
+        expect(resolver.preference).to(eq(:destination))
+      end
+
+      it "sets strategy correctly" do
+        expect(resolver.strategy).to(eq(strategy))
+      end
+
+      it "stores template_analysis" do
+        expect(resolver.template_analysis).to(eq(template_analysis))
+      end
+
+      it "stores dest_analysis" do
+        expect(resolver.dest_analysis).to(eq(dest_analysis))
+      end
+    end
+
+    context "with :template preference" do
+      let(:resolver) do
+        build_conflict_resolver.call(
+          preference: :template,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+        )
+      end
+
+      it "sets preference to :template" do
+        expect(resolver.preference).to(eq(:template))
+      end
+    end
+  end
+
+  describe "attr_readers" do
+    let(:template_analysis) { build_mock_analysis.call }
+    let(:dest_analysis) { build_mock_analysis.call }
+    let(:resolver) do
+      build_conflict_resolver.call(
+        preference: :destination,
+        template_analysis: template_analysis,
+        dest_analysis: dest_analysis,
+      )
+    end
+
+    it "has #strategy reader" do
+      expect(resolver).to(respond_to(:strategy))
+    end
+
+    it "has #preference reader" do
+      expect(resolver).to(respond_to(:preference))
+    end
+
+    it "has #template_analysis reader" do
+      expect(resolver).to(respond_to(:template_analysis))
+    end
+
+    it "has #dest_analysis reader" do
+      expect(resolver).to(respond_to(:dest_analysis))
+    end
+
+    it "has #add_template_only_nodes reader" do
+      expect(resolver).to(respond_to(:add_template_only_nodes))
+    end
+  end
+
+  describe "#resolve" do
+    let(:template_analysis) { build_mock_analysis.call }
+    let(:dest_analysis) { build_mock_analysis.call }
+    let(:resolver) do
+      build_conflict_resolver.call(
+        preference: :destination,
+        template_analysis: template_analysis,
+        dest_analysis: dest_analysis,
+      )
+    end
+
+    it "responds to #resolve" do
+      expect(resolver).to(respond_to(:resolve))
+    end
+  end
+
+  describe "#freeze_node?" do
+    let(:template_analysis) { build_mock_analysis.call }
+    let(:dest_analysis) { build_mock_analysis.call }
+    let(:resolver) do
+      build_conflict_resolver.call(
+        preference: :destination,
+        template_analysis: template_analysis,
+        dest_analysis: dest_analysis,
+      )
+    end
+
+    it "returns false for nodes without freeze_node? method" do
+      node = double("Node")
+      expect(resolver.freeze_node?(node)).to(be(false))
+    end
+
+    it "returns true for nodes that respond to freeze_node? and return true" do
+      node = double("FreezeNode", freeze_node?: true)
+      expect(resolver.freeze_node?(node)).to(be(true))
+    end
+
+    it "returns false for nodes that respond to freeze_node? and return false" do
+      node = double("RegularNode", freeze_node?: false)
+      expect(resolver.freeze_node?(node)).to(be(false))
+    end
+  end
+end
+
+RSpec.shared_examples("Ast::Merge::ConflictResolverBase validation") do
+  # Tests for invalid initialization arguments
+  # These test the base class validation directly
+
+  let(:template_analysis) { build_mock_analysis.call }
+  let(:dest_analysis) { build_mock_analysis.call }
+
+  describe "argument validation" do
+    it "raises ArgumentError for invalid strategy" do
+      expect do
+        Ast::Merge::ConflictResolverBase.new(
+          strategy: :invalid,
+          preference: :destination,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+        )
+      end.to(raise_error(ArgumentError, /Invalid strategy/))
+    end
+
+    it "raises ArgumentError for invalid preference" do
+      expect do
+        Ast::Merge::ConflictResolverBase.new(
+          strategy: :node,
+          preference: :invalid,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+        )
+      end.to(raise_error(ArgumentError, /Invalid preference/))
+    end
+
+    it "accepts :node strategy" do
+      expect do
+        Ast::Merge::ConflictResolverBase.new(
+          strategy: :node,
+          preference: :destination,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+        )
+      end.not_to(raise_error)
+    end
+
+    it "accepts :batch strategy" do
+      expect do
+        Ast::Merge::ConflictResolverBase.new(
+          strategy: :batch,
+          preference: :destination,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+        )
+      end.not_to(raise_error)
+    end
+
+    it "accepts :boundary strategy" do
+      expect do
+        Ast::Merge::ConflictResolverBase.new(
+          strategy: :boundary,
+          preference: :destination,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+        )
+      end.not_to(raise_error)
+    end
+
+    it "accepts :destination preference" do
+      expect do
+        Ast::Merge::ConflictResolverBase.new(
+          strategy: :node,
+          preference: :destination,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+        )
+      end.not_to(raise_error)
+    end
+
+    it "accepts :template preference" do
+      expect do
+        Ast::Merge::ConflictResolverBase.new(
+          strategy: :node,
+          preference: :template,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+        )
+      end.not_to(raise_error)
+    end
+  end
+end
+
+RSpec.shared_examples("Ast::Merge::ConflictResolverBase node strategy") do
+  # Additional examples specific to :node strategy resolvers
+  # Use when strategy is :node
+
+  let(:template_analysis) { build_mock_analysis.call }
+  let(:dest_analysis) { build_mock_analysis.call }
+  let(:resolver) do
+    build_conflict_resolver.call(
+      preference: :destination,
+      template_analysis: template_analysis,
+      dest_analysis: dest_analysis,
+    )
+  end
+
+  describe "node strategy" do
+    it "has :node strategy" do
+      expect(resolver.strategy).to(eq(:node))
+    end
+
+    it "delegates resolve to resolve_node_pair" do
+      expect(resolver).to(respond_to(:resolve))
+    end
+  end
+end
+
+RSpec.shared_examples("Ast::Merge::ConflictResolverBase batch strategy") do
+  # Additional examples specific to :batch strategy resolvers
+  # Use when strategy is :batch
+
+  let(:template_analysis) { build_mock_analysis.call }
+  let(:dest_analysis) { build_mock_analysis.call }
+  let(:resolver) do
+    build_conflict_resolver.call(
+      preference: :destination,
+      template_analysis: template_analysis,
+      dest_analysis: dest_analysis,
+    )
+  end
+
+  describe "batch strategy" do
+    it "has :batch strategy" do
+      expect(resolver.strategy).to(eq(:batch))
+    end
+
+    it "delegates resolve to resolve_batch" do
+      expect(resolver).to(respond_to(:resolve))
+    end
+  end
+
+  describe "#add_template_only_nodes" do
+    context "with default value" do
+      it "defaults to false" do
+        expect(resolver.add_template_only_nodes).to(be(false))
+      end
+    end
+
+    context "with add_template_only_nodes: true" do
+      let(:resolver_with_add) do
+        build_conflict_resolver.call(
+          preference: :destination,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+          add_template_only_nodes: true,
+        )
+      end
+
+      it "returns true when set" do
+        expect(resolver_with_add.add_template_only_nodes).to(be(true))
+      end
+    end
+  end
+end
+
+RSpec.shared_examples("Ast::Merge::ConflictResolverBase boundary strategy") do
+  # Additional examples specific to :boundary strategy resolvers
+  # Use when strategy is :boundary
+  #
+  # Boundary strategy is used for ASTs where content is processed
+  # in sections/ranges rather than individual nodes or all at once.
+  # This is typical for languages like Ruby where file alignment
+  # identifies boundaries (sections with differences) between
+  # template and destination files.
+
+  let(:template_analysis) { build_mock_analysis.call }
+  let(:dest_analysis) { build_mock_analysis.call }
+  let(:resolver) do
+    build_conflict_resolver.call(
+      preference: :destination,
+      template_analysis: template_analysis,
+      dest_analysis: dest_analysis,
+    )
+  end
+
+  describe "boundary strategy" do
+    it "has :boundary strategy" do
+      expect(resolver.strategy).to(eq(:boundary))
+    end
+
+    it "delegates resolve to resolve_boundary" do
+      expect(resolver).to(respond_to(:resolve))
+    end
+  end
+
+  describe "#add_template_only_nodes" do
+    context "with default value" do
+      it "defaults to false" do
+        expect(resolver.add_template_only_nodes).to(be(false))
+      end
+    end
+
+    context "with add_template_only_nodes: true" do
+      let(:resolver_with_add) do
+        build_conflict_resolver.call(
+          preference: :destination,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+          add_template_only_nodes: true,
+        )
+      end
+
+      it "returns true when set" do
+        expect(resolver_with_add.add_template_only_nodes).to(be(true))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "silent_stream"
+require "rspec/stubbed_env"
+
+# Shared examples for validating DebugLogger integration
+#
+# Usage in your spec:
+#   require "ast/merge/rspec/shared_examples/debug_logger"
+#
+#   RSpec.describe MyMerge::DebugLogger do
+#     it_behaves_like "Ast::Merge::DebugLogger" do
+#       let(:described_logger) { MyMerge::DebugLogger }
+#       let(:env_var_name) { "MY_MERGE_DEBUG" }
+#       let(:log_prefix) { "[MyMerge]" }
+#     end
+#   end
+#
+# @note The extending module must configure:
+#   - self.env_var_name = "YOUR_ENV_VAR"
+#   - self.log_prefix = "[YourPrefix]"
+
+RSpec.shared_examples("Ast::Merge::DebugLogger") do
+  include SilentStream
+
+  include_context "with stubbed env"
+
+  # Required let blocks that must be provided by including spec:
+  # - described_logger: The module that extends Ast::Merge::DebugLogger
+  # - env_var_name: Expected environment variable name
+  # - log_prefix: Expected log prefix
+
+  describe "module configuration" do
+    it "has env_var_name configured" do
+      expect(described_logger.env_var_name).to(eq(env_var_name))
+    end
+
+    it "has log_prefix configured" do
+      expect(described_logger.log_prefix).to(eq(log_prefix))
+    end
+
+    it "has BENCHMARK_AVAILABLE constant from base" do
+      expect(described_logger::BENCHMARK_AVAILABLE).to(eq(Ast::Merge::DebugLogger::BENCHMARK_AVAILABLE))
+    end
+  end
+
+  describe "core methods from Ast::Merge::DebugLogger" do
+    it "responds to #enabled?" do
+      expect(described_logger).to(respond_to(:enabled?))
+    end
+
+    it "responds to #debug" do
+      expect(described_logger).to(respond_to(:debug))
+    end
+
+    it "responds to #info" do
+      expect(described_logger).to(respond_to(:info))
+    end
+
+    it "responds to #warning" do
+      expect(described_logger).to(respond_to(:warning))
+    end
+
+    it "responds to #time" do
+      expect(described_logger).to(respond_to(:time))
+    end
+
+    it "responds to #log_node" do
+      expect(described_logger).to(respond_to(:log_node))
+    end
+
+    it "responds to #extract_node_info" do
+      expect(described_logger).to(respond_to(:extract_node_info))
+    end
+
+    it "responds to #safe_type_name" do
+      expect(described_logger).to(respond_to(:safe_type_name))
+    end
+
+    it "responds to #extract_lines" do
+      expect(described_logger).to(respond_to(:extract_lines))
+    end
+  end
+
+  describe "when debug is enabled" do
+    before do
+      stub_env(env_var_name => "1")
+    end
+
+    it "#enabled? returns true" do
+      expect(described_logger.enabled?).to(be(true))
+    end
+
+    it "#debug outputs message with configured prefix" do
+      expect { described_logger.debug("test message") }
+        .to(output(/#{Regexp.escape(log_prefix)} test message/).to_stderr)
+    end
+
+    it "#debug includes context hash when provided" do
+      expect { described_logger.debug("test", key: "value") }
+        .to(output(/key.*value/).to_stderr)
+    end
+
+    it "#info outputs with INFO label" do
+      expect { described_logger.info("info message") }
+        .to(output(/#{Regexp.escape(log_prefix)} INFO\] info message/).to_stderr)
+    end
+
+    it "#time logs start and completion with timing" do
+      output = capture(:stderr) { described_logger.time("test operation") { 42 } }
+      expect(output).to(include("Starting: test operation"))
+      expect(output).to(include("Completed: test operation"))
+      expect(output).to(match(/real_ms/))
+    end
+
+    it "#time returns the block result" do
+      result = described_logger.time("operation") { 42 }
+      expect(result).to(eq(42))
+    end
+  end
+
+  describe "when debug is disabled" do
+    before do
+      stub_env(env_var_name => nil)
+    end
+
+    it "#enabled? returns false" do
+      expect(described_logger.enabled?).to(be(false))
+    end
+
+    it "#debug does not output anything" do
+      expect { described_logger.debug("test") }.not_to(output.to_stderr)
+    end
+
+    it "#info does not output anything" do
+      expect { described_logger.info("test") }.not_to(output.to_stderr)
+    end
+
+    it "#time still executes block and returns result without logging" do
+      output = capture(:stderr) { @result = described_logger.time("operation") { 42 } }
+      expect(@result).to(eq(42))
+      expect(output).to(be_empty)
+    end
+  end
+
+  describe "#warning (always outputs)" do
+    before do
+      stub_env(env_var_name => nil)
+    end
+
+    it "outputs warning even when debug is disabled" do
+      expect { described_logger.warning("warning message") }
+        .to(output(/#{Regexp.escape(log_prefix)} WARNING\] warning message/).to_stderr)
+    end
+  end
+
+  describe "#extract_node_info" do
+    it "extracts type name from object" do
+      node = Object.new
+      info = described_logger.extract_node_info(node)
+      expect(info[:type]).to(eq("Object"))
+    end
+  end
+
+  describe "#safe_type_name" do
+    it "returns class name for standard objects" do
+      expect(described_logger.safe_type_name("test")).to(eq("String"))
+    end
+
+    it "returns short name without module prefix" do
+      expect(described_logger.safe_type_name([])).to(eq("Array"))
+    end
+  end
+end