markbridge 0.1.0

data/lib/markbridge/ast/poll.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a Discourse poll.
+    #
+    # @example Basic poll
+    #   poll = AST::Poll.new(
+    #     name: "poll",
+    #     type: "regular",
+    #     options: ["A", "B", "C"]
+    #   )
+    #
+    # @example Poll with all attributes
+    #   poll = AST::Poll.new(
+    #     name: "favorite-color",
+    #     type: "multiple",
+    #     results: "on_vote",
+    #     public: true,
+    #     chart_type: "pie",
+    #     options: ["Red", "Blue", "Green"],
+    #     raw: "[poll name=\"favorite-color\"]..."
+    #   )
+    class Poll < Node
+      # @return [String] the poll name/identifier
+      attr_reader :name
+
+      # @return [String, nil] poll type (regular, multiple, number)
+      attr_reader :type
+
+      # @return [String, nil] when to show results (always, on_vote, on_close, staff_only)
+      attr_reader :results
+
+      # @return [Boolean] whether votes are public
+      attr_reader :public
+
+      # @return [String, nil] chart type (bar, pie)
+      attr_reader :chart_type
+
+      # @return [Array<String>] poll options
+      attr_reader :options
+
+      # @return [String, nil] the original raw BBCode
+      attr_reader :raw
+
+      # Create a new Poll node.
+      #
+      # @param name [String] the poll name/identifier
+      # @param type [String, nil] poll type
+      # @param results [String, nil] when to show results
+      # @param public [Boolean] whether votes are public
+      # @param chart_type [String, nil] chart type
+      # @param options [Array<String>] poll options
+      # @param raw [String, nil] the original raw BBCode
+      def initialize(
+        name: "poll",
+        type: nil,
+        results: nil,
+        public: false,
+        chart_type: nil,
+        options: [],
+        raw: nil
+      )
+        @name = name
+        @type = type
+        @results = results
+        @public = public
+        @chart_type = chart_type
+        @options = options
+        @raw = raw
+      end
+    end
+  end
+end

data/lib/markbridge/ast/quote.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a quote/blockquote element.
+    #
+    # @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::Text.new("quoted text")
+    #
+    # @example Quote with full Discourse context
+    #   quote = AST::Quote.new(author: "John", post: "123", topic: "456", username: "john123")
+    #   quote << AST::Text.new("quoted text")
+    class Quote < Element
+      # @return [String, nil] the author/username of the quote
+      attr_reader :author
+
+      # @return [String, nil] the post ID for Discourse quotes
+      attr_reader :post
+
+      # @return [String, nil] the topic ID for Discourse quotes
+      attr_reader :topic
+
+      # @return [String, nil] the username for Discourse quotes
+      attr_reader :username
+
+      # 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)
+        super()
+        @author = author
+        @post = post
+        @topic = topic
+        @username = username
+      end
+    end
+  end
+end

data/lib/markbridge/ast/size.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents sized text.
+    # Note: Discourse doesn't support inline size changes by default,
+    # but this preserves size information for migration/custom rendering.
+    #
+    # @example Sized text
+    #   size = AST::Size.new(size: "20")
+    #   size << AST::Text.new("Big text")
+    class Size < Element
+      # @return [String, nil] the font size value
+      attr_reader :size
+
+      # Create a new Size element.
+      #
+      # @param size [String, nil] font size value
+      def initialize(size: nil)
+        super()
+        @size = size
+      end
+    end
+  end
+end

data/lib/markbridge/ast/spoiler.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a spoiler element (hidden content).
+    #
+    # @example Basic spoiler
+    #   spoiler = AST::Spoiler.new
+    #   spoiler << AST::Text.new("Hidden content")
+    #
+    # @example Spoiler with title
+    #   spoiler = AST::Spoiler.new(title: "Click to reveal")
+    #   spoiler << AST::Text.new("Hidden content")
+    class Spoiler < Element
+      # @return [String, nil] the spoiler title/label
+      attr_reader :title
+
+      # Create a new Spoiler element.
+      #
+      # @param title [String, nil] optional title for the spoiler
+      def initialize(title: nil)
+        super()
+        @title = title
+      end
+    end
+  end
+end

