markdown-merge 7.0.0 → 7.1.3

data/lib/markdown/merge/comment_tracker.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Markdown
+  module Merge
+    # Conservatively tracks standalone HTML comment lines in Markdown sources.
+    class CommentTracker < Ast::Merge::Comment::HashTrackerBase
+      STANDALONE_HTML_COMMENT_REGEX = /\A(?<indent>\s*)<!--\s?(?<text>.*?)\s?-->\s*\z/
+
+      def initialize(lines)
+        super(Array(lines))
+      end
+
+      private
+
+      def comment_style
+        :html_comment
+      end
+
+      def extract_comments
+        @lines.each_with_index.filter_map do |line, index|
+          match = line.match(STANDALONE_HTML_COMMENT_REGEX)
+          next unless match
+
+          {
+            line: index + 1,
+            indent: match[:indent].length,
+            text: match[:text].to_s,
+            full_line: true,
+            raw: line
+          }
+        end
+      end
+
+      def owner_line_num(owner)
+        pos = owner.respond_to?(:source_position) ? owner.source_position : nil
+        return pos[:start_line] if pos && pos[:start_line]
+
+        nil
+      end
+    end
+  end
+end

data/lib/markdown/merge/conflict_resolver.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+module Markdown
+  module Merge
+    # Resolves conflicts between matching Markdown elements from template and destination.
+    #
+    # When two elements have the same signature but different content, the resolver
+    # determines which version to use based on the configured preference.
+    #
+    # Inherits from Ast::Merge::ConflictResolverBase using the :node strategy,
+    # which resolves conflicts on a per-node-pair basis.
+    #
+    # @example Basic usage
+    #   resolver = ConflictResolver.new(
+    #     preference: :destination,
+    #     template_analysis: template_analysis,
+    #     dest_analysis: dest_analysis
+    #   )
+    #   resolution = resolver.resolve(template_node, dest_node, template_index: 0, dest_index: 0)
+    #   case resolution[:source]
+    #   when :template
+    #     # Use template version
+    #   when :destination
+    #     # Use destination version
+    #   end
+    #
+    # @see SmartMergerBase
+    # @see Ast::Merge::ConflictResolverBase
+    class ConflictResolver < Ast::Merge::ConflictResolverBase
+      # Initialize a conflict resolver
+      #
+      # @param preference [Symbol] Which version to prefer (:destination or :template)
+      # @param template_analysis [FileAnalysisBase] Analysis of the template file
+      # @param dest_analysis [FileAnalysisBase] Analysis of the destination file
+      # @param options [Hash] Additional options for forward compatibility
+      def initialize(preference:, template_analysis:, dest_analysis:, **options)
+        @resolution_mode = options.fetch(:resolution_mode, :eager)
+        @unresolved_policy = Ast::Merge::UnresolvedPolicy.coerce(options[:unresolved_policy])
+        super(
+          strategy: :node,
+          preference: preference,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+          **options
+        )
+      end
+
+      protected
+
+      # Resolve a conflict between template and destination nodes
+      #
+      # @param template_node [Object] Node from template
+      # @param dest_node [Object] Node from destination
+      # @param template_index [Integer] Index in template statements
+      # @param dest_index [Integer] Index in destination statements
+      # @return [Hash] Resolution with :source, :decision, and node references
+      def resolve_node_pair(template_node, dest_node, template_index:, dest_index:)
+        # Frozen blocks always win
+        if freeze_node?(dest_node)
+          return frozen_resolution(
+            source: :destination,
+            template_node: template_node,
+            dest_node: dest_node,
+            reason: dest_node.reason
+          )
+        end
+
+        if freeze_node?(template_node)
+          return frozen_resolution(
+            source: :template,
+            template_node: template_node,
+            dest_node: dest_node,
+            reason: template_node.reason
+          )
+        end
+
+        # Check if content is identical
+        if content_identical?(template_node, dest_node)
+          return identical_resolution(
+            template_node: template_node,
+            dest_node: dest_node
+          )
+        end
+
+        if unresolved_mode? && @unresolved_policy.unresolved_for?(:matched_block)
+          return unresolved_resolution(
+            template_node: template_node,
+            dest_node: dest_node
+          )
+        end
+
+        # Use preference to decide
+        preference_resolution(
+          template_node: template_node,
+          dest_node: dest_node
+        )
+      end
+
+      private
+
+      # Check if two nodes have identical content
+      #
+      # @param template_node [Object] Template node
+      # @param dest_node [Object] Destination node
+      # @return [Boolean] True if content is identical
+      def content_identical?(template_node, dest_node)
+        template_text = node_to_text(template_node, @template_analysis)
+        dest_text = node_to_text(dest_node, @dest_analysis)
+        template_text == dest_text
+      end
+
+      def unresolved_resolution(template_node:, dest_node:)
+        preferred_resolution = preference_resolution(template_node: template_node, dest_node: dest_node)
+        provisional_winner = @unresolved_policy.provisional_winner_for(
+          :matched_block,
+          fallback: preferred_resolution[:source]
+        )
+        line = node_line_range(dest_node)&.first || node_line_range(template_node)&.first
+        case_id = ['markdown', 'matched_block', line].compact.join('-')
+        surface_path = unresolved_surface_path("matched_block[line=#{line}]")
+
+        unresolved_case = Ast::Merge::Runtime::ResolutionCase.new(
+          case_id: case_id,
+          reason: :conflict,
+          candidates: {
+            template: node_to_text(template_node, @template_analysis),
+            destination: node_to_text(dest_node, @dest_analysis)
+          },
+          provisional_winner: provisional_winner,
+          surface_path: surface_path,
+          metadata: {
+            match_kind: :matched_block,
+            template_lines: node_line_range(template_node),
+            destination_lines: node_line_range(dest_node),
+            node_type: markdown_node_type(dest_node || template_node)
+          }.compact
+        )
+
+        {
+          source: provisional_winner,
+          decision: Ast::Merge::MergeResultBase::DECISION_UNRESOLVED,
+          template_node: template_node,
+          dest_node: dest_node,
+          unresolved_case: unresolved_case,
+          conflict: {
+            case_id: case_id,
+            reason: :conflict,
+            template: unresolved_case.candidates[:template],
+            destination: unresolved_case.candidates[:destination],
+            provisional_winner: provisional_winner,
+            location: line ? "line #{line}" : nil
+          }.compact
+        }
+      end
+
+      # Convert a node to its source text
+      #
+      # @param node [Object] Node to convert
+      # @param analysis [FileAnalysisBase] Analysis for source lookup
+      # @return [String] Source text
+      def node_to_text(node, analysis)
+        # Check for any FreezeNode type (base class or subclass)
+        if node.is_a?(Ast::Merge::FreezeNodeBase)
+          node.full_text
+        else
+          pos = node.source_position
+          start_line = pos&.dig(:start_line)
+          end_line = pos&.dig(:end_line)
+
+          if start_line && end_line
+            analysis.source_range(start_line, end_line)
+          else
+            # simplecov:disable defensive - Markdown nodes typically have source positions
+            node.to_commonmark
+            # simplecov:enable
+          end
+        end
+      end
+
+      def node_line_range(node)
+        if node.respond_to?(:source_position)
+          pos = node.source_position
+          start_line = pos&.dig(:start_line)
+          end_line = pos&.dig(:end_line)
+          return [start_line, end_line] if start_line && end_line
+        end
+        return [node.start_line, node.end_line] if node.respond_to?(:start_line) && node.respond_to?(:end_line)
+
+        nil
+      end
+
+      def markdown_node_type(node)
+        return node.type.to_sym if node.respond_to?(:type) && !node.type.nil?
+
+        node.class.name.split('::').last
+      end
+    end
+  end
+end

