ast-merge 1.0.0 → 2.0.0

data/lib/ast/merge/detector/fenced_code_block.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Detector
+      # Detects fenced code blocks with a specific language identifier.
+      #
+      # This detector finds Markdown-style fenced code blocks (using ``` or ~~~)
+      # that have a specific language identifier. It can be configured for any
+      # language: ruby, json, yaml, mermaid, etc.
+      #
+      # ## When to Use This Detector
+      #
+      # **Use FencedCodeBlock when:**
+      # - Working with raw Markdown text without parsing to AST
+      # - Quick extraction from strings without parser dependencies
+      # - Custom text processing requiring line-level precision
+      # - Operating on source text directly (e.g., linters, formatters)
+      #
+      # **Do NOT use FencedCodeBlock when:**
+      # - Working with parsed Markdown AST (use native code block nodes instead)
+      # - Integrating with markdown-merge's CodeBlockMerger (it uses native nodes)
+      # - Using tree_haver's unified Markdown backend API
+      #
+      # @example Detecting Ruby code blocks
+      #   detector = FencedCodeBlock.new("ruby", aliases: ["rb"])
+      #   regions = detector.detect_all(markdown_source)
+      #
+      # @example Using factory methods
+      #   detector = FencedCodeBlock.ruby
+      #   detector = FencedCodeBlock.yaml
+      #   detector = FencedCodeBlock.json
+      #
+      # @api public
+      #
+      class FencedCodeBlock < Base
+        # @return [String] The primary language identifier
+        attr_reader :language
+
+        # @return [Array<String>] Alternative language identifiers
+        attr_reader :aliases
+
+        # Creates a new detector for the specified language.
+        #
+        # @param language [String, Symbol] The language identifier (e.g., "ruby", "json")
+        # @param aliases [Array<String, Symbol>] Alternative identifiers (e.g., ["rb"] for ruby)
+        def initialize(language, aliases: [])
+          super()
+          @language = language.to_s.downcase
+          @aliases = aliases.map { |a| a.to_s.downcase }
+          @all_identifiers = [@language] + @aliases
+        end
+
+        # @return [Symbol] The region type (e.g., :ruby_code_block)
+        def region_type
+          :"#{@language}_code_block"
+        end
+
+        # Check if a language identifier matches this detector.
+        #
+        # @param lang [String] The language identifier to check
+        # @return [Boolean] true if the language matches
+        def matches_language?(lang)
+          @all_identifiers.include?(lang.to_s.downcase)
+        end
+
+        # Detects all fenced code blocks with the configured language.
+        #
+        # @param source [String] The full document content
+        # @return [Array<Region>] All detected code blocks, sorted by start_line
+        def detect_all(source)
+          return [] if source.nil? || source.empty?
+
+          regions = []
+          lines = source.lines
+          in_block = false
+          start_line = nil
+          content_lines = []
+          current_language = nil
+          fence_char = nil
+          fence_length = nil
+          indent = ""
+
+          lines.each_with_index do |line, idx|
+            line_num = idx + 1
+
+            if !in_block
+              # Match opening fence: ```lang or ~~~lang (optionally indented)
+              match = line.match(/^(\s*)(`{3,}|~{3,})(\w*)\s*$/)
+              if match
+                indent = match[1] || ""
+                fence = match[2]
+                lang = match[3].downcase
+
+                if @all_identifiers.include?(lang)
+                  in_block = true
+                  start_line = line_num
+                  content_lines = []
+                  current_language = lang
+                  fence_char = fence[0]
+                  fence_length = fence.length
+                end
+              end
+            elsif line.match?(/^#{Regexp.escape(indent)}#{Regexp.escape(fence_char)}{#{fence_length},}\s*$/)
+              # Match closing fence (must use same char, same indent, and at least same length)
+              opening_fence = "#{fence_char * fence_length}#{current_language}"
+              closing_fence = fence_char * fence_length
+
+              regions << build_region(
+                type: region_type,
+                content: content_lines.join,
+                start_line: start_line,
+                end_line: line_num,
+                delimiters: [opening_fence, closing_fence],
+                metadata: {language: current_language, indent: indent.empty? ? nil : indent},
+              )
+              in_block = false
+              start_line = nil
+              content_lines = []
+              current_language = nil
+              fence_char = nil
+              fence_length = nil
+              indent = ""
+            else
+              # Accumulate content lines (strip the indent if present)
+              content_lines << if indent.empty?
+                line
+              else
+                # Strip the common indent from content lines
+                line.sub(/^#{Regexp.escape(indent)}/, "")
+              end
+            end
+          end
+
+          # Note: Unclosed blocks are ignored (no region created)
+          regions
+        end
+
+        # @return [String] A description of this detector
+        def inspect
+          aliases_str = @aliases.empty? ? "" : " aliases=#{@aliases.inspect}"
+          "#<#{self.class.name} language=#{@language}#{aliases_str}>"
+        end
+
+        class << self
+          # Creates a detector for Ruby code blocks.
+          # @return [FencedCodeBlock]
+          def ruby
+            new("ruby", aliases: ["rb"])
+          end
+
+          # Creates a detector for JSON code blocks.
+          # @return [FencedCodeBlock]
+          def json
+            new("json")
+          end
+
+          # Creates a detector for YAML code blocks.
+          # @return [FencedCodeBlock]
+          def yaml
+            new("yaml", aliases: ["yml"])
+          end
+
+          # Creates a detector for TOML code blocks.
+          # @return [FencedCodeBlock]
+          def toml
+            new("toml")
+          end
+
+          # Creates a detector for Mermaid diagram blocks.
+          # @return [FencedCodeBlock]
+          def mermaid
+            new("mermaid")
+          end
+
+          # Creates a detector for JavaScript code blocks.
+          # @return [FencedCodeBlock]
+          def javascript
+            new("javascript", aliases: ["js"])
+          end
+
+          # Creates a detector for TypeScript code blocks.
+          # @return [FencedCodeBlock]
+          def typescript
+            new("typescript", aliases: ["ts"])
+          end
+
+          # Creates a detector for Python code blocks.
+          # @return [FencedCodeBlock]
+          def python
+            new("python", aliases: ["py"])
+          end
+
+          # Creates a detector for Bash/Shell code blocks.
+          # @return [FencedCodeBlock]
+          def bash
+            new("bash", aliases: ["sh", "shell", "zsh"])
+          end
+
+          # Creates a detector for SQL code blocks.
+          # @return [FencedCodeBlock]
+          def sql
+            new("sql")
+          end
+
+          # Creates a detector for HTML code blocks.
+          # @return [FencedCodeBlock]
+          def html
+            new("html")
+          end
+
+          # Creates a detector for CSS code blocks.
+          # @return [FencedCodeBlock]
+          def css
+            new("css")
+          end
+
+          # Creates a detector for Markdown code blocks (nested markdown).
+          # @return [FencedCodeBlock]
+          def markdown
+            new("markdown", aliases: ["md"])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ast/merge/detector/mergeable.rb

@@ -0,0 +1,369 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Detector
+      ##
+      # 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 Detector::Mergeable
+      #
+      #     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: Detector::YamlFrontmatter.new,
+      #         merger_class: SomeYamlMerger,
+      #         merger_options: { preserve_order: true }
+      #       }
+      #     ]
+      #   )
+      #
+      # @example With nested regions (code blocks in markdown)
+      #   merger = SmartMerger.new(
+      #     template,
+      #     dest,
+      #     regions: [
+      #       {
+      #         detector: Detector::FencedCodeBlock.ruby,
+      #         merger_class: Prism::Merge::SmartMerger,
+      #         regions: [...]  # Nested regions!
+      #       }
+      #     ]
+      #   )
+      #
+      # @see Base For implementing custom detectors
+      # @see Region The data struct for detected regions
+      #
+      module Mergeable
+        # Default placeholder prefix for extracted regions
+        DEFAULT_PLACEHOLDER_PREFIX = "<<<AST_MERGE_REGION_"
+        DEFAULT_PLACEHOLDER_SUFFIX = ">>>"
+
+        ##
+        # Configuration for a single region type.
+        #
+        # @attr detector [Base] 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)
+        #
+        Config = 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 [Config] 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 Config objects from configuration hashes.
+        #
+        # @param configs [Array<Hash>] Array of configuration hashes
+        # @return [Array<Config>] Array of Config objects
+        #
+        def build_region_configs(configs)
+          return [] if configs.nil? || configs.empty?
+
+          configs.map do |config|
+            case config
+            when Config
+              config
+            when Hash
+              Config.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
+end

data/lib/ast/merge/detector/toml_frontmatter.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Detector
+      ##
+      # 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 = TomlFrontmatter.new
+      #   regions = detector.detect_all(markdown_source)
+      #   # => [#<Region type=:toml_frontmatter content="title = \"My Document\"\n...">]
+      #
+      # @see YamlFrontmatter For YAML frontmatter detection
+      #
+      class TomlFrontmatter < Base
+        ##
+        # 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
+      end
+    end
+  end
+end