markbridge 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbebafc60a3665c98544f3cfd9496c3c5cdc2c0940339c998791b2df1f04aa44
-  data.tar.gz: 2be35c042f803e37302fa149af772897326241488a9429a525ddc714af0623d1
+  metadata.gz: 6d958f4d4c04108de2f92388f6a62ac37ab126700f535af2c6cf38f832928e20
+  data.tar.gz: 86510bc530a71fefb9f30e350a7800d159dd9e5fa77231f2f6259253373c11b4
 SHA512:
-  metadata.gz: 6b3e3dc46705d4f7cf52aabaac8b272cbc9241e57473caf11a6c53b1d1355ec2e7874ae485732ba526f67445144f12daccc521dae40a6405994e409a34e00ede
-  data.tar.gz: 89385e8ec7942af10b79b267e6400bfb209af7871775e0891f86153e792e3ef61b15b08eb025f9a6f6d5673c3aaf9bcbb6ec26200ac3a62440b426121fcba1fa
+  metadata.gz: 828a0d60a75ac730dd882e7825e2ea2e0fec53ca6b2efea6329cac03030157fba4ea086118476445ea9505835ab28031221ed786be526bdfb1b2340e2c570c56
+  data.tar.gz: 3df501c15e4050edcbd2225d356440e4672d30a5feb8d85a3b225af0daa4cd66f09f743044ac41b7e75b01a8378951aceac7784078833facb4d42cefcfc3aa24

data/lib/markbridge/ast/code.rb

@@ -15,12 +15,19 @@ module Markbridge
       # @return [String, nil] the programming language for syntax highlighting
       attr_reader :language
 
+      # @return [Boolean, nil] +true+ forces a fenced block; anything else
+      #   leaves the block-or-inline decision to the renderer
+      attr_reader :block
+
       # Create a new code element.
       #
       # @param language [String, nil] optional language identifier for syntax highlighting
-      def initialize(language: nil)
+      # @param block [Boolean, nil] +true+ when the source construct is a code
+      #   block by definition (e.g. +<pre>+), even with single-line content
+      def initialize(language: nil, block: nil)
         super()
         @language = language
+        @block = block
       end
     end
   end

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/node.rb

@@ -14,6 +14,47 @@ module Markbridge
     #
     # @abstract Subclass and add specific behavior
     class Node
