markdown-merge 1.0.3 → 7.1.1

data/lib/markdown/merge/file_analysis_base.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-require "digest"
-require "set"
+require 'digest'
 
 module Markdown
   module Merge
@@ -40,7 +39,7 @@ module Markdown
 
       # Default freeze token for identifying freeze blocks
       # @return [String]
-      DEFAULT_FREEZE_TOKEN = "markdown-merge"
+      DEFAULT_FREEZE_TOKEN = 'markdown-merge'
 
       # @return [Object] The root document node
       attr_reader :document
@@ -48,7 +47,10 @@ module Markdown
       # @return [Array] Parse errors if any
       attr_reader :errors
 
-      # Note: :source is inherited from Ast::Merge::FileAnalyzable
+      # @return [CommentTracker] Comment tracker for this file
+      attr_reader :comment_tracker
+
+      # NOTE: :source is inherited from Ast::Merge::FileAnalyzable
 
       # Initialize file analysis
       #
@@ -61,7 +63,8 @@ module Markdown
         # But remove the final empty string if source ends with newline
         # (that empty string represents the "line after the last newline" which doesn't exist)
         @lines = source.split("\n", -1)
-        @lines.pop if @lines.last == "" && source.end_with?("\n")
+        @lines.pop if @lines.last == '' && source.end_with?("\n")
+        @comment_tracker = CommentTracker.new(@lines)
 
         @freeze_token = freeze_token
         @signature_generator = signature_generator
@@ -69,19 +72,19 @@ module Markdown
         @errors = []
 
         # Parse the Markdown source - subclasses implement this
-        @document = DebugLogger.time("FileAnalysisBase#parse") do
+        @document = DebugLogger.time('FileAnalysisBase#parse') do
           parse_document(source)
         end
 
         # Extract and integrate all nodes including freeze blocks
         @statements = extract_and_integrate_all_nodes
 
-        DebugLogger.debug("FileAnalysisBase initialized", {
-          signature_generator: signature_generator ? "custom" : "default",
-          document_children: count_children(@document),
-          statements_count: @statements.size,
-          freeze_blocks: freeze_blocks.size,
-        })
+        DebugLogger.debug('FileAnalysisBase initialized', {
+                            signature_generator: signature_generator ? 'custom' : 'default',
+                            document_children: count_children(@document),
+                            statements_count: @statements.size,
+                            freeze_blocks: freeze_blocks.size
+                          })
       end
 
       # Parse the source document.
@@ -110,6 +113,106 @@ module Markdown
         @errors.empty? && !@document.nil?
       end
 
+      # Get shared comment capability information for this analysis.
+      #
+      # @return [Object]
+      def comment_capability
+        @comment_capability ||= comment_tracker.augment(owners: []).capability
+      end
+
+      # Describe how Markdown merges currently own and emit comments.
+      #
+      # Standalone HTML comments are source-augmented and emitted through the
+      # shared synthetic comment layer rather than parser-native comment AST.
+      #
+      # @return [Ast::Merge::Comment::SupportStyle]
+      def comment_support_style
+        @comment_support_style ||= shared_comment_support_style(
+          source: :markdown_source,
+          style: :html_comment,
+          read_strategy: :source_augmented_portable_write
+        )
+      end
+
+      # Get all tracked comments converted to shared comment nodes.
+      #
+      # @return [Array]
+      def comment_nodes
+        comment_tracker.comment_nodes
+      end
+
+      # Get a shared comment node at a specific line.
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Object, nil]
+      def comment_node_at(line_num)
+        comment_tracker.comment_node_at(line_num)
+      end
+
+      # Get comments in a line range converted to a shared comment region.
+      #
+      # @param range [Range] Range of 1-based line numbers
+      # @param kind [Symbol] Region kind
+      # @param full_line_only [Boolean] Whether to keep only full-line comments
+      # @return [Object]
+      def comment_region_for_range(range, kind:, full_line_only: false)
+        comment_tracker.comment_region_for_range(
+          range,
+          kind: kind,
+          full_line_only: full_line_only
+        )
+      end
+
+      # Build a passive shared comment attachment for an owner.
+      #
+      # @param owner [Object] Structural owner for the attachment
+      # @param options [Hash] Additional metadata / lookup overrides
+      # @return [Object]
+      def comment_attachment_for(owner, **options)
+        augmented_attachment = comment_augmenter(**options).attachment_for(owner)
+
+        shared_comment_attachment_for(
+          owner,
+          tracker_attachment: augmented_attachment || comment_tracker.comment_attachment_for(owner, **options),
+          **options
+        )
+      end
+
+      # @return [Symbol]
+      def comment_attachment_strategy
+        :normalize_tracked_layout_merge
+      end
+
+      def ruleset_logical_owners
+        {
+          link_definition: :preserve_if_referenced
+        }
+      end
+
+      def ruleset_surfaces
+        [
+          { name: :fenced_code_block, selector: :language_tag }
+        ]
+      end
+
+      def ruleset_delegation_policies
+        [
+          { surface_name: :fenced_code_block, strategy: :by_language }
+        ]
+      end
+
+      # Build a passive shared comment augmenter for this analysis.
+      #
+      # @param owners [Array, nil] Owners used for attachment inference
+      # @param options [Hash] Additional augmenter options
+      # @return [Object]
+      def comment_augmenter(owners: nil, **options)
+        comment_tracker.augment(
+          owners: owners || comment_augmenter_default_owners,
+          **options
+        )
+      end
+
       # Get all statements (block nodes outside freeze blocks + FreezeNode instances)
       # @return [Array<Object, FreezeNode>]
       attr_reader :statements
