Redesign migration API around Conversion/Parse result types

[gschlager]

Summary

Reshapes the Markbridge public API to return structured result objects (Parse and Conversion) instead of raw strings, consolidates render-side customization into a single renderer: parameter built via a discourse_renderer(...) factory, and adds AST-mutation hooks plus selective escaper customisation. Eliminates the global configuration singleton and per-process default registries in favor of explicit, reusable renderer instances.

Squashed to a single commit on the current origin/main, plus dependency-update and version-bump commits. Linear history; no merge commits.

Bumps the gem version to 0.2.0 — merging this PR publishes the gem and creates the GitHub release automatically (the publish job releases on push to main whenever version.rb carries a new version).

Key Changes

• New result types: Parse (parse-only) and Conversion (render) — Data.define value objects wrapping AST, markdown output, format, unknown tags, diagnostics, and errors

  • parse_* methods return Parse; *_to_markdown methods return Conversion
  • Conversion#to_s delegates to markdown for string-coercion contexts; Conversion#parsed exposes the underlying Parse

• Removed global configuration: Markbridge::Configuration, .configuration, .configure, .reset_defaults!, and all default_* accessors are gone

• Renderer factory: Markbridge.discourse_renderer(...) builds reusable Renderer instances

  • Accepts: tags:, tag_library:, unregister:, escaper:, escape:, escape_hard_line_breaks:, allow:, postprocessor:, strip_trailing_invisibles:

• Simplified method signatures: *_to_markdown and convert now accept only handlers:, renderer:, raise_on_error: plus an optional block yielding the parsed AST between parse and render

• Markbridge.render accepts a Parse or an AST::Node: when given a Parse, the resulting Conversion carries unknown_tags, diagnostics, and source format forward; when given a bare AST node those default to empty and format is nil — there was no source document, so there is no source format to report. A bare non-Document node is wrapped in an AST::Document, so Conversion#ast is always a Document

• AST traversal/mutation helpers: AST::Element#each_descendant, #descendants(klass = nil), and #replace_child(old, new) support mutating the AST between parse and render

• AST::Details + DetailsTag: renders Discourse [details=…]…[/details] collapsible sections. No built-in parser produces the node — it exists for custom migration handlers

• Handler registry #overlay: BBCode, HTML, and TextFormatter registries gain #overlay(name) { |previous| ... } for wrapping defaults

• Pre-parsed Nokogiri input: the HTML and TextFormatter parsers accept a Nokogiri::XML::Node (DocumentFragment, Document, Element) in addition to Strings, so importers can run their own Nokogiri-driven pre-processing on the live tree without a re-encode/re-parse round-trip

• TagLibrary#unregister: removes a binding so the renderer falls through to render_children (auto-passthrough for unregistered AST classes)

• Postprocessor: extracted from Markbridge#cleanup_markdown into Renderers::Discourse::Postprocessor; injectable on the Renderer

• MarkdownEscaper#allow: for selective passthrough: replaces the subclass-and-override pattern. Recognised keys: :bullet_list, :ordered_list, :atx_heading, :block_quote. Alias :lists expands to [:bullet_list, :ordered_list]. Unknown keys raise. Marker bytes pass through verbatim while inline content after the marker is still escaped.

• IdentityEscaper + escape: false sugar: new no-op escaper for migration paths where source content is already trusted Markdown. discourse_renderer(escape: false) swaps it in. Mutually exclusive with escape_hard_line_breaks: / allow:; an explicit escaper: always wins.

• Class-only handlers: BBCode, HTML, and TextFormatter parsers now require objects responding to #process(...). The br/hr lambdas in HTML's default registry became Handlers::SelfClosingHandler; the example file's lambda demos became Handler classes.

  Note on the rebase: main shipped its own VoidHandler (same shape, different name) to fix the related whitespace-trim bug. The rebase unified these — kept this branch's SelfClosingHandler name (covers both <br> and <hr> since they're both self-closing void elements per HTML), kept main's whitespace-trim behavior via produces_block? (now simplified — no Proc gate needed).

• MediaWiki API consistency: inline_tag_registry: parameter renamed to handlers: for parity with sibling parsers

• TextFormatter handler signature: handlers accept processor: so they can call back into processor.process_children(xml, ast_node)

Notable Implementation Details

