Skip to content

A platform for community discussion. Free, open, simple.

MT: Add the Markbridge-based MarkdownRenderer

Gerhard Schlager90284c50ea4c
diff --git a/Gemfile.lock b/Gemfile.lock
index f29f9722096..a4e2e8af47f 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -5,6 +5,7 @@ PATH
activesupport
colored2
i18n
+ markbridge (>= 0.3.1)
migrations-core
pg
zeitwerk
@@ -349,6 +350,7 @@ GEM
net-imap
net-pop
net-smtp
+ markbridge (0.3.1)
matrix (0.4.3)
maxminddb (0.1.22)
memory_profiler (1.1.0)
@@ -1123,6 +1125,7 @@ CHECKSUMS
lru_redux (1.1.0) sha256=ee71d0ccab164c51de146c27b480a68b3631d5b4297b8ffe8eda1c72de87affb
lz4-ruby (0.3.3) sha256=011be5ee230cfddc8308d4e2e0b05300c7bc755a887de799377ca6c5b6aede89
mail (2.9.0) sha256=6fa6673ecd71c60c2d996260f9ee3dd387d4673b8169b502134659ece6d34941
+ markbridge (0.3.1) sha256=a36dff4e79e666fe7f944d4a806f507212191b80d22878ab3ee9008d9df975a3
matrix (0.4.3) sha256=a0d5ab7ddcc1973ff690ab361b67f359acbb16958d1dc072b8b956a286564c5b
maxminddb (0.1.22) sha256=50933be438fbed9dceabef4163eab41884bd8830d171fdb8f739bee769c4907e
memory_profiler (1.1.0) sha256=79a17df7980a140c83c469785905409d3027ca614c42c086089d128b805aa8f8
diff --git a/migrations/converters/lib/migrations/converters/markdown_renderer.rb b/migrations/converters/lib/migrations/converters/markdown_renderer.rb
new file mode 100644
index 00000000000..c3f4a3b56e9
--- /dev/null
+++ b/migrations/converters/lib/migrations/converters/markdown_renderer.rb
@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "markbridge"
+
+module Migrations
+ module Converters
+ # Convert-time wrapper over the Markbridge gem: renders a source forum's post
+ # markup (BBCode, HTML, MediaWiki, TextFormatter XML) into Discourse Markdown,
+ # optionally deferring the embeds that cannot be finalized until import time.
+ #
+ # When an embed collector (an {EmbedBuffer}, or anything that responds to
+ # the embed callbacks) is given at construction via `embeds:`, the configured
+ # embed node types are not rendered inline: each is recorded on the collector
+ # and replaced in the output by a placeholder token (see
+ # {Migrations::Placeholder}). Everything else renders natively. With no
+ # collector, it just renders the source to Markdown.
+ #
+ # Markbridge does not parse Markdown, so a Discourse -> Discourse migration
+ # (whose `raw` is already Markdown) does not use this; this renderer is for
+ # forums whose post bodies are in one of the formats above.
+ #
+ # Not thread-safe: the held Markbridge renderer keeps per-render state, so
+ # an instance must not convert in two threads at once.
+ #
+ # @example deferring uploads and quotes into an EmbedBuffer
+ # buffer = EmbedBuffer.new(owner_type: Enums::EmbedOwner::POST)
+ # renderer = MarkdownRenderer.new(format: :bbcode, embeds: buffer)
+ # raw = renderer.to_markdown(item[:body])
+ # # `raw` now carries placeholder tokens; `buffer.uploads` / `buffer.quotes`
+ # # hold the typed linkage descriptors.
+ class MarkdownRenderer
+ class UnknownFormat < StandardError
+ end
+
+ # The `require` path for each supported source format. HTML / MediaWiki /
+ # TextFormatter additionally need nokogiri (provided by the host
+ # application); BBCode has no extra dependency.
+ FORMATS = {
+ bbcode: "markbridge/bbcode",
+ html: "markbridge/html",
+ mediawiki: "markbridge/mediawiki",
+ text_formatter_xml: "markbridge/textformatter",
+ }.freeze
+
+ # Embeds deferred unless the caller narrows or extends the set. These three
+ # can't be finalized at convert time: an upload must first exist on the
+ # destination, an attributed quote references a source post the import
+ # renumbers, and a mention names a user a merge may rename — they can only be
+ # resolved at import time, using the import maps.
+ #
+ # `:link` is excluded by default because this generic handler records only
+ # `url` and `text`; telling an internal link from an external one takes
+ # source-specific URL parsing. With a plain EmbedBuffer, deferring links just
+ # round-trips every link through the database unchanged. A converter that
+ # wants internal links rewritten opts in with `defer:` and supplies a
+ # collector whose `link` callback classifies the URL and records the target
+ # fields.
+ DEFAULT_DEFER = %i[upload quote mention].freeze
+
+ # Markbridge types a mention as `:user` or `:group`; map that to the
+ # `MentionType` enum stored on `embed_mentions`. Markbridge has no
+ # `here`/`all` mention types, so they never show up here.
+ MENTION_TYPES = {
+ user: Migrations::Database::IntermediateDB::Enums::MentionType::USER,
+ group: Migrations::Database::IntermediateDB::Enums::MentionType::GROUP,
+ }.freeze
+ private_constant :MENTION_TYPES
+
+ # @param format [Symbol] one of {FORMATS}.
+ # @param embeds [#upload, #quote, #mention, #link, nil] the embed collector;
+ # when nil the embeds render natively.
+ # @param defer [Array<Symbol>] which embed kinds to defer (default
+ # {DEFAULT_DEFER}). Ignored when `embeds` is nil.
+ def initialize(format: :bbcode, embeds: nil, defer: DEFAULT_DEFER)
+ @format = format.to_sym
+ raise UnknownFormat, "Unknown source format: #{format}" unless FORMATS.key?(@format)
+
+ require FORMATS.fetch(@format)
+
+ @embeds = embeds
+ @renderer = embeds ? build_deferring_renderer(defer) : nil
+ end
+
+ # Markbridge's default rules cover CommonMark legality only: they unwrap a
+ # link nested in a link and hoist block or multi-line-code content out of
+ # an inline container. A linked image is legal CommonMark and Discourse
+ # cooks it fine (the anchor simply wraps the image), so an image stays
+ # inside its link — the defaults leave it alone and we add nothing for it.
+ #
+ # Our one rule turns a mention inside a link label into plain text.
+ # Discourse doesn't cook mentions inside links, so nothing is lost — and as
+ # text the label stays deferrable, so the link keeps its import-time
+ # rewrite instead of falling back to native rendering. Trade-off: the
+ # mention becomes frozen source text instead of being remapped through the
+ # user map — acceptable, because Discourse would only render it as plain
+ # label text inside a link anyway.
+ #
+ # Built once; safe to share, the frozen normalizer keeps no per-run state.
+ def self.normalizer
+ @normalizer ||=
+ Markbridge::Normalizer
+ .default
+ .rule(parent: Markbridge::AST::Url, child: Markbridge::AST::Mention, strategy: :textify)
+ .freeze
+ end
+
+ # @param source [String] the source post body.
+ # @return [String] Discourse Markdown.
+ def to_markdown(source)
+ Markbridge
+ .convert(
+ source,
+ format: @format,
+ renderer: @renderer,
+ normalize: self.class.normalizer,
+ ) { |ast| unwrap_self_links(ast) }
+ .markdown
+ end
+
+ # Maps each deferrable embed kind to the Markbridge AST node class it
+ # overrides and the method that records it on the collector. Each method
+ # returns the placeholder token, which Markbridge then emits as the
+ # node's rendered output.
+ def embed_handlers
+ {
+ upload: [Markbridge::AST::Upload, method(:defer_upload)],
+ quote: [Markbridge::AST::Quote, method(:defer_quote)],
+ mention: [Markbridge::AST::Mention, method(:defer_mention)],
+ link: [Markbridge::AST::Url, method(:defer_link)],
+ }
+ end
+
+ private
+
+ def defer_upload(node, _interface)
+ @embeds.upload(upload_id: node.sha1)
+ end
+
+ def defer_quote(node, interface)
+ # Only the attribution carries the foreign post/topic/user reference that
+ # needs remapping; the quoted body renders normally and the closing tag
+ # stays in place. A quote attributed only by a display name (`author`) has
+ # nothing to remap, so it renders natively and keeps that attribution as
+ # written. The token stands in for the opening `[quote="…"]`, which
+ # PlaceholderResolver#render_quote rebuilds.
+ return interface.render_default(node) unless attributed?(node)
+
+ token =
+ @embeds.quote(
+ quoted_post_id: storable_id(node.post_id),
+ quoted_topic_id: storable_id(node.topic_id),
+ quoted_post_number: storable_id(node.post_number),
+ quoted_user_id: storable_id(node.user_id),
+ quoted_username: node.username,
+ # The BBCode parser copies the leading token into both author and
+ # username, so recording that as a name too would just repeat the
+ # username. Keep the name only when it is distinct.
+ quoted_name: (node.author unless node.author == node.username),
+ )
+ content = interface.render_children(node, context: interface.with_parent(node))
+ "\n\n#{token}\n#{content}\n[/quote]\n\n"
+ end
+
+ def defer_mention(node, _interface)
+ @embeds.mention(mention_type: MENTION_TYPES[node.type], name: node.name)
+ end
+
+ def defer_link(node, interface)
+ # After normalization the only deferrable embed a label can still hold is
+ # an upload or attachment — a linked image, which is legal and Discourse
+ # cooks fine. What is left to decide is deferral. Only a label of plain
+ # text or simple inline formatting may be recorded into the `text` column.
+ # If the label contained a deferrable embed, its placeholder would be
+ # recorded into the `text` column — but the importer only substitutes
+ # placeholders in the raw, so that embed would never be resolved and would
+ # be reported as an orphan. Such a link renders natively instead; the
+ # nested embed then tokenizes into the raw, where the importer resolves it.
+ return interface.render_default(node) unless deferrable_children?(node)
+
+ # A bare URL records no text, so the importer re-emits it bare and
+ # autolinking/oneboxing keep working; `presence` catches a blank label the
+ # same way (`[](url)` shows nothing).
+ text = node.bare? ? nil : interface.render_children(node).presence
+ @embeds.link(url: node.href, text:)
+ end
+
+ # Whether the quote carries a source post/topic/user reference that needs
+ # remapping. A quote attributed only by a display name has none.
+ def attributed?(node)
+ node.post_number || node.topic_id || node.post_id || node.user_id || node.username
+ end
+
+ # Markbridge attribution numbers are unbounded Integers, but the
+ # IntermediateDB stores ids as SQLite signed 64-bit integers (binding a
+ # bignum raises). At most 18 digits fit. A longer number is a numeric post
+ # title or junk, not a real id — drop it and let the remaining attribution
+ # carry the quote. The Discourse MarkdownScanner quote detector applies the
+ # same 18-digit bound (see markdown_scanner/detectors/quote.rb).
+ def storable_id(value)
+ value if value && value < 10**18
+ end
+
+ # Whether a link label contains only plain text and the inline formatting
+ # Discourse allows inside `[…](url)`. This is the single policy point for
+ # what a *deferred* link may carry. Extend the formatting list carefully: a
+ # kind qualifies only if it renders inline (no blank lines) and is not
+ # deferrable itself. Called on the link node and recursively on formatting
+ # nodes, so it checks a parent's children either way.
+ def deferrable_children?(node)
+ node.children.all? { |child| deferrable_label_node?(child) }
+ end
+
+ def deferrable_label_node?(node)
+ case node
+ when Markbridge::AST::Text, Markbridge::AST::MarkdownText
+ true
+ when Markbridge::AST::Code
+ # The normalizer already hoisted any multi-line code out of inline
+ # containers, so a Code still sitting in a label renders inline (a
+ # backtick span) whether or not it carries a language — a language
+ # alone never makes it a block. Safe to record.
+ true
+ when Markbridge::AST::Bold, Markbridge::AST::Italic, Markbridge::AST::Strikethrough
+ deferrable_children?(node)
+ else
+ false
+ end
+ end
+
+ # An image linked to its own source URL — the thumbnail-links-to-itself
+ # pattern — is just noise: the anchor points where the image already
+ # lives. Drop the link so the bare image gets Discourse's lightbox on
+ # import. This runs in markbridge's parse-time yield hook, before
+ # normalization, so the freed image is normalized like any other node.
+ def unwrap_self_links(element)
+ element.children.dup.each do |child|
+ unwrap_self_links(child) if child.is_a?(Markbridge::AST::Element)
+
+ image = self_link_image(child)
+ element.replace_child(child, image) if image
+ end
+ end
+
+ # The lone Image a self-link wraps, or nil when `node` is not a self-link:
+ # a Url whose only non-whitespace child is an Image whose `src` is exactly
+ # the link's href. Only Image carries a source URL to compare — Upload and
+ # Attachment reference their target by sha1/id, not a URL, so they never
+ # match here.
+ def self_link_image(node)
+ return unless node.is_a?(Markbridge::AST::Url)
+
+ content = node.children.reject { |child| whitespace_text?(child) }
+ return unless content.size == 1
+
+ image = content.first
+ image if image.is_a?(Markbridge::AST::Image) && image.src == node.href
+ end
+
+ def whitespace_text?(node)
+ node.instance_of?(Markbridge::AST::Text) && node.text.strip.empty?
+ end
+
+ # Called once, at construction: building the tag library and Markbridge's
+ # Discourse renderer costs about as much as converting a small post, so a
+ # per-post build would roughly double the hot path (the collector serves a
+ # worker's whole run anyway — EmbedBuffer#clear resets it between posts).
+ def build_deferring_renderer(defer)
+ tags =
+ Array(defer).to_h do |kind|
+ node_class, handler =
+ embed_handlers.fetch(kind) do
+ raise ArgumentError,
+ "Unknown defer kind #{kind.inspect}; expected one of #{embed_handlers.keys.join(", ")}"
+ end
+ [node_class, Markbridge::Renderers::Discourse::Tag.new(&handler)]
+ end
+
+ Markbridge.discourse_renderer(tags:)
+ end
+ end
+ end
+end
diff --git a/migrations/converters/migrations-converters.gemspec b/migrations/converters/migrations-converters.gemspec
index 8aece43074e..d1f4c121e5f 100644
--- a/migrations/converters/migrations-converters.gemspec
+++ b/migrations/converters/migrations-converters.gemspec
@@ -13,6 +13,7 @@ Gem::Specification.new do |s|
s.add_dependency "activesupport"
s.add_dependency "colored2"
s.add_dependency "i18n"
+ s.add_dependency "markbridge", ">= 0.3.1"
s.add_dependency "pg"
s.add_dependency "zeitwerk"
end
diff --git a/migrations/converters/spec/lib/migrations/converters/markdown_renderer_spec.rb b/migrations/converters/spec/lib/migrations/converters/markdown_renderer_spec.rb
new file mode 100644
index 00000000000..f6690ec13be
--- /dev/null
+++ b/migrations/converters/spec/lib/migrations/converters/markdown_renderer_spec.rb
@@ -0,0 +1,397 @@
+# frozen_string_literal: true
+
+RSpec.describe Migrations::Converters::MarkdownRenderer do
+ describe "#to_markdown without an embed collector" do
+ subject(:renderer) { described_class.new(format: :bbcode) }
+
+ it "renders BBCode to Discourse Markdown" do
+ expect(renderer.to_markdown("[b]hi[/b] and [url=https://example.com]a link[/url]")).to eq(
+ "**hi** and [a link](https://example.com)",
+ )
+ end
+
+ it "raises for an unknown source format" do
+ expect { described_class.new(format: :wikitextish) }.to raise_error(
+ described_class::UnknownFormat,
+ )
+ end
+
+ it "unwraps a link nested in a link (CommonMark legality)" do
+ # A link inside a link is illegal Markdown; markbridge's default rules
+ # unwrap the inner one, keeping only its label, so the outer link stays
+ # the single link.
+ expect(
+ renderer.to_markdown("[url=https://a.com]outer [url=https://b.com]inner[/url] end[/url]"),
+ ).to eq("[outer inner end](https://a.com)")
+ end
+
+ it "keeps a linked image inside the link" do
+ # A linked image is legal Markdown and Discourse cooks it fine (the anchor
+ # wraps the image), so the image stays nested inside the link.
+ expect(
+ renderer.to_markdown(
+ "[url=https://example.com][img]https://example.com/pic.png[/img][/url]",
+ ),
+ ).to eq("[![](https://example.com/pic.png)](https://example.com)")
+ end
+
+ it "unwraps a self-link so the image stands alone" do
+ # The image links to its own source URL — the link is noise. Dropping it
+ # leaves a bare image, which gets Discourse's lightbox on import.
+ expect(
+ renderer.to_markdown("[url=https://x/pic.png][img]https://x/pic.png[/img][/url]"),
+ ).to eq("![](https://x/pic.png)")
+ end
+
+ it "keeps the link when the image points elsewhere" do
+ # Only an exact src == href match is a self-link; a near miss (image is a
+ # different resource on the same host) keeps the link.
+ expect(renderer.to_markdown("[url=https://x/page][img]https://x/pic.png[/img][/url]")).to eq(
+ "[![](https://x/pic.png)](https://x/page)",
+ )
+ end
+ end
+
+ describe "#to_markdown deferring embeds into an EmbedBuffer" do
+ subject(:renderer) { described_class.new(format: :bbcode, embeds: buffer) }
+
+ let(:buffer) do
+ Migrations::Converters::EmbedBuffer.new(
+ owner_type: Migrations::Database::IntermediateDB::Enums::EmbedOwner::POST,
+ )
+ end
+
+ let(:link_renderer) { described_class.new(format: :bbcode, embeds: buffer, defer: %i[link]) }
+
+ it "defers an attributed quote, recording the linkage and preserving the body" do
+ raw =
+ renderer.to_markdown('[quote="John, post:12, topic:34, username:john"]quoted body[/quote]')
+
+ expect(buffer.quotes.size).to eq(1)
+ descriptor = buffer.quotes.first
+ # The Discourse attribution format carries coordinates: `post:` is a post
+ # number, `topic:` a topic id.
+ expect(descriptor[:quoted_post_id]).to be_nil
+ expect(descriptor[:quoted_topic_id]).to eq(34)
+ expect(descriptor[:quoted_post_number]).to eq(12)
+ expect(descriptor[:quoted_username]).to eq("John")
+ # The BBCode parser copies the leading token into both author and username,
+ # so there's no distinct display name to keep.
+ expect(descriptor[:quoted_name]).to be_nil
+
+ # The token stands in for the opening tag; the body and closer remain.
+ expect(raw).to include(descriptor[:placeholder])
+ expect(raw).to include("quoted body")
+ expect(raw).to include("[/quote]")
+ end
+
+ it "drops an attribution number too large for an id column" do
+ # Meta really has a post titled like this; SQLite raises binding a bignum.
+ raw = renderer.to_markdown('[quote="A, post:77777777777777777789999, topic:2"]q[/quote]')
+
+ descriptor = buffer.quotes.first
+ expect(descriptor[:quoted_post_number]).to be_nil
+ expect(descriptor[:quoted_topic_id]).to eq(2)
+ expect(descriptor[:quoted_username]).to eq("A")
+ expect(raw).to include(descriptor[:placeholder])
+ end
+
+ it "renders an unattributed quote natively (nothing to remap)" do
+ raw = renderer.to_markdown("[quote]just text[/quote]")
+
+ expect(buffer).to be_empty
+ expect(Migrations::Placeholder).not_to be_include(raw)
+ end
+
+ it "defers links only when asked via defer:" do
+ raw = link_renderer.to_markdown("see [url=https://example.com/t/5]here[/url]")
+
+ expect(buffer.links.size).to eq(1)
+ descriptor = buffer.links.first
+ expect(descriptor[:url]).to eq("https://example.com/t/5")
+ expect(descriptor[:text]).to eq("here")
+ expect(raw).to include(descriptor[:placeholder])
+ end
+
+ it "defers a link whose label is simple inline formatting" do
+ raw = link_renderer.to_markdown("see [url=https://example.com/t/5][b]here[/b][/url]")
+
+ expect(buffer.links.size).to eq(1)
+ expect(buffer.links.first[:text]).to eq("**here**")
+ expect(raw).to include(buffer.links.first[:placeholder])
+ end
+
+ it "defers a link whose label is inline code carrying a language" do
+ # A language attribute alone never makes code a block, so code-with-a-
+ # language still renders inline inside a link and stays deferrable — only
+ # multi-line code is hoisted out.
+ raw =
+ link_renderer.to_markdown("see [url=https://example.com/t/5][code=ruby]x = 1[/code][/url]")
+
+ expect(buffer.links.size).to eq(1)
+ expect(buffer.links.first[:text]).to eq("`x = 1`")
+ expect(raw).to include(buffer.links.first[:placeholder])
+ end
+
+ it "hoists multi-line code out of a link label instead of deferring it into text" do
+ # The normalizer pulls multi-line code out of the inline container before
+ # we render, so the link arrives with an empty (deferrable) label and the
+ # code fence lands as a sibling block in the raw.
+ raw = link_renderer.to_markdown("[url=https://example.com][code=ruby]a\nb[/code][/url]")
+
+ expect(buffer.links).to contain_exactly(hash_including(url: "https://example.com", text: nil))
+ expect(raw).to include(buffer.links.first[:placeholder])
+ expect(raw).to include("```ruby\na\nb\n```")
+ end
+
+ it "defers a link whose quote label the normalizer hoisted out" do
+ # Markbridge's normalizer pulls the quote out of the link before we
+ # render, so the link arrives with an empty (hence deferrable) label
+ # and the quote defers separately, as a sibling in the raw.
+ raw =
+ described_class.new(format: :bbcode, embeds: buffer, defer: %i[quote link]).to_markdown(
+ '[url=https://example.com][quote="A, post:1, topic:2"]q[/quote][/url]',
+ )
+
+ expect(buffer.links).to contain_exactly(hash_including(url: "https://example.com", text: nil))
+ expect(buffer.quotes.size).to eq(1)
+ expect(raw).to include(buffer.links.first[:placeholder])
+ expect(raw).to include(buffer.quotes.first[:placeholder])
+ end
+
+ it "renders a linked image natively instead of deferring the link" do
+ raw =
+ link_renderer.to_markdown(
+ "[url=https://example.com][img]https://example.com/pic.png[/img][/url]",
+ )
+
+ # An image label isn't deferrable, so the link falls back to native
+ # rendering and stays a clickable image — nothing is recorded.
+ expect(buffer.links).to be_empty
+ expect(raw).to eq("[![](https://example.com/pic.png)](https://example.com)")
+ end
+
+ it "unwraps a self-link even with link deferral on" do
+ raw = link_renderer.to_markdown("[url=https://x/pic.png][img]https://x/pic.png[/img][/url]")
+
+ # The self-link is dropped before rendering, so there is no link to defer;
+ # the bare image renders inline.
+ expect(buffer.links).to be_empty
+ expect(raw).to eq("![](https://x/pic.png)")
+ end
+
+ it "records a bare URL's text as nil so the importer re-emits it bare" do
+ link_renderer.to_markdown("see [url=https://example.com/t/5]https://example.com/t/5[/url]")
+
+ expect(buffer.links.size).to eq(1)
+ expect(buffer.links.first[:text]).to be_nil
+ end
+
+ it "records a text-less link's text as nil, not an empty string" do
+ link_renderer.to_markdown("see [url=https://example.com/t/5][/url]")
+
+ expect(buffer.links.size).to eq(1)
+ expect(buffer.links.first[:text]).to be_nil
+ end
+
+ it "leaves links alone by default" do
+ raw = renderer.to_markdown("see [url=https://example.com]here[/url]")
+
+ expect(buffer.links).to be_empty
+ expect(raw).to eq("see [here](https://example.com)")
+ end
+
+ # The contract: every token in the rendered raw maps to exactly one recorded
+ # linkage descriptor.
+ it "keeps placeholders and linkage rows one-to-one" do
+ raw =
+ described_class.new(format: :bbcode, embeds: buffer, defer: %i[quote link]).to_markdown(
+ 'a [quote="A, post:1, topic:2, username:a"]q[/quote] b ' \
+ "[url=https://example.com/t/9]L[/url] c",
+ )
+
+ expect(Migrations::Placeholder.scan(raw)).to match_array(buffer.placeholders)
+ end
+
+ it "raises for an unknown defer kind at construction" do
+ expect {
+ described_class.new(format: :bbcode, embeds: buffer, defer: %i[bogus])
+ }.to raise_error(ArgumentError, /Unknown defer kind :bogus; expected one of/)
+ end
+ end
+
+ describe "#to_markdown reusing the built renderer across posts" do
+ subject(:renderer) { described_class.new(format: :bbcode, embeds: buffer) }
+
+ let(:buffer) do
+ Migrations::Converters::EmbedBuffer.new(
+ owner_type: Migrations::Database::IntermediateDB::Enums::EmbedOwner::POST,
+ )
+ end
+
+ # Guards against reintroducing a per-post build: constructing Markbridge's
+ # Discourse renderer costs about as much as converting a small post.
+ it "converts every post through the one renderer built at construction" do
+ built_renderers = []
+ allow(Markbridge).to receive(:convert).and_wrap_original do |original, *args, **kwargs|
+ built_renderers << kwargs[:renderer]
+ original.call(*args, **kwargs)
+ end
+
+ renderer.to_markdown("a")
+ renderer.to_markdown("b")
+
+ expect(built_renderers.size).to eq(2)
+ expect(built_renderers.first).to be(built_renderers.last)
+ end
+ end
+
+ describe ".normalizer" do
+ it "textifies a mention inside a link so the label stays deferrable" do
+ node = Markbridge::AST::Url.new(href: "https://example.com")
+ node << Markbridge::AST::Text.new("hi ")
+ node << Markbridge::AST::Mention.new(name: "sam", type: :user)
+ document = Markbridge::AST::Document.new
+ document << node
+
+ described_class.normalizer.normalize(document)
+
+ # Textified and coalesced with the neighbouring text: one plain-text
+ # label, which the :link handler will accept for deferral.
+ expect(node.children.map(&:class)).to eq([Markbridge::AST::Text])
+ expect(node.children.first.text).to eq("hi @sam")
+ end
+
+ it "is what to_markdown converts through" do
+ allow(Markbridge).to receive(:convert).and_call_original
+
+ described_class.new(format: :bbcode).to_markdown("plain")
+
+ expect(Markbridge).to have_received(:convert).with(
+ "plain",
+ hash_including(normalize: described_class.normalizer),
+ )
+ end
+ end
+
+ describe "#embed_handlers extraction" do
+ # Upload and Mention nodes don't arise from BBCode, so exercise their
+ # extraction methods directly against the real AST nodes.
+ let(:collector) do
+ Migrations::Converters::EmbedBuffer.new(
+ owner_type: Migrations::Database::IntermediateDB::Enums::EmbedOwner::POST,
+ )
+ end
+
+ let(:renderer) { described_class.new(format: :bbcode, embeds: collector) }
+
+ it "maps an Upload node's sha1 to upload_id" do
+ _node_class, extract = renderer.embed_handlers.fetch(:upload)
+ node = Markbridge::AST::Upload.new(sha1: "abc123", filename: "x.png")
+
+ token = extract.call(node, nil)
+
+ expect(collector.uploads).to contain_exactly(
+ { placeholder: token, upload_id: "abc123", original_markdown: nil },
+ )
+ end
+
+ it "maps a Quote node's ids to quoted_post_id and quoted_user_id" do
+ # BBCode can't carry them (phpBB-style id attribution arrives via the
+ # TextFormatter parser), so exercise the method directly.
+ _node_class, extract = renderer.embed_handlers.fetch(:quote)
+ node = Markbridge::AST::Quote.new(username: "alice", post_id: 9001, user_id: 12)
+ interface = instance_double(Markbridge::Renderers::Discourse::RenderingInterface)
+ allow(interface).to receive(:with_parent).with(node).and_return(:child_context)
+ allow(interface).to receive(:render_children).with(node, context: :child_context).and_return(
+ "body",
+ )
+
+ extract.call(node, interface)
+
+ expect(collector.quotes).to contain_exactly(
+ hash_including(quoted_post_id: 9001, quoted_user_id: 12, quoted_username: "alice"),
+ )
+ end
+
+ it "records a display name that differs from the username" do
+ _node_class, extract = renderer.embed_handlers.fetch(:quote)
+ node = Markbridge::AST::Quote.new(author: "John Doe", username: "jdoe", user_id: 12)
+ interface = instance_double(Markbridge::Renderers::Discourse::RenderingInterface)
+ allow(interface).to receive(:with_parent).with(node).and_return(:child_context)
+ allow(interface).to receive(:render_children).with(node, context: :child_context).and_return(
+ "body",
+ )
+
+ extract.call(node, interface)
+
+ expect(collector.quotes).to contain_exactly(
+ hash_including(quoted_username: "jdoe", quoted_name: "John Doe"),
+ )
+ end
+
+ it "records no name when the author equals the username" do
+ # The BBCode parser fills author and username with the same leading token.
+ _node_class, extract = renderer.embed_handlers.fetch(:quote)
+ node = Markbridge::AST::Quote.new(author: "john", username: "john", post_id: 9001)
+ interface = instance_double(Markbridge::Renderers::Discourse::RenderingInterface)
+ allow(interface).to receive(:with_parent).with(node).and_return(:child_context)
+ allow(interface).to receive(:render_children).with(node, context: :child_context).and_return(
+ "body",
+ )
+
+ extract.call(node, interface)
+
+ expect(collector.quotes).to contain_exactly(
+ hash_including(quoted_username: "john", quoted_name: nil),
+ )
+ end
+
+ it "defers a link whose label is single-line inline code" do
+ _node_class, extract = renderer.embed_handlers.fetch(:link)
+ node = Markbridge::AST::Url.new(href: "https://example.com")
+ code = Markbridge::AST::Code.new << Markbridge::AST::Text.new("x")
+ node << code
+ interface = instance_double(Markbridge::Renderers::Discourse::RenderingInterface)
+ allow(interface).to receive(:render_children).with(node).and_return("`x`")
+
+ extract.call(node, interface)
+
+ expect(collector.links).to contain_exactly(hash_including(text: "`x`"))
+ end
+
+ it "falls back to native rendering for a label containing an upload" do
+ # An upload inside a link keeps the label non-deferrable, so the link
+ # renders natively rather than deferring a token into its `text` column.
+ # An upload is the only deferrable embed that reaches this branch; a
+ # mention never does, because the normalizer textifies it before the
+ # :link handler sees the label.
+ _node_class, extract = renderer.embed_handlers.fetch(:link)
+ node = Markbridge::AST::Url.new(href: "https://example.com")
+ node << Markbridge::AST::Upload.new(sha1: "abc123", filename: "x.png")
+ interface = instance_double(Markbridge::Renderers::Discourse::RenderingInterface)
+ allow(interface).to receive(:render_default).with(node).and_return("NATIVE")
+
+ result = extract.call(node, interface)
+
+ expect(result).to eq("NATIVE")
+ expect(collector.links).to be_empty
+ end
+
+ it "maps a Mention node's type and name" do
+ _node_class, extract = renderer.embed_handlers.fetch(:mention)
+ node = Markbridge::AST::Mention.new(name: "gerhard", type: :user)
+
+ token = extract.call(node, nil)
+
+ expect(collector.mentions).to contain_exactly(
+ {
+ placeholder: token,
+ mention_type: Migrations::Database::IntermediateDB::Enums::MentionType::USER,
+ target_id: nil,
+ name: "gerhard",
+ },
+ )
+ end
+ end
+end