ast-merge 1.0.0

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

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+# Shared examples for validating FileAnalyzable integration
+#
+# Usage in your spec:
+#   require "ast/merge/rspec/shared_examples/file_analyzable"
+#
+#   RSpec.describe MyMerge::FileAnalysis do
+#     it_behaves_like "Ast::Merge::FileAnalyzable" do
+#       let(:file_analysis_class) { MyMerge::FileAnalysis }
+#       let(:freeze_node_class) { MyMerge::FreezeNode }
+#       let(:sample_source) { "# Some valid source for this parser" }
+#       let(:sample_source_with_freeze) do
+#         <<~SOURCE
+#           # Some source
+#           # my-merge:freeze
+#           frozen content
+#           # my-merge:unfreeze
+#           # More source
+#         SOURCE
+#       end
+#       # Factory to create file analysis instance
+#       let(:build_file_analysis) { ->(source, **opts) { file_analysis_class.new(source, **opts) } }
+#     end
+#   end
+#
+# @note The extending class should include Ast::Merge::FileAnalyzable
+
+RSpec.shared_examples("Ast::Merge::FileAnalyzable") do
+  # Required let blocks:
+  # - file_analysis_class: The class under test (e.g., MyMerge::FileAnalysis)
+  # - freeze_node_class: The freeze node class (e.g., MyMerge::FreezeNode)
+  # - sample_source: A valid source string for this parser
+  # - sample_source_with_freeze: Source containing a freeze block
+  # - build_file_analysis: Lambda that creates a file analysis instance
+
+  describe "module inclusion" do
+    it "includes Ast::Merge::FileAnalyzable" do
+      expect(file_analysis_class.ancestors).to(include(Ast::Merge::FileAnalyzable))
+    end
+  end
+
+  describe "attr_readers from FileAnalyzable" do
+    let(:analysis) { build_file_analysis.call(sample_source) }
+
+    it "has #source reader" do
+      expect(analysis).to(respond_to(:source))
+    end
+
+    it "has #lines reader" do
+      expect(analysis).to(respond_to(:lines))
+    end
+
+    it "has #freeze_token reader" do
+      expect(analysis).to(respond_to(:freeze_token))
+    end
+
+    it "has #signature_generator reader" do
+      expect(analysis).to(respond_to(:signature_generator))
+    end
+
+    it "has #statements reader" do
+      expect(analysis).to(respond_to(:statements))
+    end
+  end
+
+  describe "#freeze_blocks" do
+    context "without freeze blocks" do
+      let(:analysis) { build_file_analysis.call(sample_source) }
+
+      it "returns an empty array" do
+        expect(analysis.freeze_blocks).to(eq([]))
+      end
+    end
+
+    context "with freeze blocks" do
+      let(:analysis) { build_file_analysis.call(sample_source_with_freeze) }
+
+      it "returns an array of FreezeNode instances" do
+        expect(analysis.freeze_blocks).to(be_an(Array))
+        analysis.freeze_blocks.each do |block|
+          expect(block).to(be_a(freeze_node_class))
+        end
+      end
+    end
+  end
+
+  describe "#in_freeze_block?" do
+    let(:analysis) { build_file_analysis.call(sample_source_with_freeze) }
+
+    it "returns false for lines outside freeze blocks" do
+      expect(analysis.in_freeze_block?(1)).to(be(false))
+    end
+
+    it "responds to the method" do
+      expect(analysis).to(respond_to(:in_freeze_block?))
+    end
+  end
+
+  describe "#freeze_block_at" do
+    let(:analysis) { build_file_analysis.call(sample_source_with_freeze) }
+
+    it "returns nil for lines outside freeze blocks" do
+      expect(analysis.freeze_block_at(1)).to(be_nil)
+    end
+
+    it "responds to the method" do
+      expect(analysis).to(respond_to(:freeze_block_at))
+    end
+  end
+
+  describe "#signature_at" do
+    let(:analysis) { build_file_analysis.call(sample_source) }
+
+    it "returns nil for invalid index" do
+      expect(analysis.signature_at(-1)).to(be_nil)
+      expect(analysis.signature_at(9999)).to(be_nil)
+    end
+
+    it "responds to the method" do
+      expect(analysis).to(respond_to(:signature_at))
+    end
+  end
+
+  describe "#line_at" do
+    let(:analysis) { build_file_analysis.call(sample_source) }
+
+    it "returns nil for line 0" do
+      expect(analysis.line_at(0)).to(be_nil)
+    end
+
+    it "returns nil for negative line" do
+      expect(analysis.line_at(-1)).to(be_nil)
+    end
+
+    it "responds to the method" do
+      expect(analysis).to(respond_to(:line_at))
+    end
+  end
+
+  describe "#normalized_line" do
+    let(:analysis) { build_file_analysis.call(sample_source) }
+
+    it "responds to the method" do
+      expect(analysis).to(respond_to(:normalized_line))
+    end
+  end
+
+  describe "#generate_signature" do
+    let(:analysis) { build_file_analysis.call(sample_source) }
+
+    it "responds to the method" do
+      expect(analysis).to(respond_to(:generate_signature))
+    end
+
+    context "with NodeTyping::Wrapper" do
+      let(:analysis) { build_file_analysis.call(sample_source) }
+
+      it "unwraps NodeTyping::Wrapper and computes signature from underlying node" do
+        # Skip if no statements to test with
+        skip "No statements available for testing" if analysis.statements.empty?
+
+        node = analysis.statements.first
+
+        # Create a NodeTyping::Wrapper around the node
+        wrapper = Ast::Merge::NodeTyping::Wrapper.new(node, :test_type)
+
+        # Create a signature generator that returns the wrapper
+        wrapped_analysis = build_file_analysis.call(
+          sample_source,
+          signature_generator: ->(_n) { wrapper },
+        )
+
+        # The signature should be computed from the unwrapped node, not the wrapper itself
+        # Get the expected signature from the unwrapped node
+        expected_sig = analysis.generate_signature(node)
+
+        # The wrapped analysis should produce the same signature
+        actual_sig = wrapped_analysis.generate_signature(node)
+
+        expect(actual_sig).to(eq(expected_sig))
+        expect(actual_sig).not_to(be_a(Ast::Merge::NodeTyping::Wrapper))
+      end
+
+      it "recognizes NodeTyping::Wrapper in fallthrough_node?" do
+        node = analysis.statements.first || {type: :test}
+        wrapper = Ast::Merge::NodeTyping::Wrapper.new(node, :test_type)
+
+        expect(analysis.send(:fallthrough_node?, wrapper)).to(be(true))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+# Shared examples for validating FreezeNodeBase integration
+#
+# Usage in your spec:
+#   require "ast/merge/rspec/shared_examples/freeze_node_base"
+#
+#   RSpec.describe MyMerge::FreezeNode do
+#     it_behaves_like "Ast::Merge::FreezeNodeBase" do
+#       let(:freeze_node_class) { MyMerge::FreezeNode }
+#       let(:default_pattern_type) { :hash_comment }
+#       # Factory to create a freeze node instance
+#       let(:build_freeze_node) do
+#         ->(start_line:, end_line:, **opts) {
+#           freeze_node_class.new(start_line: start_line, end_line: end_line, **opts)
+#         }
+#       end
+#     end
+#   end
+#
+# @note The extending class should inherit from or behave like Ast::Merge::FreezeNodeBase
+
+RSpec.shared_examples("Ast::Merge::FreezeNodeBase") do
+  # Required let blocks:
+  # - freeze_node_class: The class under test (e.g., MyMerge::FreezeNode)
+  # - default_pattern_type: The default pattern type (:hash_comment, etc.)
+  # - build_freeze_node: Lambda that creates a freeze node instance
+
+  describe "class methods" do
+    describe ".pattern_for" do
+      it "returns a hash with :start and :end keys" do
+        pattern = freeze_node_class.pattern_for(:hash_comment)
+        expect(pattern).to(be_a(Hash))
+        expect(pattern).to(have_key(:start))
+        expect(pattern).to(have_key(:end))
+      end
+
+      it "returns Regexp patterns" do
+        pattern = freeze_node_class.pattern_for(:hash_comment)
+        expect(pattern[:start]).to(be_a(Regexp))
+        expect(pattern[:end]).to(be_a(Regexp))
+      end
+
+      it "raises ArgumentError for unknown pattern type" do
+        expect { freeze_node_class.pattern_for(:unknown_pattern) }
+          .to(raise_error(ArgumentError, /unknown pattern type/i))
+      end
+    end
+
+    describe ".start_pattern" do
+      it "returns a Regexp" do
+        expect(freeze_node_class.start_pattern).to(be_a(Regexp))
+      end
+
+      it "accepts pattern_type argument" do
+        expect(freeze_node_class.start_pattern(:hash_comment)).to(be_a(Regexp))
+      end
+    end
+
+    describe ".end_pattern" do
+      it "returns a Regexp" do
+        expect(freeze_node_class.end_pattern).to(be_a(Regexp))
+      end
+
+      it "accepts pattern_type argument" do
+        expect(freeze_node_class.end_pattern(:hash_comment)).to(be_a(Regexp))
+      end
+    end
+
+    describe ".freeze_start?" do
+      it "returns true for valid freeze start markers" do
+        expect(freeze_node_class.freeze_start?("# token:freeze")).to(be(true))
+        expect(freeze_node_class.freeze_start?("  # my-merge:freeze")).to(be(true))
+      end
+
+      it "returns false for invalid markers" do
+        expect(freeze_node_class.freeze_start?("not a marker")).to(be(false))
+        expect(freeze_node_class.freeze_start?("# unfreeze")).to(be(false))
+      end
+
+      it "returns false for nil" do
+        expect(freeze_node_class.freeze_start?(nil)).to(be(false))
+      end
+    end
+
+    describe ".freeze_end?" do
+      it "returns true for valid freeze end markers" do
+        expect(freeze_node_class.freeze_end?("# token:unfreeze")).to(be(true))
+        expect(freeze_node_class.freeze_end?("  # my-merge:unfreeze")).to(be(true))
+      end
+
+      it "returns false for invalid markers" do
+        expect(freeze_node_class.freeze_end?("not a marker")).to(be(false))
+        expect(freeze_node_class.freeze_end?("# freeze")).to(be(false))
+      end
+
+      it "returns false for nil" do
+        expect(freeze_node_class.freeze_end?(nil)).to(be(false))
+      end
+    end
+
+    describe ".pattern_types" do
+      it "returns an array of symbols" do
+        types = freeze_node_class.pattern_types
+        expect(types).to(be_an(Array))
+        expect(types).to(all(be_a(Symbol)))
+      end
+
+      it "includes :hash_comment" do
+        expect(freeze_node_class.pattern_types).to(include(:hash_comment))
+      end
+    end
+  end
+
+  describe "instance methods" do
+    let(:freeze_node) { build_freeze_node.call(start_line: 5, end_line: 10) }
+
+    describe "#start_line" do
+      it "returns the start line number" do
+        expect(freeze_node.start_line).to(eq(5))
+      end
+    end
+
+    describe "#end_line" do
+      it "returns the end line number" do
+        expect(freeze_node.end_line).to(eq(10))
+      end
+    end
+
+    describe "#location" do
+      it "returns a location object" do
+        expect(freeze_node.location).to(respond_to(:start_line))
+        expect(freeze_node.location).to(respond_to(:end_line))
+      end
+
+      it "has correct line numbers" do
+        expect(freeze_node.location.start_line).to(eq(5))
+        expect(freeze_node.location.end_line).to(eq(10))
+      end
+    end
+
+    describe "#freeze_node?" do
+      it "returns true" do
+        expect(freeze_node.freeze_node?).to(be(true))
+      end
+    end
+
+    describe "#signature" do
+      it "returns an Array" do
+        expect(freeze_node.signature).to(be_an(Array))
+      end
+
+      it "starts with :FreezeNode" do
+        expect(freeze_node.signature.first).to(eq(:FreezeNode))
+      end
+    end
+
+    describe "#inspect" do
+      it "returns a string representation" do
+        expect(freeze_node.inspect).to(be_a(String))
+        expect(freeze_node.inspect).to(include("5"))
+        expect(freeze_node.inspect).to(include("10"))
+      end
+    end
+
+    describe "#pattern_type" do
+      it "returns the pattern type" do
+        expect(freeze_node.pattern_type).to(be_a(Symbol))
+      end
+    end
+  end
+
+  describe "InvalidStructureError" do
+    it "is defined" do
+      expect(freeze_node_class::InvalidStructureError).to(be_a(Class))
+    end
+
+    it "is a StandardError" do
+      expect(freeze_node_class::InvalidStructureError.ancestors).to(include(StandardError))
+    end
+
+    it "accepts start_line, end_line, and unclosed_nodes" do
+      error = freeze_node_class::InvalidStructureError.new(
+        "test error",
+        start_line: 1,
+        end_line: 10,
+        unclosed_nodes: [],
+      )
+      expect(error.start_line).to(eq(1))
+      expect(error.end_line).to(eq(10))
+      expect(error.unclosed_nodes).to(eq([]))
+    end
+  end
+
+  describe "Location struct" do
+    let(:location) { freeze_node_class::Location.new(5, 10) }
+
+    it "has start_line" do
+      expect(location.start_line).to(eq(5))
+    end
+
+    it "has end_line" do
+      expect(location.end_line).to(eq(10))
+    end
+
+    it "responds to cover?" do
+      expect(location).to(respond_to(:cover?))
+    end
+
+    it "#cover? returns true for lines within range" do
+      expect(location.cover?(7)).to(be(true))
+    end
+
+    it "#cover? returns false for lines outside range" do
+      expect(location.cover?(3)).to(be(false))
+      expect(location.cover?(15)).to(be(false))
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Shared examples for validating MergeResultBase integration
+#
+# Usage in your spec:
+#   require "ast/merge/rspec/shared_examples/merge_result_base"
+#
+#   RSpec.describe MyMerge::MergeResult do
+#     it_behaves_like "Ast::Merge::MergeResultBase" do
+#       let(:merge_result_class) { MyMerge::MergeResult }
+#       # Factory to create a merge result instance
+#       let(:build_merge_result) { -> { merge_result_class.new } }
+#     end
+#   end
+#
+# @note The extending class should inherit from or behave like Ast::Merge::MergeResultBase
+
+RSpec.shared_examples("Ast::Merge::MergeResultBase") do
+  # Required let blocks:
+  # - merge_result_class: The class under test
+  # - build_merge_result: Lambda that creates a merge result instance
+
+  describe "decision constants" do
+    it "has DECISION_KEPT_TEMPLATE" do
+      expect(merge_result_class::DECISION_KEPT_TEMPLATE).to(eq(:kept_template))
+    end
+
+    it "has DECISION_KEPT_DEST" do
+      expect(merge_result_class::DECISION_KEPT_DEST).to(eq(:kept_destination))
+    end
+
+    it "has DECISION_MERGED" do
+      expect(merge_result_class::DECISION_MERGED).to(eq(:merged))
+    end
+
+    it "has DECISION_ADDED" do
+      expect(merge_result_class::DECISION_ADDED).to(eq(:added))
+    end
+
+    it "has DECISION_FREEZE_BLOCK" do
+      expect(merge_result_class::DECISION_FREEZE_BLOCK).to(eq(:freeze_block))
+    end
+
+    it "has DECISION_REPLACED" do
+      expect(merge_result_class::DECISION_REPLACED).to(eq(:replaced))
+    end
+
+    it "has DECISION_APPENDED" do
+      expect(merge_result_class::DECISION_APPENDED).to(eq(:appended))
+    end
+  end
+
+  describe "instance methods" do
+    let(:result) { build_merge_result.call }
+
+    describe "#lines" do
+      it "returns an Array" do
+        expect(result.lines).to(be_an(Array))
+      end
+
+      it "is initially empty" do
+        expect(result.lines).to(be_empty)
+      end
+    end
+
+    describe "#decisions" do
+      it "returns an Array" do
+        expect(result.decisions).to(be_an(Array))
+      end
+
+      it "is initially empty" do
+        expect(result.decisions).to(be_empty)
+      end
+    end
+
+    describe "#empty?" do
+      it "returns true when no lines" do
+        expect(result.empty?).to(be(true))
+      end
+    end
+
+    describe "#line_count" do
+      it "returns 0 for empty result" do
+        expect(result.line_count).to(eq(0))
+      end
+    end
+
+    describe "#decision_summary" do
+      it "returns a Hash" do
+        expect(result.decision_summary).to(be_a(Hash))
+      end
+
+      it "returns empty hash for empty result" do
+        expect(result.decision_summary).to(eq({}))
+      end
+    end
+
+    describe "#inspect" do
+      it "returns a string representation" do
+        expect(result.inspect).to(be_a(String))
+        expect(result.inspect).to(include("lines="))
+        expect(result.inspect).to(include("decisions="))
+      end
+    end
+  end
+end