• Parse and Conversion use Data.define (frozen, structural equality)
• Renderer instances are designed to be built once and reused across thousands of posts
• The raise_on_error: false mode allows per-row failure isolation in batch migrations
• Auto-passthrough for unregistered AST classes eliminates boilerplate "passthrough" Tags
• MarkdownEscaper#allow: storage is a private Array (≤ 4 elements) — #include? is observably identical to Set#include? at this size, no allocation
• examples/forum_migration.rb exercises the migration API end-to-end: discourse_renderer factory, tags:, unregister:, allow: :lists, the AST-mutation block, Conversion#errors, raise_on_error: false, and the convert(format:) dispatcher
• UPGRADING.md covers every breaking change

Migration-side resolution

The migration use case resolves placeholders (uploads, mentions, internal links) at parse time via custom handler subclasses. The handler stores the source-side reference in the converter's upload/user/topic store, gets back a stable identifier, and pins it on the AST node directly. Renderer Tags stay trivial output formatters — no per-post state, no side-channel.

The earlier drafts of this PR shipped an interface.emit / Conversion#emissions API for render-time side data; that has been removed. Resolution is a write, not a read — it should happen exactly once per source attachment regardless of how many times the post is rendered, the lookup table varies per post (defeating "build-once-reuse-many" if state lived in Tag constructors), and re-renders should be pure functions of the AST. With resolution in the handler, every job emit was trying to do is now done by something simpler. The BaseAttachmentHandler template-method pattern (extract source ref → store_or_lookup → AttachmentPlaceholder.new) reuses cleanly across phpBB / vBulletin / SMF / IPB attachment handlers — that layer lives in the converter framework, not Markbridge.

Tests

• All existing system and unit tests updated for the new result types
• New tests for discourse_renderer, #overlay, #unregister, Postprocessor, MarkdownEscaper#allow:, IdentityEscaper, polymorphic Markbridge.render(Parse|AST), AST-mutation block form, SelfClosingHandler, AST::Details/DetailsTag, the Element traversal helpers, and pre-parsed Nokogiri input
• Removed tests for deleted Configuration, interface.emit, Conversion#emissions, with_provisional_emissions, obsolete Proc-handler shape
• 3322 examples green at HEAD (114095d)
• Mutation: 100% coverage on every subject changed since main on every local pass

---

This change is

[Copilot]

Pull request overview

Reshapes Markbridge’s migration-facing public API to return structured Parse/Conversion result objects and to route render customization through explicit, reusable Renderer instances (via Markbridge.discourse_renderer(...)), replacing prior global/singleton configuration patterns.

Changes:

• Introduces/standardizes Parse and Conversion result types across parse/convert entrypoints, including raise_on_error: error-collection mode.
• Consolidates Discourse rendering customization behind a renderer factory and expands renderer/tag capabilities (e.g., new Details support, tag library unregistering, postprocessing).
• Updates docs and unit specs to cover the new API and behaviors.

Reviewed changes

Copilot reviewed 70 out of 70 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
UPGRADING.md	New/expanded upgrade guide describing the redesigned API and migration patterns.
docs/renderers/discourse.md	Updates renderer documentation around configuration and usage patterns.
lib/markbridge.rb	Public API surface and YARD docs for parse/convert/render entrypoints and error-handling semantics.
lib/markbridge/parsers/html/parser.rb	HTML parser input handling for pre-parsed Nokogiri nodes.
lib/markbridge/renderers/discourse/postprocessor.rb	Extracted postprocessing/cleanup pipeline for rendered Markdown.
lib/markbridge/parsers/text_formatter/handler_registry.rb	Handler registry behavior updates (e.g., overlay, processor plumbing) supporting the new handler API.
spec/unit/markbridge/renderers/discourse/tags/table_tag_spec.rb	Adds coverage for “effectively empty table” rendering behavior.
spec/unit/markbridge/renderers/discourse/tags/details_tag_spec.rb	Adds coverage for the new Details tag in markdown + html_mode.
spec/unit/markbridge/renderers/discourse/tag_library_spec.rb	Adds coverage for TagLibrary#unregister and merge semantics.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gschlager]

@gschlager partially reviewed 71 files and all commit messages, and made 1 comment.
Reviewable status: all files reviewed, 1 unresolved discussion.

---

lib/markbridge.rb line 109 at r2 (raw file):

      ast = parser.parse(input)

      # stree-ignore

Why is there a # stree-ignore?

Code quote:

# stree-ignore