markdown-merge 1.0.0

data/lib/markdown/merge/freeze_node.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Markdown
+  module Merge
+    # Represents a frozen block of Markdown content that should be preserved during merges.
+    #
+    # Freeze blocks are marked with HTML comments:
+    #   <!-- markdown-merge:freeze -->
+    #   ... frozen content ...
+    #   <!-- markdown-merge:unfreeze -->
+    #
+    # Content within freeze blocks is preserved exactly as-is during merge operations,
+    # preventing automated tools from modifying manually-curated sections.
+    #
+    # @example Basic freeze block
+    #   <!-- markdown-merge:freeze -->
+    #   ## Custom Section
+    #   This content will not be modified by merge operations.
+    #   <!-- markdown-merge:unfreeze -->
+    #
+    # @example Freeze block with reason
+    #   <!-- markdown-merge:freeze Manual TOC -->
+    #   ## Table of Contents
+    #   - [Introduction](#introduction)
+    #   - [Usage](#usage)
+    #   <!-- markdown-merge:unfreeze -->
+    #
+    # @see Ast::Merge::FreezeNodeBase Base class
+    class FreezeNode < Ast::Merge::FreezeNodeBase
+      # Initialize a new FreezeNode
+      #
+      # @param start_line [Integer] Starting line number (1-indexed)
+      # @param end_line [Integer] Ending line number (1-indexed)
+      # @param content [String] Raw Markdown content within the block
+      # @param start_marker [String] The freeze marker comment
+      # @param end_marker [String] The unfreeze marker comment
+      # @param nodes [Array] Parsed nodes within the block
+      # @param reason [String, nil] Optional reason extracted from marker
+      def initialize(start_line:, end_line:, content:, start_marker:, end_marker:, nodes: [], reason: nil)
+        # Let the base class handle reason extraction via pattern_for
+        super(
+          start_line: start_line,
+          end_line: end_line,
+          content: content,
+          nodes: nodes,
+          start_marker: start_marker,
+          end_marker: end_marker,
+          pattern_type: :html_comment,
+          reason: reason
+        )
+      end
+
+      # Generate a signature for matching this freeze block
+      #
+      # Signatures are based on the normalized content, allowing freeze blocks
+      # with the same content to be matched across files.
+      #
+      # @return [Array<Symbol, String>] Signature array [:freeze_block, content_digest]
+      def signature
+        [:freeze_block, Digest::SHA256.hexdigest(content.strip)[0, 16]]
+      end
+
+      # Get the full text including markers
+      #
+      # @return [String] Complete freeze block with markers
+      def full_text
+        "#{start_marker}\n#{content}\n#{end_marker}"
+      end
+
+      # Get line count of the freeze block
+      #
+      # @return [Integer] Number of lines
+      def line_count
+        end_line - start_line + 1
+      end
+
+      # Check if block contains a specific node type
+      #
+      # @param type [Symbol] Node type to check for (e.g., :heading, :paragraph)
+      # @return [Boolean] True if block contains the node type
+      def contains_type?(type)
+        nodes.any? { |node| node.type == type }
+      end
+
+      # String representation for debugging
+      #
+      # @return [String] Debug representation
+      def inspect
+        "#<#{self.class.name} lines=#{start_line}..#{end_line} nodes=#{nodes.size} reason=#{reason.inspect}>"
+      end
+    end
+  end
+end

