markdown-merge 1.0.0

data/lib/markdown/merge/whitespace_normalizer.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Markdown
+  module Merge
+    # Normalizes whitespace in markdown documents.
+    #
+    # Supports multiple normalization modes:
+    # - `:basic` (or `true`) - Collapse excessive blank lines (3+ → 2)
+    # - `:link_refs` - Also remove blank lines between consecutive link reference definitions
+    # - `:strict` - All of the above normalizations
+    #
+    # Uses {LinkParser} for detecting link reference definitions, which supports:
+    # - Standard definitions: `[label]: url`
+    # - Definitions with titles: `[label]: url "title"`
+    # - Angle-bracketed URLs: `[label]: <url>`
+    # - Emoji in labels: `[🎨logo]: url`
+    #
+    # @example Basic normalization (default)
+    #   content = "Hello\n\n\n\nWorld"
+    #   normalized = WhitespaceNormalizer.normalize(content)
+    #   # => "Hello\n\nWorld"
+    #
+    # @example With link_refs mode
+    #   content = "[link1]: url1\n\n[link2]: url2"
+    #   normalized = WhitespaceNormalizer.normalize(content, mode: :link_refs)
+    #   # => "[link1]: url1\n[link2]: url2"
+    #
+    # @example With problem tracking
+    #   normalizer = WhitespaceNormalizer.new(content, mode: :link_refs)
+    #   result = normalizer.normalize
+    #   normalizer.problems.by_category(:link_ref_spacing)
+    #
+    class WhitespaceNormalizer
+      # Valid normalization modes
+      MODES = %i[basic link_refs strict].freeze
+
+      # @return [String] The original content
+      attr_reader :content
+
+      # @return [Symbol] The normalization mode
+      attr_reader :mode
+
+      # @return [DocumentProblems] Problems found during normalization
+      attr_reader :problems
+
+      class << self
+        # Normalize whitespace in content (class method for convenience).
+        #
+        # @param content [String] Content to normalize
+        # @param mode [Symbol, Boolean] Normalization mode (:basic, :link_refs, :strict, or true for :basic)
+        # @return [String] Normalized content
+        def normalize(content, mode: :basic)
+          new(content, mode: mode).normalize
+        end
+      end
+
+      # Initialize a new normalizer.
+      #
+      # @param content [String] Content to normalize
+      # @param mode [Symbol, Boolean] Normalization mode (:basic, :link_refs, :strict, or true for :basic)
+      def initialize(content, mode: :basic)
+        @content = content
+        @mode = normalize_mode(mode)
+        @problems = DocumentProblems.new
+        @link_parser = LinkParser.new
+      end
+
+      # Normalize whitespace based on the configured mode.
+      #
+      # @return [String] Normalized content
+      def normalize
+        result = content.dup
+
+        # Always collapse excessive blank lines (3+ → 2)
+        result = collapse_excessive_blank_lines(result)
+
+        # Remove blank lines between link refs if mode requires it
+        if @mode == :link_refs || @mode == :strict
+          result = remove_blank_lines_between_link_refs(result)
+        end
+
+        result
+      end
+
+      # Check if normalization made any changes.
+      #
+      # @return [Boolean] true if content had whitespace issues
+      def changed?
+        !@problems.empty?
+      end
+
+      # Get count of normalizations performed.
+      #
+      # @return [Integer] Number of whitespace issues fixed
+      def normalization_count
+        @problems.count
+      end
+
+      private
+
+      # Normalize mode parameter to a symbol.
+      #
+      # @param mode [Symbol, Boolean] Input mode
+      # @return [Symbol] Normalized mode
+      def normalize_mode(mode)
+        case mode
+        when true
+          :basic
+        when false
+          :basic  # Still do basic normalization
+        when Symbol
+          raise ArgumentError, "Unknown mode: #{mode}. Valid modes: #{MODES.join(", ")}" unless MODES.include?(mode)
+
+          mode
+        else
+          raise ArgumentError, "Mode must be a Symbol or Boolean, got: #{mode.class}"
+        end
+      end
+
+      # Collapse 3+ consecutive newlines to 2.
+      #
+      # This detects runs of blank lines (empty lines) and collapses them.
+      # Note: A blank line is a line containing only whitespace.
+      # 3+ consecutive newlines means 2+ blank lines.
+      #
+      # @param text [String] Text to process
+      # @return [String] Processed text
+      def collapse_excessive_blank_lines(text)
+        lines = text.lines
+        result = []
+        consecutive_blank_count = 0
+        problem_start_line = nil
+        line_number = 0
+
+        lines.each do |line|
+          line_number += 1
+
+          if line.chomp.empty?
+            consecutive_blank_count += 1
+            # The problem starts at the line BEFORE the first blank line
+            # (i.e., the line that ends with the first \n of the excessive sequence)
+            problem_start_line ||= line_number - 1
+
+            # Only add up to 1 blank line (which creates the standard paragraph gap)
+            if consecutive_blank_count <= 1
+              result << line
+            end
+            # Skip adding lines when consecutive_blank_count >= 2
+          else
+            # Record problem if we had 2+ blank lines (which means 3+ newlines)
+            # consecutive_blank_count is the count of blank lines, so >= 2 means excessive
+            if consecutive_blank_count >= 2
+              @problems.add(
+                :excessive_whitespace,
+                severity: :warning,
+                line: problem_start_line,
+                newline_count: consecutive_blank_count + 1, # +1 because first line ends with \n too
+                collapsed_to: 2,
+              )
+            end
+
+            consecutive_blank_count = 0
+            problem_start_line = nil
+            result << line
+          end
+        end
+
+        # Handle trailing blank lines
+        if consecutive_blank_count >= 2
+          @problems.add(
+            :excessive_whitespace,
+            severity: :warning,
+            line: problem_start_line,
+            newline_count: consecutive_blank_count + 1,
+            collapsed_to: 2,
+          )
+        end
+
+        result.join
+      end
+
+      # Remove blank lines between consecutive link reference definitions.
+      #
+      # Uses {LinkParser} to detect link definitions, supporting:
+      # - Standard: `[label]: url`
+      # - With title: `[label]: url "title"`
+      # - Angle-bracketed: `[label]: <url>`
+      # - Emoji labels: `[🎨logo]: url`
+      #
+      # @param text [String] Text to process
+      # @return [String] Processed text
+      def remove_blank_lines_between_link_refs(text)
+        lines = text.lines
+        result = []
+        i = 0
+
+        while i < lines.length
+          line = lines[i]
+          result << line
+
+          # Check if current line is a link ref definition using LinkParser
+          if link_definition_line?(line)
+            # Look ahead for blank lines followed by another link ref
+            j = i + 1
+            while j < lines.length
+              next_line = lines[j]
+              if next_line.chomp.empty?
+                # Check if there's a link ref definition after the blank line(s)
+                k = j + 1
+                while k < lines.length && lines[k].chomp.empty?
+                  k += 1
+                end
+                if k < lines.length && link_definition_line?(lines[k])
+                  # Skip all blank lines between link refs
+                  blanks_skipped = k - j
+                  @problems.add(
+                    :link_ref_spacing,
+                    severity: :info,
+                    line: j + 1,
+                    blank_lines_removed: blanks_skipped,
+                  )
+                  j = k
+                else
+                  # Not followed by a link ref, keep the blank line
+                  break
+                end
+              else
+                break
+              end
+            end
+            i = j
+          else
+            i += 1
+          end
+        end
+
+        result.join
+      end
+
+      # Check if a line is a link reference definition using LinkParser.
+      #
+      # @param line [String] Line to check
+      # @return [Boolean] true if line is a link definition
+      def link_definition_line?(line)
+        # Use LinkParser to attempt parsing the line as a definition
+        result = @link_parser.parse_definition_line(line.chomp)
+        !result.nil?
+      end
+    end
+  end
+end

