coradoc-mirror 0.1.1

data/lib/coradoc/mirror/handlers.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    # Handler modules for transforming CoreModel types to Mirror nodes.
+    #
+    # Each handler is a module/class that responds to +call(element, context:)+,
+    # where +element+ is a CoreModel instance and +context+ is the
+    # CoreModelToMirror transformer providing shared helpers.
+    #
+    # New handlers are added by creating a new module file and registering
+    # it in +Coradoc::Mirror.default_registry+ — no existing code changes (OCP).
+    module Handlers
+      autoload :Structural, "#{__dir__}/handlers/structural"
+      autoload :Paragraph, "#{__dir__}/handlers/paragraph"
+      autoload :CodeBlock, "#{__dir__}/handlers/code_block"
+      autoload :Blockquote, "#{__dir__}/handlers/blockquote"
+      autoload :Example, "#{__dir__}/handlers/example"
+      autoload :Sidebar, "#{__dir__}/handlers/sidebar"
+      autoload :OpenBlock, "#{__dir__}/handlers/open_block"
+      autoload :Verse, "#{__dir__}/handlers/verse"
+      autoload :Comment, "#{__dir__}/handlers/comment"
+      autoload :HorizontalRule, "#{__dir__}/handlers/horizontal_rule"
+      autoload :Reviewer, "#{__dir__}/handlers/reviewer"
+      autoload :Admonition, "#{__dir__}/handlers/admonition"
+      autoload :List, "#{__dir__}/handlers/list"
+      autoload :DefinitionList, "#{__dir__}/handlers/definition_list"
+      autoload :Table, "#{__dir__}/handlers/table"
+      autoload :Image, "#{__dir__}/handlers/image"
+      autoload :Inline, "#{__dir__}/handlers/inline"
+      autoload :Bibliography, "#{__dir__}/handlers/bibliography"
+      autoload :Footnote, "#{__dir__}/handlers/footnote"
+      autoload :Toc, "#{__dir__}/handlers/toc"
+      autoload :Frontmatter, "#{__dir__}/handlers/frontmatter"
+      autoload :GenericBlock, "#{__dir__}/handlers/generic_block"
+    end
+  end
+end

data/lib/coradoc/mirror/mark.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Coradoc
+  module Mirror
+    # ProseMirror-compatible inline mark (formatting annotation).
+    #
+    # Marks decorate inline text nodes with formatting semantics like
+    # bold, italic, link, etc. Wire format:
+    #
+    #   { "type": "strong" }
+    #   { "type": "link", "attrs": { "href": "..." } }
+    #
+    # All built-in Mark subclasses live below in this file so the
+    # TYPE_TO_CLASS registry at the bottom can see every PM_TYPE at
+    # load time. Adding a new mark type = adding one subclass + letting
+    # the registry walker pick it up (OCP).
+    class Mark < Lutaml::Model::Serializable
+      PM_TYPE = 'mark'
+
+      attribute :type, :string, default: -> { self.class::PM_TYPE }
+
+      key_value do
+        map 'type', to: :type, render_default: true
+      end
+
+      def text_content
+        ''
+      end
+    end
+  end
+end
+
+module Coradoc
+  module Mirror
+    class Mark
+      # ── Marks without attrs ──
+
+      class Bold < Mark
+        PM_TYPE = 'strong'
+      end
+
+      class Italic < Mark
+        PM_TYPE = 'emphasis'
+      end
+
+      class Monospace < Mark
+        PM_TYPE = 'code'
+      end
+
+      class Underline < Mark
+        PM_TYPE = 'underline'
+      end
+
+      class Strikethrough < Mark
+        PM_TYPE = 'strike'
+      end
+
+      class Subscript < Mark
+        PM_TYPE = 'subscript'
+      end
+
+      class Superscript < Mark
+        PM_TYPE = 'superscript'
+      end
+
+      class Highlight < Mark
+        PM_TYPE = 'highlight'
+      end
+
+      # ── Marks with attrs ──
+
+      class Link < Mark
+        PM_TYPE = 'link'
+
+        class Attrs < Lutaml::Model::Serializable
+          attribute :href, :string
+
+          key_value do
+            map 'href', to: :href
+          end
+        end
+
+        attribute :attrs, Attrs
+
+        key_value do
+          map 'type', to: :type, render_default: true
+          map 'attrs', to: :attrs
+        end
+      end
+
+      class CrossReference < Mark
+        PM_TYPE = 'xref'
+
+        class Attrs < Lutaml::Model::Serializable
+          attribute :target, :string
+          attribute :resolved, :string
+
+          key_value do
+            map 'target', to: :target
+            map 'resolved', to: :resolved
+          end
+        end
+
+        attribute :attrs, Attrs
+
+        key_value do
+          map 'type', to: :type, render_default: true
+          map 'attrs', to: :attrs
+        end
+      end
+
+      class Stem < Mark
+        PM_TYPE = 'stem'
+
+        class Attrs < Lutaml::Model::Serializable
+          attribute :stem_type, :string
+
+          key_value do
+            map 'stem_type', to: :stem_type
+          end
+        end
+
+        attribute :attrs, Attrs
+
+        key_value do
+          map 'type', to: :type, render_default: true
+          map 'attrs', to: :attrs
+        end
+      end
+
+      class Span < Mark
+        PM_TYPE = 'span'
+
+        class Attrs < Lutaml::Model::Serializable
+          attribute :role, :string
+
+          key_value do
+            map 'role', to: :role
+          end
+        end
+
+        attribute :attrs, Attrs
+
+        key_value do
+          map 'type', to: :type, render_default: true
+          map 'attrs', to: :attrs
+        end
+      end
+    end
+  end
+end
+
+module Coradoc
+  module Mirror
+    class Mark
+      # Polymorphic class map — flat hash from PM_TYPE wire string to
+      # fully-qualified Ruby class name. Used by Node and Mark mappings
+      # to dispatch polymorphic deserialization. Populated once after
+      # all subclasses are defined above.
+      TYPE_TO_CLASS = begin
+        result = {}
+        Mark.constants.each do |name|
+          k = Mark.const_get(name)
+          next unless k.is_a?(Class) && k < Mark && k::PM_TYPE != 'mark'
+
+          result[k::PM_TYPE] = k.name
+        end
+        result.freeze
+      end
+
+      # Frozen polymorphic option block. Referenced verbatim by every
+      # Node mapping that has a `marks` collection.
+      POLYMORPHIC = {
+        attribute: 'type',
+        class_map: TYPE_TO_CLASS
+      }.freeze
+    end
+  end
+end

