coradoc-mirror 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ac58d41a9214d72f32b3bcc107ddaf463c772598cd9be21e267c56b4dcfee8e
-  data.tar.gz: bfd5bce725a65f86cf449cd4e59e9c78539968742237b002d2726dfdc3b37f52
+  metadata.gz: f3f7f901c9228258999b71326b31ee0af3950fd176c0c5f7c4701e0e0790ca00
+  data.tar.gz: 3135226a74f13af90415fe808e1320199276112d0bb1adb7e147600604c36f00
 SHA512:
-  metadata.gz: 264dba99b8eecd0e218f52d30dd6498a21b5248c640e837dc5ee4140df6b6f64e7416f75b6c8905c032d4c5fa9a078fbfdfc026c1b3160f0f943f930e5ff6e61
-  data.tar.gz: 51639279c428a6e1d1707bb922bd6da2d59576e96d0cfc7d266eef3de96281e3b2dca61fa63afee3fd3bf920799c7258fc1e40ab59782ee6ec06a5dbe2626340
+  metadata.gz: 62ea64db65b369ebd32a473e2bd43db96a53b883ca0d30c506660f13f22baa21b08968706ebace768799907cd68b120eb2292774f68cd3272f84865174f77395
+  data.tar.gz: e277c3ef10c119f6e2ecb2899b96f94140ccf155abba5588dab6ab58d405c66ce7bd1e0e0f5ac1dc85eae0c448d1c470a95b9b51e9d0166019b42dfe20dd2adf

data/lib/coradoc/mirror/core_model_to_mirror.rb

@@ -48,12 +48,17 @@ module Coradoc
         )
       end
 
-      # Partitions flat doc children into [preface?, sections?, *bibliography,
-      # *trailing] per the @metanorma/mirror JS structural contract. See
-      # Partitioner for the bucketing rules.
+      # Partitions flat doc children into [*metadata, preface?, sections?,
+      # *bibliography, *trailing] per the @metanorma/mirror JS structural
+      # contract. See Partitioner for the bucketing rules.
+      #
+      # Metadata blocks (frontmatter) are prepended verbatim so consumers
+      # like FrontmatterQuery can find them by walking content[0..n], and
+      # renderers can skip them via their type ('frontmatter').
       def wrap_structural(children)
         partitioned = Partitioner.partition(children)
         wrapped = []
+        wrapped.concat(partitioned[:metadata])
         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])

data/lib/coradoc/mirror/frontmatter_query.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    # Public read-API: extract a flat Ruby Hash from a Mirror document's
+    # frontmatter node.
+    #
+    # Why this exists: site generators (e.g. metanorma.org's convert-adoc.rb)
+    # need frontmatter as a plain Hash for templating VitePress/Jekyll
+    # frontmatter output. Without this, callers would either (a) re-parse
+    # the source YAML — violating FrontmatterBlock::Codec's "single source
+    # of truth" rule — or (b) hand-walk the typed FrontmatterEntry /
+    # FrontmatterValue tree themselves, duplicating the reverse builder's
+    # logic. This module is the single entry point for both problems.
+    #
+    # Reuses FrontmatterTreeToHash — same translator the reverse builder
+    # uses — so the read-path is shared (DRY/MECE).
+    module FrontmatterQuery
+      module_function
+
+      # @param mirror_doc [Mirror::Node::Document, nil]
+      # @return [Hash{String,Object}] flat key→value mapping; empty Hash
+      #   if the document has no frontmatter node or no entries
+      def to_hash(mirror_doc)
+        frontmatter = find_frontmatter(mirror_doc)
+        return {} unless frontmatter
+
+        entries = frontmatter.attrs&.entries || []
+        FrontmatterTreeToHash.to_hash(entries)
+      end
+
+      # @param mirror_doc [Mirror::Node::Document, nil] (see #to_hash)
+      # @return [Boolean] true if the document carries a frontmatter node
+      #   with at least one entry
+      def has_frontmatter?(mirror_doc)
+        frontmatter = find_frontmatter(mirror_doc)
+        !frontmatter.nil? && !(frontmatter.attrs&.entries || []).empty?
+      end
+
+      def find_frontmatter(mirror_doc)
+        return nil if mirror_doc.nil?
+
+        content = mirror_doc.content
+        return nil unless content
+
+        content.find { |node| node.is_a?(Node) && node.type == 'frontmatter' }
+      end
+    end
+  end
+end

