ast-merge 1.0.0 → 2.0.0

data/lib/ast/merge/region_mergeable.rb

@@ -1,364 +0,0 @@
-# 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

data/lib/ast/merge/toml_frontmatter_detector.rb

@@ -1,88 +0,0 @@
-# frozen_string_literal: true
-
-module Ast
-  module Merge
-    ##
-    # Detects TOML frontmatter at the beginning of a document.
-    #
-    # TOML frontmatter is delimited by `+++` at the start and end,
-    # and must begin on the first line of the document (optionally
-    # preceded by a UTF-8 BOM). This format is commonly used by
-    # Hugo and other static site generators.
-    #
-    # @example TOML frontmatter
-    #   +++
-    #   title = "My Document"
-    #   author = "Jane Doe"
-    #   +++
-    #
-    # @example Usage
-    #   detector = TomlFrontmatterDetector.new
-    #   regions = detector.detect_all(markdown_source)
-    #   # => [#<Region type=:toml_frontmatter content="title = \"My Document\"\n...">]
-    #
-    class TomlFrontmatterDetector < RegionDetectorBase
-      ##
-      # Pattern for detecting TOML frontmatter.
-      # - Must start at beginning of document (or after BOM)
-      # - Opening delimiter is `+++` followed by optional whitespace and newline
-      # - Content is captured (non-greedy)
-      # - Closing delimiter is `+++` at start of line, followed by optional whitespace and newline/EOF
-      #
-      FRONTMATTER_PATTERN = /\A(?:\xEF\xBB\xBF)?(\+\+\+[ \t]*\r?\n)(.*?)(^\+\+\+[ \t]*(?:\r?\n|\z))/m
-
-      ##
-      # @return [Symbol] the type identifier for TOML frontmatter regions
-      #
-      def region_type
-        :toml_frontmatter
-      end
-
-      ##
-      # Detects TOML frontmatter at the beginning of the document.
-      #
-      # @param source [String] the source document to scan
-      # @return [Array<Region>] array containing at most one Region for frontmatter
-      #
-      def detect_all(source)
-        return [] if source.nil? || source.empty?
-
-        match = source.match(FRONTMATTER_PATTERN)
-        return [] unless match
-
-        opening_delimiter = match[1]
-        content = match[2]
-        closing_delimiter = match[3]
-
-        # Calculate line numbers
-        start_line = 1
-
-        # Count total newlines in the full match to determine end line
-        full_match = match[0]
-        total_newlines = full_match.count("\n")
-        end_line = total_newlines + (full_match.end_with?("\n") ? 0 : 1)
-
-        [
-          Region.new(
-            type: region_type,
-            content: content,
-            start_line: start_line,
-            end_line: end_line,
-            delimiters: [opening_delimiter.strip, closing_delimiter.strip],
-            metadata: {format: :toml},
-          ),
-        ]
-      end
-
-      private
-
-      ##
-      # @return [Array<Region>] array containing at most one Region
-      #
-      def build_regions(source, matches)
-        # Not used - detect_all is overridden directly
-        raise NotImplementedError, "TomlFrontmatterDetector overrides detect_all directly"
-      end
-    end
-  end
-end

data/lib/ast/merge/yaml_frontmatter_detector.rb

@@ -1,108 +0,0 @@
-# frozen_string_literal: true
-
-module Ast
-  module Merge
-    ##
-    # Detects YAML frontmatter at the beginning of a document.
-    #
-    # YAML frontmatter is delimited by `---` at the start and end,
-    # and must begin on the first line of the document (optionally
-    # preceded by a UTF-8 BOM).
-    #
-    # @example YAML frontmatter
-    #   ---
-    #   title: My Document
-    #   author: Jane Doe
-    #   ---
-    #
-    # @example Usage
-    #   detector = YamlFrontmatterDetector.new
-    #   regions = detector.detect_all(markdown_source)
-    #   # => [#<Region type=:yaml_frontmatter content="title: My Document\n...">]
-    #
-    class YamlFrontmatterDetector < RegionDetectorBase
-      ##
-      # Pattern for detecting YAML frontmatter.
-      # - Must start at beginning of document (or after BOM)
-      # - Opening delimiter is `---` followed by optional whitespace and newline
-      # - Content is captured (non-greedy)
-      # - Closing delimiter is `---` at start of line, followed by optional whitespace and newline/EOF
-      #
-      FRONTMATTER_PATTERN = /\A(?:\xEF\xBB\xBF)?(---[ \t]*\r?\n)(.*?)(^---[ \t]*(?:\r?\n|\z))/m
-
-      ##
-      # @return [Symbol] the type identifier for YAML frontmatter regions
-      #
-      def region_type
-        :yaml_frontmatter
-      end
-
-      ##
-      # Detects YAML frontmatter at the beginning of the document.
-      #
-      # @param source [String] the source document to scan
-      # @return [Array<Region>] array containing at most one Region for frontmatter
-      #
-      def detect_all(source)
-        return [] if source.nil? || source.empty?
-
-        match = source.match(FRONTMATTER_PATTERN)
-        return [] unless match
-
-        opening_delimiter = match[1]
-        content = match[2]
-        closing_delimiter = match[3]
-
-        # Calculate line numbers
-        # Frontmatter starts at line 1 (or after BOM)
-        start_line = 1
-        # Count newlines in content to determine end line
-        # Opening delimiter ends at line 1
-        # Content spans from line 2 to line 2 + content_lines - 1
-        # Closing delimiter is on the next line
-        content_newlines = content.count("\n")
-        # end_line is the line with the closing ---
-        end_line = start_line + 1 + content_newlines
-
-        # Adjust if content ends without newline
-        end_line - 1 if content.end_with?("\n") && content_newlines > 0
-
-        # Actually, let's calculate more carefully
-        # Line 1: ---
-        # Line 2 to N: content
-        # Line N+1: ---
-        if content.empty?
-          0
-        else
-          content.count("\n") + (content.end_with?("\n") ? 0 : 1)
-        end
-
-        # Simplify: count total newlines in the full match to determine end line
-        full_match = match[0]
-        total_newlines = full_match.count("\n")
-        end_line = total_newlines + (full_match.end_with?("\n") ? 0 : 1)
-
-        [
-          Region.new(
-            type: region_type,
-            content: content,
-            start_line: start_line,
-            end_line: end_line,
-            delimiters: [opening_delimiter.strip, closing_delimiter.strip],
-            metadata: {format: :yaml},
-          ),
-        ]
-      end
-
-      private
-
-      ##
-      # @return [Array<Region>] array containing at most one Region
-      #
-      def build_regions(source, matches)
-        # Not used - detect_all is overridden directly
-        raise NotImplementedError, "YamlFrontmatterDetector overrides detect_all directly"
-      end
-    end
-  end
-end