markbridge 0.3.0 → 0.4.0

data/lib/markbridge/normalizer.rb

@@ -0,0 +1,187 @@
+# 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 without
+    # a forced +block+ flag 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
+    # its +block+ flag is set or a Text child has a newline (the language alone
+    # does not make it a block).
+    KEEP_INLINE_CODE =
+      lambda do |_boundary, node|
+        block =
+          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 = []
+      # Per-call cache for RuleSet#resolve's ancestry analysis; keeps the
+      # Normalizer instance itself free of state, so a frozen shared
+      # instance stays safe across threads.
+      collect_violations(ast, EMPTY_STACK, found, {})
+      found
+    end
+
+    def freeze
+      @rules.freeze
+      super
+    end
+
+    private
+
+    def collect_violations(element, ancestors, found, walk_cache)
+      stack = ancestors + [element]
+      element.children.each do |child|
+        strategy, boundary = @rules.resolve(child, stack, walk_cache)
+        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, walk_cache) if child.is_a?(AST::Element)
+      end
+    end
+
+    def demodulize(klass)
+      klass.name.split("::").last
+    end
+  end
+end

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

@@ -11,9 +11,26 @@ module Markbridge
         #   # end
         #   # [/code]
         class CodeHandler < RawHandler
+          # Tags that mean a code block by definition; [tt] is inline
+          # teletype and leaves the decision to the renderer.
+          BLOCK_TAGS = %w[code pre].freeze
+          private_constant :BLOCK_TAGS
+
           def initialize
             super(AST::Code)
           end
+
+          private
+
+          def create_element(token:, content:)
+            element =
+              AST::Code.new(
+                language: token.attrs[:lang] || token.attrs[:option],
+                block: (true if BLOCK_TAGS.include?(token.tag)),
+              )
+            element << AST::Text.new(content) unless content.empty?
+            element
+          end
         end
       end
     end

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

@@ -132,6 +132,7 @@ module Markbridge
             registry.register("a", Handlers::UrlHandler.new)
             registry.register("img", Handlers::ImageHandler.new)
             registry.register("blockquote", Handlers::QuoteHandler.new)
+            registry.register(%w[h1 h2 h3 h4 h5 h6], Handlers::HeadingHandler.new)
             registry.register("br", Handlers::SelfClosingHandler.new(AST::LineBreak))
             registry.register("hr", Handlers::SelfClosingHandler.new(AST::HorizontalRule))
             registry.register(%w[ul ol], Handlers::ListHandler.new)

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module HTML
+      module Handlers
+        # Handles <h1> through <h6> by creating a Heading element with the
+        # matching level and processing children into it.
+        class HeadingHandler < BaseHandler
+          # @param element [Nokogiri::XML::Element] the heading element
+          # @param parent [AST::Element] the parent AST node
+          # @return [AST::Heading] the created heading, so children get processed into it
+          def process(element:, parent:)
+            level = element.name.delete_prefix("h").to_i.clamp(1, 6)
+            heading = AST::Heading.new(level:)
+            parent << heading
+
+            heading
+          end
+
+          # @return [Class] AST::Heading
+          def element_class
+            AST::Heading
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -6,6 +6,12 @@ module Markbridge
       module Handlers
         # Handler for raw/preformatted tags that preserve content as-is
         class RawHandler < BaseHandler
+          # A language must be one clean token — the renderer splices it
+          # into the code fence line, so a class attribute with spaces or
+          # other markup characters must not end up there.
+          LANGUAGE_PATTERN = /\A[a-z0-9][a-z0-9_+-]*\z/
+          private_constant :LANGUAGE_PATTERN
+
           def initialize(element_class)
             @element_class = element_class
           end
@@ -14,10 +20,8 @@ module Markbridge
             # Get the inner text content
             content = element.inner_text
 
-            # Extract language from class or lang attribute
-            language = element["class"] || element["lang"]
-
-            ast_element = @element_class.new(language:)
+            ast_element =
+              @element_class.new(language: language_for(element), block: block_for(element))
             ast_element << AST::Text.new(content) unless content.empty?
             parent << ast_element
 
@@ -26,6 +30,53 @@ module Markbridge
           end
 
           attr_reader :element_class
