markbridge 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f805bfbca5d3f0ecb098c54a27c367a3b5c44bdf79a59bd4f4f04073f3b4e3d7
-  data.tar.gz: 77d62ba2660fc967f9475fafb768e3728e54ad0811f562bc575fdfcfbd2bfe5a
+  metadata.gz: 1f501e9875d69ca60aa8fcf7d1e46ef5ce83d24b69da46b192121e00b7414919
+  data.tar.gz: db9a49e5d6b0c0c5f68f84109c153f619e59d1b07fbb5e695a6443ed099b1436
 SHA512:
-  metadata.gz: b65279c8b48a47f1c745e601dca97ccdaa170279830ed6ecb82aed03439cb0ed05a37d5ff3818920efde337fbe65c32c9cf3e24e354bbd072b230fe7334128ea
-  data.tar.gz: a6139242a1f81149bf0e3eb1560ec70028979e5ee2aba12d0b0477e1b8b505e526a657e4dc5854a89f4903aad376fe687bf80a72d77b8eb3238f46f76b267cb8
+  metadata.gz: 1f5b7bac5d2ee008db7a012040de5394a615811420fcd90a8a95064349a2cf074254c3310dffb27e93f7d0c51c06f47c16b1f361015a9fad61e8fb14380c0a19
+  data.tar.gz: de4b3625ef287981cec8a5c6683ccbbf88d7593af0cd5ca7798393f377dc930a20f3f1228b225d49880f5f0323ccfa8bb7957186b644cbefd55770e153948ade

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 Gerhard Schlager
+Copyright (c) 2025 Civilized Discourse Construction Kit, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/markbridge/ast/details.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a Discourse +[details=…]…[/details]+ collapsible section.
+    #
+    # Carries a +title+ string (used as the +summary+ text when the
+    # block renders) and any child nodes.
+    #
+    # @example
+    #   block = AST::Details.new(title: "Show more")
+    #   block << AST::Text.new("Hidden body")
+    class Details < Element
+      # @return [String, nil] the summary / collapsed-state label
+      attr_reader :title
+
+      # @param title [String, nil] optional summary text
+      def initialize(title: nil)
+        super()
+        @title = title
+      end
+    end
+  end
+end

data/lib/markbridge/ast/element.rb

@@ -42,6 +42,69 @@ module Markbridge
 
         self
       end
+
+      # Depth-first pre-order traversal yielding every descendant node.
+      # Returns an +Enumerator+ when called without a block so it
+      # composes through +Enumerable+:
+      #
+      #   document.each_descendant.select { |n| n.is_a?(AST::Url) }
+      #
+      # Iteration semantics: each Element snapshots its own +children+
+      # array at the moment iteration enters it, so replacing a child
+      # via {#replace_child} mid-walk is safe — descent uses the
+      # pre-replacement reference. Adding or removing siblings on an
+      # Element you are currently descending into is *not* guaranteed
+      # to be visible to the current walk.
+      #
+      # @yieldparam node [Node] each descendant in document order
+      # @return [Enumerator, Element] +Enumerator+ without a block, +self+ otherwise
+      def each_descendant(&block)
+        return enum_for(:each_descendant) unless block_given?
+
+        @children.dup.each do |child|
+          yield child
+          child.each_descendant(&block) if child.is_a?(Element)
+        end
+        self
+      end
+
+      # Array of descendant nodes, optionally filtered by class.
+      #
+      #   document.descendants                    # every descendant
+      #   document.descendants(AST::Url)          # every Url descendant
+      #
+      # @param klass [Class, nil] when given, only descendants that
+      #   +is_a?(klass)+ are returned
+      # @return [Array<Node>]
+      def descendants(klass = nil)
+        result = each_descendant.to_a
+        return result if klass.nil?
+
+        result.select { |node| node.is_a?(klass) }
+      end
+
+      # Replace a direct child of this Element with a different Node.
+      # Preserves the child's index — useful for AST-mutation passes
+      # that need to swap one Element type for another in place
+      # (e.g. wrapping trailing paragraphs in a +Details+ block).
+      #
+      # @param old_child [Node] the child to remove (matched by +equal?+ via {Array#index})
+      # @param new_child [Node] the replacement
+      # @return [Element] +self+
+      # @raise [ArgumentError] when +old_child+ is not currently a child of this Element
+      # @raise [TypeError] when +new_child+ is not a {Node}
+      def replace_child(old_child, new_child)
+        index = @children.index(old_child)
+        raise ArgumentError, "child not found in #{self.class}" if index.nil?
+
+        unless new_child.is_a?(Node)
+          actual = new_child.nil? ? "nil" : new_child.class
+          raise TypeError, "replace_child on #{self.class} expected a #{Node}, got #{actual}"
+        end
+
+        @children[index] = new_child
+        self
+      end
     end
   end
 end

