markbridge 0.1.1 → 0.1.3

data/lib/markbridge/renderers/discourse/renderer.rb

@@ -5,10 +5,13 @@ module Markbridge
     module Discourse
       # Renders AST to Discourse-flavored Markdown in-memory.
       class Renderer
-        def initialize(tag_library: nil, escaper: nil)
+        def initialize(tag_library: nil, escaper: nil, html_escaper: nil)
           @tag_library = tag_library || TagLibrary.default
           @escaper = escaper || MarkdownEscaper.new
-          @interface_cache = nil
+          @html_escaper = html_escaper || HtmlEscaper
+          # @interface_cache is lazily initialized in #render's top-level
+          # call and reset to nil after the call completes. No init
+          # needed here — unset ivar returns nil under `.nil?` check.
         end
 
         # Render a node to Markdown
@@ -26,18 +29,12 @@ module Markbridge
           end
 
           case node
-          when AST::Document, AST::Element
+          when AST::Element # Document is an Element subclass
             render_children(node, context:)
           when AST::MarkdownText
-            # Pass through markdown text as-is (already formatted)
-            node.text
+            render_markdown_text(node, context)
           when AST::Text
-            # Escape plain text unless we're inside a code block
-            if context.has_parent?(AST::Code)
-              node.text
-            else
-              @escaper.escape(node.text)
-            end
+            render_text(node, context)
           else
             ""
           end
@@ -50,14 +47,59 @@ module Markbridge
         # @param context [RenderContext] rendering context
         # @return [String]
         def render_children(node, context:)
-          node.children.map { |child| render(child, context:) }.join
+          result = +""
+          node.children.each do |child|
+            part = render(child, context:)
+            next if part.empty?
+
+            # Integer-byte check avoids allocating substrings for the
+            # per-child adjacency probe. EMPHASIS_DELIMITER_BYTES.include?
+            # over a 4-element Set is O(1).
+            if !result.empty? && (last_byte = result.getbyte(-1)) == part.getbyte(0) &&
+                 EMPHASIS_DELIMITER_BYTES.include?(last_byte)
+              result << EMPHASIS_BOUNDARY
+            end
+            result << part
+          end
+          result
         end
 
         private
 
+        # Inserted between sibling outputs when their adjacent characters
+        # would merge into a longer Markdown emphasis delimiter run (e.g.
+        # `***` + `*...` becoming `****...`). The HTML comment is invisible
+        # in rendered output but breaks the delimiter run during Markdown
+        # parsing.
+        EMPHASIS_BOUNDARY = "<!---->"
+        # Bytes where adjacent runs merge into a single longer run during
+        # Markdown parsing: emphasis (* _), strikethrough (~), code spans (`).
+        EMPHASIS_DELIMITER_BYTES = Set[42, 95, 126, 96].freeze
+        private_constant :EMPHASIS_BOUNDARY, :EMPHASIS_DELIMITER_BYTES
+
         def interface_for(context)
           @interface_cache[context.object_id] ||= RenderingInterface.new(self, context)
         end
+
+        # In html_mode, surround pre-formatted Markdown with blank lines so that
+        # CommonMark terminates the enclosing HTML block (e.g. <table>) and
+        # parses the content as Markdown before the closing tags reopen another
+        # HTML block.
+        def render_markdown_text(node, context)
+          context.html_mode? ? "\n\n#{node.text}\n\n" : node.text
+        end
+
+        def render_text(node, context)
+          # In html_mode even inside a code block we must HTML-escape, otherwise a
+          # stray `<` in a code cell would break the surrounding <td>.
+          if context.has_parent?(AST::Code)
+            context.html_mode? ? @html_escaper.escape(node.text) : node.text
+          elsif context.html_mode?
+            @html_escaper.escape(node.text)
+          else
+            @escaper.escape(node.text)
+          end
+        end
       end
     end
   end

data/lib/markbridge/renderers/discourse/rendering_interface.rb

@@ -27,6 +27,14 @@ module Markbridge
           @context.with_parent(element)
         end
 
+        def with_html_mode(value)
+          @context.with_html_mode(value)
+        end
+
+        def html_mode?
+          @context.html_mode?
+        end
+
         def find_parent(klass)
           @context.find_parent(klass)
         end
@@ -48,18 +56,18 @@ module Markbridge
         # @return [Boolean]
         def block_context?(node)
           # Check if it's a block-level element type (but not code, which can be inline)