+
+          private
+
+          # <pre> is a block by definition, so its content keeps the fenced
+          # form even on one line; <code> and <tt> leave the decision to the
+          # renderer's newline check.
+          #
+          # @param element [Nokogiri::XML::Element]
+          # @return [Boolean, nil]
+          def block_for(element)
+            true if element.name == "pre"
+          end
+
+          # The language of a code block, from the strongest signal to the
+          # weakest: a `language-*` class on the element itself or on its
+          # direct <code> child (the CommonMark convention for fenced code,
+          # `<pre><code class="language-ruby">`), then the `lang` attribute,
+          # then a lone class used as-is. A lone class ranks below `lang`
+          # because a class can be pure styling (`hljs`, `prettyprint`).
+          def language_for(element)
+            code_child_classes = element.at_xpath("./code")&.[]("class")
+
+            prefixed_language(element["class"]) || prefixed_language(code_child_classes) ||
+              attribute_language(element["lang"]) || single_class_language(element["class"]) ||
+              single_class_language(code_child_classes)
+          end
+
+          def prefixed_language(classes)
+            classes
+              &.split
+              &.filter_map do |name|
+                name.delete_prefix("language-").downcase if name.start_with?("language-")
+              end
+              &.find { |language| LANGUAGE_PATTERN.match?(language) }
+          end
+
+          def attribute_language(value)
+            language = value&.strip&.downcase
+            language if language&.match?(LANGUAGE_PATTERN)
+          end
+
+          def single_class_language(classes)
+            names = classes&.split
+            return unless names&.length == 1
+
+            attribute_language(names.first)
+          end
         end
       end
     end

data/lib/markbridge/parsers/html.rb

@@ -17,6 +17,7 @@ require_relative "html/handlers/image_handler"
 require_relative "html/handlers/list_handler"
 require_relative "html/handlers/list_item_handler"
 require_relative "html/handlers/quote_handler"
+require_relative "html/handlers/heading_handler"
 require_relative "html/handlers/paragraph_handler"
 require_relative "html/handlers/table_handler"
 require_relative "html/handlers/table_row_handler"

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

@@ -347,7 +347,7 @@ module Markbridge
           consumed = lines[start_index..].take_while { |line| line.start_with?(" ") }
           content = consumed.map { |line| line[1..] }.join("\n")
 
-          code = AST::Code.new
+          code = AST::Code.new(block: true)
           code << AST::Text.new(content)
           @document << code
 
@@ -372,7 +372,7 @@ module Markbridge
           combined = consumed.join("\n")
           content = combined.sub(PRE_TAG_OPEN, "").sub(PRE_TAG_CLOSE_TRAILING, "")
 
-          code = AST::Code.new
+          code = AST::Code.new(block: true)
           code << AST::Text.new(content)
           @document << code
 

data/lib/markbridge/parsers/text_formatter/handlers/code_handler.rb

@@ -13,7 +13,9 @@ module Markbridge
           def process(element:, parent:, processor: nil)
             attrs = extract_attributes(element)
             lang = attrs[:lang] || attrs[:language]
