metanorma-mirror 1.0.0

data/lib/metanorma/mirror/output/pipeline.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Output
+      class Pipeline
+        attr_reader :steps, :context
+
+        def initialize(xml_path:, steps: nil, flavor: nil, title: nil,
+id_strategy: nil)
+          @steps = steps || [Steps::ParseXml, Steps::TransformMirror, Steps::AttachMetadata]
+          @context = PipelineContext.new(
+            xml_path: xml_path,
+            flavor: flavor,
+            title: title || File.basename(xml_path, ".*"),
+            id_strategy: id_strategy,
+          )
+        end
+
+        def process
+          @steps.each { |step_class| step_class.new.call(@context) }
+          Model::Guide.new(
+            content: @context.content,
+            meta: @context.meta,
+            title: @context.title,
+            document: @context.parsed,
+          )
+        end
+
+        module Steps
+          class ParseXml
+            def call(context)
+              flavor = context.flavor || infer_flavor(context.xml_path)
+              doc_class = flavor_class(flavor)
+              xml_content = File.read(context.xml_path)
+              context.parsed = doc_class.from_xml(xml_content)
+            end
+
+            def self.flavor_map
+              @flavor_map ||= Metanorma.constants.each_with_object({}) do |c, map|
+                next unless c.to_s.end_with?("Document")
+
+                flavor = c.to_s.delete_suffix("Document").downcase
+                map[flavor] = c.to_s
+              end.freeze
+            end
+
+            def infer_flavor(xml_path)
+              basename = File.basename(xml_path, ".*")
+              from_name = basename.split("-").first.to_s.downcase
+              return from_name if self.class.flavor_map.key?(from_name)
+
+              File.dirname(xml_path).split("/").reverse_each do |seg|
+                prefix = seg.split("-").first.to_s.downcase
+                return prefix if self.class.flavor_map.key?(prefix)
+              end
+
+              nil
+            end
+
+            def flavor_class(flavor)
+              camel = flavor.split("_").map(&:capitalize).join
+              new_namespace = "Metanorma::#{camel}::Document"
+              begin
+                require "metanorma/#{flavor}/document"
+              rescue LoadError
+                nil
+              end
+              if Object.const_defined?(new_namespace)
+                return Object.const_get(new_namespace).const_get(:Root)
+              end
+
+              begin
+                require "metanorma/standoc"
+              rescue LoadError
+                nil
+              end
+              class_name = self.class.flavor_map[flavor] || "StandardDocument"
+              Metanorma.const_get(class_name).const_get(:Root)
+            end
+          end
+
+          class TransformMirror
+            def call(context)
+              id_strategy = context.id_strategy || Mirror::DEFAULT_ID_STRATEGY
+              transformer = Mirror::Transformer.new(id_strategy: id_strategy)
+              context.content = transformer.from_metanorma(context.parsed)
+            end
+          end
+
+          class AttachMetadata
+            def call(context)
+              parsed = context.parsed
+              return unless parsed
+
+              bibdata = SafeAttr.read(parsed, :bibdata)
+              return unless bibdata
+
+              meta = {}
+              meta["title"] = Metadata.title_from_bibdata(bibdata)
+              meta["flavor"] = context.flavor if context.flavor
+              context.meta = meta
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/output/pipeline_context.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Output
+      class PipelineContext
+        attr_reader :xml_path, :flavor, :title, :id_strategy
+        attr_accessor :parsed, :content, :meta
+
+        def initialize(xml_path:, flavor: nil, title: nil, id_strategy: nil)
+          @xml_path = xml_path
+          @flavor = flavor
+          @title = title
+          @id_strategy = id_strategy
+          @parsed = nil
+          @content = nil
+          @meta = {}
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/output.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Output
+      autoload :Pipeline, "#{__dir__}/output/pipeline"
+      autoload :PipelineContext, "#{__dir__}/output/pipeline_context"
+      autoload :Builder, "#{__dir__}/output/builder"
+      autoload :Formats, "#{__dir__}/output/formats"
+    end
+  end
+end