data/lib/markbridge/ast/strikethrough.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents strikethrough/deleted text formatting.
+    #
+    # @example
+    #   strikethrough = AST::Strikethrough.new
+    #   strikethrough << AST::Text.new("deleted text")
+    class Strikethrough < Element
+    end
+  end
+end

data/lib/markbridge/ast/subscript.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents subscript text (e.g., for chemical formulas).
+    #
+    # @example Subscript text
+    #   sub = AST::Subscript.new
+    #   sub << AST::Text.new("2")  # For H2O
+    class Subscript < Element
+    end
+  end
+end

data/lib/markbridge/ast/superscript.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents superscript text (e.g., for exponents).
+    #
+    # @example Superscript text
+    #   sup = AST::Superscript.new
+    #   sup << AST::Text.new("2")  # For x^2
+    class Superscript < Element
+    end
+  end
+end

data/lib/markbridge/ast/text.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a text node (leaf node) in the AST.
+    # Text nodes contain the actual text content and cannot have children.
+    #
+    # @example Creating a text node
+    #   text = AST::Text.new("Hello, world!")
+    #
+    # @example Merging text nodes
+    #   text1 = AST::Text.new("Hello")
+    #   text2 = AST::Text.new(" world")
+    #   text1.merge(text2)
+    #   text1.text # => "Hello world"
+    class Text < Node
+      # @return [String] the text content of this node
+      attr_reader :text
+
+      # Create a new text node with the given content.
+      #
+      # @param text [String] the text content
+      def initialize(text)
+        @text = +text
+      end
+
+      # Merge another text node's content into this one.
+      # This mutates the current text node by appending the other's text.
+      #
+      # @param other [Text] the text node to merge from
+      # @return [Text] self for method chaining
+      def merge(other)
+        @text << other.text
+        self
+      end
+    end
+  end
+end

data/lib/markbridge/ast/underline.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents underlined text formatting.
+    #
+    # @example
+    #   underline = AST::Underline.new
+    #   underline << AST::Text.new("underlined text")
+    class Underline < Element
+    end
+  end
+end

data/lib/markbridge/ast/upload.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a Discourse upload reference (image or file attachment).
+    # Uses the upload:// URL scheme.
+    #
+    # @example Image upload
+    #   upload = AST::Upload.new(
+    #     sha1: "RBhXLF6381Te3mneJQNnnyNNt5",
+    #     filename: "image.png",
+    #     type: :image,
+    #     alt: "My image",
+    #     dimensions: "64x64"
+    #   )
+    #
+    # @example File attachment
+    #   upload = AST::Upload.new(
+    #     sha1: "ppJp89TTiLOo6Vl4mAmo21MV28w",
+    #     filename: "document.pdf",
+    #     type: :attachment,
+    #     size: "502.1 KB"
+    #   )
+    class Upload < Node
+      # @return [String] the base62 SHA1 identifier from upload:// URL
+      attr_reader :sha1
+
+      # @return [String, nil] original filename
+      attr_reader :filename
+
+      # @return [Symbol] type of upload (:image or :attachment)
+      attr_reader :type
+
+      # @return [String, nil] alt text (for images)
+      attr_reader :alt
+
+      # @return [String, nil] dimensions string like "64x64" (for images)
+      attr_reader :dimensions
+
+      # @return [String, nil] file size string like "502.1 KB" (for attachments)
+      attr_reader :size
+
+      # @return [String, nil] the original raw Markdown
+      attr_reader :raw
+
+      # Create a new Upload node.
+      #
+      # @param sha1 [String] the base62 SHA1 identifier
+      # @param filename [String, nil] original filename
+      # @param type [Symbol] type of upload (:image or :attachment)
+      # @param alt [String, nil] alt text
+      # @param dimensions [String, nil] dimensions string
+      # @param size [String, nil] file size string
+      # @param raw [String, nil] the original raw Markdown
+      def initialize(
+        sha1:,
+        filename: nil,
+        type: :image,
+        alt: nil,
+        dimensions: nil,
+        size: nil,
+        raw: nil
+      )
+        @sha1 = sha1
+        @filename = filename
+        @type = type
+        @alt = alt
+        @dimensions = dimensions
+        @size = size
+        @raw = raw
+      end
+    end
+  end
+end