data/lib/markdown/merge.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+# External gems
+require "version_gem"
+require "set"
+
+# Shared merge infrastructure
+require "ast/merge"
+
+# tree_haver provides unified markdown parsing via multiple backends
+require "tree_haver"
+
+# This gem - only require version
+require_relative "merge/version"
+
+module Markdown
+  # Smart merging for Markdown files using AST-based parsers via tree_haver.
+  #
+  # Markdown::Merge provides intelligent Markdown merging with support for
+  # multiple parsing backends (Commonmarker, Markly) through tree_haver:
+  # - Standalone SmartMerger that works with any available backend
+  # - Matching structural elements (headings, paragraphs, lists, etc.) between files
+  # - Preserving frozen sections marked with HTML comments
+  # - Resolving conflicts based on configurable preferences
+  # - Node type normalization for portable merge rules across backends
+  #
+  # Can be used directly or through parser-specific wrappers
+  # (commonmarker-merge, markly-merge) that provide hard dependencies
+  # and backend-specific defaults.
+  #
+  # @example Direct usage with auto backend detection
+  #   require "markdown/merge"
+  #   merger = Markdown::Merge::SmartMerger.new(template, destination)
+  #   result = merger.merge
+  #
+  # @example With specific backend
+  #   merger = Markdown::Merge::SmartMerger.new(
+  #     template,
+  #     destination,
+  #     backend: :markly,
+  #     flags: Markly::DEFAULT,
+  #     extensions: [:table, :strikethrough]
+  #   )
+  #   result = merger.merge
+  #
+  # @example Using via commonmarker-merge
+  #   require "commonmarker/merge"
+  #   merger = Commonmarker::Merge::SmartMerger.new(template, destination)
+  #   result = merger.merge
+  #
+  # @see SmartMerger Main entry point for merging
+  # @see FileAnalysis For parsing and analyzing Markdown files
+  # @see NodeTypeNormalizer For type normalization across backends
+  module Merge
+    # Base error class for Markdown::Merge
+    # Inherits from Ast::Merge::Error for consistency across merge gems.
+    class Error < Ast::Merge::Error; end
+
+    # Raised when a Markdown file has parsing errors.
+    # Inherits from Ast::Merge::ParseError for consistency across merge gems.
+    #
+    # @example Handling parse errors
+    #   begin
+    #     analysis = FileAnalysis.new(markdown_content)
+    #   rescue ParseError => e
+    #     puts "Markdown syntax error: #{e.message}"
+    #     e.errors.each { |error| puts "  #{error}" }
+    #   end
+    class ParseError < Ast::Merge::ParseError
+      # @param message [String, nil] Error message (auto-generated if nil)
+      # @param content [String, nil] The Markdown source that failed to parse
+      # @param errors [Array] Parse errors from Markdown
+      def initialize(message = nil, content: nil, errors: [])
+        super(message, errors: errors, content: content)
+      end
+    end
+
+    # Raised when the template file has syntax errors.
+    #
+    # @example Handling template parse errors
+    #   begin
+    #     merger = SmartMerger.new(template, destination)
+    #     result = merger.merge
+    #   rescue TemplateParseError => e
+    #     puts "Template syntax error: #{e.message}"
+    #     e.errors.each { |error| puts "  #{error.message}" }
+    #   end
+    class TemplateParseError < ParseError; end
+
+    # Raised when the destination file has syntax errors.
+    #
+    # @example Handling destination parse errors
+    #   begin
+    #     merger = SmartMerger.new(template, destination)
+    #     result = merger.merge
+    #   rescue DestinationParseError => e
+    #     puts "Destination syntax error: #{e.message}"
+    #     e.errors.each { |error| puts "  #{error.message}" }
+    #   end
+    class DestinationParseError < ParseError; end
+
+    # Autoload all components - base classes
+    autoload :Cleanse, "markdown/merge/cleanse"
+    autoload :DebugLogger, "markdown/merge/debug_logger"
+    autoload :FreezeNode, "markdown/merge/freeze_node"
+    autoload :FileAnalysisBase, "markdown/merge/file_analysis_base"
+    autoload :FileAligner, "markdown/merge/file_aligner"
+    autoload :ConflictResolver, "markdown/merge/conflict_resolver"
+    autoload :MergeResult, "markdown/merge/merge_result"
+    autoload :TableMatchAlgorithm, "markdown/merge/table_match_algorithm"
+    autoload :TableMatchRefiner, "markdown/merge/table_match_refiner"
+    autoload :CodeBlockMerger, "markdown/merge/code_block_merger"
+    autoload :SmartMergerBase, "markdown/merge/smart_merger_base"
+    autoload :LinkDefinitionNode, "markdown/merge/link_definition_node"
+    autoload :GapLineNode, "markdown/merge/gap_line_node"
+    autoload :OutputBuilder, "markdown/merge/output_builder"
+    autoload :LinkDefinitionFormatter, "markdown/merge/link_definition_formatter"
+    autoload :MarkdownStructure, "markdown/merge/markdown_structure"
+    autoload :DocumentProblems, "markdown/merge/document_problems"
+    autoload :WhitespaceNormalizer, "markdown/merge/whitespace_normalizer"
+    autoload :LinkParser, "markdown/merge/link_parser"
+    autoload :LinkReferenceRehydrator, "markdown/merge/link_reference_rehydrator"
+
+    # Autoload concrete implementations (tree_haver-based)
+    autoload :NodeTypeNormalizer, "markdown/merge/node_type_normalizer"
+    autoload :FileAnalysis, "markdown/merge/file_analysis"
+    autoload :SmartMerger, "markdown/merge/smart_merger"
+    autoload :PartialTemplateMerger, "markdown/merge/partial_template_merger"
+  end
+end
+
+# Register with ast-merge's MergeGemRegistry for RSpec dependency tags
+# Note: markdown-merge requires a backend (markly or commonmarker) to instantiate,
+# so we use skip_instantiation: true
+# Only register if MergeGemRegistry is loaded (i.e., in test environment)
+if defined?(Ast::Merge::RSpec::MergeGemRegistry)
+  Ast::Merge::RSpec::MergeGemRegistry.register(
+    :markdown_merge,
+    require_path: "markdown/merge",
+    merger_class: "Markdown::Merge::SmartMerger",
+    test_source: "# Test\n\nParagraph",
+    category: :markdown,
+    skip_instantiation: true,
+  )
+end
+
+Markdown::Merge::Version.class_eval do
+  extend VersionGem::Basic
+end

data/lib/markdown-merge.rb

@@ -0,0 +1,4 @@
+# For technical reasons, if we move to Zeitwerk, this cannot be require_relative.
+#   See: https://github.com/fxn/zeitwerk#for_gem_extension
+# Hook for other libraries to load this library (e.g. via bundler)
+require "markdown/merge"