data/lib/markdown/merge/debug_logger.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Markdown
+  module Merge
+    # Debug logging utility for Markdown::Merge operations.
+    #
+    # Extends Ast::Merge::DebugLogger to provide consistent logging
+    # across all merge gems. Logs are controlled via environment variables.
+    #
+    # @example Enable debug logging
+    #   ENV["MARKDOWN_MERGE_DEBUG"] = "1"
+    #   DebugLogger.debug("Parsing markdown", { file: "README.md" })
+    #
+    # @example Time an operation
+    #   result = DebugLogger.time("parse") { Markly.parse(source) }
+    #
+    # @see Ast::Merge::DebugLogger Base module
+    module DebugLogger
+      extend Ast::Merge::DebugLogger
+
+      # Configure for markdown-merge
+      self.env_var_name = 'MARKDOWN_MERGE_DEBUG'
+      self.log_prefix = '[markdown-merge]'
+    end
+  end
+end

data/lib/markdown/merge/document_problems.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Markdown
+  module Merge
+    # Container for document issues found during processing.
+    #
+    # Collects problems discovered during merge operations, link reference
+    # rehydration, whitespace normalization, and other document transformations.
+    # Problems are categorized and have severity levels for filtering and reporting.
+    #
+    # @example Basic usage
+    #   problems = DocumentProblems.new
+    #   problems.add(:duplicate_link_definition, label: "example", url: "https://example.com")
+    #   problems.add(:excessive_whitespace, line: 42, count: 5, severity: :warning)
+    #   problems.empty? # => false
+    #   problems.count # => 2
+    #
+    # @example Filtering by category
+    #   problems.by_category(:duplicate_link_definition)
+    #   # => [{ category: :duplicate_link_definition, label: "example", ... }]
+    #
+    # @example Filtering by severity
+    #   problems.by_severity(:error)
+    #   problems.warnings
+    #   problems.errors
+    #
+    class DocumentProblems
+      # Problem entry struct
+      Problem = Struct.new(:category, :severity, :details, keyword_init: true) do
+        def to_h
+          { category: category, severity: severity, **details }
+        end
+
+        def warning?
+          severity == :warning
+        end
+
+        def error?
+          severity == :error
+        end
+
+        def info?
+          severity == :info
+        end
+      end
+
+      # Valid severity levels
+      SEVERITIES = %i[info warning error].freeze
+
+      # Valid problem categories
+      CATEGORIES = %i[
+        duplicate_link_definition
+        excessive_whitespace
+        link_has_title
+        image_has_title
+        link_ref_spacing
+      ].freeze
+
+      # @return [Array<Problem>] All collected problems
+      attr_reader :problems
+
+      def initialize
+        @problems = []
+      end
+
+      # Add a problem to the collection.
+      #
+      # @param category [Symbol] Problem category (see CATEGORIES)
+      # @param severity [Symbol] Severity level (:info, :warning, :error), default :warning
+      # @param details [Hash] Additional details about the problem
+      # @return [Problem] The added problem
+      def add(category, severity: :warning, **details)
+        validate_category!(category)
+        validate_severity!(severity)
+
+        problem = Problem.new(category: category, severity: severity, details: details)
+        @problems << problem
+        problem
+      end
+
+      # Get all problems as an array of hashes.
+      #
+      # @return [Array<Hash>] All problems
+      def all
+        @problems.map(&:to_h)
+      end
+
+      # Get problems by category.
+      #
+      # @param category [Symbol] Category to filter by
+      # @return [Array<Problem>] Problems in that category
+      def by_category(category)
+        @problems.select { |p| p.category == category }
+      end
+
+      # Get problems by severity.
+      #
+      # @param severity [Symbol] Severity to filter by
+      # @return [Array<Problem>] Problems with that severity
+      def by_severity(severity)
+        @problems.select { |p| p.severity == severity }
+      end
+
+      # Get all info-level problems.
+      #
+      # @return [Array<Problem>] Info problems
+      def infos
+        by_severity(:info)
+      end
+
+      # Get all warning-level problems.
+      #
+      # @return [Array<Problem>] Warning problems
+      def warnings
+        by_severity(:warning)
+      end
+
+      # Get all error-level problems.
+      #
+      # @return [Array<Problem>] Error problems
+      def errors
+        by_severity(:error)
+      end
+
+      # Check if there are any problems.
+      #
+      # @return [Boolean] true if no problems
+      def empty?
+        @problems.empty?
+      end
+
+      # Get the count of problems.
+      #
+      # @param category [Symbol, nil] Optional category filter
+      # @param severity [Symbol, nil] Optional severity filter
+      # @return [Integer] Problem count
+      def count(category: nil, severity: nil)
+        filtered = @problems
+        filtered = filtered.select { |p| p.category == category } if category
+        filtered = filtered.select { |p| p.severity == severity } if severity
+        filtered.size
+      end
+
+      # Merge another DocumentProblems into this one.
+      #
+      # @param other [DocumentProblems] Problems to merge
+      # @return [self]
+      def merge!(other)
+        @problems.concat(other.problems)
+        self
+      end
+
+      # Clear all problems.
+      #
+      # @return [self]
+      def clear
+        @problems.clear
+        self
+      end
+
+      # Get a summary of problems by category.
+      #
+      # @return [Hash<Symbol, Integer>] Counts by category
+      def summary_by_category
+        @problems.group_by(&:category).transform_values(&:size)
+      end
+
+      # Get a summary of problems by severity.
+      #
+      # @return [Hash<Symbol, Integer>] Counts by severity
+      def summary_by_severity
+        @problems.group_by(&:severity).transform_values(&:size)
+      end
+
+      private
+
+      def validate_category!(category)
+        return if CATEGORIES.include?(category)
+
+        raise ArgumentError, "Invalid category: #{category}. Valid: #{CATEGORIES.join(', ')}"
+      end
+
+      def validate_severity!(severity)
+        return if SEVERITIES.include?(severity)
+
+        raise ArgumentError, "Invalid severity: #{severity}. Valid: #{SEVERITIES.join(', ')}"
+      end
+    end
+  end
+end