data/lib/markbridge/ast.rb

@@ -10,6 +10,7 @@ require_relative "ast/attachment"
 require_relative "ast/bold"
 require_relative "ast/code"
 require_relative "ast/color"
+require_relative "ast/details"
 require_relative "ast/email"
 require_relative "ast/heading"
 require_relative "ast/horizontal_rule"

data/lib/markbridge/conversion.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Markbridge
+  # Result of a *_to_markdown / convert / render call.
+  #
+  # Wraps a {Parse} (the input-side fields: +ast+, +format+,
+  # +unknown_tags+, +diagnostics+) and adds the render-side outputs:
+  # +markdown+ and +errors+. The wrapped {Parse} is reachable via
+  # {#parsed}, and each of its fields is also exposed as a delegated
+  # reader so the common usage stays ergonomic
+  # (+conversion.ast+, +conversion.unknown_tags+, …) without forcing
+  # callers to chain through +#parsed+.
+  #
+  # @!attribute [r] parsed
+  #   @return [Parse] the parsed input — also reusable for a direct
+  #     re-render via +Markbridge.render(conversion.parsed, …)+.
+  # @!attribute [r] markdown
+  #   @return [String] the rendered Discourse-flavored Markdown
+  # @!attribute [r] errors
+  #   @return [Array<StandardError>] render-time errors collected when
+  #     +raise_on_error: false+ was passed; empty otherwise.
+  # @!method ast
+  #   @return [AST::Document] delegated to {Parse#ast}
+  # @!method format
+  #   @return [Symbol, nil] delegated to {Parse#format}
+  # @!method unknown_tags
+  #   @return [Hash{String => Integer}] delegated to {Parse#unknown_tags}
+  # @!method diagnostics
+  #   @return [Hash{Symbol => Object}] delegated to {Parse#diagnostics}
+  Conversion =
+    Data.define(:parsed, :markdown, :errors) do
+      def ast = parsed.ast
+      def format = parsed.format
+      def unknown_tags = parsed.unknown_tags
+      def diagnostics = parsed.diagnostics
+
+      # Allows +puts result+ and +"text: #{result}"+ to work seamlessly.
+      def to_s = markdown
+    end
+end

data/lib/markbridge/parse.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Markbridge
+  # Result of a parse-only call (Markbridge.parse_bbcode and friends).
+  #
+  # @!attribute [r] ast
+  #   @return [AST::Document]
+  # @!attribute [r] format
+  #   @return [Symbol, nil] :bbcode, :html, :text_formatter_xml, or
+  #     :mediawiki. +nil+ when synthesized by {Markbridge.render} from
+  #     a bare AST node — there was no source document to parse.
+  # @!attribute [r] unknown_tags
+  #   @return [Hash{String => Integer}] tag-name → occurrence count.
+  #     Empty for parsers that do not yet track unknown tags.
+  # @!attribute [r] diagnostics
+  #   @return [Hash{Symbol => Object}] format-specific diagnostics.
+  #     BBCode supplies :auto_closed_tags_count, :depth_exceeded_count,
+  #     :unclosed_raw_tags. Other parsers supply an empty hash for now.
+  Parse = Data.define(:ast, :format, :unknown_tags, :diagnostics)
+end

data/lib/markbridge/parsers/bbcode/handler_registry.rb

