coradoc 2.0.18 → 2.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d959d40057c13f8a634e88fb5f60b9a42c4d80cda2ccf5c701222afd33799017
-  data.tar.gz: 933c97c0ffc3691683760d256354a5c03148aa929f2c61b51c3a41e859f54c9b
+  metadata.gz: 05f1c48e0de6edb3f2473ab0e1c0cdb4747c513bf805820b8456846888b86c37
+  data.tar.gz: caaadd87ea878292673070688c08c8a7bfb7c39c58173f928e1960eb5af397ad
 SHA512:
-  metadata.gz: 55e37e38878cc8728ed4d12cebfac1fd370fe19c1e69339a10a3de9492cde1f096a75ee6e49917869440c8c72b90109281cfd392e19741f56d9bd3cfd968319b
-  data.tar.gz: 5d8c7ca506943cad23f79c61c511666b2cd466324dd849d2c267a381f8f119f3d956f50c6c26fa879664a3d49e7467c057500ff7d4a8515edb0574929d718815
+  metadata.gz: 86f2108a83a94d30b5660586c5b83085b1b9f1ebd0ab470d21292f258cc0473d4769eb266394082d335a7d39ed2499297f0d4d1f1e2ac517c42f3d5b3bbe3527
+  data.tar.gz: aa4241a2a9c0ae8cec854b747b76a709bb8954b9bbbf6a3c15b3ebaad77f7b1dea199fc57129541fadcce94bee957cde48f7c3bda906379a5095a4893efdd0e1

data/lib/coradoc/core_model/base.rb

@@ -117,6 +117,23 @@ module Coradoc
         end
       end
 
+      def flat_text
+        ""
+      end
+
+      # Flatten this element to a plain-text string.
+      #
+      # Subclasses that include ChildrenContent override this to
+      # concatenate their children's text. Block-level elements
+      # without textual content (ListBlock, Table, etc.) fall back
+      # to the empty string — they are serialized structurally,
+      # not flattened into inline text.
+      #
+      # @return [String]
+      def flat_text
+        ""
+      end
+
       # Accept a visitor to traverse this element
       #
       # Implements the visitor pattern for document traversal.

data/lib/coradoc/core_model/block.rb

@@ -53,10 +53,16 @@ module Coradoc
       #   @return [String, nil] language identifier for source code blocks
       attribute :language, :string
 
+      # @!attribute callouts
+      #   @return [Array<Callout>] callout annotations attached to this
+      #     block. Empty for most block types; populated by format gems
+      #     when AsciiDoc-style `<N>` annotations follow a verbatim block.
+      attribute :callouts, Callout, collection: true, default: -> { [] }
+
       private
 
       def comparable_attributes
-        super + %i[block_semantic_type content]
+        super + %i[block_semantic_type content callouts]
       end
     end
   end

