markbridge 0.2.1 → 0.3.1

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

@@ -178,6 +178,12 @@ module Markbridge
         end
 
         def escape_text(text)
+          # Single-line fast path (the common case for inline text nodes):
+          # skip the split and its Array + line-String allocations. A lone
+          # `\r` without `\n` stays on the line either way — `/\r?\n/`
+          # needs the `\n` — so `include?("\n")` alone decides correctly.
+          return escape_line(text, false) unless text.include?("\n")
+
           # On CRLF input, consume `\r` as part of the line terminator instead
           # of leaving it on the line. A trailing `\r` breaks line-end anchored
           # regexes (e.g. SETEXT_UNDERLINE_*) and the `ws_end >= line_length`
@@ -186,7 +192,6 @@ module Markbridge
           # LF-only fast path on a string split (regex split is ~20% slower
           # on the indented-code hot path).
           lines = text.include?("\r") ? text.split(/\r?\n/, -1) : text.split("\n", -1)
-          return escape_line(lines[0], false) if lines.size == 1
 
           # Pre-allocate result buffer
           bytesize = text.bytesize
@@ -231,6 +236,12 @@ module Markbridge
             result = String.new(encoding: line.encoding)
             result << line[0, indent_len] << escaped
             result
+          elsif escaped.equal?(line)
+            # Nothing needed escaping, so `escaped` IS the input line: its
+            # encoding is already right, and since escape_text's
+            # single-line fast path that input can be the caller's own
+            # (possibly frozen) string — force_encoding would raise.
+            line
           else
             escaped.force_encoding(line.encoding)
           end

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/event_tag.rb

@@ -18,11 +18,9 @@ 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"
+            "\n\n#{body}\n\n"
           end
 
           private

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

@@ -18,11 +18,9 @@ module Markbridge
         #     end
         #   end
         class PollTag < Tag
-          def render(element, interface)
+          def render(element, _interface)
             body = element.raw || build_poll_bbcode(element)
-            return "\n\n#{body}\n\n" if interface.html_mode?
-
-            "#{body}\n\n"
+            "\n\n#{body}\n\n"
           end
 
           private

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.1"
 end

data/lib/markbridge.rb

@@ -5,6 +5,7 @@ require_relative "markbridge/parse"
 require_relative "markbridge/conversion"
 
 require_relative "markbridge/ast"
+require_relative "markbridge/normalizer"
 require_relative "markbridge/renderers/discourse"
 
 module Markbridge
@@ -44,11 +45,21 @@ module Markbridge
     #   {Conversion} with an empty +markdown+ string, and surface the
     #   exceptions via {Conversion#errors}.
     # @yieldparam ast [AST::Document] mutate before rendering (optional)
+    # @param normalize [Boolean, Normalizer] apply target-format nesting
+    #   rules between the +yield+ hook and render. +true+ (default) uses the
+    #   shared default normalizer; a {Normalizer} is used as-is; +false+
+    #   skips normalization. See {Normalizer}.
     # @return [Conversion]
-    def bbcode_to_markdown(input, handlers: nil, renderer: nil, raise_on_error: true)
+    def bbcode_to_markdown(
+      input,
+      handlers: nil,
+      renderer: nil,
+      raise_on_error: true,
+      normalize: true
+    )
       parse = parse_bbcode(input, handlers:)
       yield(parse.ast) if block_given?
-      build_conversion(parse, renderer:, raise_on_error:)
+      build_conversion(parse, renderer:, raise_on_error:, normalize:)
     end
 
     # Parse HTML to AST.
@@ -85,11 +96,12 @@ module Markbridge
     #   {Conversion} with an empty +markdown+ string, and surface the
     #   exceptions via {Conversion#errors}.
     # @yieldparam ast [AST::Document] mutate before rendering (optional)
+    # @param normalize [Boolean, Normalizer] see {.bbcode_to_markdown}
     # @return [Conversion]
-    def html_to_markdown(input, handlers: nil, renderer: nil, raise_on_error: true)
+    def html_to_markdown(input, handlers: nil, renderer: nil, raise_on_error: true, normalize: true)
       parse = parse_html(input, handlers:)
       yield(parse.ast) if block_given?
-      build_conversion(parse, renderer:, raise_on_error:)
+      build_conversion(parse, renderer:, raise_on_error:, normalize:)
     end
 
     # Parse s9e/TextFormatter XML to AST.
@@ -122,11 +134,18 @@ module Markbridge
     # @param renderer [Renderers::Discourse::Renderer, nil] custom renderer
     # @param raise_on_error [Boolean] see {.bbcode_to_markdown}
     # @yieldparam ast [AST::Document] mutate before rendering (optional)