@@ -37,6 +37,27 @@ module Markbridge
           self
         end
 
+        # Replace the handler bound to one or more tag names by yielding
+        # the previously-bound handler (which may be +nil+) and
+        # registering whatever the block returns. Used to install a
+        # delegating handler that wraps the default.
+        #
+        # @example Wrap the default URL handler
+        #   registry.overlay(%w[url link iurl]) do |default|
+        #     LinkifyingUrlHandler.new(default:)
+        #   end
+        #
+        # @param tag_names [String, Array<String>]
+        # @yieldparam previous [BaseHandler, nil] previously bound handler
+        # @return [self]
+        def overlay(tag_names)
+          Array(tag_names).each do |name|
+            previous = self[name]
+            register(name, yield(previous))
+          end
+          self
+        end
+
         # Get handler for a tag name
         # @param tag_name [String]
         # @return [BaseHandler, nil]
@@ -69,8 +90,10 @@ module Markbridge
         # Create the default handler registry with common BBCode tags.
         #
         # Each call returns a *fresh* instance — mutations made to one will
-        # not be visible to another. If you want a process-wide singleton,
-        # use {Markbridge.default_handlers} instead, which memoizes.
+        # not be visible to another. Convenience methods on +Markbridge+
+        # build a fresh default registry per call when none is supplied;
+        # to share state across calls, build one once and pass it via
+        # the +handlers:+ kwarg.
         #
         # @param closing_strategy [Object, nil] optional closing strategy to apply, defaults to Reordering strategy
         # @return [HandlerRegistry]

data/lib/markbridge/parsers/bbcode/handlers/raw_handler.rb

@@ -32,11 +32,22 @@ module Markbridge
           private
 
           def create_element(token:, content:)
-            language = token.attrs[:lang] || token.attrs[:option]
-            element = @element_class.new(language:)
+            element =
+              if accepts_language?
+                @element_class.new(language: token.attrs[:lang] || token.attrs[:option])
+              else
+                @element_class.new
+              end
             element << AST::Text.new(content) unless content.empty?
             element
           end
+
+          def accepts_language?
+            @element_class
+              .instance_method(:initialize)
+              .parameters
+              .any? { |_kind, name| name == :language }
+          end
         end
       end
     end

data/lib/markbridge/parsers/html/handler_registry.rb

@@ -3,23 +3,114 @@
 module Markbridge
   module Parsers
     module HTML
-      # Registry of HTML tag handlers
+      # Registry of HTML tag handlers and per-tag-name parser configuration.
+      #
+      # Handlers map a tag name to a handler instance. `block_level_tags` and
+      # `whitespace_preserving_tags` configure parser whitespace behavior by
+      # tag name, independent of whether a handler is registered — so unknown
+      # tags like <div> or <section> still trigger boundary collapsing and
+      # <pre>/<code> still pass through verbatim. Both sets are mutable, so
+      # downstream consumers can add or remove tags freely:
+      #
+      #     registry = HandlerRegistry.default
+      #     registry.block_level_tags << "my-block"
+      #     registry.whitespace_preserving_tags.delete("tt")
       class HandlerRegistry
+        # HTML5 block-level elements (per MDN). The trim-before-block rule
+        # applies to these regardless of whether a handler is registered.
+        DEFAULT_BLOCK_LEVEL_TAGS = %w[
+          address
+          article
+          aside
+          blockquote
+          canvas
+          dd
+          details
+          dialog
+          div
+          dl
+          dt
+          fieldset
+          figcaption
+          figure
+          footer
+          form
+          h1
+          h2
+          h3
+          h4
+          h5
+          h6
+          header
+          hgroup
+          hr
+          html
+          li
+          main
+          nav
+          noscript
+          ol
+          output
+          p
+          pre
+          section
+          table
+          tbody
+          td
+          tfoot
+          th
+          thead
+          tr
+          ul
+          video
+        ].freeze
+
+        # Tags whose default CSS preserves source whitespace
+        # (`white-space: pre*`). Text inside these is passed through
+        # verbatim; outside, `\s+` runs collapse to a single space.
+        DEFAULT_WHITESPACE_PRESERVING_TAGS = %w[pre code textarea tt].freeze
+
+        # @return [Set<String>] mutable set of tag names treated as block-level.
+        attr_reader :block_level_tags
+
+        # @return [Set<String>] mutable set of tag names whose contents
+        #   preserve source whitespace.
+        attr_reader :whitespace_preserving_tags
+
         def initialize
           @handlers = {}
