markbridge 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbebafc60a3665c98544f3cfd9496c3c5cdc2c0940339c998791b2df1f04aa44
-  data.tar.gz: 2be35c042f803e37302fa149af772897326241488a9429a525ddc714af0623d1
+  metadata.gz: e077560817f865c035c136edffd868cbabb934b6a8986614c5e1c48139b05b9b
+  data.tar.gz: 6511b321b0245010d0df81cea6e5b19950de430753a34aea54f4c99c2fa10fc9
 SHA512:
-  metadata.gz: 6b3e3dc46705d4f7cf52aabaac8b272cbc9241e57473caf11a6c53b1d1355ec2e7874ae485732ba526f67445144f12daccc521dae40a6405994e409a34e00ede
-  data.tar.gz: 89385e8ec7942af10b79b267e6400bfb209af7871775e0891f86153e792e3ef61b15b08eb025f9a6f6d5673c3aaf9bcbb6ec26200ac3a62440b426121fcba1fa
+  metadata.gz: 7e807c4b7fc8eae29bbcfea9fa6c855f2b627caf2403965e5e0e4d1792a39612e74db2a37e85be72e60f2b3a9e200a70cedf695ed57256e27c03b2569bc9ba26
+  data.tar.gz: 77f38f9577c366005a6b06c25a6287b3631d8d2f4dbcfe54043a0c882587600f95c94f10e4110356573f72a1041e6e7ab0b05fc40bbf9d353258ee7a5dc1fc24

data/lib/markbridge/ast/element.rb

@@ -105,6 +105,34 @@ module Markbridge
         @children[index] = new_child
         self
       end
+
+      # Replace this element's entire child list in one shot.
+      #
+      # A plain validated setter for tree-rewriting passes (e.g. the
+      # {Markbridge::Normalizer}) that rebuild an element's children out
+      # of band and need to commit the result without re-running the
+      # per-append logic of {#<<}. Every entry must be a {Node}.
+      #
+      # NOTE: unlike {#<<}, this does *not* merge adjacent {Text} nodes —
+      # the auto-merge invariant is a property of {#<<} only. Callers that
+      # build the array themselves own that coalescing (the Normalizer's
+      # walker merges adjacent text as it assembles the list, so it never
+      # hands a state {#<<} would not have produced).
+      #
+      # @param new_children [Array<Node>] the replacement children
+      # @return [Element] +self+
+      # @raise [TypeError] when any entry is not a {Node}
+      def replace_children(new_children)
+        new_children.each do |child|
+          next if child.is_a?(Node)
+
+          actual = child.nil? ? "nil" : child.class
+          raise TypeError, "replace_children on #{self.class} expected #{Node}s, got #{actual}"
+        end
+
+        @children = new_children
+        self
+      end
     end
   end
 end

data/lib/markbridge/normalizer/report.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Markbridge
+  class Normalizer
+    # Tally of the transformations a single {Normalizer#normalize} pass
+    # applied. Held as a local per call (never on the Normalizer), so a
+    # frozen shared instance stays reusable and thread-safe.
+    class Report
+      def initialize
+        @counts = Hash.new(0)
+      end
+
+      # @param parent_class [Class] the offending ancestor's class
+      # @param child_class [Class] the moved/removed node's class
+      # @param strategy [Symbol] the strategy actually applied
+      def record(parent_class, child_class, strategy)
+        @counts[[demodulize(parent_class), demodulize(child_class), strategy]] += 1
+      end
+
+      # @return [Boolean]
+      def empty?
+        @counts.empty?
+      end
+
+      # One +{parent:, child:, strategy:, count:}+ row per distinct
+      # transformation, e.g.
+      # +{parent: "Url", child: "Image", strategy: :hoist_after, count: 3}+.
+      #
+      # @return [Array<Hash>]
+      def to_a
+        @counts.map { |(parent, child, strategy), count| { parent:, child:, strategy:, count: } }
+      end
+
+      private
+
+      def demodulize(klass)
+        klass.name.split("::").last
+      end
+    end
+  end
+end