data/lib/metanorma/mirror/rewriter.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    # Rewrites a mirror Model graph with configurable type-skipping and
+    # per-type customization. Despite living in the reverse-conversion
+    # namespace, this class produces a Model graph (not Metanorma XML) —
+    # the output is a fully model-driven representation that can be
+    # serialized via Model#to_hash or embedded into HTML output by
+    # Output::Formats::InlineFormat (which renders the source document
+    # through the classic Metanorma::Html renderer).
+    #
+    # Instance API:
+    #   Rewriter.new(skip: Set.new(%w[review footnotes]))
+    #   rewriter.skip("my_type")
+    #   rewriter.register("my_type") { |n, r| ... }
+    #
+    # Class API (seeds defaults copied into each new instance):
+    #   Rewriter.skip("review")        # adds to defaults
+    #   Rewriter.register("my_type") { |n, r| ... }
+    #
+    # Two Rewriter instances do not share state. Class-level mutation only
+    # affects instances created afterwards (the default snapshot is copied
+    # at `new` time).
+    class Rewriter
+      DEFAULT_SKIPPED_TYPES = %w[review footnotes].freeze
+
+      class << self
+        # Default skip set, copied into each new instance.
+        def default_skipped_types
+          @default_skipped_types ||= Set.new(DEFAULT_SKIPPED_TYPES)
+        end
+
+        # Default builder map, copied into each new instance.
+        def default_builders
+          @default_builders ||= {}
+        end
+
+        # Add a type to the default skip set. Affects instances created
+        # afterwards; existing instances are unchanged.
+        def skip(type)
+          default_skipped_types << type
+          self
+        end
+
+        # Register a builder for a type at the default level. Affects
+        # instances created afterwards; existing instances are unchanged.
+        def register(type, &block)
+          default_builders[type] = block
+          self
+        end
+      end
+
+      def initialize(skip: nil, builders: nil)
+        @skipped_types = skip || self.class.default_skipped_types.dup
+        @builders = builders || self.class.default_builders.dup
+      end
+
+      attr_reader :skipped_types, :builders
+
+      def skip(type)
+        skipped_types << type
+        self
+      end
+
+      def skipped?(type)
+        skipped_types.include?(type)
+      end
+
+      def register(type, &block)
+        builders[type] = block
+        self
+      end
+
+      def call(mirror_node)
+        build(mirror_node)
+      end
+
+      def build(node)
+        return nil unless node
+
+        return rewrite_string(node) if node.is_a?(String)
+
+        node.accept_rewriter(self)
+      end
+
+      def rewrite_container(node)
+        return nil if skipped?(node.type)
+
+        builder = builders[node.type]
+        return builder.call(node, self) if builder
+
+        Model::Container.new(
+          type: node.type,
+          attrs: node.attrs,
+          content: build_children(node.content),
+        )
+      end
+
+      def rewrite_leaf(node)
+        return nil if skipped?(node.type)
+
+        Model::Leaf.new(type: node.type, attrs: node.attrs)
+      end
+
+      def rewrite_text(node)
+        Model::Text.new(text: node.text, marks: node.marks)
+      end
+
+      def rewrite_soft_break(_node)
+        Model::SoftBreak.new
+      end
+
+      def rewrite_string(string)
+        Model::Text.new(text: string)
+      end
+
+      def build_children(content)
+        Array(content).filter_map { |child| build(child) }
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/safe_attr.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module SafeAttr
+      def self.read(element, attr_name)
+        return nil unless element.is_a?(Lutaml::Model::Serializable)
+
+        klass = element.class
+        return nil unless klass.attributes.key?(attr_name)
+
+        element.public_send(attr_name)
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/serialization/json_serializer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Metanorma
+  module Mirror
+    module Serialization
+      class JsonSerializer
+        # Every Model::Node (Leaf included) has a data to_hash; the former
+        # Container-only guard serialized bare leaves as inspect strings.
+        def self.serialize(node)
+          data = node.is_a?(Model::Node) ? node.to_hash : node
+          data.to_json
+        end
+
+        def self.serialize_pretty(node)
+          data = node.is_a?(Model::Node) ? node.to_hash : node
+          JSON.pretty_generate(data)
+        end
+
+        def self.deserialize(json_string)
+          Model::Factory.from_hash(JSON.parse(json_string))
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/serialization/yaml_serializer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Metanorma
+  module Mirror
+    module Serialization
+      class YamlSerializer
+        def self.serialize(node)
+          data = node.is_a?(Model::Container) ? node.to_hash : node
+          data.to_yaml
+        end
+
+        def self.deserialize(yaml_string)
+          Model::Factory.from_hash(YAML.safe_load(yaml_string))
+        end
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/serialization.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    module Serialization
+      autoload :JsonSerializer, "#{__dir__}/serialization/json_serializer"
+      autoload :YamlSerializer, "#{__dir__}/serialization/yaml_serializer"
+    end
+  end
+end

