ast-merge 1.1.0 → 2.0.1

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

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Detector namespace for region detection and merging functionality.
+    #
+    # Regions are portions of a document that can be handled by a specialized
+    # merger. For example, YAML frontmatter in a Markdown file, or Ruby code
+    # blocks that should be merged with Prism.
+    #
+    # @example Detecting regions
+    #   detector = Ast::Merge::Detector::FencedCodeBlock.ruby
+    #   regions = detector.detect_all(markdown_content)
+    #   regions.each do |region|
+    #     puts "Found #{region.type} at lines #{region.start_line}-#{region.end_line}"
+    #   end
+    #
+    # @see Detector::Region Data struct for detected regions
+    # @see Detector::Base Base class for detectors
+    # @see Detector::Mergeable Mixin for region-aware merging
+    #
+    module Detector
+      # 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 }
+      #   )
+      #
+      # @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
+        :delimiters,
+
+        # @return [Hash, nil] Optional metadata for detector-specific information
+        :metadata,
+        keyword_init: true,
+      ) do
+        # Returns the line range covered by this region.
+        # @return [Range]
+        def line_range
+          start_line..end_line
+        end
+
+        # Returns the number of lines this region spans.
+        # @return [Integer]
+        def line_count
+          end_line - start_line + 1
+        end
+
+        # Reconstructs the full region text including delimiters.
+        # @return [String]
+        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 contains the given line number.
+        # @param line [Integer] The line number to check (1-indexed)
+        # @return [Boolean]
+        def contains_line?(line)
+          line_range.cover?(line)
+        end
+
+        # Checks if this region overlaps with another region.
+        # @param other [Region] Another region
+        # @return [Boolean]
+        def overlaps?(other)
+          line_range.cover?(other.start_line) ||
+            line_range.cover?(other.end_line) ||
+            other.line_range.cover?(start_line)
+        end
+
+        # @return [String]
+        def to_s
+          "Region<#{type}:#{start_line}-#{end_line}>"
+        end
+
+        # @return [String]
+        def inspect
+          truncated = if content && content.length > 30
+            "#{content[0, 30]}..."
+          else
+            content.inspect
+          end
+          "#{self} #{truncated}"
+        end
+      end
+
+      # Base class for region detection.
+      #
+      # Region detectors identify portions of a document that should be handled
+      # by a specialized merger.
+      #
+      # 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::Detector::Base
+      #     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 Base
+        # Returns the type symbol for regions detected by this detector.
+        # @return [Symbol]
+        # @abstract
+        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
+        def detect_all(_source)
+          raise NotImplementedError, "#{self.class}#detect_all must be implemented"
+        end
+
+        # Whether to strip delimiters from content before passing to merger.
+        # @return [Boolean]
+        def strip_delimiters?
+          true
+        end
+
+        # A human-readable name for this detector.
+        # @return [String]
+        def name
+          self.class.name || "AnonymousDetector"
+        end
+
+        # @return [String]
+        def inspect
+          "#<#{name} region_type=#{region_type}>"
+        end
+
+        protected
+
+        # Helper to build a Region struct.
+        # @return [Region]
+        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
+
+      autoload :FencedCodeBlock, "ast/merge/detector/fenced_code_block"
+      autoload :YamlFrontmatter, "ast/merge/detector/yaml_frontmatter"
+      autoload :TomlFrontmatter, "ast/merge/detector/toml_frontmatter"
+      autoload :Mergeable, "ast/merge/detector/mergeable"
+    end
+  end
+end

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