markdown-merge 1.0.0

data/lib/markdown/merge/code_block_merger.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+module Markdown
+  module Merge
+    # Merges fenced code blocks using language-specific *-merge gems.
+    #
+    # When two code blocks with the same signature are matched, this class
+    # delegates the merge to the appropriate language-specific merger:
+    # - Ruby code → prism-merge
+    # - YAML code → psych-merge
+    # - JSON code → json-merge
+    # - TOML code → toml-merge
+    #
+    # @example Basic usage
+    #   merger = CodeBlockMerger.new
+    #   result = merger.merge_code_blocks(template_node, dest_node, preference: :destination)
+    #   if result[:merged]
+    #     puts result[:content]
+    #   else
+    #     # Fall back to standard resolution
+    #   end
+    #
+    # @example With custom mergers
+    #   merger = CodeBlockMerger.new(
+    #     mergers: {
+    #       "ruby" => ->(template, dest, pref) { MyCustomRubyMerger.merge(template, dest, pref) },
+    #     }
+    #   )
+    #
+    # @see SmartMergerBase
+    # @api public
+    class CodeBlockMerger
+      # Default language-to-merger mapping
+      # Each merger is a lambda that takes (template_content, dest_content, preference)
+      # and returns { merged: true/false, content: String, stats: Hash }
+      # :nocov: integration - DEFAULT_MERGERS lambdas require external gems
+      DEFAULT_MERGERS = {
+        # Ruby code blocks
+        "ruby" => ->(template, dest, preference, **opts) {
+          require "prism/merge"
+          CodeBlockMerger.merge_with_prism(template, dest, preference, **opts)
+        },
+        "rb" => ->(template, dest, preference, **opts) {
+          require "prism/merge"
+          CodeBlockMerger.merge_with_prism(template, dest, preference, **opts)
+        },
+
+        # YAML code blocks
+        "yaml" => ->(template, dest, preference, **opts) {
+          require "psych/merge"
+          CodeBlockMerger.merge_with_psych(template, dest, preference, **opts)
+        },
+        "yml" => ->(template, dest, preference, **opts) {
+          require "psych/merge"
+          CodeBlockMerger.merge_with_psych(template, dest, preference, **opts)
+        },
+
+        # JSON code blocks
+        "json" => ->(template, dest, preference, **opts) {
+          require "json/merge"
+          CodeBlockMerger.merge_with_json(template, dest, preference, **opts)
+        },
+
+        # TOML code blocks
+        "toml" => ->(template, dest, preference, **opts) {
+          require "toml/merge"
+          CodeBlockMerger.merge_with_toml(template, dest, preference, **opts)
+        },
+      }.freeze
+      # :nocov:
+
+      # @return [Hash<String, Proc>] Language to merger mapping
+      attr_reader :mergers
+
+      # @return [Boolean] Whether inner-merge is enabled
+      attr_reader :enabled
+
+      # Creates a new CodeBlockMerger.
+      #
+      # @param mergers [Hash<String, Proc>] Custom language-to-merger mapping.
+      #   Mergers are merged with defaults, allowing selective overrides.
+      # @param enabled [Boolean] Whether to enable inner-merge (default: true)
+      def initialize(mergers: {}, enabled: true)
+        @mergers = DEFAULT_MERGERS.merge(mergers)
+        @enabled = enabled
+      end
+
+      # Check if inner-merge is available for a language.
+      #
+      # @param language [String] The language identifier from fence_info
+      # @return [Boolean] true if a merger exists for this language
+      def supports_language?(language)
+        return false unless @enabled
+        return false if language.nil? || language.empty?
+
+        @mergers.key?(language.downcase)
+      end
+
+      # Merge two code blocks using the appropriate language-specific merger.
+      #
+      # @param template_node [Object] Template code block node
+      # @param dest_node [Object] Destination code block node
+      # @param preference [Symbol] :destination or :template
+      # @param opts [Hash] Additional options passed to the merger
+      # @return [Hash] { merged: Boolean, content: String, stats: Hash }
+      def merge_code_blocks(template_node, dest_node, preference:, **opts)
+        return not_merged("inner-merge disabled") unless @enabled
+
+        language = extract_language(template_node) || extract_language(dest_node)
+        return not_merged("no language specified") unless language
+
+        merger = @mergers[language.downcase]
+        return not_merged("no merger for language: #{language}") unless merger
+
+        template_content = extract_content(template_node)
+        dest_content = extract_content(dest_node)
+
+        # If content is identical, no need to merge
+        if template_content == dest_content
+          return {
+            merged: true,
+            content: rebuild_code_block(language, dest_content, dest_node),
+            stats: {decision: :identical},
+          }
+        end
+
+        begin
+          result = merger.call(template_content, dest_content, preference, **opts)
+          if result[:merged]
+            {
+              merged: true,
+              content: rebuild_code_block(language, result[:content], dest_node),
+              stats: result[:stats] || {},
+            }
+          else
+            not_merged(result[:reason] || "merger declined")
+          end
+        rescue LoadError => e
+          not_merged("merger gem not available: #{e.message}")
+        rescue TreeHaver::Error => e
+          # TreeHaver::NotAvailable and TreeHaver::Error inherit from Exception (not StandardError)
+          # for safety reasons related to backend conflicts. We catch them here to handle
+          # gracefully when a backend isn't properly configured.
+          not_merged("backend not available: #{e.message}")
+        rescue StandardError => e
+          # :nocov: defensive - Prism::Merge::ParseError handling when prism/merge is loaded
+          # Check for Prism::Merge::ParseError if prism/merge is loaded
+          if defined?(::Prism::Merge::ParseError) && e.is_a?(::Prism::Merge::ParseError)
+            not_merged("Ruby parse error: #{e.message}")
+          else
+            not_merged("merge failed: #{e.class}: #{e.message}")
+          end
+          # :nocov:
+        end
+      end
+
+      private
+
+      # Extract language from a code block node.
+      #
+      # @param node [Object] The code block node
+      # @return [String, nil] The language identifier
+      def extract_language(node)
+        return unless node.respond_to?(:fence_info)
+
+        info = node.fence_info
+        return if info.nil? || info.empty?
+
+        # fence_info may contain additional info after the language (e.g., "ruby linenos")
+        info.split(/\s+/).first
+      end
+
+      # Extract content from a code block node.
+      #
+      # @param node [Object] The code block node
+      # @return [String] The code content
+      def extract_content(node)
+        node.string_content || ""
+      end
+
+      # Rebuild a fenced code block with merged content.
+      #
+      # @param language [String] The language identifier
+      # @param content [String] The merged content
+      # @param reference_node [Object] Node to copy fence style from
+      # @return [String] The reconstructed code block
+      def rebuild_code_block(language, content, reference_node)
+        # Ensure content ends with newline for proper fence closing
+        content = content.chomp + "\n" unless content.end_with?("\n")
+
+        # Use backticks as default fence
+        fence = "```"
+
+        "#{fence}#{language}\n#{content}#{fence}"
+      end
+
+      # Return a not-merged result.
+      #
+      # @param reason [String] Why merge was not performed
+      # @return [Hash] Not-merged result hash
+      def not_merged(reason)
+        {merged: false, reason: reason}
+      end
+
+      class << self
+        # Merge Ruby code using prism-merge.
+        #
+        # @param template [String] Template Ruby code
+        # @param dest [String] Destination Ruby code
+        # @param preference [Symbol] :destination or :template
+        # @return [Hash] Merge result
+        # @raise [Prism::Merge::ParseError] If template or dest has syntax errors
+        # @note Errors are handled by merge_code_blocks when called via DEFAULT_MERGERS
+        def merge_with_prism(template, dest, preference, **opts)
+          merger = ::Prism::Merge::SmartMerger.new(
+            template,
+            dest,
+            preference: preference,
+            add_template_only_nodes: opts.fetch(:add_template_only_nodes, false),
+          )
+
+          {
+            merged: true,
+            content: merger.merge,
+            stats: merger.stats,
+          }
+        end
+
+        # Merge YAML code using psych-merge.
+        #
+        # @param template [String] Template YAML code
+        # @param dest [String] Destination YAML code
+        # @param preference [Symbol] :destination or :template
+        # @return [Hash] Merge result
+        # @raise [Psych::Merge::ParseError] If template or dest has syntax errors
+        # @note Errors are handled by merge_code_blocks when called via DEFAULT_MERGERS
+        def merge_with_psych(template, dest, preference, **opts)
+          merger = ::Psych::Merge::SmartMerger.new(
+            template,
+            dest,
+            preference: preference,
+            add_template_only_nodes: opts.fetch(:add_template_only_nodes, false),
+          )
+
+          {
+            merged: true,
+            content: merger.merge,
+            stats: merger.stats,
+          }
+        end
+
+        # Merge JSON code using json-merge.
+        #
+        # @param template [String] Template JSON code
+        # @param dest [String] Destination JSON code
+        # @param preference [Symbol] :destination or :template
+        # @return [Hash] Merge result
+        # @raise [Json::Merge::ParseError] If template or dest has syntax errors
+        # @note Errors are handled by merge_code_blocks when called via DEFAULT_MERGERS
+        def merge_with_json(template, dest, preference, **opts)
+          merger = ::Json::Merge::SmartMerger.new(
+            template,
+            dest,
+            preference: preference,
+            add_template_only_nodes: opts.fetch(:add_template_only_nodes, false),
+          )
+
+          {
+            merged: true,
+            content: merger.merge,
+            stats: merger.stats,
+          }
+        end
+
+        # Merge TOML code using toml-merge.
+        #
+        # @param template [String] Template TOML code
+        # @param dest [String] Destination TOML code
+        # @param preference [Symbol] :destination or :template
+        # @return [Hash] Merge result
+        # @raise [Toml::Merge::ParseError] If template or dest has syntax errors
+        # @note Errors are handled by merge_code_blocks when called via DEFAULT_MERGERS
+        def merge_with_toml(template, dest, preference, **opts)
+          merger = ::Toml::Merge::SmartMerger.new(
+            template,
+            dest,
+            preference: preference,
+            add_template_only_nodes: opts.fetch(:add_template_only_nodes, false),
+          )
+
+          {
+            merged: true,
+            content: merger.merge,
+            stats: merger.stats,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/markdown/merge/conflict_resolver.rb

@@ -0,0 +1,128 @@
+# 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)
+        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
+
+        # 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
+
+      # 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
+            # :nocov: defensive - Markdown nodes typically have source positions
+            node.to_commonmark
+            # :nocov:
+          end
+        end
+      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