markdown-merge 7.0.0 → 7.1.3

data/lib/markdown/merge/backend_support.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Markdown
+  module Merge
+    # Shared boilerplate for backend-specific Markdown wrapper backends.
+    module BackendSupport
+      DEFAULT_CAPABILITIES = {
+        query: false,
+        bytes_field: false,
+        incremental: false,
+        pure_ruby: false,
+        markdown_only: true,
+        error_tolerant: true
+      }.freeze
+
+      module_function
+
+      def install!(backend_module:, backend_name:, gem_name:, require_path:, capabilities: {})
+        install_availability_methods!(
+          backend_module: backend_module,
+          backend_name: backend_name,
+          gem_name: gem_name,
+          capabilities: capabilities
+        )
+        install_tree_wrapper!(backend_module)
+        register_backend!(
+          backend_module: backend_module,
+          backend_name: backend_name,
+          gem_name: gem_name,
+          require_path: require_path
+        )
+      end
+
+      def configure_markdown_only_language_class!(klass, backend_label:, factory_method: :markdown,
+                                                  unsupported_language_message: nil)
+        klass.singleton_class.class_eval do
+          define_method(:from_library) do |_path = nil, symbol: nil, name: nil|
+            lang_name = name || symbol&.to_s&.sub(/^tree_sitter_/, '')&.to_sym || :markdown
+
+            unless lang_name == :markdown
+              message = if unsupported_language_message.respond_to?(:call)
+                          unsupported_language_message.call(lang_name)
+                        else
+                          unsupported_language_message || "#{backend_label} backend only supports Markdown, not #{lang_name}."
+                        end
+              raise TreeHaver::NotAvailable, message
+            end
+
+            public_send(factory_method)
+          end
+        end
+      end
+
+      def configure_node_link_and_navigation!(klass, next_sibling_selector:, prev_sibling_selector:,
+                                              parent_selector: :parent)
+        klass.class_eval do
+          define_method(:url) do
+            Markdown::Merge::BackendSupport.send(:safe_inner_node_call, inner_node, :url)
+          end
+
+          define_method(:title) do
+            Markdown::Merge::BackendSupport.send(:safe_inner_node_call, inner_node, :title)
+          end
+
+          define_method(:next_sibling) do
+            sibling = Markdown::Merge::BackendSupport.send(:safe_inner_node_call, inner_node, next_sibling_selector)
+            sibling ? self.class.new(sibling, source: source, lines: lines) : nil
+          end
+
+          define_method(:prev_sibling) do
+            sibling = Markdown::Merge::BackendSupport.send(:safe_inner_node_call, inner_node, prev_sibling_selector)
+            sibling ? self.class.new(sibling, source: source, lines: lines) : nil
+          end
+
+          define_method(:parent) do
+            parent_node = Markdown::Merge::BackendSupport.send(:safe_inner_node_call, inner_node, parent_selector)
+            parent_node ? self.class.new(parent_node, source: source, lines: lines) : nil
+          end
+        end
+      end
+
+      def configure_node_heading_and_code_block_helpers!(klass, heading_matcher:, code_block_matcher:,
+                                                         heading_level_extractor: nil,
+                                                         code_block_info_extractor: nil)
+        klass.class_eval do
+          define_method(:header_level) do
+            return unless Markdown::Merge::BackendSupport.send(:node_helper_match?, self, heading_matcher)
+
+            if heading_level_extractor.respond_to?(:call)
+              heading_level_extractor.call(inner_node)
+            else
+              Markdown::Merge::BackendSupport.send(:safe_inner_node_call, inner_node, :header_level)
+            end
+          end
+
+          define_method(:fence_info) do
+            return unless Markdown::Merge::BackendSupport.send(:node_helper_match?, self, code_block_matcher)
+
+            if code_block_info_extractor.respond_to?(:call)
+              code_block_info_extractor.call(inner_node)
+            else
+              Markdown::Merge::BackendSupport.send(:safe_inner_node_call, inner_node, :fence_info)
+            end
+          end
+        end
+      end
+
+      def install_availability_methods!(backend_module:, backend_name:, gem_name:, capabilities: {})
+        backend_module.instance_variable_set(:@load_attempted, false)
+        backend_module.instance_variable_set(:@loaded, false)
+
+        merged_capabilities = DEFAULT_CAPABILITIES.merge(backend: backend_name).merge(capabilities)
+
+        backend_module.singleton_class.class_eval do
+          define_method(:available?) do
+            return @loaded if @load_attempted
+
+            @load_attempted = true
+            begin
+              require gem_name
+              @loaded = true
+            rescue LoadError, StandardError
+              @loaded = false
+            end
+            @loaded
+          end
+
+          define_method(:reset!) do
+            @load_attempted = false
+            @loaded = false
+          end
+
+          define_method(:capabilities) do
+            return {} unless available?
+
+            merged_capabilities.dup
+          end
+        end
+      end
+      private_class_method :install_availability_methods!
+
+      def install_tree_wrapper!(backend_module)
+        return if backend_module.const_defined?(:Tree, false)
+
+        tree_class = Class.new(::TreeHaver::Base::Tree) do
+          define_method(:initialize) do |document, source|
+            super(document, source: source)
+          end
+
+          define_method(:root_node) do
+            backend_module.const_get(:Node).new(inner_tree, source: source, lines: lines)
+          end
+        end
+
+        backend_module.const_set(:Tree, tree_class)
+        backend_module.const_set(:Point, ::TreeHaver::Base::Point) unless backend_module.const_defined?(:Point, false)
+      end
+      private_class_method :install_tree_wrapper!
+
+      def register_backend!(backend_module:, backend_name:, gem_name:, require_path:)
+        ::TreeHaver::BackendRegistry.register(
+          ::TreeHaver::BackendReference.new(id: backend_name.to_s, family: 'native')
+        )
+
+        ::TreeHaver.register_language(
+          :markdown,
+          backend_type: backend_name,
+          backend_module: backend_module,
+          gem_name: gem_name
+        )
+
+        if ::TreeHaver::BackendRegistry.respond_to?(:register_tag)
+          ::TreeHaver::BackendRegistry.register_tag(
+            :"#{backend_name}_backend",
+            category: :backend,
+            backend_name: backend_name,
+            require_path: require_path
+          ) { backend_module.available? }
+        else
+          ::TreeHaver::BackendRegistry.register_availability_checker(backend_name) do
+            backend_module.available?
+          end
+        end
+      end
+      private_class_method :register_backend!
+
+      def safe_inner_node_call(node, method_name)
+        node.public_send(method_name)
+      rescue StandardError
+        nil
+      end
+      private_class_method :safe_inner_node_call
+
+      def node_helper_match?(node, matcher)
+        matcher.respond_to?(:call) ? matcher.call(node) : false
+      end
+      private_class_method :node_helper_match?
+    end
+  end
+end