data/lib/coradoc/mirror/frontmatter_tree_to_hash.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Mirror
+    # Walks a typed FrontmatterEntry / FrontmatterValue tree (the Mirror
+    # representation of CoreModel::FrontmatterBlock#data) and rebuilds the
+    # flat Ruby Hash. Inverse of Handlers::Frontmatter.build_value.
+    #
+    # Single source of truth for tree → Hash translation. Consumed by:
+    #   - ReverseBuilder::Frontmatter (mirror → CoreModel round-trip)
+    #   - FrontmatterQuery (mirror doc → flat Hash for downstream readers)
+    #
+    # Extracted from ReverseBuilder so the read-path is shared (DRY/MECE)
+    # and FrontmatterQuery does not depend on the reverse-builder constant.
+    module FrontmatterTreeToHash
+      module_function
+
+      def to_hash(entries)
+        entries.each_with_object({}) do |entry, result|
+          result[entry.key] = unwrap_value(entry.value)
+        end
+      end
+
+      def unwrap_value(value)
+        case value.value_type
+        when 'map'     then to_hash(value.entries || [])
+        when 'array'   then (value.items || []).map { |v| unwrap_value(v) }
+        when 'integer'   then value.integer_value
+        when 'float'     then value.float_value
+        when 'boolean'   then value.boolean_value
+        when 'date'      then value.date_value
+        when 'datetime'  then value.datetime_value
+        when 'symbol'    then value.symbol_value&.to_sym
+        when 'nil'       then nil
+        else value.string_value
+        end
+      end
+    end
+  end
+end

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

@@ -43,24 +43,26 @@ module Coradoc
           end
 
           def build_description(item, context)
-            definitions = item.definitions
-            return nil unless definitions && !definitions.empty?
+            desc_nodes = description_nodes(item, context)
+            return nil if desc_nodes.empty?
 
-            desc_nodes = definitions.map do |defn|
-              context.text_node(defn.to_s)
-            end
+            Node::DefinitionDescription.new(content: desc_nodes)
+          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
+          # Emit one text node per source — never both. Rich
+          # definition_children (inline nodes) win over plain definitions
+          # (strings) because they preserve formatting; falling back to
+          # the plain string keeps this handler robust for DefinitionItem
+          # instances populated by paths that don't build inline children.
+          def description_nodes(item, context)
+            unless item.is_a?(CoreModel::DefinitionItem)
+              return Array(item.definitions).map { |defn| context.text_node(defn.to_s) }
             end
 
-            return nil if desc_nodes.empty?
+            children = item.definition_children
+            return Array(item.definitions).map { |defn| context.text_node(defn.to_s) } if children.empty?
 
-            Node::DefinitionDescription.new(content: desc_nodes)
+            children.flat_map { |child| Handlers::Inline.process_child(child, context) }
           end
         end
       end

data/lib/coradoc/mirror/partitioner.rb

@@ -15,9 +15,15 @@ module Coradoc
       # (clause, annex, abstract, foreword, introduction, terms,
       # definitions, references, content_section, acknowledgements).
       SECTION_TYPES = Set.new(%w[
-        clause annex content_section abstract foreword introduction
-        acknowledgements terms definitions references section
-      ]).freeze
+                                clause annex content_section abstract foreword introduction
+                                acknowledgements terms definitions references section
+                              ]).freeze
+
+      # Mirror node types that are doc-level metadata, not body content.
+      # They pass through the partitioner untouched (in document order)
+      # so the renderer can choose to skip them — they never land in the
+      # preface bucket where they would render as visible body.
+      METADATA_TYPES = Set.new(%w[frontmatter]).freeze
 
       module_function
 
@@ -29,11 +35,16 @@ module Coradoc
       # Once a bibliography appears → :trailing.
       # Footnotes blocks always go into :trailing regardless of state.
       #
+      # Metadata blocks (frontmatter) are returned in their own bucket,
+      # outside the preface/sections/trailing flow, so they survive the
+      # partition round-trip but are never rendered as body content.
+      #
       # @param children [Array<Node>] flat list of built Mirror nodes
       # @return [Hash{Symbol=>Array<Node>}] buckets under :preface,
-      #   :sections, :bibliography, :trailing
+      #   :sections, :bibliography, :trailing, :metadata
       def partition(children)