data/lib/markbridge/normalizer/rule_set.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Markbridge
+  class Normalizer
+    # Maps a node and its ancestor stack to a strategy.
+    #
+    # Matching is exact-class (equivalent to +instance_of?+): rules are
+    # keyed by +Class+ and looked up via +node.class+, so an anonymous
+    # +Class.new(AST::Element)+ or any future subclass never accidentally
+    # matches a rule written for the base class. Registering a rule for a
+    # +(parent, child)+ pair that already has one replaces it, so later
+    # layers (Discourse, a consumer's +#rule+) override earlier ones.
+    class RuleSet
+      NO_MATCH = [nil, nil].freeze
+
+      def initialize
+        @by_parent = {} # parent_class => { child_class => strategy }
+        @child_classes = Set.new
+      end
+
+      # Register (or replace) a rule.
+      #
+      # @param parent [Class] ancestor AST class
+      # @param child [Class] contained AST class
+      # @param strategy [Symbol, #call] a strategy symbol or callable
+      # @return [self]
+      def add(parent:, child:, strategy:)
+        validate_strategy!(strategy)
+        (@by_parent[parent] ||= {})[child] = strategy
+        @child_classes << child
+        self
+      end
+
+      # Resolve the strategy for +child+ given its ancestor stack (root
+      # first). Returns +[strategy, boundary]+ where +boundary+ is the
+      # *outermost* ancestor whose class has a rule for +child+'s class, or
+      # {NO_MATCH} (+[nil, nil]+) when nothing matches.
+      #
+      # @param child [AST::Node]
+      # @param ancestors [Array<AST::Element>] root-first ancestor stack
+      # @return [Array(Object, AST::Element), Array(nil, nil)]
+      def resolve(child, ancestors)
+        child_class = child.class
+        # Skip the ancestor scan for a class no rule targets (most nodes, for
+        # example plain text). The scan below returns the same result for such
+        # a class, so this only saves work.
+        return NO_MATCH unless @child_classes.include?(child_class)
+
+        scan_ancestors(child_class, ancestors)
+      end
+
+      # Freeze so a shared instance raises if something tries to change it.
+      # Freezing +@by_parent+ and its inner hashes is enough: {#add} writes
+      # there before it touches +@child_classes+, so a frozen instance raises
+      # on the +@by_parent+ write first. +@child_classes+ is never reached, so
+      # it does not need freezing.
+      def freeze
+        @by_parent.each_value(&:freeze)
+        @by_parent.freeze
+        super
+      end
+
+      private
+
+      # The ancestor scan behind {#resolve}: the outermost matching ancestor
+      # wins. It is split from the skip check in {#resolve} so the scan can be
+      # tested on its own.
+      def scan_ancestors(child_class, ancestors)
+        ancestors.each do |ancestor|
+          strategies = @by_parent[ancestor.class]
+          next unless strategies
+
+          strategy = strategies[child_class]
+          return strategy, ancestor if strategy
+        end
+        NO_MATCH
+      end
+
+      def validate_strategy!(strategy)
+        return if strategy.respond_to?(:call)
+        return if STRATEGIES.include?(strategy)
+
+        raise ArgumentError,
+              "unknown strategy #{strategy.inspect} " \
+                "(expected one of #{STRATEGIES.inspect} or a callable)"
+      end
+    end
+  end
+end