data/lib/markbridge/ast/url.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module AST
+    # Represents a hyperlink/URL element.
+    #
+    # @example URL with explicit href
+    #   url = AST::Url.new(href: "https://example.com")
+    #   url << AST::Text.new("Click here")
+    #
+    # @example URL with text as href
+    #   url = AST::Url.new(href: "https://example.com")
+    #   url << AST::Text.new("https://example.com")
+    class Url < Element
+      # @return [String, nil] the URL/href for this link
+      attr_reader :href
+
+      # Create a new URL element.
+      #
+      # @param href [String, nil] the URL/href for this link
+      def initialize(href: nil)
+        super()
+        @href = href
+      end
+    end
+  end
+end

data/lib/markbridge/ast.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# base / dependency order first
+require_relative "ast/node"
+require_relative "ast/element"
+require_relative "ast/document"
+
+require_relative "ast/align"
+require_relative "ast/attachment"
+require_relative "ast/bold"
+require_relative "ast/code"
+require_relative "ast/color"
+require_relative "ast/email"
+require_relative "ast/heading"
+require_relative "ast/horizontal_rule"
+require_relative "ast/image"
+require_relative "ast/italic"
+require_relative "ast/line_break"
+require_relative "ast/list"
+require_relative "ast/list_item"
+require_relative "ast/paragraph"
+require_relative "ast/quote"
+require_relative "ast/size"
+require_relative "ast/spoiler"
+require_relative "ast/strikethrough"
+require_relative "ast/subscript"
+require_relative "ast/superscript"
+require_relative "ast/text"
+require_relative "ast/markdown_text"
+require_relative "ast/underline"
+require_relative "ast/url"
+
+# Discourse-specific nodes
+require_relative "ast/event"
+require_relative "ast/mention"
+require_relative "ast/poll"
+require_relative "ast/upload"
+
+module Markbridge
+  module AST
+  end
+end

data/lib/markbridge/configuration.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Markbridge
+  class Configuration
+    attr_accessor :escape_hard_line_breaks
+
+    def initialize
+      @escape_hard_line_breaks = false
+    end
+  end
+end