data/lib/markdown/merge/gap_line_node.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Markdown
+  module Merge
+    # Represents a "gap" line that exists between parsed Markdown nodes.
+    #
+    # Markdown parsers like Markly consume certain content during parsing (like
+    # link reference definitions) and don't preserve blank lines between nodes
+    # in the AST. This class represents lines that fall into "gaps" between
+    # parsed nodes, allowing them to be preserved during merge operations.
+    #
+    # Gap lines include:
+    # - Blank lines between sections
+    # - Link reference definitions (handled specially by LinkDefinitionNode)
+    # - Any other content consumed by the parser
+    #
+    # @example
+    #   node = GapLineNode.new("", line_number: 5)
+    #   node.type      # => :gap_line
+    #   node.blank?    # => true
+    #   node.signature # => [:gap_line, 5, ""]
+    class GapLineNode < Ast::Merge::AstNode
+      # @return [String] The line content (may be empty for blank lines)
+      attr_reader :content
+
+      # @return [Integer] 1-based line number
+      attr_reader :line_number
+
+      # @return [Object, nil] The preceding structural node (for context-aware signatures)
+      # This is set after integration to avoid circular dependencies during creation
+      attr_accessor :preceding_node
+
+      # Initialize a new GapLineNode
+      #
+      # @param content [String] The line content (without trailing newline)
+      # @param line_number [Integer] 1-based line number
+      def initialize(content, line_number:)
+        @content = content.chomp
+        @line_number = line_number
+        @preceding_node = nil  # Set later during integration
+
+        location = Ast::Merge::AstNode::Location.new(
+          start_line: line_number,
+          end_line: line_number,
+          start_column: 0,
+          end_column: @content.length,
+        )
+
+        super(slice: @content, location: location)
+      end
+
+      # TreeHaver::Node protocol: type
+      # @return [Symbol] :gap_line
+      def type
+        :gap_line
+      end
+
+      # Alias for compatibility with wrapped nodes that have merge_type
+      # @return [Symbol] :gap_line
+      alias_method :merge_type, :type
+
+      # Generate a signature for matching gap lines.
+      # Gap lines are matched by their position relative to the preceding structural node.
+      # This allows blank lines after a heading in template to match blank lines after
+      # the same heading in destination, even if they're on different absolute line numbers.
+      #
+      # For gap lines at the start of the document (no preceding node), we use line number.
+      # For gap lines after a structural node, we use offset from that node's end line.
+      #
+      # @return [Array] Signature array
+      def signature
+        if @preceding_node&.respond_to?(:source_position)
+          pos = @preceding_node.source_position
+          preceding_end_line = pos[:end_line] if pos
+
+          if preceding_end_line
+            # Offset from preceding node's end (e.g., heading ends on line 1, gap is line 2, offset = 1)
+            offset = @line_number - preceding_end_line
+
+            # Use the preceding node's type as context (simpler than full signature)
+            # This works because gap lines after headings match gap lines after headings, etc.
+            preceding_type = @preceding_node.respond_to?(:type) ? @preceding_node.type : :unknown
+
+            [:gap_line_after, preceding_type, offset, @content]
+          else
+            # Fallback if we can't get position
+            [:gap_line, @line_number, @content]
+          end
+        else
+          # No preceding node - use absolute line number (for gaps at document start)
+          [:gap_line, @line_number, @content]
+        end
+      end
+
+      # TreeHaver::Node protocol: source_position
+      # @return [Hash] Position info for source extraction
+      def source_position
+        {
+          start_line: @line_number,
+          end_line: @line_number,
+          start_column: 0,
+          end_column: @content.length,
+        }
+      end
+
+      # TreeHaver::Node protocol: children (none)
+      # @return [Array] Empty array
+      def children
+        []
+      end
+
+      # TreeHaver::Node protocol: text
+      # @return [String] The line content
+      def text
+        @content
+      end
+
+      # Check if this is a blank line
+      # @return [Boolean] true if line is empty or whitespace only
+      def blank?
+        @content.strip.empty?
+      end
+
+      # Convert to commonmark format
+      # @return [String] The line with trailing newline
+      def to_commonmark
+        "#{@content}\n"
+      end
+
+      # For debugging
+      def inspect
+        "#<#{self.class.name} line=#{@line_number} content=#{@content.inspect}>"
+      end
+    end
+  end
+end

data/lib/markdown/merge/link_definition_formatter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Markdown
+  module Merge
+    # Formats link reference definitions for output.
+    #
+    # Markdown parsers (especially cmark-based ones like Markly/Commonmarker)
+    # consume link reference definitions during parsing and resolve them into
+    # inline links. This means they don't appear as nodes in the AST.
+    #
+    # This formatter reconstructs the markdown syntax from LinkDefinitionNode
+    # instances so they can be included in the merged output.
+    #
+    # @example
+    #   node = LinkDefinitionNode.new(
+    #     "[ref]: https://example.com \"Title\"",
+    #     label: "ref",
+    #     url: "https://example.com",
+    #     title: "Title"
+    #   )
+    #   LinkDefinitionFormatter.format(node)
+    #   # => "[ref]: https://example.com \"Title\""
+    module LinkDefinitionFormatter
+      class << self
+        # Format a link definition node
+        #
+        # @param node [LinkDefinitionNode] The link definition node
+        # @return [String] Formatted link definition
+        def format(node)
+          return node.content if node.content && !node.content.empty?
+
+          # Reconstruct from components
+          output = "[#{node.label}]: #{node.url}"
+          output += " \"#{node.title}\"" if node.title && !node.title.empty?
+          output
+        end
+
+        # Format multiple link definitions
+        #
+        # @param nodes [Array<LinkDefinitionNode>] Link definition nodes
+        # @param separator [String] Separator between definitions
+        # @return [String] Formatted link definitions
+        def format_all(nodes, separator: "\n")
+          nodes.map { |node| format(node) }.join(separator)
+        end
+      end
+    end
+  end
+end