data/lib/markbridge/normalizer/text_projection.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Markbridge
+  class Normalizer
+    # Best-effort plain-text projection of a subtree, used by the
+    # +:textify+ strategy. Concatenates text content; renders a {AST::Mention}
+    # as its literal +@name+, and opaque leaf nodes as their alt/raw text
+    # when they carry one, otherwise the empty string.
+    module TextProjection
+      class << self
+        # @param node [AST::Node]
+        # @return [String]
+        def call(node)
+          case node
+          when AST::Text, AST::MarkdownText
+            node.text
+          when AST::Mention
+            "@#{node.name}"
+          when AST::Element
+            node.children.map { |child| call(child) }.join
+          else
+            leaf_text(node)
+          end
+        end
+
+        # @param node [AST::Node] an opaque leaf (Upload, Attachment, …)
+        # @return [String]
+        def leaf_text(node)
+          return node.alt if node.respond_to?(:alt) && node.alt
+          return node.raw if node.respond_to?(:raw) && node.raw
+
+          ""
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/normalizer/walker.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module Markbridge
+  class Normalizer
+    # The parent-aware tree-rewriting engine. One {Walker} is built per
+    # {Normalizer#normalize} call (holding that call's {RuleSet} and
+    # {Report}; no state is kept on the Normalizer). It changes the tree
+    # in place via {AST::Element#replace_children}, touching only elements
+    # whose children actually changed.
+    #
+    # The main rule is resolve-before-descend: a child's strategy is resolved
+    # against its current ancestor stack first, and a moved subtree (hoist or
+    # unwrap) is then walked against the ancestor stack it will have in its
+    # new place. So a node that leaves a link does not see the link while its
+    # own inside is normalized. That keeps a legally nested quote-in-quote or
+    # image-in-quote intact, and it means a second normalize reports nothing.
+    #
+    # Hoisting: a node taken out of an inline container is moved up, tagged
+    # with its boundary (the outermost matching ancestor, compared by
+    # identity), and placed right after that boundary, at the boundary's
+    # parent. A wrapper left empty by a hoist or drop is removed (see
+    # {PRUNE_WHEN_EMPTY}), so no empty +**+ +**+ markers stay.
+    #
+    # For speed, the ancestor stack is one shared array that is pushed and
+    # popped, and an element's children list is copied only when a child
+    # first changes (copy-on-write). A subtree with no violations allocates
+    # nothing and is left as it was, so the pass can run by default.
+    class Walker
+      EMPTY = [].freeze
+
+      # Wrappers that mean nothing once they are empty, so an empty one is
+      # removed instead of kept. +AST::Url+ is not here on purpose: an empty
+      # link still renders as a bare URL, so a hoist that empties a link keeps
+      # the link.
+      PRUNE_WHEN_EMPTY = [
+        AST::Bold,
+        AST::Italic,
+        AST::Underline,
+        AST::Strikethrough,
+        AST::Superscript,
+        AST::Subscript,
+        AST::Color,
+        AST::Size,
+        AST::Align,
+        AST::Email,
+      ].freeze
+
+      # @param rule_set [RuleSet]
+      # @param report [Report]
+      def initialize(rule_set, report)
+        @rules = rule_set
+        @report = report
+      end
+
+      # Normalize +document+'s subtree in place.
+      # @param document [AST::Document]
+      def call(document)
+        _element, bubble = normalize_element(document, [])
+        # Defensive: anything that never reached its boundary becomes a
+        # trailing sibling rather than being lost. Well-formed rule tables
+        # do not get here.
+        bubble.each { |node, _boundary| document << node }
+      end
+
+      private
+
+      # Copy-on-write check: a kept child that came back as the same object
+      # (so normalizing it changed nothing) with no bubble, while nothing
+      # earlier changed, needs no rebuilt +out+. This only saves work. If it
+      # is wrong, the code still rebuilds the same child list, so its
+      # mutations do not change the output.
+      def unchanged?(out, normalized, child, child_bubble)
+        out.nil? && normalized.equal?(child) && child_bubble.empty?
+      end
+
+      # Normalize a node's descendants. Elements recurse; leaves are
+      # returned untouched. Returns +[node_or_nil, bubble]+ — +nil+ when the
+      # element was pruned, and +bubble+ is the list of +[node, boundary]+
+      # pairs to hoist above this node.
+      def normalize_node(node, stack)
+        return node, EMPTY unless node.is_a?(AST::Element)
+
+        normalize_element(node, stack)
+      end
+
+      # +stack+ is a shared, mutable ancestor stack (root first): +element+
+      # is pushed for the duration of its children's processing and popped
+      # after. +out+ (the rebuilt child list) and +bubble+ stay +nil+ until
+      # a child actually changes, so the clean path allocates nothing.
+      def normalize_element(element, stack)
+        stack.push(element)
+        children = element.children
+        out = nil
+        bubble = nil
+
+        children.each_with_index do |child, index|
+          strategy, boundary = @rules.resolve(child, stack)
+          strategy = strategy.call(boundary, child) if strategy.respond_to?(:call)
+
+          if strategy.nil? || strategy == :keep
+            normalized, child_bubble = normalize_node(child, stack)
+            next if unchanged?(out, normalized, child, child_bubble)
+
+            out ||= children[0, index]
+            bubble = append_kept(normalized, child_bubble, child, out, bubble)
+          else
+            out ||= children[0, index]
+            bubble = emit(child, strategy, boundary, stack, out, bubble)
+          end
+        end
+
+        stack.pop
+        element.replace_children(coalesce(out)) if out
+
+        raised = bubble || EMPTY
+        return nil, raised if prune?(element, out, children)
+
+        [element, raised]
+      end
+
+      # An element is removed when it ends up with no children and is one of
+      # the wrappers in {PRUNE_WHEN_EMPTY}.
+      def prune?(element, out, children)
+        empty = out ? out.empty? : children.empty?
+        empty && PRUNE_WHEN_EMPTY.include?(element.class)
+      end
+
+      # Resolve one child (against +stack+) and place it into an existing
+      # +out+ — the shared entry point used by {#emit}'s +:unwrap+ recursion,
+      # where +out+ already exists.
+      def resolve_into(child, stack, out, bubble)
+        strategy, boundary = @rules.resolve(child, stack)
+        strategy = strategy.call(boundary, child) if strategy.respond_to?(:call)
+
+        if strategy.nil? || strategy == :keep
+          child2, child_bubble = normalize_node(child, stack)
+          append_kept(child2, child_bubble, child, out, bubble)
+        else
+          emit(child, strategy, boundary, stack, out, bubble)
+        end
+      end
+
+      # Append a kept child that is already normalized, then place any of its
+      # bubbles whose boundary is this child. ({#land} does nothing when
+      # +child_bubble+ is empty, so there is no separate check for that.)
+      def append_kept(normalized, child_bubble, child, out, bubble)
+        out << normalized unless normalized.nil?
+        land(child_bubble, child, out, bubble)
+      end
+
+      # Apply a non-keep strategy for +child+, appending to +out+ and
+      # returning the (possibly newly allocated) +bubble+.
+      def emit(child, strategy, boundary, stack, out, bubble)
+        case strategy
+        when :hoist_after
+          hoist(child, boundary, stack, bubble)
+        when :unwrap
+          unwrap(child, boundary, stack, out, bubble)
+        when :textify
+          @report.record(boundary.class, child.class, :textify)
+          out << AST::Text.new(TextProjection.call(child))
+          bubble
+        when :drop
+          @report.record(boundary.class, child.class, :drop)
+          bubble
+        when Array
+          # A callable returned replacement nodes to splice in place.
+          @report.record(boundary.class, child.class, :replace)
+          strategy.each { |node| out << node }
+          bubble
+        else
+          raise ArgumentError, "strategy resolved to #{strategy.inspect}"
+        end
+      end
+
+      def hoist(child, boundary, stack, bubble)
+        @report.record(boundary.class, child.class, :hoist_after)
+        # Walk the relocated subtree against its destination stack (the
+        # ancestors strictly above the boundary) so its interior never sees
+        # the boundary it is leaving.
+        child2, child_bubble = normalize_node(child, ancestors_above(boundary, stack))
+        bubble ||= []
+        bubble << [child2, boundary] unless child2.nil?
+        # For the built-in tables a hoisted subtree yields no escaping
+        # bubbles; carry any (from a custom rule) up as a best effort.
+        child_bubble.each { |entry| bubble << entry }
+        bubble
+      end
+
+      def unwrap(child, boundary, stack, out, bubble)
+        # Unwrap means "promote the element's children"; a leaf has none. A
+        # rule that targets one is a misconfiguration, so keep the node in
+        # place rather than silently dropping it (and don't report a no-op).
+        unless child.is_a?(AST::Element)
+          out << child
+          return bubble
+        end
+
+        @report.record(boundary.class, child.class, :unwrap)
+        # Unwrap: run the child's children through the current +out+, resolved
+        # against the current stack. Resolving them again in the same pass is
+        # what fixes deeply nested links in one go.
+        child.children.each { |grandchild| bubble = resolve_into(grandchild, stack, out, bubble) }
+        bubble
+      end
+
+      # Land inbound bubbles whose boundary is +child+ (this level is the
+      # boundary's parent), each after the previous to preserve order;
+      # propagate the rest upward.
+      def land(child_bubble, child, out, bubble)
+        child_bubble.each do |node, boundary|
+          if boundary.equal?(child)
+            out << node
+          else
+            bubble ||= []
+            bubble << [node, boundary]
+          end
+        end
+        bubble
+      end
+
+      # Ancestors strictly above +boundary+ in +stack+ — the stack the
+      # hoisted node inherits (its parent becomes the boundary's parent).
+      def ancestors_above(boundary, stack)
+        index = stack.index { |ancestor| ancestor.equal?(boundary) }
+        stack.first(index)
+      end
+
+      # Coalesce adjacent text (textify can create neighbours that +#<<+
+      # would have merged) just before committing a changed child list.
+      def coalesce(nodes)
+        nodes.each_with_object([]) do |node, acc|
+          last = acc.last
+          # mergeable? is false when +last+ is nil (the first node), so no
+          # separate nil-guard is needed.
+          if mergeable?(last, node)
+            last.merge(node)
+          else
+            acc << node
+          end
+        end
+      end
+
+      def mergeable?(left, right)
+        (left.instance_of?(AST::Text) && right.instance_of?(AST::Text)) ||
+          (left.instance_of?(AST::MarkdownText) && right.instance_of?(AST::MarkdownText))
+      end
+    end
+  end
+end

