coradoc-mirror 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ac58d41a9214d72f32b3bcc107ddaf463c772598cd9be21e267c56b4dcfee8e
+  data.tar.gz: bfd5bce725a65f86cf449cd4e59e9c78539968742237b002d2726dfdc3b37f52
+SHA512:
+  metadata.gz: 264dba99b8eecd0e218f52d30dd6498a21b5248c640e837dc5ee4140df6b6f64e7416f75b6c8905c032d4c5fa9a078fbfdfc026c1b3160f0f943f930e5ff6e61
+  data.tar.gz: 51639279c428a6e1d1707bb922bd6da2d59576e96d0cfc7d266eef3de96281e3b2dca61fa63afee3fd3bf920799c7258fc1e40ab59782ee6ec06a5dbe2626340

data/lib/coradoc/mirror/core_model_to_mirror.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    # Transforms CoreModel documents into ProseMirror-compatible Mirror nodes.
+    #
+    # Uses a HandlerRegistry for OCP-compliant dispatch: each CoreModel type
+    # maps to a handler module/class that produces the corresponding Mirror node.
+    class CoreModelToMirror
+      attr_reader :registry
+
+      # Typed struct for pending footnote data (model-driven, not hash bags).
+      FootnoteData = Struct.new(:id, :ref_id, :number, :content, keyword_init: true)
+
+      # Maps element types to their children accessors.
+      COLLECTION_ACCESSORS = {
+        CoreModel::ListBlock => :items,
+        CoreModel::DefinitionList => :items,
+        CoreModel::Table => :rows,
+        CoreModel::Bibliography => :entries
+      }.freeze
+
+      def initialize(registry: Coradoc::Mirror.default_registry)
+        @registry = registry
+        @footnote_counter = 0
+        @footnotes = []
+        @partition_structural = false
+      end
+
+      # Read by Handlers::Structural.section to decide whether to emit
+      # generic `section` (legacy) or a JS SECTION_TYPE (`clause`, `annex`,
+      # etc.) when partition_structural mode is on.
+      attr_accessor :partition_structural
+
+      def call(document, partition_structural: false)
+        @footnote_counter = 0
+        @footnotes = []
+        @partition_structural = partition_structural
+
+        content = extract_content(document)
+        fn_block = flush_footnotes
+        content << fn_block if fn_block
+
+        attrs = build_document_attrs(document)
+        Node::Document.new(
+          attrs: Node::Document::Attrs.new(title: attrs[:title], id: attrs[:id]),
+          content: partition_structural ? wrap_structural(content) : content
+        )
+      end
+
+      # Partitions flat doc children into [preface?, sections?, *bibliography,
+      # *trailing] per the @metanorma/mirror JS structural contract. See
+      # Partitioner for the bucketing rules.
+      def wrap_structural(children)
+        partitioned = Partitioner.partition(children)
+        wrapped = []
+        wrapped << Node::Preamble.new(content: partitioned[:preface]) if partitioned[:preface].any?
+        wrapped << Node::Sections.new(content: partitioned[:sections]) if partitioned[:sections].any?
+        wrapped.concat(partitioned[:bibliography])
+        wrapped.concat(partitioned[:trailing])
+        wrapped
+      end
+
+      def extract_content(element)
+        children = element_children(element)
+
+        if children && !children.empty?
+          content = []
+          children.each { |child| handle_element(child, content) }
+          content.compact
+        elsif element_has_text_content?(element)
+          process_inline_content(element)
+        else
+          []
+        end
+      end
+
+      def process_inline_content(element)
+        Handlers::Inline.process(element, context: self)
+      end
+
+      def text_node(text, marks: [])
+        Node::Text.new(text: text, marks: marks)
+      end
+
+      def register_footnote(footnote)
+        @footnote_counter += 1
+        num = @footnote_counter
+        fn_id = footnote.id || "fn-#{num}"
+        ref_id = "fn-ref-#{num}"
+
+        fn_content = footnote.content ? [text_node(footnote.content)] : []
+        @footnotes << FootnoteData.new(
+          id: fn_id, ref_id: ref_id, number: num, content: fn_content
+        )
+
+        Node::FootnoteMarker.new(
+          attrs: Node::FootnoteMarker::Attrs.new(
+            id: fn_id, ref_id: ref_id, number: num
+          )
+        )
+      end
+
+      def resolve_footnote_reference(ref)
+        target_id = ref.id
+        entry = @footnotes.find { |fn| fn.id == target_id } if target_id
+
+        if entry
+          Node::FootnoteMarker.new(
+            attrs: Node::FootnoteMarker::Attrs.new(
+              id: entry.id,
+              ref_id: "fn-ref-#{entry.number}-dup-#{@footnote_counter}",
+              number: entry.number
+            )
+          )
+        else
+          text_node("[#{target_id || 'footnote'}]")
+        end
+      end
+
+      def flush_footnotes
+        return nil if @footnotes.empty?
+
+        entries = @footnotes.map do |fn|
+          Node::FootnoteEntry.new(
+            attrs: Node::FootnoteEntry::Attrs.new(
+              id: fn.id, ref_id: fn.ref_id, number: fn.number
+            ),
+            content: fn.content
+          )
+        end
+
+        @footnotes = []
+        Node::Footnotes.new(content: entries)
+      end
+
+      private
+
+      def element_has_text_content?(element)
+        element.is_a?(CoreModel::Block) &&
+          element.content &&
+          !element.content.to_s.empty?
+      end
+
+      def element_children(element)
+        if element.is_a?(Coradoc::CoreModel::HasChildren)
+          children = element.children
+          return children if children && !children.empty?
+        end
+
+        accessor = COLLECTION_ACCESSORS[element.class]
+        element.public_send(accessor) if accessor
+      end
+
+      def handle_element(element, content)
+        result = @registry.handle(element, context: self)
+        return unless result
+
+        value, concat = result
+        return unless value
+
+        concat ? content.concat(Array(value)) : content << value
+      end
+
+      def build_document_attrs(document)
+        attrs = {}
+        attrs[:title] = document.title if document.title
+        attrs[:id] = document.id if document.id
+
+        if document.is_a?(CoreModel::DocumentElement) &&
+           document.attributes.is_a?(CoreModel::Metadata)
+          document.attributes.entries&.each do |entry|
+            attrs[entry.key.to_sym] = entry.value
+          end
+        end
+
+        attrs
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/handler_registry.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    # Open registry mapping CoreModel classes to handler modules.
+    #
+    # Replaces closed case/when dispatch with an extensible registry.
+    # Third-party gems can register additional handlers without modifying
+    # core classes (OCP).
+    #
+    # @example Registering a handler
+    #   registry = Coradoc::Mirror.default_registry
+    #   registry.register(MyCustomBlock, MyHandler)
+    #
+    # @example Creating a custom registry
+    #   registry = Coradoc::Mirror::HandlerRegistry.new
+    #   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 = {}
+      end
+
+      # Register a handler for a CoreModel class.
+      #
+      # @param model_class [Class] CoreModel class to handle
+      # @param handler [Module, Class, Proc] handler implementation.
+      #   If a Module/Class, +method_name+ is called on it.
+      #   If a Proc, called directly with (element, context:).
+      # @param method_name [Symbol] method to call on handler (default: :call)
+      # @param concat [Boolean] if true, handler result is an array to
+      #   concat into content rather than a single item to append
+      # @param extra_kwargs [Hash] additional keyword arguments passed
+      #   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
+        )
+      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.
+      #
+      # @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
+      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)
+      end
+
+      # Invoke the handler for a given element.
+      #
+      # @param element [CoreModel::Base] element to handle
+      # @param context [CoreModelToMirror] transformer context
+      # @return [Array(result, concat_flag), nil] handler result or nil
+      def handle(element, context:)
+        entry = entry_for(element)
+        return nil unless entry
+
+        kwargs = { context: context }.merge(entry.extra_kwargs || {})
+
+        result = case entry.handler
+                 when Proc
+                   entry.handler.call(element, context)
+                 else
+                   entry.handler.public_send(entry.method_name, element, **kwargs)
+                 end
+
+        [result, entry.concat]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    module Handlers
+      # Admonition (NOTE, TIP, WARNING, CAUTION, IMPORTANT) handler.
+      #
+      # Emits a dialect-agnostic `Node::Admonition`. The canonical Ruby
+      # attribute is `admonition_type`; the model renames it to the wire
+      # name `type` on #to_h unconditionally. No flag, no dialect branch.
+      module Admonition
+        def self.call(element, context:)
+          content = context.extract_content(element)
+          return nil if content.empty?
+
+          Node::Admonition.new(
+            attrs: Node::Admonition::Attrs.new(
+              admonition_type: element.annotation_type,
+              title: element.title,
+              label: element.annotation_label,
+              id: element.id
+            ),
+            content: content
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    module Handlers
+      module Bibliography
+        def self.call(element, context:)
+          entries = Array(element.entries).filter_map do |entry|
+            build_entry(entry, context)
+          end
+          return nil if entries.empty?
+
+          Node::Bibliography.new(
+            attrs: Node::Bibliography::Attrs.new(
+              id: element.id,
+              title: element.title,
+              level: element.level
+            ),
+            content: entries
+          )
+        end
+
+        class << self
+          private
+
+          def build_entry(entry, context)
+            text = entry.display_text
+            return nil if text.nil? || text.empty?
+
+            Node::BibliographyEntry.new(
+              attrs: Node::BibliographyEntry::Attrs.new(
+                anchor_name: entry.anchor_name,
+                document_id: entry.document_id,
+                url: entry.url
+              ),
+              content: [context.text_node(text)]
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    module Handlers
+      module Blockquote
+        def self.call(element, context:)
+          content = context.extract_content(element)
+          return nil if content.empty?
+
+          Node::Blockquote.new(
+            attrs: Node::Blockquote::Attrs.new(attribution: element.attribution),
+            content: content
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    module Handlers
+      module CodeBlock
+        def self.source(element, context:)
+          build_code_block(element, context)
+        end
+
+        def self.listing(element, context:)
+          build_code_block(element, context)
+        end
+
+        def self.literal(element, context:)
+          build_code_block(element, context)
+        end
+
+        def self.pass(element, context:)
+          build_code_block(element, context, passthrough: true)
+        end
+
+        class << self
+          private
+
+          def build_code_block(element, context, passthrough: false)
+            text = extract_text(element)
+            js_mode = context.partition_structural
+
+            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: []
+              )
+            else
+              Node::CodeBlock.new(
+                attrs: Node::CodeBlock::Attrs.new(
+                  title: element.title,
+                  language: element.language,
+                  passthrough: passthrough || nil
+                ),
+                content: [context.text_node(text)]
+              )
+            end
+          end
+
+          def extract_text(element)
+            return '' unless element.is_a?(CoreModel::Block)
+
+            if element.content && !element.content.to_s.empty?
+              element.flat_text || element.content.to_s
+            elsif element.lines && !element.lines.empty?
+              Array(element.lines).join("\n")
+            else
+              ''
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    module Handlers
+      # Handles CommentBlock → omitted (comments are not rendered).
+      module Comment
+        def self.call(_element, *)
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    module Handlers
+      module DefinitionList
+        def self.call(element, context:)
+          entries = Array(element.items).flat_map do |item|
+            definition_entry(item, context)
+          end
+          return nil if entries.empty?
+
+          Node::DefinitionList.new(
+            attrs: Node::DefinitionList::Attrs.new(id: element.id),
+            content: entries
+          )
+        end
+
+        class << self
+          private
+
+          def definition_entry(item, context)
+            term_node = build_term(item, context)
+            desc_node = build_description(item, context)
+            return nil unless term_node || desc_node
+
+            [term_node, desc_node].compact
+          end
+
+          def build_term(item, context)
+            term_text = item.term
+            return nil unless term_text && !term_text.to_s.empty?
+
+            term_children = item.term_children if item.is_a?(CoreModel::DefinitionItem)
+            if term_children && !term_children.empty?
+              inline_nodes = term_children.flat_map do |child|
+                Handlers::Inline.process_child(child, context)
+              end
+              return Node::DefinitionTerm.new(content: inline_nodes) unless inline_nodes.empty?
+            end
+
+            Node::DefinitionTerm.new(content: [context.text_node(term_text.to_s)])
+          end
+
+          def build_description(item, context)
+            definitions = item.definitions
+            return nil unless definitions && !definitions.empty?
+
+            desc_nodes = definitions.map do |defn|
+              context.text_node(defn.to_s)
+            end
+
+            def_children = item.definition_children if item.is_a?(CoreModel::DefinitionItem)
+            if def_children && !def_children.empty?
+              def_children.each do |child|
+                nodes = Handlers::Inline.process_child(child, context)
+                desc_nodes.concat(Array(nodes)) if nodes && !nodes.empty?
+              end
+            end
+
+            return nil if desc_nodes.empty?
+
+            Node::DefinitionDescription.new(content: desc_nodes)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    module Handlers
+      module Example
+        def self.call(element, context:)
+          content = context.extract_content(element)
+          return nil if content.empty?
+
+          Node::Example.new(
+            attrs: Node::Example::Attrs.new(id: element.id, title: element.title),
+            content: content
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    module Handlers
+      # Handles Footnote and FootnoteReference.
+      module Footnote
+        def self.call(element, context:)
+          context.register_footnote(element)
+        end
+
+        def self.reference(element, context:)
+          context.resolve_footnote_reference(element)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    module Handlers
+      # Handles FrontmatterBlock → frontmatter node.
+      #
+      # Walks the CoreModel +data+ hash and builds a typed tree of
+      # FrontmatterEntry / FrontmatterValue nodes. Dates/times are ISO
+      # 8601-encoded so the wire shape is JSON-native.
+      module Frontmatter
+        def self.call(element, *)
+          entries = build_entries(element.data || {})
+
+          Node::Frontmatter.new(
+            attrs: Node::Frontmatter::Attrs.new(
+              schema: element.schema,
+              entries: entries
+            )
+          )
+        end
+
+        class << self
+          private
+
+          def build_entries(data)
+            data.map { |key, value| build_entry(key.to_s, value) }
+          end
+
+          def build_entry(key, value)
+            Node::FrontmatterEntry.new(
+              key: key,
+              value: build_value(value)
+            )
+          end
+
+          def build_value(value)
+            case value
+            when Hash
+              Node::FrontmatterValue.new(
+                value_type: 'map',
+                entries: build_entries(value)
+              )
+            when Array
+              Node::FrontmatterValue.new(
+                value_type: 'array',
+                items: value.map { |v| build_value(v) }
+              )
+            when Integer
+              Node::FrontmatterValue.new(value_type: 'integer', integer_value: value)
+            when Float
+              Node::FrontmatterValue.new(value_type: 'float', float_value: value)
+            when TrueClass, FalseClass
+              Node::FrontmatterValue.new(value_type: 'boolean', boolean_value: value)
+            when Date, DateTime
+              Node::FrontmatterValue.new(value_type: 'date', date_value: value)
+            when Time
+              Node::FrontmatterValue.new(value_type: 'datetime', datetime_value: value)
+            when Symbol
+              Node::FrontmatterValue.new(value_type: 'symbol', symbol_value: value.to_s)
+            when nil
+              Node::FrontmatterValue.new(value_type: 'nil')
+            else
+              Node::FrontmatterValue.new(value_type: 'string', string_value: value.to_s)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    module Handlers
+      module GenericBlock
+        def self.call(element, context:)
+          semantic_type = element.resolve_semantic_type
+          content = context.extract_content(element)
+          return nil if content.empty?
+
+          Node::GenericBlock.new(
+            attrs: Node::GenericBlock::Attrs.new(
+              id: element.id,
+              title: element.title,
+              semantic_type: semantic_type&.to_s
+            ),
+            content: content
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    module Handlers
+      # Handles HorizontalRuleBlock → horizontal_rule node.
+      module HorizontalRule
+        def self.call(_element, *)
+          Node::HorizontalRule.new
+        end
+      end
+    end
+  end
+end