+    # @param normalize [Boolean, Normalizer] see {.bbcode_to_markdown}
     # @return [Conversion]
-    def text_formatter_xml_to_markdown(input, handlers: nil, renderer: nil, raise_on_error: true)
+    def text_formatter_xml_to_markdown(
+      input,
+      handlers: nil,
+      renderer: nil,
+      raise_on_error: true,
+      normalize: true
+    )
       parse = parse_text_formatter_xml(input, handlers:)
       yield(parse.ast) if block_given?
-      build_conversion(parse, renderer:, raise_on_error:)
+      build_conversion(parse, renderer:, raise_on_error:, normalize:)
     end
 
     # Parse MediaWiki wikitext to AST.
@@ -155,11 +174,18 @@ module Markbridge
     # @param renderer [Renderers::Discourse::Renderer, nil] custom renderer
     # @param raise_on_error [Boolean] see {.bbcode_to_markdown}
     # @yieldparam ast [AST::Document] mutate before rendering (optional)
+    # @param normalize [Boolean, Normalizer] see {.bbcode_to_markdown}
     # @return [Conversion]
-    def mediawiki_to_markdown(input, handlers: nil, renderer: nil, raise_on_error: true)
+    def mediawiki_to_markdown(
+      input,
+      handlers: nil,
+      renderer: nil,
+      raise_on_error: true,
+      normalize: true
+    )
       parse = parse_mediawiki(input, handlers:)
       yield(parse.ast) if block_given?
-      build_conversion(parse, renderer:, raise_on_error:)
+      build_conversion(parse, renderer:, raise_on_error:, normalize:)
     end
 
     # Convert input in the given format. Thin dispatcher over the
@@ -211,8 +237,17 @@ module Markbridge
     # @param format [Symbol] :discourse (only renderer currently shipped)
     # @param renderer [Renderers::Discourse::Renderer, nil]
     # @param raise_on_error [Boolean]
+    # @param normalize [Boolean, Normalizer] see {.bbcode_to_markdown}.
+    #   Normalization is idempotent, so re-rendering an already-normalized
+    #   {Parse} is a no-op.
     # @return [Conversion]
-    def render(parse_or_ast, format: :discourse, renderer: nil, raise_on_error: true)
+    def render(
+      parse_or_ast,
+      format: :discourse,
+      renderer: nil,
+      raise_on_error: true,
+      normalize: true
+    )
       raise ArgumentError, "unknown render format #{format.inspect}" unless format == :discourse
 
       parse =
@@ -228,7 +263,7 @@ module Markbridge
           raise ArgumentError, "expected Parse or AST::Node, got #{parse_or_ast.class}"
         end
 
-      build_conversion(parse, renderer:, raise_on_error:)
+      build_conversion(parse, renderer:, raise_on_error:, normalize:)
     end
 
     # Build a configured Discourse {Renderers::Discourse::Renderer}
@@ -297,13 +332,28 @@ module Markbridge
       }
     end
 
-    def build_conversion(parse, renderer:, raise_on_error:)
+    def build_conversion(parse, renderer:, raise_on_error:, normalize:)
+      parse = apply_normalization(parse, normalize)
       renderer ||= Renderers::Discourse::Renderer.new
       markdown, errors = render_through(renderer, parse.ast, raise_on_error:)
 
       Conversion.new(parsed: parse, markdown:, errors:)
     end
 
+    # Normalize +parse.ast+ in place (target-format nesting rules) and fold
+    # any report into +diagnostics[:normalization]+. Returns the +parse+ to
+    # render — a new one carrying the report when something changed, else
+    # the original unchanged.
+    def apply_normalization(parse, normalize)
+      return parse unless normalize
+
+      normalizer = normalize.is_a?(Normalizer) ? normalize : Normalizer.shared_default
+      report = normalizer.normalize(parse.ast)
+      return parse if report.empty?
+
+      parse.with(diagnostics: parse.diagnostics.merge(normalization: report))
+    end
+
     def build_escaper(escape:, escape_hard_line_breaks:, allow:)
       if escape == false
         if escape_hard_line_breaks || allow

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markbridge
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - Discourse Team
@@ -58,6 +58,11 @@ files:
 - lib/markbridge/gem_loader.rb
 - lib/markbridge/html.rb
 - lib/markbridge/mediawiki.rb
+- lib/markbridge/normalizer.rb
+- lib/markbridge/normalizer/report.rb
+- lib/markbridge/normalizer/rule_set.rb
+- lib/markbridge/normalizer/text_projection.rb
+- lib/markbridge/normalizer/walker.rb
 - lib/markbridge/parse.rb
 - lib/markbridge/parsers/bbcode.rb
 - lib/markbridge/parsers/bbcode/closing_strategies/base.rb