coradoc-mirror 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 000b9fd36ba19db9a57b3ad656292b1629eb82a12e7004add2e97b7823060e19
-  data.tar.gz: f5364e581508705701aac01de53a2d03371213a4224356d4343f197aa37edab0
+  metadata.gz: ec671d9e6bbd3654635451d5a9ae2284f7e778f313b56e4e8d87e237e853b15e
+  data.tar.gz: 51f63185d93bda861e6f545fdd4bceb0e07a9516db1d8d51011fda4e08236b35
 SHA512:
-  metadata.gz: 8bcd0570c09daf184700080579a5cb17c54a2cccc16d8afb95b3f0598d644d5f5b14790c81024fafdb8306720170ae1e9ddeda893f111446e854b03effcb6826
-  data.tar.gz: f40e562805ca5466db7847773f7386c8709471c8aa4acbfbc4971db7e8255ede4b32e54b42cec361fa517cd31b1fbed1f283e6c01c3efadcf29ea1b33e75112f
+  metadata.gz: 40d4b935ed85cdfb2a0d4845807df32367541498c4921879d5875194f8c1572402ad7bd809055cdb285b9ea2b7457c1847c8039c861c88db9c5094ea42d6edfa
+  data.tar.gz: 91b105b79f7eef2230869c1cc386d0ec105b08346a36e66f4e18e95b6931a66382ae786910c9d6bc72c04e287dd9f856a38cc569dadfe3a9f2304f710186e0f7

data/lib/coradoc/mirror/handler_registry.rb

@@ -8,6 +8,10 @@ module Coradoc
     # Third-party gems can register additional handlers without modifying
     # core classes (OCP).
     #
+    # Lookup (including ancestor walking) is delegated to
+    # `Coradoc::Dispatch.hierarchical`. This class keeps the Entry shape and
+    # the handler-invocation semantics — those are mirror-specific.
+    #
     # @example Registering a handler
     #   registry = Coradoc::Mirror.default_registry
     #   registry.register(MyCustomBlock, MyHandler)
@@ -17,12 +21,11 @@ module Coradoc
     #   registry.register(Coradoc::CoreModel::ParagraphBlock, MyParagraphHandler)
     #
     class HandlerRegistry
-      # Structured entry for a registered handler.
       Entry = Struct.new(:handler, :method_name, :concat, :extra_kwargs,
                          keyword_init: true)
 
       def initialize
-        @handlers = {}
+        @dispatch = Coradoc::Dispatch.hierarchical
       end
 
       # Register a handler for a CoreModel class.
@@ -38,46 +41,32 @@ module Coradoc
       #   to the handler
       def register(model_class, handler, method_name: :call, concat: false,
                    extra_kwargs: {})