-          return true if node.is_a?(AST::List) || node.is_a?(AST::HorizontalRule)
+          return true if node.instance_of?(AST::List) || node.instance_of?(AST::HorizontalRule)
           return false unless node.is_a?(AST::Element)
 
           # Check if content has newlines
-          node.children.any? { |c| c.is_a?(AST::Text) && c.text.include?("\n") }
+          node.children.any? { |c| c.instance_of?(AST::Text) && c.text.include?("\n") }
         end
 
         # Helper: wrap inline content with markers
         # Handles edge cases like existing markers and whitespace
         def wrap_inline(content, open_marker, close_marker = nil)
           close_marker ||= open_marker
-          return content if content.strip.empty?
+          return content unless content.match?(/\S/)
 
           # Handle conflicts with existing markers
           if content.include?(open_marker) || content.include?(close_marker)
@@ -75,7 +83,7 @@ module Markbridge
           end
 
           # Preserve leading/trailing whitespace
-          content.sub(/^(\s*)(.+?)(\s*)$/m) do
+          content.sub(/\A(\s*)(.+?)(\s*)\z/m) do
             match = Regexp.last_match
             "#{match[1]}#{open_marker}#{match[2]}#{close_marker}#{match[3]}"
           end

data/lib/markbridge/renderers/discourse/tag.rb

@@ -12,7 +12,20 @@ module Markbridge
           @render_block = block
         end
 
-        # Render a node to Discourse Markdown
+        # Render a node to Discourse Markdown.
+        #
+        # When `interface.html_mode?` is true the surrounding output is
+        # a CommonMark HTML block (§4.6): content is treated as raw HTML
+        # and is not re-parsed for Markdown except across blank lines.
+        # Every tag must pick one of two contracts:
+        #
+        # 1. Emit raw HTML (e.g. `<strong>` for `**`).
+        # 2. Wrap Markdown output in `\n\n…\n\n` so the blank lines close
+        #    the HTML block, CommonMark parses the content as a Markdown
+        #    island, then re-opens. Visible: blank-line wrapping forces a
+        #    `<p>` margin around inline content, so prefer (1) when the
+        #    tag has an HTML form.
+        #
         # @param element [AST::Node] the node to render
         # @param interface [RenderingInterface] the rendering interface
         # @return [String] the rendered markdown

data/lib/markbridge/renderers/discourse/tag_library.rb

@@ -5,6 +5,8 @@ module Markbridge
     module Discourse
       # Library of rendering tags for different element types
       class TagLibrary
+        include Enumerable
+
         def initialize
           @tags = {}
         end
@@ -24,42 +26,45 @@ module Markbridge
           @tags[element_class]
         end
 
+        # Iterate over registered (element_class, tag) pairs.
+        # Useful for debugging custom libraries — e.g. confirming an override
+        # has stuck. Iteration order matches registration order.
+        # @yieldparam element_class [Class]
+        # @yieldparam tag [Tag]
+        # @return [Enumerator] when no block is given
+        def each(&block)
+          @tags.each(&block)
+        end
+
         # Auto-register all tags using naming convention
         # Convention: BoldTag handles AST::Bold, ItalicTag handles AST::Italic, etc.
         # @return [self]
         def auto_register!
           Tags.constants.each do |tag_constant|
-            tag_class = Tags.const_get(tag_constant)
-            next unless tag_class.is_a?(Class) && tag_class < Tag
-
-            # Extract element name from tag name: BoldTag → Bold
-            element_name = tag_constant.to_s.sub(/Tag$/, "")
-            element_class =
-              begin
-                AST.const_get(element_name)
-              rescue StandardError
-                nil
-              end
-
-            register(element_class, tag_class.new) if element_class
+            element_class = ast_class_for(tag_constant)
+            register(element_class, Tags.const_get(tag_constant).new) if element_class
           end
-
           self
         end
 
-        # Create the default tag library for Discourse Markdown
+        # Look up the AST element class matching a +XxxTag+ constant via the
+        # +XxxTag → AST::Xxx+ naming convention.
+        # @return [Class, nil]
+        def ast_class_for(tag_constant)
+          AST.const_get(tag_constant.to_s.sub(/Tag\z/, ""))
+        rescue NameError
+          nil
+        end
+
+        # Create the default tag library for Discourse Markdown.
+        #
+        # Each call returns a *fresh* instance — mutations made to one will
+        # not be visible to another. If you want a process-wide singleton,
+        # use {Markbridge.default_tag_library} instead, which memoizes.
+        #
         # @return [TagLibrary]
         def self.default
