markbridge 0.2.1 → 0.3.0

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

@@ -3,30 +3,74 @@
 module Markbridge
   module Renderers
     module Discourse
-      # Immutable context for rendering that wraps the parent chain.
+      # Immutable context for rendering, implemented as a linked parent
+      # chain: each context holds the nearest parent element plus a link
+      # to the enclosing context. {#with_parent} runs once per rendered
+      # element — the chain form makes it a single fixed-size allocation
+      # instead of copying (and freezing) a parents array per element.
       # Provides query methods to ask about parent elements without the
       # renderer knowing about specific element types.
       class RenderContext
-        attr_reader :parents, :depth
+        # @return [Integer] number of parent elements in the chain
+        attr_reader :depth
 
-        def initialize(parents = [], html_mode: false)
-          @parents = parents.freeze
-          @depth = parents.size
+        # @return [AST::Element, nil] the nearest parent element (nil at root)
+        attr_reader :element
+
+        # @return [RenderContext, nil] the enclosing context (nil at root)
+        attr_reader :parent_context
+
+        # @param parents [Array<AST::Element>] parent elements in document
+        #   order (outermost first); convenience form for building a
+        #   context from scratch. Ignored when +element:+ is given.
+        # @param html_mode [Boolean] see {#html_mode?}
+        # @param parent [RenderContext, nil] enclosing context (chain form)
+        # @param element [AST::Element, nil] nearest parent element (chain form)
+        def initialize(parents = [], html_mode: false, parent: nil, element: nil)
           @html_mode = html_mode
+          if element
+            @parent_context = parent
+            @element = element
+            @depth = (parent ? parent.depth : 0) + 1
+          elsif parents.empty?
+            # Root context: @element and @parent_context stay unset and
+            # read as nil.
+            @depth = 0
+          else
+            @parent_context = self.class.new(parents[0, parents.size - 1], html_mode:)
+            @element = parents.last
+            @depth = parents.size
+          end
+        end
+
+        # Parent elements in document order (outermost first), materialized
+        # from the chain into a frozen Array. Allocates on every call —
+        # prefer {#find_parent} / {#has_parent?} / {#count_parents} on hot
+        # paths.
+        # @return [Array<AST::Element>]
+        def parents
+          result = []
+          context = self
+          while context && (parent = context.element)
+            result << parent
+            context = context.parent_context
+          end
+          result.reverse!
+          result.freeze
         end
 
         # Create new context with element added to parent chain.
         # @param element [AST::Element]
         # @return [RenderContext]
         def with_parent(element)
-          self.class.new(@parents + [element], html_mode: @html_mode)
+          self.class.new(html_mode: @html_mode, parent: self, element:)
         end
 
         # Create new context with html_mode toggled.
         # @param value [Boolean]
         # @return [RenderContext]
         def with_html_mode(value)
-          self.class.new(@parents, html_mode: value)
+          self.class.new(html_mode: value, parent: @parent_context, element: @element)
         end
 
         # @return [Boolean]
@@ -35,24 +79,43 @@ module Markbridge
         end
 
         # Find closest parent that is_a? klass (handles subclasses).
+        # The chain walks are inlined in each query (instead of a shared
+        # yielding helper) — these run several times per rendered text
+        # node, and a plain while loop avoids the block invocation.
         # @param klass [Class]
-        # @return [AST::Element, nil]
+        # @return [AST::Element, nil] nil when no parent matches (implicit
+        #   from the exhausted while loop)
         def find_parent(klass)
-          @parents.reverse_each.find { |parent| parent.is_a?(klass) }
+          context = self
+          while context && (parent = context.element)
+            return parent if parent.is_a?(klass)
+            context = context.parent_context
+          end
         end
 
         # Count parents that are is_a? klass (handles subclasses).
         # @param klass [Class]
         # @return [Integer]
         def count_parents(klass)
-          @parents.count { |parent| parent.is_a?(klass) }
+          count = 0
+          context = self
+          while context && (parent = context.element)
+            count += 1 if parent.is_a?(klass)
+            context = context.parent_context
+          end
+          count
         end
 
         # Check if any parent is_a? klass (handles subclasses).
         # @param klass [Class]
         # @return [Boolean]
         def has_parent?(klass)
-          @parents.any? { |parent| parent.is_a?(klass) }
+          context = self
+          while context && (parent = context.element)
+            return true if parent.is_a?(klass)
+            context = context.parent_context
+          end
+          false
         end
 
         # Check if we're at the root (no parents).

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

@@ -8,7 +8,7 @@ module Markbridge
         attr_reader :postprocessor
 
         def initialize(tag_library: nil, escaper: nil, html_escaper: nil, postprocessor: nil)
-          @tag_library = tag_library || TagLibrary.default
+          @tag_library = tag_library || TagLibrary.shared_default
           @escaper = escaper || MarkdownEscaper.new
           @html_escaper = html_escaper || HtmlEscaper
           @postprocessor = postprocessor || Postprocessor::DEFAULT