data/lib/markbridge/normalizer.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative "normalizer/rule_set"
+require_relative "normalizer/report"
+require_relative "normalizer/text_projection"
+require_relative "normalizer/walker"
+
+module Markbridge
+  # Rewrites an AST so the renderer only gets markup the target format can
+  # express. It runs once, between parse and render. The default rules are
+  # CommonMark legality: no link inside a link, no block element inside an
+  # inline container, and an inline-only code span. Each match resolves to a
+  # strategy (+:keep+, +:hoist_after+, +:unwrap+, +:textify+, +:drop+, or a
+  # callable) that the {Walker} applies.
+  #
+  # Discourse-specific policy (for example, moving an image out of a link) is
+  # not built in. A consumer adds those with {#rule}.
+  #
+  # @example The default, reused across conversions
+  #   Markbridge::Normalizer.shared_default
+  #
+  # @example A customized normalizer
+  #   n = Markbridge::Normalizer.default
+  #   n.rule(parent: AST::Url, child: AST::Image, strategy: :hoist_after)
+  #   Markbridge.convert(input, format: :bbcode, normalize: n)
+  #
+  # @example List what would change, without changing it
+  #   Markbridge::Normalizer.default.violations(ast) # => [...]
+  class Normalizer
+    # The strategy symbols a rule may resolve to.
+    STRATEGIES = %i[keep hoist_after unwrap textify drop].freeze
+
+    EMPTY_STACK = [].freeze
+    private_constant :EMPTY_STACK
+
+    # Containers that hold inline content only: a link's text (CommonMark
+    # §6.3), and emphasis and heading content.
+    INLINE_CONTAINERS = [
+      AST::Url,
+      AST::Bold,
+      AST::Italic,
+      AST::Strikethrough,
+      AST::Underline,
+      AST::Superscript,
+      AST::Subscript,
+      AST::Heading,
+    ].freeze
+
+    # AST nodes the Discourse renderer prints as block-level Markdown (their
+    # output has blank lines around it). One inside an inline container breaks
+    # that container, so it is moved out. Spoiler and single-line Code stay
+    # inline and are not listed (Code is handled by {KEEP_INLINE_CODE}).
+    BLOCK_NODES = [
+      AST::Quote,
+      AST::Heading,
+      AST::List,
+      AST::ListItem,
+      AST::Table,
+      AST::TableRow,
+      AST::TableCell,
+      AST::Details,
+      AST::Paragraph,
+      AST::HorizontalRule,
+      AST::Align,
+      AST::Poll,
+      AST::Event,
+    ].freeze
+
+    # A code span may stay inside an inline container while it is on one line.
+    # A fenced or multi-line block is moved out. This matches
+    # +RenderingInterface#block_context?+: Code prints as a fenced block when a
+    # Text child has a newline (the language alone does not make it a block).
+    KEEP_INLINE_CODE =
+      lambda do |_boundary, node|
+        block = node.children.any? { |c| c.instance_of?(AST::Text) && c.text.include?("\n") }
+        block ? :hoist_after : :keep
+      end
+
+    class << self
+      # A fresh, customizable normalizer with the default rules. Add more with
+      # {#rule}.
+      # @return [Normalizer]
+      def default
+        new(build_rules)
+      end
+
+      # The default normalizer, built once and frozen, reused across
+      # conversions. +#normalize+ and +#violations+ keep no state on the
+      # instance, so one frozen instance is safe to reuse, also across threads.
+      # @return [Normalizer] the same frozen instance on every call
+      def shared_default
+        @shared_default ||= default.freeze
+      end
+
+      private
+
+      def build_rules
+        rules = RuleSet.new
+
+        # §6.3 A link may not contain another link, at any depth. Unwrap the
+        # inner link and keep its text.
+        rules.add(parent: AST::Url, child: AST::Url, strategy: :unwrap)
+
+        INLINE_CONTAINERS.each do |container|
+          rules.add(parent: container, child: AST::Code, strategy: KEEP_INLINE_CODE)
+
+          BLOCK_NODES.each do |block|
+            next if container == block
+
+            rules.add(parent: container, child: block, strategy: :hoist_after)
+          end
+        end
+
+        rules
+      end
+    end
+
+    # @param rule_set [RuleSet]
+    def initialize(rule_set)
+      @rules = rule_set
+    end
+
+    # Add or override a rule. Chainable. A rule for a +(parent, child)+ pair
+    # that already exists is replaced. Raises on a frozen ({shared_default})
+    # instance; build a fresh one with {.default}.
+    #
+    # @param parent [Class] ancestor AST class
+    # @param child [Class] contained AST class
+    # @param strategy [Symbol, #call] one of {STRATEGIES} or a callable
+    # @return [self]
+    def rule(parent:, child:, strategy:)
+      @rules.add(parent:, child:, strategy:)
+      self
+    end
+
+    # Rewrite +ast+ in place so it satisfies the rules.
+    #
+    # @param ast [AST::Document, AST::Element]
+    # @return [Array<Hash>] a report of what changed (empty when nothing did),
+    #   one +{parent:, child:, strategy:, count:}+ row per distinct change.
+    def normalize(ast)
+      report = Report.new
+      Walker.new(@rules, report).call(ast)
+      report.to_a
+    end
+
+    # List the violations in +ast+ without changing it.
+    #
+    # @param ast [AST::Document, AST::Element]
+    # @return [Array<Hash>] +{parent:, child:, strategy:}+ per occurrence
+    def violations(ast)
+      found = []
+      collect_violations(ast, EMPTY_STACK, found)
+      found
+    end
+
+    def freeze
+      @rules.freeze
+      super
+    end
+
+    private
+
+    def collect_violations(element, ancestors, found)
+      stack = ancestors + [element]
+      element.children.each do |child|
+        strategy, boundary = @rules.resolve(child, stack)
+        strategy = strategy.call(boundary, child) if strategy.respond_to?(:call)
+        unless strategy.nil? || strategy == :keep
+          found << { parent: demodulize(boundary.class), child: demodulize(child.class), strategy: }
+        end
+        collect_violations(child, stack, found) if child.is_a?(AST::Element)
+      end
+    end
+
+    def demodulize(klass)
+      klass.name.split("::").last
+    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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Markbridge
-  VERSION = "0.3.0"
+  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.3.0
+  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