ast-merge 1.0.0

data/lib/ast/merge/region.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Represents a detected region within a document.
+    #
+    # Regions are portions of a document that can be handled by a specialized
+    # merger. For example, YAML frontmatter in a Markdown file, or a Ruby code
+    # block that should be merged using a Ruby-aware merger.
+    #
+    # @example Creating a region for YAML frontmatter
+    #   Region.new(
+    #     type: :yaml_frontmatter,
+    #     content: "title: My Doc\nversion: 1.0\n",
+    #     start_line: 1,
+    #     end_line: 4,
+    #     delimiters: ["---", "---"],
+    #     metadata: { format: :yaml }
+    #   )
+    #
+    # @example Creating a region for a Ruby code block
+    #   Region.new(
+    #     type: :ruby_code_block,
+    #     content: "def hello\n  puts 'world'\nend\n",
+    #     start_line: 5,
+    #     end_line: 9,
+    #     delimiters: ["```ruby", "```"],
+    #     metadata: { language: "ruby" }
+    #   )
+    #
+    # @api public
+    Region = Struct.new(
+      # @return [Symbol] The type of region (e.g., :yaml_frontmatter, :ruby_code_block)
+      :type,
+
+      # @return [String] The raw string content of this region (inner content, without delimiters)
+      :content,
+
+      # @return [Integer] 1-indexed start line in the original document
+      :start_line,
+
+      # @return [Integer] 1-indexed end line in the original document
+      :end_line,
+
+      # @return [Array<String>, nil] Delimiter strings to reconstruct the region
+      #   ["```ruby", "```"] - [opening_delimiter, closing_delimiter]
+      :delimiters,
+
+      # @return [Hash, nil] Optional metadata for detector-specific information
+      #   (e.g., { language: "ruby" }, { format: :yaml })
+      :metadata,
+      keyword_init: true,
+    ) do
+      # Returns the line range covered by this region.
+      #
+      # @return [Range] The range from start_line to end_line (inclusive)
+      # @example
+      #   region.line_range # => 1..4
+      def line_range
+        start_line..end_line
+      end
+
+      # Returns the number of lines this region spans.
+      #
+      # @return [Integer] The number of lines
+      # @example
+      #   region.line_count # => 4
+      def line_count
+        end_line - start_line + 1
+      end
+
+      # Reconstructs the full region text including delimiters.
+      #
+      # @return [String] The complete region with start and end delimiters
+      # @example
+      #   region.full_text
+      #   # => "```ruby\ndef hello\n  puts 'world'\nend\n```"
+      def full_text
+        return content if delimiters.nil? || delimiters.empty?
+
+        opening = delimiters[0] || ""
+        closing = delimiters[1] || ""
+        "#{opening}\n#{content}#{closing}"
+      end
+
+      # Checks if this region overlaps with the given line number.
+      #
+      # @param line [Integer] The line number to check (1-indexed)
+      # @return [Boolean] true if the line is within this region
+      def contains_line?(line)
+        line_range.cover?(line)
+      end
+
+      # Checks if this region overlaps with another region.
+      #
+      # @param other [Region] Another region to check for overlap
+      # @return [Boolean] true if the regions overlap
+      def overlaps?(other)
+        line_range.cover?(other.start_line) ||
+          line_range.cover?(other.end_line) ||
+          other.line_range.cover?(start_line)
+      end
+
+      # Returns a short string representation of the region.
+      #
+      # @return [String] A concise string describing the region
+      def to_s
+        "Region<#{type}:#{start_line}-#{end_line}>"
+      end
+
+      # Returns a detailed human-readable representation of the region.
+      #
+      # @return [String] A string describing the region with truncated content
+      def inspect
+        truncated = if content && content.length > 30
+          "#{content[0, 30]}..."
+        else
+          content.inspect
+        end
+        "#{self} #{truncated}"
+      end
+    end
+  end
+end