@@ -20,26 +20,56 @@ module Markbridge
         # @param node [AST::Node]
         # @param context [RenderContext] rendering context with parent chain
         # @return [String]
+        # @raise [TypeError] when the tag bound to the node's class returns
+        #   something other than a String (a nil from a custom tag would
+        #   otherwise surface as an inscrutable concatenation error deep
+        #   inside render_children)
         def render(node, context: RenderContext.new)
           root_call = @interface_cache.nil?
           @interface_cache = {} if root_call
 
           tag = @tag_library[node.class]
           if tag
-            interface = interface_for(context)
-            return tag.render(node, interface)
+            result = tag.render(node, interface_for(context))
+            unless result.is_a?(String)
+              raise TypeError,
+                    "#{tag.class} rendered #{node.class} to " \
+                      "#{result.inspect} — tags must return a String " \
+                      "(use interface.render_default(node) to fall back " \
+                      "to the stock rendering)"
+            end
+            return result
           end
 
-          case node
-          when AST::Element # Document is an Element subclass
-            render_children(node, context:)
-          when AST::MarkdownText
-            render_markdown_text(node, context)
-          when AST::Text
-            render_text(node, context)
-          else
-            ""
-          end
+          render_without_tag(node, context)
+        ensure
+          @interface_cache = nil if root_call
+        end
+
+        # Render a node with the stock tag for its class, ignoring any
+        # override registered in this renderer's tag library. Lets a
+        # custom tag intercept only the nodes it cares about and delegate
+        # the rest:
+        #
+        #   library.register(AST::Quote, Tag.new do |node, interface|
+        #     next interface.render_default(node) unless node.username&.start_with?("legacy_")
+        #     ...custom rendering...
+        #   end)
+        #
+        # Children still render through this renderer, so overrides for
+        # other node classes keep applying inside the delegated subtree.
+        #
+        # @param node [AST::Node]
+        # @param context [RenderContext] rendering context with parent chain
+        # @return [String]
+        def render_default(node, context: RenderContext.new)
+          root_call = @interface_cache.nil?
+          @interface_cache = {} if root_call
+
+          tag = default_tag_library[node.class]
+          return tag.render(node, interface_for(context)) if tag
+
+          render_without_tag(node, context)
         ensure
           @interface_cache = nil if root_call
         end
@@ -83,6 +113,26 @@ module Markbridge
           @interface_cache[context.object_id] ||= RenderingInterface.new(self, context)
         end
 
+        # Pristine default library backing #render_default. Built lazily —
+        # most renders never need it.
+        def default_tag_library
+          @default_tag_library ||= TagLibrary.default
+        end
+
+        # The tag-less rendering paths shared by #render and #render_default.
+        def render_without_tag(node, context)
+          case node
+          when AST::Element # Document is an Element subclass
+            render_children(node, context:)
+          when AST::MarkdownText
+            render_markdown_text(node, context)
+          when AST::Text
+            render_text(node, context)
+          else
+            ""
+          end
+        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

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

@@ -18,6 +18,14 @@ module Markbridge
           @renderer.render(node, context:)
         end
 
+        # Render a node with the stock tag for its class, bypassing any
+        # override in the renderer's tag library. Lets a custom tag handle
+        # only the nodes it cares about and delegate the rest — see
+        # Renderer#render_default.
+        def render_default(node, context: @context)
+          @renderer.render_default(node, context:)
+        end
+
         def render_children(element, context: @context)
           @renderer.render_children(element, context:)
         end
@@ -63,6 +71,11 @@ module Markbridge
           node.children.any? { |c| c.instance_of?(AST::Text) && c.text.include?("\n") }
         end
 
+        # Leading or trailing whitespace (Unicode-aware, matching the
+        # flanking-preservation sub in #wrap_inline).
+        EDGE_WHITESPACE = /\A[[:space:]]|[[:space:]]\z/m
+        private_constant :EDGE_WHITESPACE
+
         # Helper: wrap inline content with markers
         # Handles edge cases like existing markers and whitespace
         def wrap_inline(content, open_marker, close_marker = nil)
@@ -82,8 +95,20 @@ module Markbridge
             end
           end
 
-          # Preserve leading/trailing whitespace (Unicode-aware, since
-          # CommonMark's flanking rules treat e.g. nbsp as whitespace).
+          apply_markers(content, open_marker, close_marker)
+        end
+
+        private
+
+        # Wrap content in markers, keeping leading/trailing whitespace
+        # outside the markers (Unicode-aware, since CommonMark's flanking
+        # rules treat e.g. nbsp as whitespace).
+        def apply_markers(content, open_marker, close_marker)
+          # Fast path: no edge whitespace to preserve (the common case), so
+          # plain interpolation replaces the capture-group sub below and its
+          # MatchData + capture allocations.
+          return "#{open_marker}#{content}#{close_marker}" unless content.match?(EDGE_WHITESPACE)
+
           content.sub(/\A([[:space:]]*)(.+?)([[:space:]]*)\z/m) do
             match = Regexp.last_match
             "#{match[1]}#{open_marker}#{match[2]}#{close_marker}#{match[3]}"

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