@@ -159,8 +262,18 @@ module Markdown
         type = node.type
         case type
         when :heading, :header
-          # Content-based: Match headings by level and text content
-          [:heading, node.header_level, extract_text_content(node)]
+          level = node.header_level
+          # H1 is the document title — treat as a singleton.
+          # A well-formed markdown document has exactly one H1. Matching by text
+          # would cause a generic template title ("AGENTS.md - Development Guide")
+          # and a project-qualified destination title ("AGENTS.md - myGem Development Guide")
+          # to be treated as different nodes, keeping both in the merged output.
+          # Using level-only for H1 makes them the same structural slot so the
+          # preferred version wins cleanly without duplication.
+          return [:heading, 1] if level == 1
+
+          # H2+ match by level and normalized text content
+          [:heading, level, extract_text_content(node)]
         when :paragraph
           # Content-based: Match paragraphs by content hash (first 32 chars of digest)
           text = extract_text_content(node)
@@ -171,9 +284,20 @@ module Markdown
           fence_info = node.respond_to?(:fence_info) ? node.fence_info : nil
           [:code_block, fence_info, Digest::SHA256.hexdigest(content)[0, 16]]
         when :list
-          # Structure-based: Match lists by type and item count (content may differ)
+          # Content-fingerprint: Match lists by type and a hash of the first few
+          # items' significant tokens. This lets two lists with similar (but not
+          # identical) content match by signature so item-level inner-merge can run,
+          # rather than the template list being appended as a template-only node.
           list_type = node.respond_to?(:list_type) ? node.list_type : nil
-          [:list, list_type, count_children(node)]
+          items_text = []
+          child = node.first_child
+          while child
+            items_text << extract_text_content(child).downcase.gsub(/\W+/, ' ').strip
+            child = next_sibling(child)
+            break if items_text.size >= 5
+          end
+          fingerprint = Digest::SHA256.hexdigest(items_text.sort.join('|'))[0, 16]
+          [:list, list_type, fingerprint]
         when :block_quote, :blockquote
           # Content-based: Match block quotes by content hash
           text = extract_text_content(node)
@@ -238,10 +362,10 @@ module Markdown
       # @param end_line [Integer] End line (1-indexed)
       # @return [String] Source text
       def source_range(start_line, end_line)
-        return "" if start_line < 1 || end_line < start_line
+        return '' if start_line < 1 || end_line < start_line
 
         extracted_lines = @lines[(start_line - 1)..(end_line - 1)]
-        return "" if extracted_lines.empty?
+        return '' if extracted_lines.empty?
 
         # Add newlines between and after lines, but not after the last line of the file
         # unless it originally had one
@@ -267,7 +391,7 @@ module Markdown
       def extract_table_header_content(node)
         # First row of a table is typically the header
         first_row = node.first_child
-        return "" unless first_row
+        return '' unless first_row
 
         extract_text_content(first_row)
       end
@@ -287,6 +411,22 @@ module Markdown
 
       private
 