+          @block_level_tags = Set.new(DEFAULT_BLOCK_LEVEL_TAGS)
+          @whitespace_preserving_tags = Set.new(DEFAULT_WHITESPACE_PRESERVING_TAGS)
         end
 
         # Register a handler for one or more tag names
         # @param tag_names [String, Array<String>] tag name(s) to register
-        # @param handler [BaseHandler, Proc] the handler instance or proc
+        # @param handler [BaseHandler] the handler instance — must
+        #   respond to +#process(element:, parent:)+
         def register(tag_names, handler)
           Array(tag_names).each { |tag_name| @handlers[tag_name.to_s.downcase] = handler }
           self
         end
 
+        # Replace the handler bound to one or more tag names by yielding
+        # the previously-bound handler (which may be +nil+) and
+        # registering whatever the block returns. Used to install a
+        # delegating handler that wraps the default.
+        #
+        # @param tag_names [String, Array<String>]
+        # @yieldparam previous [BaseHandler, nil] previously bound handler
+        # @return [self]
+        def overlay(tag_names)
+          Array(tag_names).each do |name|
+            previous = self[name]
+            register(name, yield(previous))
+          end
+          self
+        end
+
         # Get handler for a tag name
         # @param tag_name [String]
-        # @return [BaseHandler, Proc, nil]
+        # @return [BaseHandler, nil]
         def [](tag_name)
           @handlers[tag_name.to_s.downcase]
         end
@@ -38,26 +129,15 @@ module Markbridge
             registry.register("a", Handlers::UrlHandler.new)
             registry.register("img", Handlers::ImageHandler.new)
             registry.register("blockquote", Handlers::QuoteHandler.new)
-            registry.register(
-              "br",
-              lambda do |element:, parent:|
-                parent << AST::LineBreak.new
-                nil
-              end,
-            )
-            registry.register(
-              "hr",
-              lambda do |element:, parent:|
-                parent << AST::HorizontalRule.new
-                nil
-              end,
-            )
+            registry.register("br", Handlers::SelfClosingHandler.new(AST::LineBreak))
+            registry.register("hr", Handlers::SelfClosingHandler.new(AST::HorizontalRule))
             registry.register(%w[ul ol], Handlers::ListHandler.new)
             registry.register("li", Handlers::ListItemHandler.new)
             registry.register("table", Handlers::TableHandler.new)
             registry.register("tr", Handlers::TableRowHandler.new)
             registry.register(%w[td th], Handlers::TableCellHandler.new)
             registry.register("p", Handlers::ParagraphHandler.new)
+            registry.register("span", Handlers::SpanHandler.new)
           end
         end
 