data/lib/coradoc/core_model/callout.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # A single callout annotation attached to a verbatim block.
+    #
+    # Callouts are the AsciiDoc convention for annotating individual lines
+    # of a source/listing block: `<1>` markers appear inside the code and
+    # matching `<1> explanation` lines follow the block. Markdown has no
+    # native equivalent, so each format gem decides how to render them.
+    #
+    # The CoreModel stores each annotation as a typed Callout on its parent
+    # block, with the in-code marker `<index>` preserved in the block's
+    # `content` for verbatim round-trip.
+    class Callout < Base
+      # @!attribute index
+      #   @return [Integer, nil] 1-based callout number matching the
+      #     `<N>` marker embedded in the parent block's content.
+      attribute :index, :integer
+
+      # @!attribute content
+      #   @return [String, nil] human-readable annotation text.
+      attribute :content, :string
+
+      private
+
+      def comparable_attributes
+        super + %i[index content]
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/callout_text.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Shared helpers for rendering Callout-annotated verbatim blocks.
+    #
+    # Both the Markdown and HTML spokes need to (a) order callouts by their
+    # numeric index and (b) strip AsciiDoc-style `<N>` markers from the
+    # raw code so they don't leak as literal text in the output format.
+    # Centralizing these operations here keeps the behavior consistent
+    # across spokes and avoids copy-paste drift.
+    module CalloutText
+      module_function
+
+      def ordered(callouts)
+        Array(callouts).sort_by { |c| c.index || Float::INFINITY }
+      end
+
+      # Removes callout markers (`<N>`) from `code` for the indices
+      # referenced by `callouts`. Returns `code` unchanged when no
+      # callouts are provided or none carry a usable index, so literal
+      # `<N>` sequences in code without callouts are preserved.
+      def strip_markers(code, callouts)
+        list = Array(callouts)
+        return code if list.empty?
+
+        indices = list.filter_map(&:index).uniq
+        return code if indices.empty?
+
+        pattern = /<\s*(?:#{indices.join('|')})\s*>/
+        code.to_s.lines(chomp: true).map { |line| line.gsub(pattern, '').rstrip }.join("\n")
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/children_content.rb

@@ -25,6 +25,9 @@ module Coradoc
 
             CoreModel::TextContent.new(text: item.to_s)
           end.compact
+          # Lutaml defines the setter directly on the class, so we overwrite it.
+          # We cannot use `super` because the original setter is lost.
+          # `instance_variable_set` is required here to actually store the wrapped value.
           instance_variable_set(:@children, wrapped)
         end
       end
@@ -44,10 +47,21 @@ module Coradoc
         rc = renderable_content
         case rc
         when String then rc
-        when Array then rc.map { |c| c.is_a?(TextContent) ? c.text : c.content.to_s }.join
+        when Array then rc.map { |c| extract_child_text(c) }.join
         else rc.to_s
         end
       end
+
+      private
+
+      def extract_child_text(child)
+        case child
+        when TextContent then child.text
+        when String then child
+        when Base then child.flat_text
+        else child.to_s
+        end
+      end
     end
   end
 end

data/lib/coradoc/core_model/comment_line.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Single-line comment — editorial or hidden notes that do not render.
+    #
+    # Distinct from {CommentBlock} (multi-line). Round-trip fidelity for the
+    # single-line vs. block distinction is preserved across formats that have
+    # a single-line comment syntax (AsciiDoc `//`); formats without one (e.g.
+    # Markdown) collapse both to `<!-- ... -->`.
+    class CommentLine < Base
+      def self.semantic_type
+        :comment_line
+      end
+
+      attribute :text, :string
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Coradoc
+  module CoreModel
+    class FrontmatterBlock
+      # Single source of truth for YAML ↔ FrontmatterBlock translation.
+      #
+      # 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).
+      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).
+          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
+            FrontmatterBlock.new
+          end
+
+          # Serialize a FrontmatterBlock to canonical YAML text.
+          # Does NOT include leading/trailing `---` delimiters; the caller
+          # wraps the output.
+          def to_yaml(block)
+            return '' unless block.is_a?(FrontmatterBlock)
+
+            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...")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    class FrontmatterBlock
+      # OCP registry for semantic field transforms applied during
+      # format conversion (e.g., `authors` array → `author` string when
+      # emitting Markdown for Jekyll).
+      #
+      # Transforms are directional + format-specific. Each transform
+      # declares when it applies and how it rewrites the block's data
+      # hash. Never mutates the input — always returns a new block.
+      module FieldTransform
+        # Base class. Override #applies? and #apply in subclasses.
+        class Base
+          # Override: return true if this transform should fire for the
+          # given direction (:to_format or :from_format) and format
+          # (:markdown, :asciidoc, etc.).
+          def applies?(direction:, format:) # rubocop:disable Lint/UnusedMethodArgument
+            false
+          end
+
+          # Override: receive a FrontmatterBlock, return a (possibly new)
+          # FrontmatterBlock. Never mutate the input.
+          def apply(block)
+            block
+          end
+
+          protected
+
+          # Helper: produce a new FrontmatterBlock with transformed data.
+          def rebuild(block, data:)
+            FrontmatterBlock.new(schema: block.schema, data: data)
+          end
+        end
+
+        class Registry
+          DEFAULT = new
+
+          def initialize
+            @transforms = []
+          end
+
+          def register(transform_class)
+            @transforms << transform_class unless @transforms.include?(transform_class)
+          end
+
+          def count
+            @transforms.size
+          end
+
+          # Apply all registered transforms whose #applies? returns true.
+          # Returns a FrontmatterBlock (possibly the same one).
+          def apply_all(block, direction:, format:)
+            return block unless block.is_a?(FrontmatterBlock)
+
+            @transforms.reduce(block) do |current, klass|
+              transform = klass.new
+              if transform.applies?(direction: direction, format: format)
+                transform.apply(current)
+              else
+                current
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    class FrontmatterBlock
+      # OCP registry mapping `$schema` URLs to validator classes.
+      #
+      # Core ships with NO built-in validators. Downstream gems (e.g.,
+      # a future `coradoc-jsonschema`) register resolvers without
+      # modifying core code.
+      module SchemaResolver
+        # Structured validation error. Typed — never a hash bag.
+        ValidationError = Struct.new(:field, :message, keyword_init: true)
+
+        # Base class for schema resolvers. Override #validate in subclasses.
+        class Base
+          def validate(_block)
+            []
+          end
+        end
+
+        # Registry of URL → resolver class.
+        class Registry
+          DEFAULT = new
+
+          def initialize
+            @resolvers = {}
+          end
+
+          def register(schema_url, resolver_class)
+            @resolvers[schema_url.to_s] = resolver_class
+          end
+
+          def lookup(schema_url)
+            @resolvers[schema_url.to_s]
+          end
+
+          def registered?(schema_url)
+            @resolvers.key?(schema_url.to_s)
+          end
+
+          # Returns array of ValidationError structs. Empty if no schema,
+          # no resolver, or validation passes.
+          def validate(block)
+            return [] unless block.is_a?(FrontmatterBlock)
+            return [] if block.schema.nil?
+
+            resolver_class = lookup(block.schema)
+            return [] unless resolver_class
+
+            resolver_class.new.validate(block)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    class FrontmatterBlock
+      # Format-agnostic text splitter for the YAML frontmatter block
+      # convention (`---\n...\n---\n` at the very start of a document).
+      #
+      # Lives under FrontmatterBlock alongside Codec, SchemaResolver,
+      # and FieldTransform — together they form the complete frontmatter
+      # machinery (MECE):
+      #
+      #   TextSplitter   — text → (frontmatter_text, body_text)
+      #   Codec          — frontmatter_text ↔ typed FrontmatterBlock
+      #   SchemaResolver — typed FrontmatterBlock → validation errors
+      #   FieldTransform — typed FrontmatterBlock → transformed block
+      #
+      # Format gems (Markdown, AsciiDoc, ...) call this splitter at the
+      # top of their parse pipeline so frontmatter never reaches the
+      # format's block parser. Single source of truth (DRY).
+      module TextSplitter
+        OPEN_DELIMITER = '---'
+        CLOSE_DELIMITERS = %w[--- ...].freeze
+
+        # Result of splitting source text. +frontmatter+ is the raw YAML
+        # body (without delimiters), nil if no frontmatter was present.
+        # +body+ is the remaining document text.
+        Result = Struct.new(:frontmatter, :body, keyword_init: true) do
+          def frontmatter?
+            !frontmatter.nil? && !frontmatter.empty?
+          end
+        end
+
+        class << self
+          # @param text [String, nil] Source document text.
+          # @return [Result]
+          def call(text)
+            return Result.new(frontmatter: nil, body: '') if text.nil? || text.empty?
+
+            lines = text.lines
+            return empty_with(text) unless opens_frontmatter?(lines.first)
+
+            close_index = find_close_line(lines, 1)
+            return empty_with(text) if close_index.nil?
+
+            frontmatter = lines[1...close_index].join
+            body = lines[(close_index + 1)..].join
+            body = body.sub(/\A\n+/, '') if body.start_with?("\n")
+
+            Result.new(frontmatter: frontmatter, body: body)
+          end
+
+          private
+
+          def opens_frontmatter?(first_line)
+            return false unless first_line
+
+            first_line.strip == OPEN_DELIMITER
+          end
+
+          def find_close_line(lines, start_at)
+            start_at.upto(lines.size - 1) do |i|
+              return i if CLOSE_DELIMITERS.include?(lines[i].strip)
+            end
+            nil
+          end
+
+          def empty_with(text)
+            Result.new(frontmatter: nil, body: text)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/frontmatter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # First-class block representing YAML frontmatter attached to a
+    # document.
+    #
+    # Frontmatter is modeled as a Block (not a side-attribute on
+    # DocumentElement) so it flows through the standard block pipeline:
+    # parsers produce it, transformers dispatch on its class, serializers
+    # emit it. No special-casing anywhere.
+    #
+    # The +data+ hash stores the entire parsed YAML frontmatter (minus
+    # +$schema+, which is promoted to the +schema+ attribute). Using a
+    # hash — rather than a typed value tree — lets coradoc accept any
+    # frontmatter shape without code changes. Type handling is delegated
+    # to Ruby's native YAML/JSON, which already preserve Date, Integer,
+    # Float, Boolean, nil, Array, and Hash correctly for YAML round-trips.
+    #
+    # The +$schema+ key, if present in source YAML, is promoted to the
+    # +schema+ attribute (single source of truth — DRY); SchemaResolver
+    # reads it to find validators.
+    class FrontmatterBlock < Block
+      def self.semantic_type
+        :frontmatter
+      end
+
+      def self.element_type_name
+        'frontmatter'
+      end
+
+      # `$schema` URL, nil-safe. Consumed by SchemaResolver registry.
+      attribute :schema, :string
+
+      # Entire parsed YAML frontmatter (minus `$schema`). Values are
+      # native Ruby types from YAML.safe_load (String, Integer, Date,
+      # Array, Hash, etc.). Order is preserved for round-trip fidelity.
+      attribute :data, :hash, default: {}
+
+      # Convenience accessor — read a single entry by key.
+      def entry(key)
+        data[key.to_s]
+      end
+
+      def has_entry?(key)
+        data.key?(key.to_s)
+      end
+
+      def empty?
+        schema.nil? && (data.nil? || data.empty?)
+      end
+
+      # Sub-namespaces (Codec, SchemaResolver, FieldTransform, TextSplitter)
+      # live under FrontmatterBlock and autoload lazily.
+      autoload :Codec, "#{__dir__}/frontmatter/codec"
+      autoload :SchemaResolver, "#{__dir__}/frontmatter/schema_resolver"
+      autoload :FieldTransform, "#{__dir__}/frontmatter/field_transform"
+      autoload :TextSplitter, "#{__dir__}/frontmatter/text_splitter"
+    end
+  end
+end