-        @handlers[model_class] = Entry.new(
-          handler: handler,
-          method_name: method_name,
-          concat: concat,
-          extra_kwargs: extra_kwargs
+        @dispatch.register(
+          model_class,
+          Entry.new(
+            handler: handler,
+            method_name: method_name,
+            concat: concat,
+            extra_kwargs: extra_kwargs
+          )
         )
       end
 
       # Find the handler entry for a given CoreModel element.
       #
-      # Walks the element's class ancestors to find the most specific
-      # registered handler. This allows registering a handler for a
-      # base class (e.g., Block) that applies to all subclasses,
-      # while also registering specific handlers for subclasses.
+      # Walks the element's class ancestors (via Dispatch.hierarchical) to
+      # find the most specific registered handler. This allows registering
+      # a handler for a base class (e.g., Block) that applies to all
+      # subclasses, while also registering specific handlers for subclasses.
       #
       # @param element [CoreModel::Base] element to find handler for
       # @return [Entry, nil]
-      TERMINAL_ANCESTORS = [Object, BasicObject].freeze
-
       def entry_for(element)
-        entry = @handlers[element.class]
-        return entry if entry
-
-        element.class.ancestors.each do |ancestor|
-          next if ancestor == element.class
-          break if TERMINAL_ANCESTORS.include?(ancestor)
-
-          entry = @handlers[ancestor]
-          return entry if entry
-        end
-
-        nil
+        @dispatch.lookup(element.class)
       end
 
-      # Check if a handler is registered for a CoreModel class.
-      #
-      # @param model_class [Class]
-      # @return [Boolean]
       def registered?(model_class)
-        @handlers.key?(model_class)
+        @dispatch.registered?(model_class)
       end
 
       # Invoke the handler for a given element.

data/lib/coradoc/mirror/handlers/code_block.rb

@@ -5,49 +5,42 @@ module Coradoc
     module Handlers
       module CodeBlock
         def self.source(element, context:)
-          build_code_block(element, context)
+          build_code_block(element, context, node_class: Node::CodeBlock)
         end
 
         def self.listing(element, context:)
-          build_code_block(element, context)
+          build_code_block(element, context, node_class: Node::CodeBlock)
         end
 
         def self.literal(element, context:)
-          build_code_block(element, context)
+          build_code_block(element, context, node_class: Node::LiteralBlock)
         end
 
         def self.pass(element, context:)
-          build_code_block(element, context, passthrough: true)
+          build_code_block(element, context, node_class: Node::PassBlock, passthrough: true)
+        end
+
+        def self.stem(element, context:)
+          build_code_block(element, context, node_class: Node::StemBlock)
         end
 
         class << self
           private
 
-          def build_code_block(element, context, passthrough: false)
+          def build_code_block(element, context, node_class:, passthrough: false)
             text = extract_text(element)
             js_mode = context.partition_structural
+            attrs = Node::CodeBlock::Attrs.new(
+              title: element.title,
+              language: element.language,
+              passthrough: passthrough || nil,
+              text: js_mode ? text : nil
+            )
 
             if js_mode
-              # @metanorma/mirror JS sourcecode contract: text in attrs.text,
-              # no children. Pre-formatted text rendered via <pre><code>.
-              Node::CodeBlock.new(
-                attrs: Node::CodeBlock::Attrs.new(
-                  title: element.title,
-                  language: element.language,
-                  passthrough: passthrough || nil,
-                  text: text
-                ),
-                content: []
-              )
+              node_class.new(attrs: attrs, content: [])
             else
-              Node::CodeBlock.new(
-                attrs: Node::CodeBlock::Attrs.new(
-                  title: element.title,
-                  language: element.language,
-                  passthrough: passthrough || nil
-                ),
-                content: [context.text_node(text)]
-              )
+              node_class.new(attrs: attrs, content: [context.text_node(text)])
             end
           end
 

data/lib/coradoc/mirror/handlers/inline.rb

@@ -106,6 +106,8 @@ module Coradoc
               Node::SoftBreak.new
             when CoreModel::TextElement
               build_text_only(element, context)
+            when CoreModel::RawInlineElement
+              build_raw_inline(element, context)
             when CoreModel::InlineElement
               handle_generic_inline(element, context)
             end
@@ -189,6 +191,18 @@ module Coradoc
             context.text_node(text)
           end
 
+          # Passthrough content carries its own raw output-format markup
+          # (HTML, XML, etc.). Emit a typed RawInline node so renderers
+          # can skip escaping unambiguously — never a plain text node,
+          # which would force every downstream consumer to choose between
+          # XSS risk and visible literal markup.
+          def build_raw_inline(element, _context)
+            text = element.content.to_s
+            return nil if text.empty?
+
+            Node::RawInline.new(text: text)
+          end
+
           def extract_inline_text(element)
             return element.content.to_s if element.content && !element.content.to_s.empty?
 

data/lib/coradoc/mirror/node.rb

@@ -162,6 +162,25 @@ module Coradoc
         end
       end
 
+      # Raw inline passthrough — content the source format marked as "do
+      # not process, emit verbatim." Distinct from `text` so renderers can
+      # skip escaping without sniffing content for `<...>`. AsciiDoc's
+      # `+++raw+++` is the canonical producer.
+      class RawInline < Node
+        PM_TYPE = 'raw_inline'
+
+        attribute :text, :string
+
+        key_value do
+          map 'type', to: :type, render_default: true
+          map 'text', to: :text
+        end
+
+        def text_content
+          text.to_s
+        end
+      end
+
       # ── Paragraph / block text ──
 
       class Paragraph < Node
@@ -200,6 +219,26 @@ module Coradoc
         end
       end
 
+      # Literal block — preformatted text (`....` delimiter). Same shape
+      # as CodeBlock but distinguished on the wire so consumers can apply
+      # literal-vs-source rendering/styling.
+      class LiteralBlock < CodeBlock
+        PM_TYPE = 'literal'
+      end
+
+      # Pass block — raw passthrough content (`++++` delimiter). Same
+      # shape as CodeBlock; flagged via attrs.passthrough = true.
+      class PassBlock < CodeBlock
+        PM_TYPE = 'pass'
+      end
+
+      # STEM block — mathematical/scientific markup (`[stem|latexmath|
+      # asciimath]\n++++`). Carries a +language+ attr ('latex' default,
+      # 'asciimath' alternative).
+      class StemBlock < CodeBlock
+        PM_TYPE = 'stem'
+      end
+
       class Blockquote < Node
         PM_TYPE = 'quote'
 

data/lib/coradoc/mirror/reverse_builder/admonition.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      class Admonition < Base
+        registers 'admonition'
+
+        def build(node)
+          CoreModel::AnnotationBlock.new(
+            annotation_type: node.attrs&.admonition_type,
+            content: extract_text(node)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/base.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      # Base class for all reverse builders. Subclasses register one or
+      # more Mirror type strings via `registers` and implement `#build`.
+      # Shared helpers (build_content, extract_text, apply_mark, ...) are
+      # delegated to the context (a MirrorToCoreModel instance), keeping
+      # each builder focused on the per-type mapping only (DRY).
+      class Base
+        attr_reader :context
+
+        def initialize(context)
+          @context = context
+        end
+
+        def build(_node)
+          raise NotImplementedError,
+                "#{self.class} must implement #build(node)"
+        end
+
+        # Shared helpers — all delegate to the context (DRY).
+        def build_content(node) = context.build_content(node)
+        def build_inline_children(node) = context.build_inline_children(node)
+        def build_node(node)            = context.build_node(node)
+        def extract_text(node)          = context.extract_text(node)
+        def apply_mark(inner, mark)     = context.apply_mark(inner, mark)
+        def inline_content(element)     = context.inline_content(element)
+
+        class << self
+          # DSL: declare which Mirror type strings this builder handles.
+          # Multiple strings per builder are allowed (e.g. all JS
+          # SECTION_TYPES route to the same SectionElement builder).
+          def registers(*types)
+            types.each { |t| ReverseBuilder.register(t, self) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/biblio_entry.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      class BiblioEntry < Base
+        registers 'biblio_entry'
+
+        def build(node)
+          attrs = node.attrs
+          CoreModel::BibliographyEntry.new(
+            anchor_name: attrs&.anchor_name,
+            document_id: attrs&.document_id,
+            ref_text: extract_text(node)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/bibliography.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      class Bibliography < Base
+        registers 'bibliography'
+
+        def build(node)
+          entries = build_content(node).select { |c| c.is_a?(CoreModel::BibliographyEntry) }
+          CoreModel::Bibliography.new(title: node.attrs&.title, entries: entries)
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/blockquote.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      class Blockquote < Base
+        registers 'quote'
+
+        def build(node)
+          CoreModel::QuoteBlock.new(
+            attribution: node.attrs&.attribution,
+            children: build_content(node)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/bullet_list.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      class BulletList < Base
+        registers 'bullet_list'
+
+        def build(node)
+          items = build_content(node).select { |c| c.is_a?(CoreModel::ListItem) }
+          CoreModel::ListBlock.new(marker_type: 'unordered', items: items)
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/caption.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      # Caption only appears as a Figure child. If encountered standalone,
+      # extract its text as an inline element so it isn't lost.
+      class Caption < Base
+        registers 'caption'
+
+        def build(node)
+          CoreModel::InlineElement.new(content: extract_text(node))
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/code_block.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      class CodeBlock < Base
+        registers 'sourcecode'
+
+        def build(node)
+          attrs = node.attrs
+          CoreModel::SourceBlock.new(
+            content: attrs&.text || extract_text(node),
+            language: attrs&.language,
+            title: attrs&.title
+          )
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/definition_list.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      class DefinitionList < Base
+        registers 'dl'
+
+        def build(node)
+          terms = []
+          descriptions = []
+          node.content&.each do |child|
+            next unless child.is_a?(Node)
+
+            case child.type
+            when 'dt' then terms << build_node(child)
+            when 'dd' then descriptions << build_node(child)
+            end
+          end
+
+          items = terms.zip(descriptions).map do |term, desc|
+            CoreModel::DefinitionItem.new(
+              term: inline_content(term),
+              definitions: [inline_content(desc)]
+            )
+          end
+
+          CoreModel::DefinitionList.new(items: items)
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/document.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      class Document < Base
+        registers 'doc'
+
+        def build(node)
+          attrs = node.attrs
+          CoreModel::DocumentElement.new(
+            title: attrs&.title,
+            id: attrs&.id,
+            children: build_content(node)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/example.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      class Example < Base
+        registers 'example'
+
+        def build(node)
+          CoreModel::ExampleBlock.new(
+            title: node.attrs&.title,
+            children: build_content(node)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/figure.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      # JS @metanorma/mirror `figure` wraps an image plus an optional
+      # caption. Reverse: collapse back to a single CoreModel::Image,
+      # promoting the caption child to `caption:` if present.
+      class Figure < Base
+        registers 'figure'
+
+        def build(node)
+          image_child = node.content&.find { |c| c.is_a?(Node) && c.type == 'image' }
+          return nil unless image_child
+
+          image = build_node(image_child)
+          caption = extract_caption(node)
+          image.caption = caption if caption && !image.caption
+          image
+        end
+
+        private
+
+        def extract_caption(node)
+          caption_node = node.content&.find { |c| c.is_a?(Node) && c.type == 'caption' }
+          return nil unless caption_node
+
+          extract_text(caption_node)
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/footnote_entry.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      class FootnoteEntry < Base
+        registers 'footnote_entry'
+
+        def build(node)
+          attrs = node.attrs
+          CoreModel::Footnote.new(id: attrs&.id, content: extract_text(node))
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/footnote_marker.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      # Inline footnote marker (JS `footnote_marker`). The CoreModel
+      # FootnoteReference holds the same id/ref/number triple.
+      class FootnoteMarker < Base
+        registers 'footnote_marker'
+
+        def build(node)
+          attrs = node.attrs
+          CoreModel::FootnoteReference.new(
+            id: attrs&.id,
+            reference: attrs&.ref_id,
+            number: attrs&.number
+          )
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/footnotes.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      # The `footnotes` block is a structural trailing container; it has
+      # no CoreModel equivalent (each entry is built separately). Returns
+      # nil so build_content filters it out.
+      class Footnotes < Base
+        registers 'footnotes'
+
+        def build(_node)
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/frontmatter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      class Frontmatter < Base
+        registers 'frontmatter'
+
+        def build(node)
+          attrs = node.attrs
+          CoreModel::FrontmatterBlock.new(
+            schema: attrs&.schema,
+            data: FrontmatterTreeToHash.to_hash(attrs&.entries || [])
+          )
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/reverse_builder/generic_block.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Coradoc
+  module Mirror
+    module ReverseBuilder
+      # Catch-all for unrecognized block types emitted by the forward
+      # direction (`Node::GenericBlock`). Preserves the semantic_type so
+      # downstream consumers can dispatch on it.
+      class GenericBlock < Base
+        registers 'generic_block'
+
+        def build(node)
+          attrs = node.attrs
+          CoreModel::Block.new(
+            block_semantic_type: attrs&.semantic_type || 'generic',
+            title: attrs&.title,
+            id: attrs&.id,
+            content: extract_text(node)
+          )
+        end
+      end
+    end
+  end
+end