markbridge 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cee12c41cea526db53cf389e2cc2bc49310568c0ebe9979d03daa7a4c2d23ac
-  data.tar.gz: a6d541954eea2357b6bb31bcfb685a634383de405dd1f505b257c78007e087d4
+  metadata.gz: e077560817f865c035c136edffd868cbabb934b6a8986614c5e1c48139b05b9b
+  data.tar.gz: 6511b321b0245010d0df81cea6e5b19950de430753a34aea54f4c99c2fa10fc9
 SHA512:
-  metadata.gz: b7ddd72dd5d0aa197a7b2477f1bfddd72e9cf7a01f26b4def8da341c8edd739503c04a23a501175adbcc23e23064578a2a4bcb17f3518b543f2716059636e3e7
-  data.tar.gz: 409dcbed4de6b6551c420ca51a00ed998abf11aeac8bd3bce9522b49a5ca07d3e524d68737b9461ddb6e3949485c1c84123c30c8e6e44cb57d7a99d873c7c3af
+  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/ast/quote.rb

@@ -4,42 +4,72 @@ module Markbridge
   module AST
     # Represents a quote/blockquote element.
     #
+    # The attribution fields follow Discourse's quote format
+    # (`[quote="username, post:2, topic:456"]`): +post_number+ is the
+    # position of the quoted post *within its topic* (not a database
+    # id), +topic_id+ is the topic's id. Sources that attribute quotes
+    # by database id instead (phpBB, XenForo) use +post_id+ and
+    # +user_id+ — those never feed a Discourse +post:+ reference and
+    # are carried for consumers to remap.
+    #
     # @example Basic quote
     #   quote = AST::Quote.new
     #   quote << AST::Text.new("quoted text")
     #
     # @example Quote with author attribution
-    #   quote = AST::Quote.new(author: "John")
+    #   quote = AST::Quote.new(author: "alice")
     #   quote << AST::Text.new("quoted text")
     #
     # @example Quote with full Discourse context
-    #   quote = AST::Quote.new(author: "John", post: "123", topic: "456", username: "john123")
+    #   quote = AST::Quote.new(author: "alice", post_number: 123, topic_id: 456, username: "alice_b")
     #   quote << AST::Text.new("quoted text")
     class Quote < Element
-      # @return [String, nil] the author/username of the quote
+      # @return [String, nil] the author attribution (display name)
       attr_reader :author
 
-      # @return [String, nil] the post ID for Discourse quotes
-      attr_reader :post
+      # @return [Integer, nil] the quoted post's number within its topic
+      #   (Discourse semantics — not a post id)
+      attr_reader :post_number
+
+      # @return [Integer, nil] the quoted post's database id, for sources
+      #   that attribute quotes by id (phpBB's +post_id+, XenForo's
+      #   +post:+). Distinct from {#post_number}; parsers map whichever
+      #   their dialect provides.
+      attr_reader :post_id
 
-      # @return [String, nil] the topic ID for Discourse quotes
-      attr_reader :topic
+      # @return [Integer, nil] the topic id the quoted post belongs to
+      attr_reader :topic_id
 
-      # @return [String, nil] the username for Discourse quotes
+      # @return [String, nil] the quoted user's username
       attr_reader :username
 
+      # @return [Integer, nil] the quoted user's id, for sources that
+      #   attribute quotes by id (usernames may be unknown or stale)
+      attr_reader :user_id
+
       # Create a new Quote element.
       #
-      # @param author [String, nil] the author attribution
-      # @param post [String, nil] the post ID (Discourse-specific)
-      # @param topic [String, nil] the topic ID (Discourse-specific)
-      # @param username [String, nil] the username (Discourse-specific)
-      def initialize(author: nil, post: nil, topic: nil, username: nil)
+      # @param author [String, nil] the author attribution (display name)
+      # @param post_number [Integer, nil] the quoted post's number within its topic
+      # @param post_id [Integer, nil] the quoted post's database id
+      # @param topic_id [Integer, nil] the topic id
+      # @param username [String, nil] the quoted user's username
+      # @param user_id [Integer, nil] the quoted user's id
+      def initialize(
+        author: nil,
+        post_number: nil,
+        post_id: nil,
+        topic_id: nil,
+        username: nil,
+        user_id: nil
+      )
         super()
         @author = author
-        @post = post
-        @topic = topic
+        @post_number = post_number
+        @post_id = post_id
+        @topic_id = topic_id
         @username = username
+        @user_id = user_id
       end
     end
   end

data/lib/markbridge/ast/text.rb

@@ -19,13 +19,15 @@ module Markbridge
 
       # Create a new text node with the given content.
       #
-      # The text is copied into a fresh mutable buffer so that subsequent
-      # in-place mutations (e.g. via {#merge}) do not leak back to the caller's
-      # original string.
+      # Frozen input is shared as-is (copy-on-write: {#merge} dups before
+      # its first append) — the parser hot path always passes frozen token
+      # text, so no copy is made per text node. Mutable input is copied so
+      # that in-place mutations cannot leak in either direction between
+      # the caller's string and this node.
       #
       # @param text [String] the text content
       def initialize(text)
-        @text = text.dup
+        @text = text.frozen? ? text : text.dup
       end
 
       # Merge another text node's content into this one.
@@ -34,6 +36,7 @@ module Markbridge
       # @param other [Text] the text node to merge from
       # @return [Text] self for method chaining
       def merge(other)
+        @text = @text.dup if @text.frozen?
         @text << other.text
         self
       end

data/lib/markbridge/ast/url.rb

@@ -22,6 +22,21 @@ module Markbridge
         super()
         @href = href
       end
+
+      # Whether this link is "bare" — it has no link text of its own:
+      # either no children, or a single Text child whose content is
+      # exactly the href (how parsers model a URL that stands for
+      # itself). Consumers that record or rewrite links need this
+      # judgment too (a bare URL must stay bare to keep autolinking
+      # and oneboxing working), so it lives on the node rather than
+      # in the renderer.
+      #
+      # @return [Boolean]
+      def bare?
+        return true if children.empty?
+
+        children.size == 1 && children.first.instance_of?(Text) && children.first.text == href
+      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