+      def comment_augmenter_default_owners
+        @comment_augmenter_default_owners ||= @statements.select do |statement|
+          statement.respond_to?(:source_position) && statement.source_position &&
+            (!statement.respond_to?(:merge_type) || statement.merge_type != :gap_line) &&
+            !standalone_comment_statement?(statement)
+        end
+      end
+
+      def standalone_comment_statement?(statement)
+        pos = statement.respond_to?(:source_position) ? statement.source_position : nil
+        return false unless pos
+        return false unless pos[:start_line] && pos[:end_line] && pos[:start_line] == pos[:end_line]
+
+        comment_tracker.comment_node_at(pos[:start_line])
+      end
+
       # Extract all nodes and integrate freeze blocks
       # @return [Array<Object>] Integrated list of nodes and freeze blocks
       def extract_and_integrate_all_nodes
@@ -367,15 +507,11 @@ module Markdown
       # @return [Array<Object>] Gap nodes
       def create_gap_nodes(line_numbers)
         line_numbers.map do |line_num|
-          content = @lines[line_num - 1] || ""
+          content = @lines[line_num - 1] || ''
 
           # Try to parse as link definition first
           link_node = LinkDefinitionNode.parse(content, line_number: line_num)
-          if link_node
-            link_node
-          else
-            GapLineNode.new(content, line_number: line_num)
-          end
+          link_node || GapLineNode.new(content, line_number: line_num)
         end
       end
 
@@ -397,10 +533,17 @@ module Markdown
         # Set preceding_node for gap lines based on their position in the sorted list
         # This allows gap lines to have context-aware signatures
         sorted_nodes.each_with_index do |node, idx|
-          if node.is_a?(GapLineNode) && idx > 0
-            # Find the previous non-gap-line node (structural node)
-            preceding = sorted_nodes[0...idx].reverse.find { |n| !n.is_a?(GapLineNode) }
-            node.preceding_node = preceding
+          next unless node.is_a?(GapLineNode) && idx > 0
+
+          # Find the previous non-gap-line node (structural node)
+          preceding = sorted_nodes[0...idx].reverse.find { |n| !n.is_a?(GapLineNode) }
+          node.preceding_node = preceding
+          next unless preceding
+
+          node.preceding_signature = begin
+            compute_node_signature(preceding)
+          rescue StandardError
+            nil
           end
         end
 
@@ -432,7 +575,7 @@ module Markdown
 
           # Check HTML nodes for freeze markers
           # Handle both raw Markly (:html) and TreeHaver normalized ("html_block", :html_block) types
-          if node_type == :html || node_type == :html_block || node_type == "html_block" || node_type == "html"
+          if [:html, :html_block, 'html_block', 'html'].include?(node_type)
             # Try multiple content extraction methods:
             # 1. string_content (raw Markly/Commonmarker)
             # 2. to_commonmark on wrapper
@@ -448,21 +591,15 @@ module Markdown
               end
             end
 
-            if content.nil? || content.empty?
-              if child.respond_to?(:to_commonmark)
-                content = child.to_commonmark.to_s
-              end
-            end
+            content = child.to_commonmark.to_s if (content.nil? || content.empty?) && child.respond_to?(:to_commonmark)
 
             # TreeHaver Commonmarker wrapper stores content in inner_node
             if (content.nil? || content.empty?) && child.respond_to?(:inner_node)
               inner = child.inner_node
-              if inner.respond_to?(:to_commonmark)
-                content = inner.to_commonmark.to_s
-              end
+              content = inner.to_commonmark.to_s if inner.respond_to?(:to_commonmark)
             end
 
-            content ||= ""
+            content ||= ''
             match = content.match(pattern)
 
             if match
@@ -475,7 +612,7 @@ module Markdown
                 type: marker_type.to_sym,
                 text: content.strip,
                 reason: reason,
-                node: child, # Keep reference to the actual node
+                node: child # Keep reference to the actual node
               }
             end
           end
@@ -483,7 +620,7 @@ module Markdown
           child = next_sibling(child)
         end
 
-        DebugLogger.debug("Found freeze markers", {count: markers.size})
+        DebugLogger.debug('Found freeze markers', { count: markers.size })
         markers
       end
 
@@ -503,14 +640,14 @@ module Markdown
               start_marker = stack.pop
               blocks << create_freeze_block(start_marker, marker)
             else
-              DebugLogger.debug("Unmatched unfreeze marker", {line: marker[:line]})
+              DebugLogger.debug('Unmatched unfreeze marker', { line: marker[:line] })
             end
           end
         end
 
         # Warn about unclosed freeze blocks
         stack.each do |unclosed|
-          DebugLogger.debug("Unclosed freeze marker", {line: unclosed[:line]})
+          DebugLogger.debug('Unclosed freeze marker', { line: unclosed[:line] })
         end
 
         blocks.sort_by(&:start_line)