data/lib/markbridge/gem_loader.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module GemLoader
+    class << self
+      def require_gem(gem, feature:)
+        require gem.to_s
+      rescue LoadError
+        raise LoadError, missing_message(gem, feature)
+      end
+
+      private
+
+      def missing_message(gem, feature)
+        gem_name = gem.to_s
+        [
+          "#{gem_name.capitalize} is required for #{feature}.",
+          "Add 'gem \"#{gem_name}\"' to your Gemfile or install it with 'gem install #{gem_name}'.",
+        ].join(" ")
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/closing_strategies/base.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+module Markbridge
+  module Parsers
+    module BBCode
+      module ClosingStrategies
+        class Base
+          def initialize(reconciler)
+            @reconciler = reconciler
+          end
+
+          def handle_close(token:, context:, registry:, tokens: nil)
+            return unless context.current.is_a?(AST::Element)
+
+            current_handler = registry.handler_for_element(context.current)
+            closing_handler = registry[token.tag]
+
+            if current_handler == closing_handler
+              context.pop
+            elsif try_reorder(context:, tokens:, closing_handler:)
+              # Reordering handled
+            elsif @reconciler.try_auto_close(handler: closing_handler, context:)
+              # Auto-close succeeded
+            else
+              context.add_child(AST::Text.new(token.source))
+            end
+          end
+
+          private
+
+          def try_reorder(context:, tokens:, closing_handler:)
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/closing_strategies/reordering.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+module Markbridge
+  module Parsers
+    module BBCode
+      module ClosingStrategies
+        class Reordering < Base
+          private
+
+          def try_reorder(context:, tokens:, closing_handler:)
+            return false unless tokens
+            @reconciler.try_reorder(handler: closing_handler, tokens:, context:)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/closing_strategies/strict.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+module Markbridge
+  module Parsers
+    module BBCode
+      module ClosingStrategies
+        class Strict < Base
+          # Inherits Base#handle_close; no changes required for strict behavior
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/closing_strategies/tag_reconciler.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      module ClosingStrategies
+        # Encapsulates logic for reconciling mismatched closing tags
+        class TagReconciler
+          MAX_AUTO_CLOSE_DEPTH = 5
+
+          def initialize(registry:)
+            @registry = registry
+          end
+
+          # Attempt to auto-close tags to match a closing tag
+          #
+          # @param handler [BaseHandler] the handler for the closing tag
+          # @param context [ParserState]
+          # @return [Boolean] true if successful, false if auto-close not possible
+          def try_auto_close(handler:, context:)
+            match_depth = find_matching_handler_depth(handler, context)
+
+            return false if match_depth.nil? || match_depth >= MAX_AUTO_CLOSE_DEPTH
+            return false unless all_auto_closeable?(context, match_depth)
+
+            count = match_depth + 1
+            count.times { context.pop }
+            context.auto_close!(count)
+
+            true
+          end
+
+          # Attempt to reorder closing tags
+          #
+          # @param handler [BaseHandler] the handler for the closing tag
+          # @param tokens [Object] the token stream
+          # @param context [ParserState]
+          # @return [Boolean] true if successful, false otherwise
+          def try_reorder(handler:, tokens:, context:)
+            match_depth = find_matching_handler_depth(handler, context)
+            return false if match_depth.nil? || match_depth >= MAX_AUTO_CLOSE_DEPTH
+
+            opening_handlers = collect_auto_closeable_handlers(context, match_depth)
+            return false if opening_handlers.empty?
+
+            closing_handlers = [handler]
+            closing_handlers.concat(peek_closing_handlers(tokens, opening_handlers.size - 1))
+            return false if closing_handlers.size != opening_handlers.size
+            unless opening_handlers.sort_by(&:object_id) == closing_handlers.sort_by(&:object_id)
+              return false
+            end
+
+            # Consume the extra closing tags
+            (opening_handlers.size - 1).times do
+              peeked = tokens.peek
+              break unless peeked.is_a?(TagEndToken)
+              tokens.next
+            end
+
+            opening_handlers.each { context.pop }
+            context.auto_close!(opening_handlers.size)
+
+            true
+          end
+
+          private
+
+          def find_matching_handler_depth(handler, context)
+            elements = context.elements_from_current(MAX_AUTO_CLOSE_DEPTH)
+
+            elements.each_with_index do |element, depth|
+              next unless element.is_a?(AST::Element)
+
+              element_handler = @registry.handler_for_element(element)
+              return depth if element_handler == handler
+            end
+
+            nil
+          end
+
+          def all_auto_closeable?(context, target_depth)
+            context
+              .elements_from_current(target_depth)
+              .all? { |element| @registry.auto_closeable?(element.class) }
+          end
+
+          def collect_auto_closeable_handlers(context, target_depth)
+            handlers = []
+
+            context
+              .elements_from_current(target_depth)
+              .each do |element|
+                return [] unless @registry.auto_closeable?(element.class)
+
+                handler = @registry.handler_for_element(element)
+                handlers << handler if handler
+              end
+
+            handlers
+          end
+
+          def peek_closing_handlers(tokens, max_count)
+            handlers = []
+            peeked_tokens = tokens.peek_ahead(max_count)
+
+            peeked_tokens.each do |token|
+              break unless token.is_a?(TagEndToken)
+
+              handler = @registry[token.tag]
+              break unless handler
+
+              handlers << handler
+            end
+
+            handlers
+          end
+        end
+      end
+    end
+  end
+end

data/lib/markbridge/parsers/bbcode/errors/max_depth_exceeded_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Markbridge
+  module Parsers
+    module BBCode
+      class MaxDepthExceededError < StandardError
+        def initialize(max)
+          super("maximum parsing depth (#{max}) exceeded")
+        end
+      end
+    end
+  end
+end