-            node = AST::Code.new(language: lang)
+            # s9e CODE is always a block, so the flag keeps the fenced form
+            # even for single-line content.
+            node = AST::Code.new(language: lang, block: true)
             parent << node
 
             # Return node to signal: process children into this node

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Renderers
+    module Discourse
+      # Decides whether a rendered fragment is safe to splice into a
+      # CommonMark HTML block (spec §4.6). Inside such a block the
+      # content passes through as raw HTML; Markdown is only parsed
+      # again across blank lines. Safe output is therefore: a raw HTML
+      # or plain-text fragment without Markdown sigils, or a
+      # +\n\n…\n\n+ wrap — a deliberate Markdown island.
+      #
+      # Used by the html_mode contract check that ships in
+      # +markbridge/rspec+ and by this repo's own contract spec.
+      module HtmlBlockSafety
+        # Markdown sigils that would surface as literal text inside an
+        # HTML block: emphasis (`*`, `_`, `~`) and link middles (`](`).
+        MARKDOWN_SIGILS = /[*_~]|\]\(/
+        private_constant :MARKDOWN_SIGILS
+
+        # @param output [String] a tag's html_mode render result
+        # @return [Boolean]
+        def self.safe?(output)
+          return true if output.start_with?("\n\n") && output.end_with?("\n\n")
+
+          !output.match?(MARKDOWN_SIGILS)
+        end
+      end
+    end
+  end
+end

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

@@ -12,8 +12,9 @@ module Markbridge
           @escaper = escaper || MarkdownEscaper.new
           @html_escaper = html_escaper || HtmlEscaper
           @postprocessor = postprocessor || Postprocessor::DEFAULT
-          # @interface_cache is lazily initialized in #render's top-level
-          # call and reset to nil after the call completes.
+          # @interface_cache, @resolved_tags, and @resolved_default_tags
+          # are lazily initialized during a top-level #render /
+          # #render_default call and reset to nil after the call completes.
         end
 
         # Render a node to Markdown
@@ -28,7 +29,10 @@ module Markbridge
           root_call = @interface_cache.nil?
           @interface_cache = {} if root_call
 
-          tag = @tag_library[node.class]
+          # Exact-class hit first (a single Hash lookup, the common case),
+          # then the memoized ancestry fallback so a subclass without its
+          # own tag renders through its nearest ancestor's tag.
+          tag = @tag_library[node.class] || resolved_tag(node.class)
           if tag
             result = tag.render(node, interface_for(context))
             unless result.is_a?(String)
@@ -43,7 +47,11 @@ module Markbridge
 
           render_without_tag(node, context)
         ensure
-          @interface_cache = nil if root_call
+          if root_call
+            @interface_cache = nil
+            @resolved_tags = nil
+            @resolved_default_tags = nil
+          end
         end
 
         # Render a node with the stock tag for its class, ignoring any
@@ -66,12 +74,16 @@ module Markbridge
           root_call = @interface_cache.nil?
           @interface_cache = {} if root_call
 
-          tag = default_tag_library[node.class]
+          tag = default_tag_library[node.class] || resolved_default_tag(node.class)
           return tag.render(node, interface_for(context)) if tag
 
           render_without_tag(node, context)
         ensure
-          @interface_cache = nil if root_call
+          if root_call
+            @interface_cache = nil
+            @resolved_tags = nil
+            @resolved_default_tags = nil
+          end
         end
 
         # Render all children of a node
@@ -113,6 +125,24 @@ module Markbridge
           @interface_cache[context.object_id] ||= RenderingInterface.new(self, context)
         end
 
+        # Ancestry fallback for tag dispatch (see TagLibrary#resolve),
+        # memoized per top-level render call — the tag library can change
+        # between calls, so the cache must not outlive one call (it is
+        # reset in #render's ensure). +fetch+ stores nil results too, so a
+        # class that resolves to no tag is walked once per call, not once
+        # per node.
+        def resolved_tag(node_class)
+          cache = @resolved_tags ||= {}
+          cache.fetch(node_class) { cache[node_class] = @tag_library.resolve(node_class) }
+        end
+
+        # Same as {#resolved_tag}, against the default library backing
+        # #render_default.
+        def resolved_default_tag(node_class)
+          cache = @resolved_default_tags ||= {}
+          cache.fetch(node_class) { cache[node_class] = default_tag_library.resolve(node_class) }
+        end
+
         # Pristine default library backing #render_default. Built lazily —
         # most renders never need it.
         def default_tag_library

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

@@ -65,6 +65,10 @@ module Markbridge
         def block_context?(node)
           # Check if it's a block-level element type (but not code, which can be inline)
           return true if node.instance_of?(AST::List) || node.instance_of?(AST::HorizontalRule)
+          # A Code node whose source construct is a block by definition keeps
+          # its block form even with single-line content (is_a?, so Code
+          # subclasses inherit the behavior).
+          return true if node.is_a?(AST::Code) && node.block
           return false unless node.is_a?(AST::Element)
 
           # Check if content has newlines

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

@@ -36,6 +36,16 @@ module Markbridge
             raise NotImplementedError, "#{self.class} must implement #render or provide a block"
           end
         end
+
+        # A tag that renders only the element's children, with the element
+        # pushed on the parent chain. Tag dispatch matches by ancestry, so
+        # a subclass normally inherits its base class tag; register
+        # PASSTHROUGH for the subclass to opt out — the exact-class hit
+        # wins and the base tag is not used.
+        PASSTHROUGH =
+          new do |element, interface|
+            interface.render_children(element, context: interface.with_parent(element))
+          end.freeze
       end
     end
   end

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

@@ -15,9 +15,17 @@ module Markbridge
         # internal +@tags+ Hash is independent of the source. Without
         # this, both copies would share the same underlying Hash and
         # mutations to one would silently affect the other.
+        #
+        # A frozen source also carries flattened ancestry entries (see
+        # {#freeze}); the copy is mutable again, so those entries are
+        # dropped and the copy goes back to the lazy {#resolve} lookup.
+        # Keeping them would bake in inheritance decisions from before
+        # any changes made to the copy.
         def initialize_copy(other)
           super
           @tags = @tags.dup
+          @flattened_classes&.each { |klass| @tags.delete(klass) }
+          @flattened_classes = nil
         end
 
         # Register a tag for an element class
@@ -28,9 +36,11 @@ module Markbridge
           self
         end
 
-        # Remove a tag binding so the renderer falls through to
-        # +render_children+ for that element class. See
-        # +Renderer#render+ for the auto-passthrough path.
+        # Remove the binding for this exact element class. Lookup then
+        # falls back to the nearest ancestor class with a tag; when no
+        # ancestor has one — true for every built-in class, since
+        # nothing binds +AST::Element+ or +AST::Node+ — the renderer
+        # falls through to +render_children+. See +Renderer#render+.
         #
         # @param element_class [Class]
         # @return [self]
@@ -41,7 +51,7 @@ module Markbridge
 
         # Merge a Hash of class → Tag mappings on top of this library
         # in-place. A +nil+ value unregisters the corresponding class
-        # (so the default auto-passthrough kicks in).
+        # (see {#unregister} for what lookup does then).
         #
         # Named with a trailing +!+ because it mutates +self+ —
         # mirroring Ruby's Hash#merge / Hash#merge! convention. Use
@@ -67,6 +77,26 @@ module Markbridge
           @tags[element_class]
         end
 
+        # Find the tag for +element_class+ through its ancestry: walk the
+        # superclass chain, starting at +element_class.superclass+, and
+        # return the first registered tag. The walk stays inside the
+        # +AST::Node+ hierarchy, so a tag registered for a class outside
+        # the AST is never found. The exact-class lookup is {#[]};
+        # callers check that first.
+        #
+        # @param element_class [Class]
+        # @return [Tag, nil]
+        def resolve(element_class)
+          klass = element_class.superclass
+          while klass && klass <= AST::Node
+            tag = self[klass]
+            return tag if tag
+
+            klass = klass.superclass
+          end
+          # The while loop's own value is nil, so a miss returns nil.
+        end
+
         # Iterate over registered (element_class, tag) pairs.
         # Useful for debugging custom libraries — e.g. confirming an override
         # has stuck. Iteration order matches registration order.
@@ -122,10 +152,35 @@ module Markbridge
         # Freeze the library together with its internal Hash so that
         # registration on a shared instance fails loudly instead of
         # silently mutating state visible to every renderer.
+        #
+        # Freezing also flattens ancestry resolution: every known AST
+        # class without an explicit binding whose ancestry resolves to a
+        # tag gets that tag copied into the internal Hash, so lookup on a
+        # frozen library is a single exact Hash hit for those classes
+        # too. +AST::Node.descendants+ is boot-time state, so only
+        # classes defined before the freeze are covered; later classes
+        # keep working through the renderer's lazy {#resolve} fallback.
         def freeze
+          flatten_ancestry!
           @tags.freeze
           super
         end
+
+        private
+
+        # See {#freeze}. Records what it added in +@flattened_classes+ so
+        # {#initialize_copy} can drop those entries from a copy again.
+        def flatten_ancestry!
+          AST::Node.descendants.each do |klass|
+            next if @tags.key?(klass)
+
+            tag = resolve(klass)
+            next unless tag
+
+            (@flattened_classes ||= []) << klass
+            @tags[klass] = tag
+          end
+        end
       end
     end
   end

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

@@ -9,6 +9,10 @@ module Markbridge
             child_context = interface.with_parent(element)
             content = interface.render_children(element, context: child_context)
 
+            # An empty element renders to nothing — a bare `` pair or an
+            # empty fence would only add noise to the output.
+            return "" if content.empty?
+
             if interface.block_context?(element)
               if interface.html_mode?
                 render_html_block(content, element.language)

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

@@ -25,12 +25,16 @@ module Markbridge
 
           def render(element, interface)
             child_context = interface.with_parent(element)
-            content = interface.render_children(element, context: child_context)
+            content = interface.render_children(element, context: child_context).strip
+
+            # A details block with nothing to show renders to nothing —
+            # an empty [details] shell would only add noise to the output.
+            return "" if content.empty?
 
             return render_html(element.title, content) if interface.html_mode?
 
             opener = element.title ? %([details="#{element.title}"]) : "[details]"
-            "\n\n#{opener}\n#{content.strip}\n[/details]\n\n"
+            "\n\n#{opener}\n#{content}\n[/details]\n\n"
           end
 
           private

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