-        buckets = { preface: [], sections: [], bibliography: [], trailing: [] }
+        buckets = { preface: [], sections: [], bibliography: [],
+                    trailing: [], metadata: [] }
         state = :preface
 
         children.each do |child|
@@ -44,7 +55,9 @@ module Coradoc
             buckets[:bibliography] << child
             state = :trailing
           else
-            if SECTION_TYPES.include?(child.type)
+            if METADATA_TYPES.include?(child.type)
+              buckets[:metadata] << child
+            elsif SECTION_TYPES.include?(child.type)
               buckets[:sections] << child
               state = :sections
             elsif child.type == 'footnotes'

data/lib/coradoc/mirror/reverse_builder.rb

@@ -26,6 +26,9 @@ module Coradoc
     # full before any caller references it. Mirror-level mark dispatch
     # lives in MarkReverseBuilder (mark_reverse_builder.rb).
     module ReverseBuilder
+      # Not frozen: subclasses call `register` from their class body at
+      # load time, and `registers` may fire late via autoload. Freezing
+      # here breaks the first mirror-to-core round-trip after load.
       REGISTRY = {}
 
       module_function
@@ -567,34 +570,6 @@ module Coradoc
 
       LIST_TYPES = %w[bullet_list ordered_list].freeze
       private_constant :LIST_TYPES
-
-      # Walks a typed FrontmatterEntry / FrontmatterValue tree and
-      # rebuilds the CoreModel `data` hash. Inverse of
-      # Handlers::Frontmatter.build_value.
-      module FrontmatterTreeToHash
-        module_function
-
-        def to_hash(entries)
-          entries.each_with_object({}) do |entry, result|
-            result[entry.key] = unwrap_value(entry.value)
-          end
-        end
-
-        def unwrap_value(value)
-          case value.value_type
-          when 'map' then to_hash(value.entries || [])
-          when 'array' then (value.items || []).map { |v| unwrap_value(v) }
-          when 'integer'  then value.integer_value
-          when 'float'    then value.float_value
-          when 'boolean'  then value.boolean_value
-          when 'date'     then value.date_value
-          when 'datetime' then value.datetime_value
-          when 'symbol'   then value.symbol_value&.to_sym
-          when 'nil'      then nil
-          else value.string_value
-          end
-        end
-      end
     end
   end
 end

data/lib/coradoc/mirror/version.rb

@@ -2,6 +2,6 @@
 
 module Coradoc
   module Mirror
-    VERSION = '0.1.1'
+    VERSION = '0.1.2'
   end
 end

data/lib/coradoc/mirror.rb

@@ -14,6 +14,15 @@ module Coradoc
     autoload :CoreModelToMirror, "#{__dir__}/mirror/core_model_to_mirror"
     autoload :MirrorToCoreModel, "#{__dir__}/mirror/mirror_to_core_model"
     autoload :Partitioner, "#{__dir__}/mirror/partitioner"
+    # Shared tree→Hash translator for the frontmatter typed-tree. Read by
+    # ReverseBuilder::Frontmatter and FrontmatterQuery — single source of
+    # truth for the inverse of Handlers::Frontmatter.build_value.
+    autoload :FrontmatterTreeToHash, "#{__dir__}/mirror/frontmatter_tree_to_hash"
+    # Public read-API for downstream consumers (e.g. site generators) that
+    # need a flat Ruby Hash of a Mirror doc's frontmatter without re-parsing
+    # the source YAML. Frontmatter lives in the CoreModel and the Mirror
+    # doc, not in a parallel YAML parse.
+    autoload :FrontmatterQuery, "#{__dir__}/mirror/frontmatter_query"
     # ReverseBuilder's REGISTRY is populated by the built-in builder
     # subclasses (defined inside reverse_builder.rb) at load time. The
     # file is the autoload target, so the registry is full by the time

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coradoc-mirror
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Ribose Inc.
@@ -77,6 +77,8 @@ files:
 - lib/coradoc-mirror.rb
 - lib/coradoc/mirror.rb
 - lib/coradoc/mirror/core_model_to_mirror.rb
+- lib/coradoc/mirror/frontmatter_query.rb
+- lib/coradoc/mirror/frontmatter_tree_to_hash.rb
 - lib/coradoc/mirror/handler_registry.rb
 - lib/coradoc/mirror/handlers.rb
 - lib/coradoc/mirror/handlers/admonition.rb