data/lib/coradoc/core_model.rb

@@ -12,6 +12,8 @@ module Coradoc
     # Autoload submodules lazily using relative paths
     autoload :Base, "#{__dir__}/core_model/base"
     autoload :ChildrenContent, "#{__dir__}/core_model/children_content"
+    autoload :Callout, "#{__dir__}/core_model/callout"
+    autoload :CalloutText, "#{__dir__}/core_model/callout_text"
     autoload :Block, "#{__dir__}/core_model/block"
     autoload :AnnotationBlock, "#{__dir__}/core_model/annotation_block"
     autoload :ListBlock, "#{__dir__}/core_model/list_block"
@@ -49,6 +51,7 @@ module Coradoc
     autoload :ElementAttribute, "#{__dir__}/core_model/element_attribute"
     autoload :Metadata, "#{__dir__}/core_model/metadata"
     autoload :MetadataEntry, "#{__dir__}/core_model/metadata"
+    autoload :FrontmatterBlock, "#{__dir__}/core_model/frontmatter"
     autoload :Footnote, "#{__dir__}/core_model/footnote"
     autoload :FootnoteReference, "#{__dir__}/core_model/footnote"
     autoload :Abbreviation, "#{__dir__}/core_model/footnote"
@@ -71,6 +74,7 @@ module Coradoc
     autoload :ReviewerBlock, "#{__dir__}/core_model/reviewer_block"
     autoload :ParagraphBlock, "#{__dir__}/core_model/paragraph_block"
     autoload :CommentBlock, "#{__dir__}/core_model/comment_block"