data/lib/markdown/merge/cleanse/block_spacing.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+require 'parslet'
+
+module Markdown
+  module Merge
+    module Cleanse
+      # Fixes missing blank lines between block elements in Markdown.
+      #
+      # Markdown best practices require blank lines between:
+      # - List items and headings
+      # - Thematic breaks (---) and following content
+      # - HTML blocks (like </details>) and following markdown
+      # - Nested list items and headings
+      #
+      # This class detects and fixes these issues without using a full
+      # markdown parser, making it safe to use on documents that might
+      # have syntax issues.
+      #
+      # @example Basic usage
+      #   fixer = Markdown::Merge::Cleanse::BlockSpacing.new(content)
+      #   if fixer.malformed?
+      #     fixed_content = fixer.fix
+      #   end
+      #
+      # @example Check specific issues
+      #   fixer = Markdown::Merge::Cleanse::BlockSpacing.new(content)
+      #   fixer.issues.each do |issue|
+      #     puts "Line #{issue[:line]}: #{issue[:type]}"
+      #   end
+      #
+      class BlockSpacing
+        # Patterns for block elements that should have blank lines after them
+        THEMATIC_BREAK = /\A\s*(?:---+|\*\*\*+|___+)\s*\z/
+        HEADING = /\A\s*\#{1,6}\s+/
+        LIST_ITEM = /\A\s*(?:[-*+]|\d+\.)\s+/
+        HTML_CLOSE_TAG = %r{\A\s*</[a-zA-Z][a-zA-Z0-9]*>\s*\z}
+        HTML_OPEN_TAG = /\A\s*<[a-zA-Z][a-zA-Z0-9]*(?:\s|>)/
+        HTML_ANY_TAG = %r{\A\s*</?[a-zA-Z]}
+        LINK_REF_DEF = /\A\s*\[[^\]]+\]:\s*/
+
+        # Block-level HTML elements that can span multiple lines
+        # These create a context where we shouldn't insert blank lines
+        HTML_BLOCK_ELEMENTS = %w[
+          ul
+          ol
+          li
+          dl
+          dt
+          dd
+          div
+          table
+          thead
+          tbody
+          tfoot
+          tr
+          th
+          td
+          blockquote
+          pre
+          figure
+          figcaption
+          details
+          summary
+          section
+          article
+          aside
+          nav
+          header
+          footer
+          main
+          address
+          form
+          fieldset
+        ].freeze
+
+        # Pattern to match opening block-level HTML tags
+        HTML_BLOCK_OPEN = /\A\s*<(#{HTML_BLOCK_ELEMENTS.join('|')})(?:\s|>)/i
+
+        # Pattern to match closing block-level HTML tags
+        HTML_BLOCK_CLOSE = %r{\A\s*</(#{HTML_BLOCK_ELEMENTS.join('|')})>}i
+
+        # HTML elements that contain markdown content (not HTML content)
+        # These should have blank lines before their closing tags
+        MARKDOWN_CONTAINER_ELEMENTS = %w[details].freeze
+
+        # Pattern to match closing tags for markdown containers
+        MARKDOWN_CONTAINER_CLOSE = %r{\A\s*</(#{MARKDOWN_CONTAINER_ELEMENTS.join('|')})>}i
+
+        # Markdown content: anything that's not blank, not HTML, and not a link ref def
+        MARKDOWN_CONTENT = lambda { |line|
+          stripped = line.strip
+          return false if stripped.empty?
+          return false if stripped.start_with?('<')
+          return false if line.match?(LINK_REF_DEF)
+
+          true
+        }
+
+        # @return [String] The original content
+        attr_reader :source
+
+        # @return [Array<Hash>] Issues found
+        attr_reader :issues
+
+        # Initialize a new BlockSpacing fixer.
+        #
+        # @param source [String] The markdown content to analyze
+        def initialize(source)
+          @source = source
+          @issues = []
+          analyze
+        end
+
+        # Check if the content has block spacing issues.
+        #
+        # @return [Boolean] true if issues were found
+        def malformed?
+          @issues.any?
+        end
+
+        # Get the count of issues found.
+        #
+        # @return [Integer] number of issues
+        def issue_count
+          @issues.size
+        end
+
+        # Fix the block spacing issues.
+        #
+        # @return [String] Content with blank lines added where needed
+        def fix
+          return source unless malformed?
+
+          lines = source.lines
+          result = []
+          insertions = @issues.map { |i| i[:line] }.to_set
+
+          lines.each_with_index do |line, idx|
+            result << line
+            # If this line needs a blank line after it, add one
+            result << "\n" if insertions.include?(idx + 1) && !line.strip.empty? # issues use 1-based line numbers
+          end
+
+          result.join
+        end
+
+        private
+
+        def analyze
+          lines = source.lines
+          return if lines.empty?
+
+          # Track depth of block-level HTML elements
+          # When depth > 0, we're inside an HTML block and shouldn't add blank lines
+          html_block_depth = 0
+
+          lines.each_with_index do |line, idx|
+            next_line = lines[idx + 1]
+            prev_line = idx.positive? ? lines[idx - 1] : nil
+
+            # Special case: closing tags for markdown containers like </details>
+            # These contain markdown content, so we need blank lines before them
+            # even when inside an HTML block
+            is_markdown_container_close = line.match?(MARKDOWN_CONTAINER_CLOSE)
+
+            # Check for issues BEFORE updating depth
+            if html_block_depth <= 0
+              # Check for issues that need blank line AFTER current line
+              if next_line && !next_line.strip.empty?
+                check_thematic_break(line, next_line, idx)
+                check_list_before_heading(line, next_line, idx)
+                check_html_close_before_markdown(line, next_line, idx)
+              end
+
+              # Check for issues that need blank line BEFORE current line
+              check_markdown_before_html(prev_line, line, idx) if prev_line && !prev_line.strip.empty?
+            end
+
+            # Special case: always check for blank line before </details> etc.
+            # because they contain markdown content
+            if is_markdown_container_close && prev_line && !prev_line.strip.empty?
+              check_markdown_before_html(prev_line, line, idx)
+            end
+
+            # Update HTML block depth AFTER checking for issues
+            # Count opening block-level tags
+            html_block_depth += 1 if line.match?(HTML_BLOCK_OPEN)
+
+            # Check for closing block-level tags
+            line.scan(HTML_BLOCK_CLOSE) do
+              html_block_depth -= 1 if html_block_depth.positive?
+            end
+          end
+        end
+
+        def check_thematic_break(line, next_line, idx)
+          return unless line.match?(THEMATIC_BREAK)
+          return if next_line.strip.empty?
+
+          @issues << {
+            type: :thematic_break_needs_blank,
+            line: idx + 1,
+            description: 'Thematic break should be followed by blank line'
+          }
+        end
+
+        def check_list_before_heading(line, next_line, idx)
+          return unless line.match?(LIST_ITEM)
+          return unless next_line.match?(HEADING)
+
+          @issues << {
+            type: :list_before_heading,
+            line: idx + 1,
+            description: 'List item should be followed by blank line before heading'
+          }
+        end
+
+        def check_html_close_before_markdown(line, next_line, idx)
+          return unless line.match?(HTML_CLOSE_TAG)
+          # Next line is markdown (heading, list, paragraph start, etc.)
+          # but not HTML or blank
+          return if next_line.match?(/\A\s*</)
+          return if next_line.match?(LINK_REF_DEF)
+
+          @issues << {
+            type: :html_before_markdown,
+            line: idx + 1,
+            description: 'HTML close tag should be followed by blank line before markdown'
+          }
+        end
+
+        def check_markdown_before_html(prev_line, line, idx)
+          # Current line is HTML (open or close tag)
+          return unless line.match?(HTML_ANY_TAG)
+          # Previous line is markdown content (not HTML, not blank, not link ref)
+          return unless MARKDOWN_CONTENT.call(prev_line)
+
+          @issues << {
+            type: :markdown_before_html,
+            line: idx, # Insert blank line BEFORE this line (so after prev_line)
+            description: 'Markdown content should be followed by blank line before HTML'
+          }
+        end
+      end
+    end
+  end
+end