coradoc 2.0.22 → 2.0.24

data/lib/coradoc/core_model/frontmatter/codec.rb

@@ -10,42 +10,89 @@ module Coradoc
       # No other code in any gem may call YAML directly for frontmatter.
       # This isolates permitted-classes configuration and error handling
       # in one MECE location (DRY).
+      #
+      # The Codec emits flat YAML — values rendered with their natural
+      # YAML type. This is what Jekyll, Hugo, VitePress, VuePress, 11ty
+      # and every SSG expects: +title: Foo+ / +date: 2024-01-01+.
+      # Round-trip fidelity for typed values (Date, Time, Symbol) is
+      # preserved by Psych's permitted-classes mechanism, not by a
+      # custom discriminator scheme.
+      #
+      # For the typed-tree representation used by the coradoc-mirror JSON
+      # pipeline, see +Coradoc::Mirror::Node::FrontmatterValue+ and
+      # +Coradoc::Mirror::Handlers::Frontmatter+. The typed-tree concern
+      # lives in the mirror gem; this Codec stays focused on YAML.
       module Codec
         PERMITTED_CLASSES = [Date, Time, DateTime, Symbol].freeze
 
         class << self
-          # Parse a YAML string into a FrontmatterBlock.
-          # Returns an empty FrontmatterBlock on malformed YAML (graceful
-          # degradation — body parsing continues).
+          # Parse YAML text into a FrontmatterBlock. Returns an empty
+          # FrontmatterBlock on malformed YAML or non-Hash payload.
+          # Logs a warning so the conversion pipeline can surface the
+          # skip rather than silently dropping user-authored content.
           def from_yaml(yaml_text)
             return FrontmatterBlock.new if yaml_text.nil? || yaml_text.strip.empty?
 
-            parsed = YAML.safe_load(
-              yaml_text,
-              permitted_classes: PERMITTED_CLASSES,
-              aliases: true
-            )
-            return FrontmatterBlock.new unless parsed.is_a?(Hash)
-
-            schema = parsed['$schema']
-            data = parsed.except('$schema')
-            FrontmatterBlock.new(schema: schema&.to_s, data: data)
-          rescue YAML::SyntaxError, Psych::DisallowedClass
+            build_from_loaded(load_yaml(yaml_text))
+          rescue YAML::SyntaxError, Psych::DisallowedClass => e
+            Coradoc::Logger.warn("frontmatter parse failed: #{e.message}")
             FrontmatterBlock.new
           end
 
+          # Build a FrontmatterBlock from a Ruby hash with native-typed
+          # values (String, Integer, Date, …). Returns an empty block
+          # for non-Hash input.
+          def from_hash(hash)
+            return FrontmatterBlock.new unless hash.is_a?(Hash)
+
+            build_from_loaded(hash)
+          end
+
           # Serialize a FrontmatterBlock to canonical YAML text.
-          # Does NOT include leading/trailing `---` delimiters; the caller
-          # wraps the output.
+          # Does NOT include leading/trailing +---+ delimiters; the
+          # caller wraps the output. Returns +''+ for empty blocks.
           def to_yaml(block)
             return '' unless block.is_a?(FrontmatterBlock)
 
+            payload = flat_tree(block)
+            return '' if payload.empty?
+
+            YAML.dump(payload).delete_prefix("---\n").delete_suffix("\n...")
+          end
+
+          # Return the frontmatter as a native-typed Ruby hash.
+          # +$schema+ is included when present.
+          def to_hash(block)
+            return {} unless block.is_a?(FrontmatterBlock)
+
+            flat_tree(block)
+          end
+
+          private
+
+          def load_yaml(yaml_text)
+            YAML.safe_load(
+              yaml_text,
+              permitted_classes: PERMITTED_CLASSES,
+              aliases: true
+            )
+          end
+
+          def build_from_loaded(loaded)
+            return FrontmatterBlock.new unless loaded.is_a?(Hash)
+
+            schema = loaded['$schema']
+            FrontmatterBlock.new(
+              schema: schema&.to_s,
+              data: loaded.except('$schema')
+            )
+          end
+
+          def flat_tree(block)
             tree = {}
             tree['$schema'] = block.schema if block.schema
             tree.merge!(block.data || {})
-            return '' if tree.empty?
-
-            YAML.dump(tree).delete_prefix("---\n").delete_suffix("\n...")
+            tree
           end
         end
       end

data/lib/coradoc/core_model/frontmatter.rb