data/lib/ast/merge/region_detector_base.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Base class for region detection.
+    #
+    # Region detectors identify portions of a document that should be handled
+    # by a specialized merger. For example, detecting YAML frontmatter in a
+    # Markdown file, or Ruby code blocks that should be merged with Prism.
+    #
+    # Subclasses must implement:
+    # - {#region_type} - Returns the type symbol for detected regions
+    # - {#detect_all} - Finds all regions of this type in a document
+    #
+    # @example Implementing a custom detector
+    #   class MyBlockDetector < Ast::Merge::RegionDetectorBase
+    #     def region_type
+    #       :my_block
+    #     end
+    #
+    #     def detect_all(source)
+    #       # Return array of Region structs
+    #       []
+    #     end
+    #   end
+    #
+    # @abstract Subclass and implement {#region_type} and {#detect_all}
+    # @api public
+    class RegionDetectorBase
+      # Returns the type symbol for regions detected by this detector.
+      #
+      # This symbol is used to identify the region type in the Region struct
+      # and for matching regions between template and destination documents.
+      #
+      # @return [Symbol] The region type (e.g., :yaml_frontmatter, :ruby_code_block)
+      # @abstract Subclasses must implement this method
+      def region_type
+        raise NotImplementedError, "#{self.class}#region_type must be implemented"
+      end
+
+      # Detects all regions of this type in the given source.
+      #
+      # @param source [String] The full document content to scan
+      # @return [Array<Region>] All detected regions, sorted by start_line
+      # @abstract Subclasses must implement this method
+      #
+      # @example Return value structure
+      #   [
+      #     Region.new(
+      #       type: :yaml_frontmatter,
+      #       content: "title: My Doc\n",
+      #       start_line: 1,
+      #       end_line: 3,
+      #       delimiters: { start: "---\n", end: "---\n" },
+      #       metadata: { format: :yaml }
+      #     )
+      #   ]
+      def detect_all(source)
+        raise NotImplementedError, "#{self.class}#detect_all must be implemented"
+      end
+
+      # Whether to strip delimiters from content before passing to merger.
+      #
+      # When true (default), only the inner content is passed to the region's
+      # merger. The delimiters are stored separately and reattached after merging.
+      #
+      # When false, the full content including delimiters is passed to the merger,
+      # which must then handle the delimiters itself.
+      #
+      # @return [Boolean] true if delimiters should be stripped (default: true)
+      def strip_delimiters?
+        true
+      end
+
+      # A human-readable name for this detector.
+      #
+      # Used in error messages and debugging output.
+      #
+      # @return [String] The detector name
+      def name
+        self.class.name || "AnonymousDetector"
+      end
+
+      # Returns a string representation of this detector.
+      #
+      # @return [String] A description of the detector
+      def inspect
+        "#<#{name} region_type=#{region_type}>"
+      end
+
+      protected
+
+      # Helper to build a Region struct with common defaults.
+      #
+      # @param type [Symbol] The region type
+      # @param content [String] The inner content (without delimiters)
+      # @param start_line [Integer] 1-indexed start line
+      # @param end_line [Integer] 1-indexed end line
+      # @param delimiters [Hash, nil] { start: String, end: String }
+      # @param metadata [Hash, nil] Additional metadata
+      # @return [Region] A new Region struct
+      def build_region(type:, content:, start_line:, end_line:, delimiters: nil, metadata: nil)
+        Region.new(
+          type: type,
+          content: content,
+          start_line: start_line,
+          end_line: end_line,
+          delimiters: delimiters,
+          metadata: metadata || {},
+        )
+      end
+    end
+  end
+end