-          library = new
-
-          # Auto-register tags based on naming convention
-          library.auto_register!
-
-          # Special cases: inline tags that don't follow the convention
-          library.register AST::LineBreak, Tags::LineBreakTag.new
-          library.register AST::HorizontalRule, Tags::HorizontalRuleTag.new
-
-          library
+          new.auto_register!
         end
       end
     end

data/lib/markbridge/renderers/discourse/tags/align_tag.rb

@@ -4,18 +4,26 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering aligned text
-        # Renders as HTML div with align attribute
+        # Discourse's HTML sanitizer allows the (HTML5-deprecated) `align`
+        # attribute on `<div>` but strips inline `style`, so we emit the
+        # legacy form. Alignment is constrained to a known keyword set
+        # for defense in depth — anything outside the set falls through
+        # to bare content rather than getting interpolated into the
+        # attribute.
         class AlignTag < Tag
+          ALLOWED_ALIGNMENTS = Set["left", "right", "center", "justify"].freeze
+          private_constant :ALLOWED_ALIGNMENTS
+
           def render(element, interface)
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
 
-            if element.alignment
-              "<div align=\"#{element.alignment}\">#{content}</div>\n\n"
-            else
-              content
-            end
+            return content unless ALLOWED_ALIGNMENTS.include?(element.alignment)
+
+            wrapper = %(<div align="#{element.alignment}">#{content}</div>)
+            # Skip the trailing blank line in html_mode: a blank line would
+            # terminate the surrounding HTML block (e.g. an enclosing <table>).
+            interface.html_mode? ? wrapper : "#{wrapper}\n\n"
           end
         end
       end

data/lib/markbridge/renderers/discourse/tags/bold_tag.rb

@@ -9,6 +9,8 @@ module Markbridge
           def render(element, interface)
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
+            return "<strong>#{content}</strong>" if interface.html_mode?
+
             interface.wrap_inline(content, "**")
           end
         end

data/lib/markbridge/renderers/discourse/tags/code_tag.rb

@@ -4,15 +4,19 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering code
         class CodeTag < Tag
           def render(element, interface)
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
 
-            # Determine if inline or block based on context
             if interface.block_context?(element)
-              render_block(content, element.language)
+              if interface.html_mode?
+                render_html_block(content, element.language)
+              else
+                render_block(content, element.language)
+              end
+            elsif interface.html_mode?
+              "<code>#{content}</code>"
             else
               render_inline(content)
             end
@@ -24,24 +28,25 @@ module Markbridge
             "`#{content}`"
           end
 
+          # Trailing blank line keeps an adjacent fence on the next block from
+          # being parsed as a continuation of this one.
           def render_block(content, language)
             fence = calculate_fence(content)
-            lang = language || ""
+            "#{fence}#{language}\n#{content}\n#{fence}\n\n"
+          end
 
-            # Blank line keeps adjacent fences from merging.
-            "#{fence}#{lang}\n#{content}\n#{fence}\n\n"
+          def render_html_block(content, language)
+            class_attr = %( class="language-#{HtmlEscaper.escape(language)}") if language
+            "<pre><code#{class_attr}>#{content}</code></pre>"
           end
 
           def calculate_fence(content)
-            # Find longest sequence of backticks and tildes
             max_backticks = content.scan(/`+/).map(&:length).max || 0
             max_tildes = content.scan(/~+/).map(&:length).max || 0
 
-            # Need fence longer than any sequence in content (minimum 3)
             required_backticks = [3, max_backticks + 1].max
             required_tildes = [3, max_tildes + 1].max
 
-            # Choose whichever requires fewer characters
             if required_backticks <= required_tildes
               "`" * required_backticks
             else

data/lib/markbridge/renderers/discourse/tags/email_tag.rb

@@ -11,10 +11,12 @@ module Markbridge
             text = interface.render_children(element, context: child_context)
             address = element.address
 
-            if address
-              "[#{text}](mailto:#{address})"
+            return text unless address
+
+            if interface.html_mode?
+              %(<a href="mailto:#{HtmlEscaper.escape(address)}">#{text}</a>)
             else
-              text
+              "[#{text}](mailto:#{address})"
             end
           end
         end

data/lib/markbridge/renderers/discourse/tags/event_tag.rb

@@ -18,8 +18,10 @@ module Markbridge
         #     end
         #   end
         class EventTag < Tag
-          def render(element, _interface)
+          def render(element, interface)
             body = element.raw || build_event_bbcode(element)
+            return "\n\n#{body}\n\n" if interface.html_mode?
+
             "#{body}\n\n"
           end
 

data/lib/markbridge/renderers/discourse/tags/heading_tag.rb

@@ -4,12 +4,16 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering headings
-        # Renders as ATX-style Markdown headings (# through ######)
         class HeadingTag < Tag
           def render(element, interface)
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
+
+            if interface.html_mode?
+              level = element.level.clamp(1, 6)
+              return "<h#{level}>#{content}</h#{level}>"
+            end
+
             prefix = "#" * element.level
 
             "#{prefix} #{content}\n\n"

data/lib/markbridge/renderers/discourse/tags/horizontal_rule_tag.rb

@@ -6,8 +6,8 @@ module Markbridge
       module Tags
         # Tag for rendering horizontal rules
         class HorizontalRuleTag < Tag
-          def render(_element, _interface)
-            "\n\n---\n\n"
+          def render(_element, interface)
+            interface.html_mode? ? "<hr>" : "\n\n---\n\n"
           end
         end
       end

data/lib/markbridge/renderers/discourse/tags/image_tag.rb

@@ -7,11 +7,13 @@ module Markbridge
         # Tag for rendering images
         # Renders to Markdown image syntax with optional Discourse sizing
         class ImageTag < Tag
-          def render(element, _interface)
-            src = element.src || ""
+          def render(element, interface)
+            src = element.src
             width = element.width
             height = element.height
 
+            return render_html(src, width, height) if interface.html_mode?
+
             # Build Discourse image syntax with dimensions
             # Format: ![alt|WIDTHxHEIGHT](url) or ![alt|WIDTH](url)
             if width && height
@@ -22,6 +24,15 @@ module Markbridge
               "![](#{src})"
             end
           end
+
+          private
+
+          def render_html(src, width, height)
+            attrs = %(src="#{HtmlEscaper.escape(src)}" alt="")
+            attrs << %( width="#{width}") if width
+            attrs << %( height="#{height}") if height
+            "<img #{attrs}>"
+          end
         end
       end
     end

data/lib/markbridge/renderers/discourse/tags/italic_tag.rb

@@ -9,6 +9,8 @@ module Markbridge
           def render(element, interface)
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
+            return "<em>#{content}</em>" if interface.html_mode?
+
             interface.wrap_inline(content, "*")
           end
         end

data/lib/markbridge/renderers/discourse/tags/line_break_tag.rb

@@ -6,8 +6,8 @@ module Markbridge
       module Tags
         # Tag for rendering line breaks
         class LineBreakTag < Tag
-          def render(_element, _interface)
-            "\n"
+          def render(_element, interface)
+            interface.html_mode? ? "<br>" : "\n"
           end
         end
       end

data/lib/markbridge/renderers/discourse/tags/list_item_tag.rb

@@ -7,77 +7,54 @@ module Markbridge
         # Tag for rendering list items
         class ListItemTag < Tag
           def initialize
-            super
             @builder = Builders::ListItemBuilder.new
           end
 
           def render(element, interface)
-            # Create new context with this list item as parent
             child_context = interface.with_parent(element)
-
-            # Render children with updated context
             content = interface.render_children(element, context: child_context).strip
             return "" if content.empty?
 
-            # Get parent list to determine marker
-            parent_list = interface.find_parent(AST::List)
-            marker = determine_marker(parent_list)
-
-            # Calculate indentation based on ancestor lists
-            indent = calculate_indent(interface)
+            return "<li>#{content}</li>" if interface.html_mode?
 
-            # Delegate formatting to builder
-            @builder.build(content, marker:, indent:)
+            parent_list = interface.find_parent(AST::List)
+            @builder.build(
+              content,
+              marker: determine_marker(parent_list),
+              indent: calculate_indent(interface),
+            )
           end
 
           private
 
-          # Determine the list marker based on parent list type
           # @param parent_list [AST::List, nil]
           # @return [String]
           def determine_marker(parent_list)
             parent_list&.ordered? ? "1. " : "- "
           end
 
-          # Calculate indentation for this list item
+          # Each ancestor List (excluding the direct parent) contributes
+          # indentation matching its own marker width:
+          # ordered = "   " (3 chars for "1. "), unordered = "  " (2 chars for "- ").
           # @param interface [RenderingInterface]
           # @return [String]
           def calculate_indent(interface)
-            # Calculate indentation: count ancestor Lists (not including direct parent)
-            # The direct parent List shouldn't add indentation, only grandparent Lists
             list_count = interface.count_parents(AST::List)
-            # Subtract 1 because the immediate parent list doesn't contribute to indent
-            ancestor_lists = list_count.positive? ? list_count - 1 : 0
-
-            # Indentation width depends on markers of ancestor lists
-            # Walk up the context to determine correct indentation
-            calculate_indent_from_ancestors(interface.context, ancestor_lists)
-          end
-
-          # Calculate the correct indentation for nested list items
-          # Each level matches the marker width of its parent: ordered="1. " (3 chars), unordered="- " (2 chars)
-          # @param context [RenderContext] the rendering context
-          # @param ancestor_count [Integer] number of ancestor lists
-          # @return [String] the indentation string
-          def calculate_indent_from_ancestors(context, ancestor_count)
-            return "" if ancestor_count.zero?
-
-            # Walk through parents from outermost to innermost to build indentation
-            # Each ancestor contributes indentation based on ITS OWN marker width
-            lists = context.parents.select { |p| p.is_a?(AST::List) }
-
-            # Skip the immediate parent (last list in the array)
-            ancestor_lists = lists[0...-1]
-
-            # Build indentation string
-            indent = ""
-            ancestor_lists
-              .first(ancestor_count)
-              .each do |list|
-                # Each level's indentation matches that list's marker width
-                indent += list.ordered? ? "   " : "  "
-              end
+            # Top-level list — no ancestor lists contribute indent. The
+            # common case; short-circuit before any array allocations.
+            return "" if list_count <= 1
 
+            indent = +""
+            found = 0
+            interface.context.parents.each do |parent|
+              next unless parent.instance_of?(AST::List)
+              found += 1
+              # The immediate parent List is the LAST one in parents; its
+              # marker width is already accounted for by the item's own
+              # marker, so it doesn't contribute to indent.
+              break if found == list_count
+              indent << (parent.ordered? ? "   " : "  ")
+            end
             indent
           end
         end

data/lib/markbridge/renderers/discourse/tags/list_tag.rb

@@ -4,31 +4,26 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering lists
         class ListTag < Tag
           def render(element, interface)
-            # Create new context with this list as parent
             child_context = interface.with_parent(element)
 
-            # Render children with updated context, dropping empty items
-            rendered_items =
-              element.children.filter_map do |child|
-                rendered = interface.render_node(child, context: child_context)
-                rendered unless rendered.strip.empty?
-              end
+            content =
+              element
+                .children
+                .map { |child| interface.render_node(child, context: child_context) }
+                .join
 
-            content = rendered_items.join
+            if interface.html_mode?
+              tag_name = element.ordered? ? "ol" : "ul"
+              return "<#{tag_name}>#{content}</#{tag_name}>"
+            end
 
-            # Check if we're nested - either inside another List OR inside a ListItem
-            has_list_parent = interface.has_parent?(AST::List)
-            has_list_item_parent = interface.has_parent?(AST::ListItem)
-            nested = has_list_parent || has_list_item_parent
+            nested = interface.has_parent?(AST::List) || interface.has_parent?(AST::ListItem)
 
             if nested
-              # Nested list: add leading newline so it starts on its own line
               "\n#{content}"
             else
-              # Top-level list: add spacing
               "\n\n#{content}\n\n"
             end
           end

data/lib/markbridge/renderers/discourse/tags/mention_tag.rb

@@ -25,7 +25,11 @@ module Markbridge
         #   end
         class MentionTag < Tag
           def render(element, _interface)
-            "@#{element.name}"
+            # Escape unconditionally: realistic Discourse usernames have no
+            # HTML-special characters so the Markdown path is unaffected,
+            # and the html_mode path needs the escape to splice safely into
+            # a raw HTML block.
+            "@#{HtmlEscaper.escape(element.name)}"
           end
         end
       end

data/lib/markbridge/renderers/discourse/tags/paragraph_tag.rb

@@ -11,6 +11,16 @@ module Markbridge
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
 
+            if interface.html_mode?
+              # Inside a table cell the surrounding <td> already provides the
+              # block context, so a <p> wrapper just adds vertical margin —
+              # and if the paragraph contains a block element (e.g. a list),
+              # `<p><ul>…</ul></p>` is invalid per HTML5. Drop the wrapper.
+              return content if interface.has_parent?(AST::TableCell)
+
+              return "<p>#{content}</p>"
+            end
+
             # Paragraph followed by blank line (two newlines)
             "#{content}\n\n"
           end