+    autoload :CommentLine, "#{__dir__}/core_model/comment_line"
     autoload :HorizontalRuleBlock, "#{__dir__}/core_model/horizontal_rule_block"
     autoload :IdGenerator, "#{__dir__}/core_model/id_generator"
   end

data/lib/coradoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Coradoc
-  VERSION = '2.0.18'
+  VERSION = '2.0.20'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coradoc
 version: !ruby/object:Gem::Version
-  version: 2.0.18
+  version: 2.0.20
 platform: ruby
 authors:
 - Ribose Inc.
@@ -60,13 +60,21 @@ files:
 - lib/coradoc/core_model/bibliography.rb
 - lib/coradoc/core_model/bibliography_entry.rb
 - lib/coradoc/core_model/block.rb
+- lib/coradoc/core_model/callout.rb
+- lib/coradoc/core_model/callout_text.rb
 - lib/coradoc/core_model/children_content.rb
 - lib/coradoc/core_model/comment_block.rb
+- lib/coradoc/core_model/comment_line.rb
 - lib/coradoc/core_model/definition_item.rb
 - lib/coradoc/core_model/definition_list.rb
 - lib/coradoc/core_model/element_attribute.rb
 - lib/coradoc/core_model/example_block.rb
 - lib/coradoc/core_model/footnote.rb
+- lib/coradoc/core_model/frontmatter.rb
+- lib/coradoc/core_model/frontmatter/codec.rb
+- lib/coradoc/core_model/frontmatter/field_transform.rb
+- lib/coradoc/core_model/frontmatter/schema_resolver.rb
+- lib/coradoc/core_model/frontmatter/text_splitter.rb
 - lib/coradoc/core_model/horizontal_rule_block.rb
 - lib/coradoc/core_model/id_generator.rb
 - lib/coradoc/core_model/image.rb