@@ -106,6 +106,26 @@ module Markbridge
         def self.default
           new.auto_register!
         end
+
+        # Shared, deep-frozen default library for the no-customization
+        # fast path. Built once per process; {Renderer} falls back to it
+        # when no +tag_library:+ is given, skipping the constant-scan and
+        # ~30 tag instantiations of {.default} on every render. Tags are
+        # stateless, so sharing is safe across renderers and threads.
+        # +dup+ yields a mutable copy (see {#initialize_copy}).
+        #
+        # @return [TagLibrary] the same frozen instance on every call
+        def self.shared_default
+          @shared_default ||= default.freeze
+        end
+
+        # Freeze the library together with its internal Hash so that
+        # registration on a shared instance fails loudly instead of
+        # silently mutating state visible to every renderer.
+        def freeze
+          @tags.freeze
+          super
+        end
       end
     end
   end

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

@@ -14,14 +14,16 @@ module Markbridge
             return "<blockquote>#{content}</blockquote>" if interface.html_mode?
 
             # Build Discourse quote BBCode
-            # Format: [quote="username, post:123, topic:456"]content[/quote]
+            # Format: [quote="username, post:2, topic:456"]content[/quote]
+            # (post: is the post number within the topic, topic: the topic id)
             body =
-              if element.post && element.topic && element.username
+              if element.post_number && element.topic_id && element.username
                 # Full Discourse quote with context
-                "[quote=\"#{element.username}, post:#{element.post}, topic:#{element.topic}\"]\n#{content}\n[/quote]"
-              elsif element.author
-                # Quote with author attribution only
-                "[quote=\"#{element.author}\"]\n#{content}\n[/quote]"
+                "[quote=\"#{element.username}, post:#{element.post_number}, topic:#{element.topic_id}\"]\n#{content}\n[/quote]"
+              elsif element.author || element.username
+                # Name-only attribution; a bare post_id/user_id can't
+                # produce a valid Discourse post reference.
+                "[quote=\"#{element.author || element.username}\"]\n#{content}\n[/quote]"
               else
                 # Plain quote rendered as Markdown blockquote
                 content.split("\n").map { |line| "> #{line}" }.join("\n")

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

@@ -5,20 +5,54 @@ module Markbridge
     module Discourse
       module Tags
         # Tag for rendering URLs
+        #
+        # Bare URLs (a single Text child equal to the href, or no link
+        # text at all) render as the plain href instead of a Markdown
+        # link — in Discourse a bare URL on its own line oneboxes, a
+        # `[text](url)` link does not.
         class UrlTag < Tag
+          # Schemes that are safe to link. Anything else that *looks*
+          # like a scheme (javascript:, data:, vbscript:, …) is dropped;
+          # scheme-less hrefs (relative paths, anchors, protocol-relative
+          # URLs) pass through — common in forum exports and harmless.
+          ALLOWED_SCHEMES = /\A(?:https?|ftps?|mailto):/i
+          SCHEME_LIKE = /\A[a-z][a-z0-9+.-]*:/i
+          private_constant :ALLOWED_SCHEMES, :SCHEME_LIKE
+
           def render(element, interface)
             child_context = interface.with_parent(element)
             text = interface.render_children(element, context: child_context)
             href = element.href
 
-            return text unless href&.match?(/\A(?:https?|ftps?|mailto):/i)
+            return text unless linkable?(href)
 
             if interface.html_mode?
               %(<a href="#{HtmlEscaper.escape(href)}">#{text}</a>)
+            elsif element.bare? || text.empty?
+              # Url#bare? judges the AST (so label escaping can't confuse
+              # it); the rendered-text check additionally catches labels
+              # that render to nothing (e.g. an empty formatting child).
+              href
             else
-              "[#{text}](#{href})"
+              "[#{text}](#{markdown_destination(href)})"
             end
           end
+
+          private
+
+          # CommonMark link destinations cannot contain whitespace unless
+          # wrapped in <> — relevant for relative targets like MediaWiki
+          # page names ("Main Page").
+          def markdown_destination(href)
+            href.match?(/\s/) ? "<#{href}>" : href
+          end
+
+          def linkable?(href)
+            return false if href.nil? || href.empty?
+            return true if href.match?(ALLOWED_SCHEMES)
+
+            !href.match?(SCHEME_LIKE)
+          end
         end
       end
     end

data/lib/markbridge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Markbridge
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markbridge
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Discourse Team