@@ -532,10 +669,10 @@ module Markdown
         content_end = end_line - 1
 
         content = if content_start <= content_end
-          source_range(content_start, content_end)
-        else
-          ""
-        end
+                    source_range(content_start, content_end)
+                  else
+                    ''
+                  end
 
         # Parse the content to get nodes (for nested analysis)
         parsed_nodes = parse_freeze_block_content(content)
@@ -547,7 +684,7 @@ module Markdown
           start_marker: start_marker[:text],
           end_marker: end_marker[:text],
           nodes: parsed_nodes,
-          reason: start_marker[:reason],
+          reason: start_marker[:reason]
         )
       end
 
@@ -579,10 +716,10 @@ module Markdown
           end
           nodes
         rescue StandardError => e
-          # :nocov: defensive - parser rarely fails on valid markdown subset
-          DebugLogger.debug("Failed to parse freeze block content", {error: e.message})
+          # simplecov:disable defensive - parser rarely fails on valid markdown subset
+          DebugLogger.debug('Failed to parse freeze block content', { error: e.message })
           []
-          # :nocov:
+          # simplecov:enable
         end
       end
 

data/lib/markdown/merge/gap_line_node.rb

@@ -30,6 +30,9 @@ module Markdown
       # This is set after integration to avoid circular dependencies during creation
       attr_accessor :preceding_node
 
+      # @return [Array, nil] Signature of the preceding structural node when available
+      attr_accessor :preceding_signature
+
       # Initialize a new GapLineNode
       #
       # @param content [String] The line content (without trailing newline)
@@ -37,13 +40,14 @@ module Markdown
       def initialize(content, line_number:)
         @content = content.chomp
         @line_number = line_number
-        @preceding_node = nil  # Set later during integration
+        @preceding_node = nil # Set later during integration
+        @preceding_signature = nil
 
         location = Ast::Merge::AstNode::Location.new(
           start_line: line_number,
           end_line: line_number,
           start_column: 0,
-          end_column: @content.length,
+          end_column: @content.length
         )
 
         super(slice: @content, location: location)
@@ -57,7 +61,7 @@ module Markdown
 
       # Alias for compatibility with wrapped nodes that have merge_type
       # @return [Symbol] :gap_line
-      alias_method :merge_type, :type
+      alias merge_type type
 
       # Generate a signature for matching gap lines.
       # Gap lines are matched by their position relative to the preceding structural node.
@@ -77,11 +81,13 @@ module Markdown
             # 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
+            context_signature = @preceding_signature || if @preceding_node.respond_to?(:type)
+                                                          @preceding_node.type
+                                                        else
+                                                          :unknown
+                                                        end
 
-            [:gap_line_after, preceding_type, offset, @content]
+            [:gap_line_after, context_signature, offset, @content]
           else
             # Fallback if we can't get position
             [:gap_line, @line_number, @content]
@@ -99,7 +105,7 @@ module Markdown
           start_line: @line_number,
           end_line: @line_number,
           start_column: 0,
-          end_column: @content.length,
+          end_column: @content.length
         }
       end
 

data/lib/markdown/merge/link_definition_node.rb

@@ -61,7 +61,7 @@ module Markdown
           start_line: line_number,
           end_line: line_number,
           start_column: 0,
-          end_column: content.length,
+          end_column: content.length
         )
 
         super(slice: content, location: location)
@@ -71,7 +71,7 @@ module Markdown
         # Shared parser instance for parsing link definitions
         # @return [LinkParser]
         def parser
-          @parser ||= LinkParser.new # rubocop:disable ThreadSafety/ClassInstanceVariable
+          @parser ||= LinkParser.new
         end
 
         # Parse a line and create a LinkDefinitionNode if it's a link definition.
@@ -88,7 +88,7 @@ module Markdown
             line_number: line_number,
             label: result[:label],
             url: result[:url],
-            title: result[:title],
+            title: result[:title]
           )
         end
 
@@ -109,7 +109,7 @@ module Markdown
 
       # Alias for compatibility with wrapped nodes that have merge_type
       # @return [Symbol] :link_definition
-      alias_method :merge_type, :type
+      alias merge_type type
 
       # Generate a signature for matching link definitions.
       # Link definitions are matched by their label (case-insensitive in Markdown).
@@ -126,7 +126,7 @@ module Markdown
           start_line: @location.start_line,
           end_line: @location.end_line,
           start_column: @location.start_column,
-          end_column: @location.end_column,
+          end_column: @location.end_column
         }
       end