data/lib/markdown/merge/link_definition_node.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Markdown
+  module Merge
+    # Represents a link reference definition that was consumed by the Markdown parser.
+    #
+    # Markdown parsers like Markly (libcmark-gfm) consume link reference definitions
+    # during parsing and resolve them into inline links. This means they don't appear
+    # as nodes in the AST. This class represents these "consumed" definitions so they
+    # can be preserved during merge operations.
+    #
+    # Link reference definitions have the form:
+    #   [label]: url "optional title"
+    #   [label]: url 'optional title'
+    #   [label]: url (optional title)
+    #   [label]: <url> "optional title"
+    #
+    # Uses {LinkParser} for robust parsing that handles:
+    # - Emoji in labels (e.g., `[🖼️galtzo-discord]`)
+    # - Multi-byte UTF-8 characters
+    # - Nested brackets in labels
+    #
+    # @example
+    #   node = LinkDefinitionNode.new(
+    #     "[ref]: https://example.com",
+    #     line_number: 10,
+    #     label: "ref",
+    #     url: "https://example.com"
+    #   )
+    #   node.type        # => :link_definition
+    #   node.label       # => "ref"
+    #   node.url         # => "https://example.com"
+    #   node.signature   # => [:link_definition, "ref"]
+    class LinkDefinitionNode < Ast::Merge::AstNode
+      # @return [String] The link label (reference name)
+      attr_reader :label
+
+      # @return [String] The URL
+      attr_reader :url
+
+      # @return [String, nil] Optional title
+      attr_reader :title
+
+      # @return [String] The full original line content
+      attr_reader :content
+
+      # Initialize a new LinkDefinitionNode
+      #
+      # @param content [String] The full line content
+      # @param line_number [Integer] 1-based line number
+      # @param label [String] The link label
+      # @param url [String] The URL
+      # @param title [String, nil] Optional title
+      def initialize(content, line_number:, label:, url:, title: nil)
+        @content = content
+        @label = label
+        @url = url
+        @title = title
+
+        location = Ast::Merge::AstNode::Location.new(
+          start_line: line_number,
+          end_line: line_number,
+          start_column: 0,
+          end_column: content.length,
+        )
+
+        super(slice: content, location: location)
+      end
+
+      class << self
+        # Shared parser instance for parsing link definitions
+        # @return [LinkParser]
+        def parser
+          @parser ||= LinkParser.new # rubocop:disable ThreadSafety/ClassInstanceVariable
+        end
+
+        # Parse a line and create a LinkDefinitionNode if it's a link definition.
+        #
+        # @param line [String] The line content
+        # @param line_number [Integer] 1-based line number
+        # @return [LinkDefinitionNode, nil] Node if line is a link definition, nil otherwise
+        def parse(line, line_number:)
+          result = parser.parse_definition_line(line.chomp)
+          return unless result
+
+          new(
+            line.chomp,
+            line_number: line_number,
+            label: result[:label],
+            url: result[:url],
+            title: result[:title],
+          )
+        end
+
+        # Check if a line looks like a link reference definition.
+        #
+        # @param line [String] The line to check
+        # @return [Boolean] true if line matches link definition pattern
+        def link_definition?(line)
+          !parser.parse_definition_line(line.strip).nil?
+        end
+      end
+
+      # TreeHaver::Node protocol: type
+      # @return [Symbol] :link_definition
+      def type
+        :link_definition
+      end
+
+      # Alias for compatibility with wrapped nodes that have merge_type
+      # @return [Symbol] :link_definition
+      alias_method :merge_type, :type
+
+      # Generate a signature for matching link definitions.
+      # Link definitions are matched by their label (case-insensitive in Markdown).
+      #
+      # @return [Array] Signature array [:link_definition, lowercase_label]
+      def signature
+        [:link_definition, @label.downcase]
+      end
+
+      # TreeHaver::Node protocol: source_position
+      # @return [Hash] Position info for source extraction
+      def source_position
+        {
+          start_line: @location.start_line,
+          end_line: @location.end_line,
+          start_column: @location.start_column,
+          end_column: @location.end_column,
+        }
+      end
+
+      # TreeHaver::Node protocol: children (none for link definitions)
+      # @return [Array] Empty array
+      def children
+        []
+      end
+
+      # TreeHaver::Node protocol: text
+      # @return [String] The full line content
+      def text
+        @content
+      end
+
+      # Convert to commonmark format (just returns the original content)
+      # @return [String] The link definition line
+      def to_commonmark
+        "#{@content}\n"
+      end
+
+      # For debugging
+      def inspect
+        "#<#{self.class.name} [#{@label}]: #{@url}>"
+      end
+    end
+  end
+end