data/lib/metanorma/mirror/transformer.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    class Transformer
+      attr_reader :registry, :id_strategy
+
+      def initialize(registry: Mirror.default_registry,
+                     id_strategy: Mirror::DEFAULT_ID_STRATEGY)
+        @registry = registry
+        @id_strategy = id_strategy
+      end
+
+      def call(root)
+        attrs = {}
+        attrs[:flavor] = root.flavor if root.flavor
+        attrs[:type] = root.type if root.type
+        attrs[:schema_version] = root.schema_version if root.schema_version
+
+        title = extract_root_title(root)
+        attrs[:title] = title if title
+
+        content = []
+
+        preface = root.preface
+        if preface
+          result = @registry.handle(preface, context: self)
+          result.append_to(content)
+        end
+
+        sections = root.sections
+        if sections
+          result = @registry.handle(sections, context: self)
+          result.append_to(content)
+        end
+
+        annex = root.annex
+        annex&.each do |a|
+          result = @registry.handle(a, context: self)
+          result.append_to(content)
+        end
+
+        bibliography = root.bibliography
+        if bibliography
+          result = @registry.handle(bibliography, context: self)
+          result.append_to(content)
+        end
+
+        Handlers.build_node("doc", attrs: attrs, content: content)
+      end
+
+      def from_metanorma(root)
+        document = call(root)
+        @id_strategy.finalize!(document)
+      end
+
+      def rewrite(mirror_node)
+        Rewriter.new.call(mirror_node)
+      end
+
+      def extract_blocks(element)
+        content = []
+
+        element.each_mixed_content do |node|
+          next if node.is_a?(String)
+
+          result = @registry.handle(node, context: self)
+          result.append_to(content)
+        end
+        content
+      end
+
+      def extract_section_children(element)
+        content = []
+        %i[clause terms definitions references floating_title].each do |attr|
+          collection = SafeAttr.read(element, attr)
+          next unless collection
+
+          collection.each do |child|
+            result = @registry.handle(child, context: self)
+            result.append_to(content)
+          end
+        end
+        content
+      end
+
+      def extract_named_collections(element, collection_attrs)
+        content = []
+        collection_attrs.each do |attr|
+          collection = SafeAttr.read(element, attr)
+          next unless collection
+
+          collection.each do |child|
+            result = @registry.handle(child, context: self)
+            result.append_to(content)
+          end
+        end
+        content
+      end
+
+      def text_node(text, marks: [])
+        Handlers.build_text(text, marks: marks)
+      end
+
+      def extract_root_title(root)
+        Metadata.title_from_bibdata(SafeAttr.read(root, :bibdata))
+      end
+    end
+  end
+end