data/lib/coradoc/mirror/mark_reverse_builder.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    # OCP-compliant registry for Mirror mark -> CoreModel transformation.
+    #
+    # This is the mark-level counterpart to ReverseBuilder (which handles
+    # node-level dispatch). Adding support for a new mark type is purely
+    # additive:
+    #
+    #   module MarkReverseBuilder
+    #     class Concept < Base
+    #       registers 'concept'
+    #
+    #       def build(inner, _mark)
+    #         CoreModel::TermElement.new(children: Array(inner))
+    #       end
+    #     end
+    #   end
+    #
+    # No edits to MirrorToCoreModel#apply_mark or any other existing class.
+    module MarkReverseBuilder
+      REGISTRY = {}
+
+      module_function
+
+      def register(type, builder_class)
+        REGISTRY[type] = builder_class
+      end
+
+      def lookup(type)
+        REGISTRY[type]
+      end
+
+      def registered_types
+        REGISTRY.keys
+      end
+
+      # Base class for all mark reverse builders. Subclasses register one
+      # mark type string via `registers` and implement `#build(inner, mark)`.
+      # `inner` is the already-built CoreModel inline content this mark
+      # wraps; `mark` is the source Mirror::Mark (for marks that carry
+      # attrs, like `link` reading `mark.href`).
+      class Base
+        def self.registers(*types)
+          types.each { |t| MarkReverseBuilder.register(t, self) }
+        end
+
+        def build(_inner, _mark)
+          raise NotImplementedError,
+                "#{self.class} must implement #build(inner, mark)"
+        end
+      end
+
+      # ── Simple wraps: typed InlineElement subclass, no attrs ──
+
+      class Bold < Base
+        registers 'strong'
+
+        def build(inner, _mark)
+          CoreModel::BoldElement.new(children: Array(inner))
+        end
+      end
+
+      class Italic < Base
+        registers 'emphasis'
+
+        def build(inner, _mark)
+          CoreModel::ItalicElement.new(children: Array(inner))
+        end
+      end
+
+      class Monospace < Base
+        registers 'code'
+
+        def build(inner, _mark)
+          CoreModel::MonospaceElement.new(children: Array(inner))
+        end
+      end
+
+      class Underline < Base
+        registers 'underline'
+
+        def build(inner, _mark)
+          CoreModel::UnderlineElement.new(children: Array(inner))
+        end
+      end
+
+      class Strikethrough < Base
+        registers 'strike'
+
+        def build(inner, _mark)
+          CoreModel::StrikethroughElement.new(children: Array(inner))
+        end
+      end
+
+      class Subscript < Base
+        registers 'subscript'
+
+        def build(inner, _mark)
+          CoreModel::SubscriptElement.new(children: Array(inner))
+        end
+      end
+
+      class Superscript < Base
+        registers 'superscript'
+
+        def build(inner, _mark)
+          CoreModel::SuperscriptElement.new(children: Array(inner))
+        end
+      end
+
+      class Highlight < Base
+        registers 'highlight'
+
+        def build(inner, _mark)
+          CoreModel::HighlightElement.new(children: Array(inner))
+        end
+      end
+
+      # ── Marks with attrs ──
+
+      class Link < Base
+        registers 'link'
+
+        def build(inner, mark)
+          CoreModel::LinkElement.new(target: mark.attrs&.href, children: Array(inner))
+        end
+      end
+
+      class CrossReference < Base
+        registers 'xref'
+
+        def build(inner, mark)
+          CoreModel::CrossReferenceElement.new(
+            target: mark.attrs&.target, children: Array(inner)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/mirror_json_format.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Coradoc
+  module Mirror
+    # Format module for mirror JSON output.
+    #
+    # Registers with Coradoc so the CLI can discover it:
+    #   Coradoc.convert(text, from: :asciidoc, to: :mirror_json)
+    #   coradoc convert doc.adoc -t mirror_json
+    module MirrorJsonFormat
+      class << self
+        # Output-only format — parsing from mirror JSON is not supported via
+        # the format registry. Use Mirror::Node.from_hash directly.
+        def parse_to_core(_input, _options = {})
+          raise Coradoc::UnsupportedFormatError,
+                'Parsing from mirror JSON is not supported via the format registry. ' \
+                'Use Coradoc::Mirror::Node.from_hash(JSON.parse(input)) directly.'
+        end
+
+        # Accept CoreModel, serialize to Mirror JSON.
+        def serialize(document, options = {})
+          pretty = options[:pretty] != false
+          node = Coradoc::Mirror.transform(document)
+          pretty ? JSON.pretty_generate(node.to_hash) : JSON.generate(node.to_hash)
+        end
+
+        def serialize?
+          true
+        end
+
+        def handles_model?(_model)
+          false
+        end
+      end
+    end
+  end
+end
+
+Coradoc.register_format(:mirror_json, Coradoc::Mirror::MirrorJsonFormat,
+                        extensions: %w[.mirror.json])

data/lib/coradoc/mirror/mirror_to_core_model.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    # Transforms ProseMirror-compatible Mirror nodes back into CoreModel.
+    #
+    # Dispatch is delegated to ReverseBuilder (node-level) and
+    # MarkReverseBuilder (mark-level) — adding a new node or mark type is
+    # done by registering a new Builder class, with no edit to this file
+    # (OCP). ReverseBuilder and MarkReverseBuilder are autoloaded from
+    # coradoc/mirror.rb; referencing them here triggers load of the
+    # registry files, which is where the built-in builders self-register.
+    class MirrorToCoreModel
+      def call(mirror_node)
+        build_node(mirror_node)
+      end
+
+      def build_node(node)
+        builder_class = ReverseBuilder.lookup(node.type)
+        raise Error, "Unknown mirror node type: #{node.type}" unless builder_class
+
+        builder_class.new(self).build(node)
+      end
+
+      # ── Shared helpers (single source of truth — used by every
+      # ReverseBuilder::Base subclass via delegation) ──
+
+      def build_content(node)
+        return [] unless node.content
+
+        node.content.flat_map do |child|
+          result = build_node(child)
+          next [] if result.nil?
+
+          result.is_a?(Array) ? result : [result]
+        end
+      end
+
+      # Mark dispatch goes through MarkReverseBuilder so adding a new
+      # mark type is purely additive (OCP parity with node dispatch).
+      # Unknown marks pass `inner` through unchanged.
+      def apply_mark(inner, mark)
+        builder_class = MarkReverseBuilder.lookup(mark.type)
+        return inner unless builder_class
+
+        builder_class.new.build(inner, mark)
+      end
+
+      def build_inline_children(node)
+        return [] unless node.content
+
+        node.content.filter_map do |child|
+          next unless child.is_a?(Node)
+
+          build_node(child)
+        end
+      end
+
+      def extract_text(node)
+        return node.text.to_s if node.is_a?(Node::Text)
+        return '' unless node.content
+
+        node.content.filter_map do |child|
+          child.is_a?(Node) ? extract_text(child) : ''
+        end.join
+      end
+
+      def inline_content(element)
+        element.is_a?(CoreModel::InlineElement) ? element.content : element.to_s
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/mirror_yaml_format.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Coradoc
+  module Mirror
+    # Format module for mirror YAML output.
+    #
+    # Registers with Coradoc so the CLI can discover it:
+    #   Coradoc.convert(text, from: :asciidoc, to: :mirror_yaml)
+    #   coradoc convert doc.adoc -t mirror_yaml
+    module MirrorYamlFormat
+      class << self
+        # Output-only format — parsing from mirror YAML is not supported via
+        # the format registry. Use Mirror::Node.from_hash directly.
+        def parse_to_core(_input, _options = {})
+          raise Coradoc::UnsupportedFormatError,
+                'Parsing from mirror YAML is not supported via the format registry. ' \
+                'Use Coradoc::Mirror::Node.from_hash(YAML.safe_load(input)) directly.'
+        end
+
+        # Accept CoreModel, serialize to Mirror YAML.
+        def serialize(document, _options = {})
+          node = Coradoc::Mirror.transform(document)
+          YAML.dump(node.to_hash)
+        end
+
+        def serialize?
+          true
+        end
+
+        def handles_model?(_model)
+          false
+        end
+      end
+    end
+  end
+end
+
+Coradoc.register_format(:mirror_yaml, Coradoc::Mirror::MirrorYamlFormat,
+                        extensions: %w[.mirror.yaml .mirror.yml])