data/lib/ast/merge/region_mergeable.rb

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    ##
+    # Mixin for adding region support to SmartMerger classes.
+    #
+    # This module provides functionality for detecting and handling regions
+    # within documents that should be merged with different strategies.
+    # Regions are portions of a document (like YAML frontmatter or fenced
+    # code blocks) that may require specialized merging.
+    #
+    # @example Basic region configuration
+    #   class SmartMerger
+    #     include RegionMergeable
+    #
+    #     def initialize(template, dest, regions: [], region_placeholder: nil)
+    #       @template_content = template
+    #       @dest_content = dest
+    #       setup_regions(regions: regions, region_placeholder: region_placeholder)
+    #     end
+    #   end
+    #
+    # @example With YAML frontmatter regions
+    #   merger = SmartMerger.new(
+    #     template,
+    #     dest,
+    #     regions: [
+    #       {
+    #         detector: YamlFrontmatterDetector.new,
+    #         merger_class: SomeYamlMerger,
+    #         merger_options: { preserve_order: true }
+    #       }
+    #     ]
+    #   )
+    #
+    # @example With nested regions (code blocks in markdown)
+    #   merger = SmartMerger.new(
+    #     template,
+    #     dest,
+    #     regions: [
+    #       {
+    #         detector: FencedCodeBlockDetector.ruby,
+    #         merger_class: Prism::Merge::SmartMerger,
+    #         regions: [...]  # Nested regions!
+    #       }
+    #     ]
+    #   )
+    #
+    module RegionMergeable
+      # Default placeholder prefix for extracted regions
+      DEFAULT_PLACEHOLDER_PREFIX = "<<<AST_MERGE_REGION_"
+      DEFAULT_PLACEHOLDER_SUFFIX = ">>>"
+
+      ##
+      # Configuration for a single region type.
+      #
+      # @attr detector [RegionDetectorBase] Detector instance for finding regions
+      # @attr merger_class [Class, nil] Merger class for merging region content (nil to skip merging)
+      # @attr merger_options [Hash] Options to pass to the region merger
+      # @attr regions [Array<Hash>] Nested region configurations (recursive)
+      #
+      RegionConfig = Struct.new(:detector, :merger_class, :merger_options, :regions, keyword_init: true) do
+        def initialize(detector:, merger_class: nil, merger_options: {}, regions: [])
+          super(
+            detector: detector,
+            merger_class: merger_class,
+            merger_options: merger_options || {},
+            regions: regions || [],
+          )
+        end
+      end
+
+      ##
+      # Extracted region with its content and placeholder.
+      #
+      # @attr region [Region] The detected region
+      # @attr config [RegionConfig] The configuration that matched this region
+      # @attr placeholder [String] The placeholder used in the document
+      # @attr merged_content [String, nil] The merged content (set after merging)
+      #
+      ExtractedRegion = Struct.new(:region, :config, :placeholder, :merged_content, keyword_init: true)
+
+      ##
+      # Set up region handling for this merger instance.
+      #
+      # @param regions [Array<Hash>] Array of region configurations
+      # @param region_placeholder [String, nil] Custom placeholder prefix (optional)
+      # @raise [ArgumentError] if regions configuration is invalid
+      #
+      def setup_regions(regions:, region_placeholder: nil)
+        @region_configs = build_region_configs(regions)
+        @region_placeholder_prefix = region_placeholder || DEFAULT_PLACEHOLDER_PREFIX
+        @extracted_template_regions = []
+        @extracted_dest_regions = []
+      end
+
+      ##
+      # Check if this merger has region configurations.
+      #
+      # @return [Boolean] true if regions are configured
+      #
+      def regions_configured?
+        @region_configs && !@region_configs.empty?
+      end
+
+      ##
+      # Extract regions from the template content, replacing with placeholders.
+      #
+      # @param content [String] Template content
+      # @return [String] Content with regions replaced by placeholders
+      # @raise [PlaceholderCollisionError] if content contains placeholder text
+      #
+      def extract_template_regions(content)
+        return content unless regions_configured?
+
+        extract_regions(content, @extracted_template_regions)
+      end
+
+      ##
+      # Extract regions from the destination content, replacing with placeholders.
+      #
+      # @param content [String] Destination content
+      # @return [String] Content with regions replaced by placeholders
+      # @raise [PlaceholderCollisionError] if content contains placeholder text
+      #
+      def extract_dest_regions(content)
+        return content unless regions_configured?
+
+        extract_regions(content, @extracted_dest_regions)
+      end
+
+      ##
+      # Merge extracted regions and substitute them back into the merged content.
+      #
+      # @param merged_content [String] The merged content with placeholders
+      # @return [String] Content with placeholders replaced by merged regions
+      #
+      def substitute_merged_regions(merged_content)
+        return merged_content unless regions_configured?
+
+        result = merged_content
+
+        # Process regions in reverse order of extraction to handle nested placeholders
+        # We need to merge template and dest regions by their placeholder index
+        merge_and_substitute_regions(result)
+      end
+
+      private
+
+      ##
+      # Build RegionConfig objects from configuration hashes.
+      #
+      # @param configs [Array<Hash>] Array of configuration hashes
+      # @return [Array<RegionConfig>] Array of RegionConfig objects
+      #
+      def build_region_configs(configs)
+        return [] if configs.nil? || configs.empty?
+
+        configs.map do |config|
+          case config
+          when RegionConfig
+            config
+          when Hash
+            RegionConfig.new(
+              detector: config[:detector],
+              merger_class: config[:merger_class],
+              merger_options: config[:merger_options] || {},
+              regions: config[:regions] || [],
+            )
+          else
+            raise ArgumentError, "Invalid region config: #{config.inspect}"
+          end
+        end
+      end
+
+      ##
+      # Extract regions from content, replacing with placeholders.
+      #
+      # @param content [String] Content to process
+      # @param storage [Array<ExtractedRegion>] Array to store extracted regions
+      # @return [String] Content with placeholders
+      #
+      def extract_regions(content, storage)
+        validate_no_placeholder_collision!(content)
+
+        result = content
+        region_index = storage.size
+
+        @region_configs.each do |config|
+          regions = config.detector.detect_all(result)
+
+          # Process regions in reverse order to maintain correct positions
+          regions.sort_by { |r| -r.start_line }.each do |region|
+            placeholder = build_placeholder(region_index)
+            region_index += 1
+
+            extracted = ExtractedRegion.new(
+              region: region,
+              config: config,
+              placeholder: placeholder,
+              merged_content: nil,
+            )
+            storage.unshift(extracted) # Add to front since we process in reverse
+
+            # Replace the region with the placeholder
+            result = replace_region_with_placeholder(result, region, placeholder)
+          end
+        end
+
+        storage.sort_by! { |e| placeholder_index(e.placeholder) }
+        result
+      end
+
+      ##
+      # Validate that the content doesn't contain placeholder text.
+      #
+      # @param content [String] Content to validate
+      # @raise [PlaceholderCollisionError] if placeholder is found
+      #
+      def validate_no_placeholder_collision!(content)
+        return if content.nil? || content.empty?
+
+        if content.include?(@region_placeholder_prefix)
+          raise PlaceholderCollisionError, @region_placeholder_prefix
+        end
+      end
+
+      ##
+      # Build a placeholder string for a given index.
+      #
+      # @param index [Integer] The region index
+      # @return [String] The placeholder string
+      #
+      def build_placeholder(index)
+        "#{@region_placeholder_prefix}#{index}#{DEFAULT_PLACEHOLDER_SUFFIX}"
+      end
+
+      ##
+      # Extract the index from a placeholder string.
+      #
+      # @param placeholder [String] The placeholder string
+      # @return [Integer] The extracted index
+      #
+      def placeholder_index(placeholder)
+        placeholder.match(/#{Regexp.escape(@region_placeholder_prefix)}(\d+)/)[1].to_i
+      end
+
+      ##
+      # Replace a region in content with a placeholder.
+      #
+      # @param content [String] The content
+      # @param region [Region] The region to replace
+      # @param placeholder [String] The placeholder to insert
+      # @return [String] Content with region replaced
+      #
+      def replace_region_with_placeholder(content, region, placeholder)
+        lines = content.lines
+        # Region line numbers are 1-indexed
+        start_idx = region.start_line - 1
+        end_idx = region.end_line - 1
+
+        # Replace the region lines with the placeholder
+        before = lines[0...start_idx]
+        after = lines[(end_idx + 1)..]
+
+        # Preserve the newline style
+        newline = content.include?("\r\n") ? "\r\n" : "\n"
+        placeholder_line = "#{placeholder}#{newline}"
+
+        (before + [placeholder_line] + (after || [])).join
+      end
+
+      ##
+      # Merge and substitute regions back into the merged content.
+      #
+      # @param content [String] Merged content with placeholders
+      # @return [String] Content with merged regions substituted
+      #
+      def merge_and_substitute_regions(content)
+        result = content
+
+        # Build a mapping of placeholder index to extracted regions from both sources
+        template_by_idx = @extracted_template_regions.each_with_object({}) do |e, h|
+          h[placeholder_index(e.placeholder)] = e
+        end
+        dest_by_idx = @extracted_dest_regions.each_with_object({}) do |e, h|
+          h[placeholder_index(e.placeholder)] = e
+        end
+
+        # Find all placeholder indices in the merged content
+        all_indices = (template_by_idx.keys + dest_by_idx.keys).uniq.sort
+
+        all_indices.each do |idx|
+          template_extracted = template_by_idx[idx]
+          dest_extracted = dest_by_idx[idx]
+          placeholder = build_placeholder(idx)
+
+          merged_region_content = merge_region(template_extracted, dest_extracted)
+          result = result.gsub(placeholder, merged_region_content) if merged_region_content
+        end
+
+        result
+      end
+
+      ##
+      # Merge a region from template and destination.
+      #
+      # @param template_extracted [ExtractedRegion, nil] Template region
+      # @param dest_extracted [ExtractedRegion, nil] Destination region
+      # @return [String, nil] Merged region content, or nil if no content
+      #
+      def merge_region(template_extracted, dest_extracted)
+        config = template_extracted&.config || dest_extracted&.config
+        return unless config
+
+        template_region = template_extracted&.region
+        dest_region = dest_extracted&.region
+
+        # Get the full text (including delimiters) for each region
+        template_text = template_region&.full_text || ""
+        dest_text = dest_region&.full_text || ""
+
+        # If no merger class, prefer destination content (preserve customizations)
+        unless config.merger_class
+          return dest_text.empty? ? template_text : dest_text
+        end
+
+        # Extract just the content (without delimiters) for merging
+        template_content = template_region&.content || ""
+        dest_content = dest_region&.content || ""
+
+        # Build merger options, including nested regions if configured
+        merger_options = config.merger_options.dup
+        merger_options[:regions] = config.regions unless config.regions.empty?
+
+        # Create the merger and merge the region content
+        merger = config.merger_class.new(template_content, dest_content, **merger_options)
+        merged_content = merger.merge
+
+        # Reconstruct with delimiters
+        reconstruct_region_with_delimiters(template_region || dest_region, merged_content)
+      end
+
+      ##
+      # Reconstruct a region with its delimiters around the merged content.
+      #
+      # @param region [Region] The original region (for delimiter info)
+      # @param content [String] The merged content
+      # @return [String] Full region text with delimiters
+      #
+      def reconstruct_region_with_delimiters(region, content)
+        return content unless region&.delimiters
+
+        opening, closing = region.delimiters
+
+        # Ensure content ends with newline if it doesn't
+        normalized_content = content.end_with?("\n") ? content : "#{content}\n"
+
+        "#{opening}\n#{normalized_content}#{closing}\n"
+      end
+    end
+  end
+end