data/lib/metanorma/mirror/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Metanorma
+  module Mirror
+    VERSION = "1.0.0"
+  end
+end

data/lib/metanorma/mirror.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Metanorma
+  # The Mirror format: a lossless JSON projection of a Metanorma
+  # document as a typed node tree (blocks, inlines, marks), for
+  # renderers and tooling (the SMART document reader, the HTML JS
+  # renderer, MKO payload provenance).
+  #
+  # This gem is format + mechanism only: node models, the handler
+  # registry, the transformer walk, serializers, and the output
+  # pipeline. Model knowledge (which document classes map to which
+  # handlers, marks, renderers, id categories) is REGISTERED by the
+  # model gems — metanorma-document and metanorma-standoc seed the
+  # defaults at load time via the registration seams below.
+  module Mirror
+    class Error < StandardError; end
+
+    autoload :VERSION, "#{__dir__}/mirror/version"
+    autoload :SafeAttr, "#{__dir__}/mirror/safe_attr"
+    autoload :MathUtil, "#{__dir__}/mirror/math_util"
+    autoload :Metadata, "#{__dir__}/mirror/metadata"
+    autoload :Model, "#{__dir__}/mirror/model"
+    autoload :ClassTable, "#{__dir__}/mirror/class_table"
+    autoload :HandlerResult, "#{__dir__}/mirror/handler_result"
+    autoload :Transformer, "#{__dir__}/mirror/transformer"
+    autoload :Rewriter, "#{__dir__}/mirror/rewriter"
+    autoload :HandlerRegistry, "#{__dir__}/mirror/handler_registry"
+    autoload :Handlers, "#{__dir__}/mirror/handlers"
+    autoload :IdStrategy, "#{__dir__}/mirror/id_strategy"
+    autoload :Output, "#{__dir__}/mirror/output"
+    autoload :Serialization, "#{__dir__}/mirror/serialization"
+    autoload :DefaultRegistry, "#{__dir__}/mirror/default_registry"
+
+    DEFAULT_ID_STRATEGY = IdStrategy::Preserve.new
+
+    # Registration seams. Model gems call these at load time so the
+    # format layer stays free of model constants:
+
+    # Handler entries for the default registry, in registration order.
+    @default_hooks = []
+
+    def self.register_default(&block)
+      @default_hooks << block
+    end
+
+    def self.default_hooks
+      @default_hooks
+    end
+
+    # Inline element classes -> mark builders (e.g. EmRawElement ->
+    # emphasis mark).
+    def self.mark_builders
+      @mark_builders ||= ClassTable.new
+    end
+
+    # Inline element classes -> rich-HTML renderer lambdas (stem, xref,
+    # link, eref, fn, span, br).
+    def self.rich_html_renderers
+      @rich_html_renderers ||= ClassTable.new
+    end
+
+    # Inline element classes -> plain-text substitutions (TabElement ->
+    # " ", BrElement -> "\n").
+    def self.inline_text_substitutions
+      @inline_text_substitutions ||= ClassTable.new
+    end
+
+    # Inline element classes -> SIMPLE_WRAPS mark types (see
+    # Handlers::Inline::Catalog).
+    def self.simple_inline_elements
+      @simple_inline_elements ||= ClassTable.new
+    end
+
+    # Element classes recognized as semx wrappers (cross-reference
+    # carriers); payload is always true.
+    def self.semx_elements
+      @semx_elements ||= ClassTable.new
+    end
+
+    # The mixed-content walker for inline containers: an object
+    # responding to each(element) { |node| } yielding semantic children
+    # in document order (document seeds register
+    # Components::Inline::SemanticContent).
+    class << self
+      attr_accessor :inline_content_iterator
+    end
+
+    def self.default_registry
+      @default_registry ||= build_default_registry
+    end
+
+    def self.build_default_registry
+      DefaultRegistry.build
+    end
+  end
+end