data/lib/markbridge/parsers/html/handlers/self_closing_handler.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module HTML
+      module Handlers
+        # Handler for self-closing leaf tags (br, hr, etc.). Creates
+        # an instance of +element_class+, appends it to +parent+, and
+        # returns nil so the parser does not try to recurse into
+        # children.
+        class SelfClosingHandler < BaseHandler
+          def initialize(element_class)
+            @element_class = element_class
+          end
+
+          def process(element:, parent:)
+            parent << @element_class.new
+            nil
+          end
+
+          attr_reader :element_class
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/html/handlers/span_handler.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module HTML
+      module Handlers
+        # Maps recognized inline `style` declarations on `<span>` to AST
+        # formatting nodes. Supports text-decoration (underline,
+        # line-through), font-weight (bold), and font-style (italic). When
+        # multiple recognized styles are set, AST elements are nested in
+        # declaration order. Unrecognized styles are ignored; a span with
+        # no recognized styles is transparent (children processed into the
+        # parent).
+        class SpanHandler < BaseHandler
+          STYLE_DECLARATION = /([a-z-]+)\s*:\s*([^;]+)/i
+          BOLD_THRESHOLD = 600
+
+          def process(element:, parent:)
+            ast_classes_for(element["style"]).reduce(parent) do |current, klass|
+              child = klass.new
+              current << child
+              child
+            end
+          end
+
+          private
+
+          def ast_classes_for(style)
+            return [] if style.nil?
+
+            classes = []
+            style.scan(STYLE_DECLARATION) do |property, value|
+              classes_for_declaration(property.downcase, value.downcase.rstrip).each do |klass|
+                classes << klass unless classes.include?(klass)
+              end
+            end
+            classes
+          end
+
+          def classes_for_declaration(property, value)
+            case property
+            when "text-decoration"
+              text_decoration_classes(value)
+            when "font-weight"
+              bold_value?(value) ? [AST::Bold] : []
+            when "font-style"
+              italic_value?(value) ? [AST::Italic] : []
+            else
+              []
+            end
+          end
+
+          def text_decoration_classes(value)
+            classes = []
+            classes << AST::Underline if value.include?("underline")
+            classes << AST::Strikethrough if value.include?("line-through")
+            classes
+          end
+
+          def bold_value?(value)
+            return true if %w[bold bolder].include?(value)
+            return false unless value.match?(/\A\d+\z/)
+
+            Integer(value) >= BOLD_THRESHOLD
+          end
+
+          def italic_value?(value)
+            %w[italic oblique].include?(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/html/parser.rb

@@ -10,6 +10,8 @@ module Markbridge
         # JavaScript, or document metadata that shouldn't appear in output.
         IGNORED_TAGS = %w[style script head title noscript template].freeze
 
+        WHITESPACE_RUN = /[ \t\r\n\f]+/
+
         attr_reader :unknown_tags
 
         # Create a new parser with optional custom handlers
@@ -25,8 +27,22 @@ module Markbridge
           @unknown_tags = Hash.new(0)
         end
 
-        # Parse HTML string into an AST
-        # @param input [String] HTML source
+        # Parse HTML into an AST.
+        #
+        # Accepts either a String of HTML source or a pre-parsed
+        # Nokogiri node (typically a +DocumentFragment+ from
+        # +Nokogiri::HTML.fragment+ or a full +Document+ from
+        # +Nokogiri::HTML.parse+). Passing a pre-parsed tree lets a
+        # caller run their own Nokogiri-driven pre-processing without
+        # forcing Markbridge to re-parse the same bytes.
+        #
+        # A +Nokogiri::HTML::Document+ is unwrapped to its +<body>+
+        # children so the +<html>+ / +<body>+ / +<head>+ wrappers
+        # don't pollute {#unknown_tags}; fragments and bare elements
+        # iterate their own children directly.
+        #
+        # @param input [String, Nokogiri::XML::Node] HTML source or
+        #   pre-parsed Nokogiri tree
         # @return [AST::Document]
         def parse(input)
           @unknown_tags.clear
@@ -36,13 +52,21 @@ module Markbridge
           # (see sparklemotion/nokogiri#2227). Table support treats thead/tbody/tfoot
           # as transparent, so the parse-tree difference (HTML5 auto-inserts tbody,
           # HTML4 does not) has no effect on the AST.
-          doc = Nokogiri::HTML.fragment(input)
+          doc =
+            if input.is_a?(Nokogiri::XML::Node)
+              input
+            else
+              Nokogiri::HTML.fragment(input.to_s)
+            end
+
+          children = doc.is_a?(Nokogiri::HTML::Document) ? body_children(doc) : doc.children
 
           # Create root AST document
           document = AST::Document.new
 
           # Process all nodes
-          doc.children.each { |node| process_node(node, document) }
+          children.each { |node| process_node(node, document) }
+          trim_trailing_whitespace(document)
 
           document
         end
@@ -72,7 +96,19 @@ module Markbridge
         # @param node [Nokogiri::XML::Text]
         # @param parent [AST::Element]
         def process_text_node(node, parent)
-          parent << AST::Text.new(node.text)
+          if preserves_whitespace?(node)
+            parent << AST::Text.new(node.text)
+            return
+          end
+
+          text = node.text.gsub(WHITESPACE_RUN, " ")
+          # Drop leading whitespace at the start of an element's content,
+          # matching the browser rule that whitespace at the beginning of a
+          # block (or before any inline content) is collapsed away.
+          text = text.lstrip if parent.children.empty?
+          return if text.empty?
+
+          parent << AST::Text.new(text)
         end
 
         # Process an element node
@@ -82,21 +118,24 @@ module Markbridge
           tag_name = node.name
           return if IGNORED_TAGS.include?(tag_name)
 
+          # Drop whitespace that sits between content and the start of a
+          # block-level tag, matching browser behavior where such whitespace
+          # collapses against the block boundary. Applies whether or not a
+          # handler is registered, so unknown tags like <div> or <section>
+          # still collapse the whitespace before them.
+          trim_trailing_whitespace(parent) if @handlers.block_level_tags.include?(tag_name)
+
           handler = @handlers[tag_name]
+          return handle_unknown_tag(node, parent) unless handler
+
+          # Handler returns element if children should be processed, nil otherwise
+          ast_element = handler.process(element: node, parent:)
 
-          if handler
-            # Handler returns element if children should be processed, nil otherwise
-            ast_element =
-              if handler.respond_to?(:process)
-                handler.process(element: node, parent:)
-              else
-                handler.call(element: node, parent:)
-              end
-
-            # Automatically process children if handler returned element
-            process_children(node, ast_element) if ast_element
-          else
-            handle_unknown_tag(node, parent)
+          return unless ast_element
+
+          process_children(node, ast_element)
+          unless @handlers.whitespace_preserving_tags.include?(tag_name)
+            trim_trailing_whitespace(ast_element)
           end
         end
 
@@ -108,6 +147,37 @@ module Markbridge
           @unknown_tags[node.name] += 1
           process_children(node, parent)
         end
+
+        # Whether `node` is inside a tag that preserves source whitespace.
+        # @param node [Nokogiri::XML::Node]
+        # @return [Boolean]
+        def preserves_whitespace?(node)
+          node.ancestors.any? do |ancestor|
+            @handlers.whitespace_preserving_tags.include?(ancestor.name)
+          end
+        end
+
+        # Direct children of the +<body>+ element of a full HTML document,
+        # falling back to the document's own children if no +<body>+ exists
+        # (malformed input).
+        # @param doc [Nokogiri::HTML::Document]
+        # @return [Nokogiri::XML::NodeSet]
+        def body_children(doc)
+          (doc.at_css("body") || doc).children
+        end
+
+        # Strip trailing whitespace from the last Text child of `element`.
+        # Removes the child entirely if it becomes empty. No-op if the last
+        # child is not a Text node.
+        # @param element [AST::Element]
+        def trim_trailing_whitespace(element)
+          last = element.children.last
+          return unless last.instance_of?(AST::Text)
+
+          trimmed = last.text.rstrip
+          element.children.pop
+          element << AST::Text.new(trimmed) unless trimmed.empty?
+        end
       end
     end
   end

data/lib/markbridge/parsers/html.rb

@@ -10,6 +10,7 @@ require_relative "../ast"
 # Handlers
 require_relative "html/handlers/base_handler"
 require_relative "html/handlers/simple_handler"
+require_relative "html/handlers/self_closing_handler"
 require_relative "html/handlers/raw_handler"
 require_relative "html/handlers/url_handler"
 require_relative "html/handlers/image_handler"
@@ -20,6 +21,7 @@ require_relative "html/handlers/paragraph_handler"
 require_relative "html/handlers/table_handler"
 require_relative "html/handlers/table_row_handler"
 require_relative "html/handlers/table_cell_handler"
+require_relative "html/handlers/span_handler"
 
 # Parser components
 require_relative "html/handler_registry"