@@ -50,6 +50,10 @@ module Coradoc
         schema.nil? && (data.nil? || data.empty?)
       end
 
+      def body_content?
+        false
+      end
+
       # Sub-namespaces (Codec, SchemaResolver, FieldTransform, TextSplitter)
       # live under FrontmatterBlock and autoload lazily.
       autoload :Codec, "#{__dir__}/frontmatter/codec"

data/lib/coradoc/core_model/inline_content.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Operations on mixed arrays of inline content (String /
+    # InlineElement / CoreModel::Base). Single source of truth for text
+    # extraction and edge cleanup, replacing parallel implementations
+    # that previously lived in the HTML converters.
+    #
+    # No method here mutates its inputs — InlineElements are duplicated
+    # via #with_content, Strings are replaced with new instances.
+    module InlineContent
+      class << self
+        # Extract plain text from a mixed content value.
+        #
+        # nil → '' / String → itself / Array → text_of mapped + joined /
+        # InlineElement → #content.to_s / StructuralElement → recurse on
+        # #children / other Base → #content if String else #title.to_s /
+        # anything else → #to_s.
+        def text_of(content)
+          return '' if content.nil?
+          return content if content.is_a?(String)
+          return text_of_one(content) unless content.is_a?(Array)
+
+          content.map { |item| text_of_one(item) }.join
+        end
+
+        # Return a new array with leading whitespace stripped from the
+        # first text-carrying item and trailing whitespace stripped from
+        # the last. Inputs are not mutated. Non-Array inputs return
+        # unchanged. If no item carries text, returns the input array
+        # unchanged.
+        def strip_edges(content)
+          return content unless content.is_a?(Array)
+          return content if content.empty?
+
+          first_idx = content.index { |i| text_carrier?(i) }
+          return content if first_idx.nil?
+          last_idx = content.rindex { |i| text_carrier?(i) }
+
+          content.map.with_index do |item, idx|
+            next item unless text_carrier?(item)
+
+            stripped = item_text(item)
+            stripped = stripped.lstrip if idx == first_idx
+            stripped = stripped.rstrip if idx == last_idx
+            item.is_a?(String) ? stripped : item.with_content(stripped)
+          end
+        end
+
+        private
+
+        def text_of_one(item)
+          case item
+          when String then item
+          when CoreModel::InlineElement then item.content.to_s
+          when CoreModel::StructuralElement then text_of(Array(item.children))
+          when CoreModel::Block
+            item.children.is_a?(Array) && !item.children.empty? ? text_of(item.children) : item.content.to_s
+          when CoreModel::Base
+            item.content.is_a?(String) ? item.content : item.title.to_s
+          else
+            item.to_s
+          end
+        end
+
+        def text_carrier?(item)
+          item.is_a?(String) || item.is_a?(CoreModel::InlineElement)
+        end
+
+        def item_text(item)
+          item.is_a?(String) ? item : item.content.to_s
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/inline_element.rb

@@ -24,13 +24,24 @@ module Coradoc
         self.class.format_type || format_type
       end
 
-      FORMAT_TYPES = %w[
-        bold italic monospace underline strikethrough
-        subscript superscript highlight
-        link xref stem footnote
-        hard_line_break text span term
-        line_break quotation
-      ].freeze
+      # Return a duplicate of this element with its content replaced.
+      # Used by InlineContent.strip_edges (and other edge-cleanup
+      # callers) so that mutations never leak through the public API.
+      def with_content(new_content)
+        dup.tap { |copy| copy.content = new_content }
+      end
+
+      # Polymorphic classification used by LinkRewriter::Visitor. Returns
+      # :link / :xref when this node carries a rewrite-able target, nil
+      # otherwise. Generic InlineElement instances defer to their
+      # resolved format_type; typed subclasses override with a literal.
+      # Keeps the visitor free of class-keyed case/when (OCP).
+      def link_kind
+        case resolve_format_type
+        when 'link' then :link
+        when 'xref' then :xref
+        end
+      end
 
       attribute :format_type, :string
       attribute :content, :string
@@ -99,12 +110,20 @@ module Coradoc
       def self.format_type
         'link'
       end
+
+      def link_kind
+        :link
+      end
     end
 
     class CrossReferenceElement < InlineElement
       def self.format_type
         'xref'
       end
+
+      def link_kind
+        :xref
+      end
     end
 
     class StemElement < InlineElement
@@ -149,24 +168,31 @@ module Coradoc
       end
     end
 
-    FORMAT_TYPE_CLASS_MAP = {
-      'bold' => BoldElement,
-      'italic' => ItalicElement,
-      'monospace' => MonospaceElement,
-      'underline' => UnderlineElement,
-      'strikethrough' => StrikethroughElement,
-      'subscript' => SubscriptElement,
-      'superscript' => SuperscriptElement,
-      'highlight' => HighlightElement,
-      'link' => LinkElement,
-      'xref' => CrossReferenceElement,
-      'stem' => StemElement,
-      'footnote' => FootnoteElement,
-      'hard_line_break' => HardLineBreakElement,
-      'text' => TextElement,
-      'span' => SpanElement,
-      'term' => TermElement,
-      'line_break' => LineBreakElement
-    }.freeze
+    # Wire-name table: bidirectional string ↔ class index. Single source
+    # of truth for serialization names and runtime dispatch. Reopened
+    # onto InlineElement so the subclasses above are defined first.
+    class InlineElement
+      FORMAT_TYPE_CLASS_MAP = {
+        'bold' => BoldElement,
+        'italic' => ItalicElement,
+        'monospace' => MonospaceElement,
+        'underline' => UnderlineElement,
+        'strikethrough' => StrikethroughElement,
+        'subscript' => SubscriptElement,
+        'superscript' => SuperscriptElement,
+        'highlight' => HighlightElement,
+        'link' => LinkElement,
+        'xref' => CrossReferenceElement,
+        'stem' => StemElement,
+        'footnote' => FootnoteElement,
+        'hard_line_break' => HardLineBreakElement,
+        'text' => TextElement,
+        'span' => SpanElement,
+        'term' => TermElement,
+        'line_break' => LineBreakElement
+      }.freeze
+
+      FORMAT_TYPES = FORMAT_TYPE_CLASS_MAP.keys.freeze
+    end
   end
 end

data/lib/coradoc/core_model/list_block.rb

@@ -108,6 +108,23 @@ module Coradoc
       #   @return [Array<ListItem>] collection of list items
       attribute :items, ListItem, collection: true
 
+      # -- Fluent construction helpers (paired with Base.build) --
+
+      # Append a new ListItem, built via ListItem.build. The block
+      # (if given) is yielded the new item so callers can chain
+      # +add_text+ / +add_link+ on it inline:
+      #
+      #   ListBlock.build do |ul|
+      #     children.each { |c| ul.add_item { |li| li.add_link(c[:slug], text: c[:title]) } }
+      #   end
+      #
+      # Returns self for chaining at the list level.
+      def add_item(marker: self.marker_type == 'ordered' ? '.' : '*')
+        item = ListItem.build(marker: marker) { |li| yield li if block_given? }
+        self.items = Array(items) + [item]
+        self
+      end
+
       private
 
       # Attributes to compare for semantic equivalence

data/lib/coradoc/core_model/list_item.rb

@@ -109,6 +109,27 @@ module Coradoc
         true
       end
 
+      # -- Fluent construction helpers (paired with Base.build) --
+
+      # Append a plain-text inline to this item's children. Returns
+      # self for chaining. Pairs naturally with ListItem.build:
+      #
+      #   ListItem.build do |li|
+      #     li.add_text("See ")
+      #     li.add_link("foo.adoc", text: "Foo")
+      #   end
+      def add_text(text)
+        self.children = Array(children) + [TextContent.new(text: text)]
+        self
+      end
+
+      # Append a +link:+ inline to this item's children. +text+ becomes
+      # the link's visible label; +target+ is the URL/anchor.
+      def add_link(target, text: nil)
+        self.children = Array(children) + [LinkElement.new(target: target, content: text)]
+        self
+      end
+
       private
 
       # Compare two list blocks for equivalence

data/lib/coradoc/core_model/output_artifact.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Output-side state object for host-system emitters (VitePress, Hugo,
+    # Astro, plain ERB, etc.).
+    #
+    # coradoc's source side has +IncludeResolver::Filesystem+ to resolve
+    # include targets without coupling to a storage layer. The output side
+    # has no analogous state object — until now. +OutputArtifact+ captures
+    # the three pieces of state coradoc genuinely needs to hand to a
+    # downstream emitter:
+    #
+    # - +output_key+ — site-relative key (e.g. "author/iso/ref/foo")
+    # - +frontmatter_block+ — parsed YAML frontmatter (may be empty)
+    # - +core_document+ — the canonical CoreModel document
+    #
+    # The consumer takes these and renders whatever wrapper it needs in
+    # its host system's native template language. coradoc does not know
+    # about VitePress, ERB, or Liquid. Symmetric with the source side:
+    # minimal protocol object, not an engine.
+    #
+    # A mirror-tree document is deliberately NOT bundled here. coradoc
+    # core has no runtime dependency on coradoc-mirror; consumers that
+    # target the mirror JSON pipeline pair an +OutputArtifact+ with a
+    # separately-computed +Coradoc::Mirror.transform(core)+ result.
+    class OutputArtifact < Base
+      # @!attribute output_key
+      #   @return [String, nil] site-relative key with no leading slash
+      #     and no trailing extension. SSGs map this to their URL space.
+      attribute :output_key, :string
+
+      # @!attribute frontmatter_block
+      #   @return [FrontmatterBlock, nil] parsed YAML frontmatter
+      attribute :frontmatter_block, FrontmatterBlock
+
+      # @!attribute core_document
+      #   @return [DocumentElement, nil] canonical CoreModel document
+      attribute :core_document, DocumentElement
+
+      private
+
+      def comparable_attributes
+        %i[output_key frontmatter_block core_document]
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/paragraph_block.rb

@@ -7,6 +7,10 @@ module Coradoc
       def self.semantic_type
         :paragraph
       end
+
+      def whitespace_only?
+        flat_text.strip.empty?
+      end
     end
   end
 end

data/lib/coradoc/core_model/stem_block.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # STEM block — mathematical/scientific content authored in LaTeX,
+    # AsciiMath, or another STEM markup. Carries a +language+ attribute so
+    # downstream renderers know which interpreter to invoke.
+    #
+    # AsciiDoc surface forms:
+    #   [stem]\n++++\nx^2\n++++        # language: "latex" (default)
+    #   [latexmath]\n++++\nx^2\n++++   # language: "latex"
+    #   [asciimath]\n++++\nx^2\n++++   # language: "asciimath"
+    class StemBlock < Block
+      attribute :language, :string, default: -> { 'latex' }
+
+      def self.semantic_type
+        :stem
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/structural_element.rb

@@ -52,6 +52,38 @@ module Coradoc
         false
       end
 
+      # Override in subclasses that carry document-title semantics.
+      # HeaderElement at level 0 represents the document title (`= Title`
+      # in AsciiDoc). Consumers that walk the body — TOC builders,
+      # section numbering — skip these so the title is not counted as
+      # "section 1". Polymorphic dispatch (vs. an is_a? guard at the
+      # call site) keeps the predicate open for future subclasses.
+      def document_title?
+        false
+      end
+
+      # Children that count as body content and aren't whitespace-only.
+      # Derived from per-node {#body_content?} and {#whitespace_only?}
+      # predicates — no central walker, no is_a? switch to maintain.
+      def visible_children
+        Array(children).select(&:body_content?).reject(&:whitespace_only?)
+      end
+
+      # True when the body has no visible content anywhere in its subtree.
+      # A document with only frontmatter + comments returns true; a
+      # document with one non-whitespace paragraph returns false.
+      def empty_body?
+        return true if children.nil? || children.empty?
+
+        children.all? do |child|
+          next true unless child.body_content?
+          next true if child.whitespace_only?
+          next child.empty_body? if child.is_a?(StructuralElement)
+
+          false
+        end
+      end
+
       # Derived element_type string for backward compatibility with
       # templates and legacy consumers. Subclasses override this.
       def element_type
@@ -108,6 +140,15 @@ module Coradoc
         true
       end
 
+      # A level-0 HeaderElement represents the document title (the `= Title`
+      # line in AsciiDoc, the `<h1>` in HTML). It is structurally part of
+      # the body but semantically the document's title, not a section —
+      # section numbering, TOC builders, and other section-aware logic
+      # skip these so the title is not counted as "section 1".
+      def document_title?
+        level.to_i.zero?
+      end
+
       def self.element_type_name
         'header'
       end

data/lib/coradoc/core_model/text_content.rb

@@ -17,6 +17,10 @@ module Coradoc
       def to_s
         text.to_s
       end
+
+      def whitespace_only?
+        text.to_s.strip.empty?
+      end
     end
   end
 end

data/lib/coradoc/core_model.rb

@@ -13,6 +13,7 @@ module Coradoc
     autoload :Base, "#{__dir__}/core_model/base"
     autoload :ChildrenContent, "#{__dir__}/core_model/children_content"
     autoload :HasChildren, "#{__dir__}/core_model/has_children"
+    autoload :InlineContent, "#{__dir__}/core_model/inline_content"
     autoload :Callout, "#{__dir__}/core_model/callout"
     autoload :CalloutText, "#{__dir__}/core_model/callout_text"
     autoload :Block, "#{__dir__}/core_model/block"
@@ -70,6 +71,7 @@ module Coradoc
     autoload :SidebarBlock, "#{__dir__}/core_model/sidebar_block"
     autoload :LiteralBlock, "#{__dir__}/core_model/literal_block"
     autoload :PassBlock, "#{__dir__}/core_model/pass_block"
+    autoload :StemBlock, "#{__dir__}/core_model/stem_block"
     autoload :ListingBlock, "#{__dir__}/core_model/listing_block"
     autoload :OpenBlock, "#{__dir__}/core_model/open_block"
     autoload :VerseBlock, "#{__dir__}/core_model/verse_block"
@@ -82,5 +84,6 @@ module Coradoc
     autoload :Include, "#{__dir__}/core_model/include"
     autoload :IncludeOptions, "#{__dir__}/core_model/include_options"
     autoload :IncludeLevelOffset, "#{__dir__}/core_model/include_level_offset"
+    autoload :OutputArtifact, "#{__dir__}/core_model/output_artifact"
   end
 end

data/lib/coradoc/dispatch.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Type-keyed handler dispatch.
+  #
+  # Replaces the bespoke `register/lookup` hashes that recur across gems with
+  # one cohesive registry. Each gem that needs type-keyed dispatch configures
+  # a single Dispatch instance and exposes its legacy DSL as thin delegates.
+  #
+  # Two resolution policies cover the common shapes:
+  #
+  # - `Coradoc::Dispatch.strict`     — exact key match, raises on miss
+  # - `Coradoc::Dispatch.hierarchical` — walks ancestors on miss, returns nil
+  #
+  # Registries that need priority ordering, predicate matching, or lazy
+  # loading do not fit this shape and stay as they are; the friction there is
+  # genuine semantic difference, not duplicated mechanism.
+  class Dispatch
+    TERMINAL_ANCESTORS = [Object, BasicObject].freeze
+    private_constant :TERMINAL_ANCESTORS
+
+    class << self
+      # Exact key match; raises if no entry. Used by registries that map a
+      # concrete type to its sole handler (e.g. AsciiDoc ElementRegistry).
+      def strict = new(walk_ancestors: false)
+
+      # Walks the key's class ancestors on miss; returns nil if no entry.
+      # Used by registries that want base-class handlers to apply to all
+      # subclasses (e.g. Mirror HandlerRegistry).
+      def hierarchical = new(walk_ancestors: true, miss: :return_nil)
+    end
+
+    def initialize(walk_ancestors: false, miss: :raise, &default)
+      @walk_ancestors = walk_ancestors
+      @miss = miss
+      @default = default
+      @entries = {}
+    end
+
+    def register(key, handler)
+      @entries[key] = handler
+    end
+
+    # Replace the handler for an existing key. Returns the previous handler
+    # so wrappers can chain: original = dispatch.override(K, Wrapper.new(original))
+    def override(key, handler)
+      previous = @entries[key]
+      @entries[key] = handler
+      previous
+    end
+
+    def unregister(key)
+      @entries.delete(key)
+    end
+
+    # Resolve the handler for a key. Returns nil if no handler matches
+    # unless the dispatch is configured to raise.
+    def lookup(key)
+      exact = @entries[key]
+      return exact if exact
+      return walk(key) if @walk_ancestors && key.is_a?(Class)
+
+      apply_default(key)
+    end
+
+    # Resolve the handler, raising Coradoc::Error on miss.
+    def lookup!(key)
+      lookup(key) || raise(Coradoc::Error, "no handler registered for #{key.inspect}")
+    end
+
+    def registered?(key) = @entries.key?(key)
+
+    def registered_keys = @entries.keys
+
+    def clear! = @entries.clear
+
+    private
+
+    def walk(klass)
+      klass.ancestors.each do |ancestor|
+        next if ancestor == klass
+        break if TERMINAL_ANCESTORS.include?(ancestor)
+
+        entry = @entries[ancestor]
+        return entry if entry
+      end
+      apply_default(klass)
+    end
+
+    def apply_default(key)
+      return @default.call(key) if @default
+      nil
+    end
+  end
+end