+      # Registry of every class that inherits from {Node}, direct or not.
+      # This is boot-time state: the built-in classes land here while the
+      # gem's requires run, and a consumer subclass is appended when its
+      # class body runs. Anything built from this list at freeze time
+      # (see +TagLibrary#freeze+ and +RuleSet#freeze+) covers only the
+      # classes defined up to that point; later classes go through the
+      # lazy ancestry lookups instead.
+      DESCENDANTS = []
+
+      # No +super+ on purpose: +Class#inherited+ is a no-op, so calling
+      # it adds nothing observable (verified by mutation testing).
+      # @param subclass [Class]
+      def self.inherited(subclass)
+        DESCENDANTS << subclass
+      end
+
+      # @return [Array<Class>] every known descendant class, in definition
+      #   order (see {DESCENDANTS} — boot-time state)
+      def self.descendants
+        DESCENDANTS
+      end
+
+      # The class chain from this class up to {Node}, most specific class
+      # first. Cached on the class: the chain is pure class structure and
+      # can never change once the class is defined, so one array per class
+      # serves the whole process. The normalizer and the tag library use
+      # it for ancestry matching.
+      #
+      # @return [Array<Class>] frozen, e.g. +[Bold, Element, Node]+
+      def self.ast_chain
+        @ast_chain ||=
+          begin
+            chain = [self]
+            sup = superclass
+            while sup <= Node
+              chain << sup
+              sup = sup.superclass
+            end
+            chain.freeze
+          end
+      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,163 @@
+# frozen_string_literal: true
+
+module Markbridge
+  class Normalizer
+    # Maps a node and its ancestor stack to a strategy.
+    #
+    # Rules are keyed by +Class+ on both sides, and matching follows the
+    # class ancestry: a rule registered for a base class also applies to
+    # its subclasses, for the parent and for the child. Only classes
+    # inside the +AST::Node+ hierarchy take part; the walk never reaches
+    # +Object+, so a rule keyed on a class outside the AST never matches.
+    #
+    # Precedence, in this order:
+    # 1. Stack position — the outermost ancestor in the stack with any
+    #    matching rule wins.
+    # 2. Child class specificity — at that ancestor, a rule keyed on the
+    #    node's own class beats a rule keyed on a superclass.
+    # 3. Parent class specificity — then a rule keyed on the ancestor's
+    #    own class beats a rule keyed on a superclass.
+    #
+    # A rule registered for the exact +(parent, child)+ pair therefore
+    # always overrides an inherited one. Registering a rule for a 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
+
+      # Shared "no rule targets this class" marker, so the cache entry for
+      # a rule-less class costs no allocation.
+      EMPTY_CANDIDATES = [].freeze
+
+      def initialize
+        @by_parent = {} # parent_class => { child_class => strategy }
+        @child_classes = Set.new
+        # @candidates_cache stays unset (nil) until #freeze fills it.
+      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 with a rule that matches +child+'s class, or
+      # {NO_MATCH} (+[nil, nil]+) when nothing matches.
+      #
+      # +walk_cache+ caches the child-rule candidates per class. The caller owns
+      # it and should reuse one Hash for a whole tree walk, so each
+      # distinct class is analyzed at most once per walk. Keeping the
+      # cache outside the RuleSet leaves a frozen shared instance free of
+      # per-call state. The cache read is a single Hash lookup because this
+      # method runs for every node in the tree.
+      #
+      # @param child [AST::Node]
+      # @param ancestors [Array<AST::Element>] root-first ancestor stack
+      # @param walk_cache [Hash{Class => Array<Class>}] per-walk cache owned by
+      #   the caller
+      # @return [Array(Object, AST::Element), Array(nil, nil)]
+      def resolve(child, ancestors, walk_cache)
+        klass = child.class
+        # A frozen rule set carries a prebuilt candidates cache (see
+        # #freeze); the walk cache is only needed for classes defined after the
+        # freeze and for mutable rule sets.
+        frozen_cache = @candidates_cache
+        candidates =
+          (frozen_cache && frozen_cache[klass]) || (walk_cache[klass] ||= child_candidates(klass))
+        # 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 if candidates.empty?
+
+        scan_ancestors(candidates, 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.
+      #
+      # Freezing also precomputes the child-rule candidates for every AST
+      # class known at this point (+AST::Node.descendants+ is boot-time
+      # state), so {#resolve} on a frozen rule set answers with one Hash
+      # lookup instead of going through the per-walk cache. The rules can
+      # not change anymore, so the cache can never go stale; classes
+      # defined after the freeze fall back to the walk cache. The +||=+ keeps a
+      # second freeze from writing to the then-frozen instance. Like
+      # +@child_classes+, the cache Hash stays unfrozen — nothing writes
+      # to it after this point.
+      def freeze
+        @candidates_cache ||=
+          AST::Node.descendants.to_h { |klass| [klass, child_candidates(klass)] }
+        @by_parent.each_value(&:freeze)
+        @by_parent.freeze
+        super
+      end
+
+      private
+
+      # The ancestor scan behind {#resolve}: the outermost ancestor with any
+      # matching rule wins (precedence 1). {#best_rule} applies the class
+      # specificity order within one ancestor.
+      def scan_ancestors(candidates, ancestors)
+        ancestors.each do |ancestor|
+          strategy = best_rule(candidates, ancestor.class)
+          return strategy, ancestor if strategy
+        end
+        NO_MATCH
+      end
+
+      # The most specific rule at one ancestor: try each child candidate
+      # (the node's own class first — precedence 2), and for each walk the
+      # ancestor's class chain inside the AST (its own class first —
+      # precedence 3). An ancestor whose class is outside the AST has no
+      # chain and can never match. (+Module#<=+ is nil for an unrelated
+      # class, so the ternary — not an inverted guard — is the correct
+      # check here.)
+      def best_rule(candidates, ancestor_class)
+        chain = ancestor_class <= AST::Node ? ancestor_class.ast_chain : EMPTY_CANDIDATES
+        candidates.each do |child_class|
+          chain.each do |parent_class|
+            strategies = @by_parent[parent_class]
+            strategy = strategies[child_class] if strategies
+            return strategy if strategy
+          end
+        end
+        nil
+      end
+
+      # The classes in +klass+'s AST chain that at least one rule targets
+      # as a child, most specific class first (empty for most classes). A
+      # fresh walk cache sees every class once per document, so this allocates
+      # nothing unless there is a match. A class outside the AST has no
+      # chain and no candidates (+Module#<=+ is nil for an unrelated
+      # class, so the ternary — not an inverted guard — is the correct
+      # check here).
+      def child_candidates(klass)
+        chain = klass <= AST::Node ? klass.ast_chain : EMPTY_CANDIDATES
+        candidates = nil
+        chain.each { |current| (candidates ||= []) << current if @child_classes.include?(current) }
+        candidates || EMPTY_CANDIDATES
+      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,255 @@
+# 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
+        # Per-run cache for RuleSet#resolve's ancestry analysis. A Walker
+        # lives for one normalize call, so each distinct node class is
+        # analyzed at most once per run while the RuleSet itself stays
+        # free of per-call state.
+        @walk_cache = {}
+      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, @walk_cache)
+          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, @walk_cache)
+        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