coradoc-adoc 2.0.8 → 2.0.10

data/lib/coradoc/asciidoc/parser/list.rb

@@ -29,10 +29,10 @@ module Coradoc
           attrs >> r.repeat(1).as(:unordered)
         end
 
-        def definition_list(delimiter = '::')
+        def definition_list(_delimiter = nil)
           (attribute_list >> newline).maybe >>
-            dlist_item(delimiter).repeat(1).as(:definition_list) >>
-            dlist_item(delimiter).absent?
+            dlist_item.repeat(1).as(:definition_list) >>
+            dlist_item.absent?
         end
 
         def list_marker(nesting_level = 1)
@@ -98,27 +98,32 @@ module Coradoc
         end
 
         def dlist_delimiter
-          (str('::') | str(':::') | str('::::') | str(';;')
+          (
+            (str(':::::') >> match(':').absent?) |
+            (str('::::') >> match(':').absent?) |
+            (str(':::') >> match(':').absent?) |
+            (str('::') >> match(':').absent?) |
+            str(';;')
           ).as(:delimiter)
         end
 
-        def dlist_term(_delimiter)
-          (element_id_inline.maybe >>
-            match("[^\n:]").repeat(1)
-                           .as(:text)
-          ).as(:dlist_term) >> dlist_delimiter
+        def dlist_term(_delimiter = nil)
+          term_chars =
+            (dlist_delimiter.absent? >> match("[^\n]")).repeat(1)
+                                                       .as(:text)
+          (element_id_inline.maybe >> term_chars).as(:dlist_term) >> dlist_delimiter
         end
 
         def dlist_definition
-          text # >> empty_line.repeat(0)
+          text
             .as(:definition) >> line_ending >> empty_line.repeat(0)
         end
 
-        def dlist_item(delimiter)
-          (((dlist_term(delimiter).as(:terms).repeat(1) >> line_ending >>
+        def dlist_item(_delimiter = nil)
+          (((dlist_term.as(:terms).repeat(1) >> line_ending >>
             empty_line.repeat(0)).repeat(1) >>
             dlist_definition) |
-            (dlist_term(delimiter).repeat(1, 1).as(:terms) >> space >>
+            (dlist_term.repeat(1, 1).as(:terms) >> space >>
               dlist_definition)
           ).as(:definition_list_item)
         end

data/lib/coradoc/asciidoc/parser/paragraph.rb

@@ -40,9 +40,7 @@ module Coradoc
         # rubocop:enable Style/OptionalBooleanParameter, Style/NumericPredicate
 
         def paragraph
-          (element_id.maybe >>
-            block_title.maybe >>
-            (attribute_list >> newline).maybe >>
+          (block_header >>
             ((paragraph_text_line(0).repeat(1, 1) >>
                    (newline.repeat(1).as(:line_break) | eof?)) |
               (paragraph_text_line(false).repeat(1) >>

data/lib/coradoc/asciidoc/parser/rule_dispatcher.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Parser
+      # Wraps every parser rule for Parslet memoization.
+      #
+      # Parameterized rules (e.g., `block_style(n_deep, delimiter, repeater)`)
+      # cannot be memoized by Parslet directly because their result depends
+      # on the args. This module aliases each rule to a per-args dispatch
+      # rule so Parslet sees a memoizable, parameterless rule for every
+      # (rule_name, args) combination. Parameterless rules get a single
+      # memoized alias.
+      #
+      # Also warns when a parser method is defined in more than one parser
+      # module — duplicate definitions are usually a refactoring mistake
+      # and produce confusing "last one wins" behavior at include time.
+      #
+      # Invoked once at Parser::Base load time.
+      module RuleDispatcher
+        DISPATCH_CONFIG = {
+          add_dispatch: true,
+          with_params: true
+        }.freeze
+
+        class << self
+          # @param parser_class [Class] Parser::Base or a subclass
+          def apply(parser_class)
+            parser_methods = collect_rule_names
+            warn_on_duplicates(parser_methods)
+            wrap_rules(parser_class, parser_methods)
+          end
+
+          # Per-instance dispatch invoked from the parameterized rule wrappers.
+          # @param parser_instance [Parser::Base]
+          # @param alias_name [Symbol] The alias created at wrap time
+          # @param args [Array]
+          # @param kwargs [Hash]
+          def dispatch(parser_instance, alias_name, *args, **kwargs)
+            cache = dispatch_cache(parser_instance)
+            key = dispatch_key(alias_name, args, kwargs)
+            unless cache.key?(key)
+              rule_name = dispatch_rule_name(alias_name, key)
+              unless parser_instance.respond_to?(rule_name)
+                build_dispatch_rule(parser_instance.class, alias_name,
+                                    rule_name, args, kwargs)
+              end
+              cache[key] = rule_name
+            end
+            parser_instance.public_send(cache[key])
+          end
+
+          private
+
+          # Walk every parser module and collect rule-method names.
+          # `instance_methods(false)` returns only methods defined in the
+          # module itself, not inherited ones — without `false` we would
+          # also wrap Object#send, Kernel#__send__, Module#class, etc.
+          # Wrapping `__send__` in particular causes infinite recursion.
+          # @return [Hash{Symbol => Array<Module>}]
+          def collect_rule_names
+            parser_constants = Parser.constants - %i[Base Cache FixFiles RuleDispatcher]
+            parser_constants.each_with_object({}) do |const, acc|
+              Parser.const_get(const).instance_methods(false).each do |name|
+                acc[name] ||= []
+                acc[name] << const
+              end
+            end
+          end
+
+          def warn_on_duplicates(parser_methods)
+            parser_methods.each do |name, sites|
+              next unless sites.size > 1
+
+              modules = sites.map { |c| Parser.const_get(c) }
+              Coradoc::Logger.warn(
+                "Parser method '#{name}' is defined #{sites.size} times in #{modules.join(', ')}"
+              )
+            end
+          end
+
+          def wrap_rules(parser_class, parser_methods)
+            parser_methods.each_key do |rule_name|
+              params = parser_class.instance_method(rule_name).parameters
+              if dispatch? && params.empty?
+                wrap_nondispatch(parser_class, rule_name)
+              elsif dispatch? && with_params?
+                wrap_dispatch(parser_class, rule_name)
+              end
+            end
+          end
+
+          def wrap_nondispatch(parser_class, rule_name)
+            alias_name = :"alias_nondispatch_#{rule_name}"
+            guard_name = :"alias_nondispatch_rule_guard_#{rule_name}"
+            return if parser_class.method_defined?(guard_name)
+
+            parser_class.class_eval do
+              alias_method alias_name, rule_name
+              define_method(guard_name) {}
+              rule(rule_name) do
+                public_send(alias_name)
+              end
+            end
+          end
+
+          def wrap_dispatch(parser_class, rule_name)
+            alias_name = :"alias_dispatch_#{rule_name}"
+            guard_name = :"alias_dispatch_rule_guard_#{rule_name}"
+            return if parser_class.method_defined?(guard_name)
+
+            parser_class.class_eval do
+              alias_method alias_name, rule_name
+              define_method(guard_name) {}
+              define_method(rule_name) do |*args, **kwargs|
+                RuleDispatcher.dispatch(self, alias_name, *args, **kwargs)
+              end
+            end
+          end
+
+          def dispatch_cache(parser_instance)
+            parser_instance.instance_variable_get(:@_rule_dispatch_cache) ||
+              parser_instance.instance_variable_set(:@_rule_dispatch_cache, {})
+          end
+
+          def dispatch?
+            DISPATCH_CONFIG[:add_dispatch]
+          end
+
+          def with_params?
+            DISPATCH_CONFIG[:with_params]
+          end
+
+          def dispatch_key(alias_name, args, kwargs)
+            [alias_name, args, kwargs.to_a.sort].hash.abs
+          end
+
+          def dispatch_rule_name(alias_name, key)
+            :"#{alias_name}_#{key}"
+          end
+
+          # Build a Parslet memoizable rule that closes over the captured
+          # args and forwards to the original aliased rule. Using Parslet's
+          # class-level `rule()` (not define_method on singleton_class) is
+          # essential — Parslet's memoization, `as()`, and tree building
+          # depend on the rule going through the standard Parslet machinery.
+          def build_dispatch_rule(parser_class, original_alias, rule_name, args, kwargs)
+            parser_class.class_eval do
+              rule(rule_name) do
+                public_send(original_alias, *args, **kwargs)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/asciidoc/parser/section.rb

@@ -27,9 +27,7 @@ module Coradoc
         def section_block(level = 2)
           return nil if level > 8
 
-          (attribute_list >> newline).maybe >>
-            element_id.maybe >>
-            (attribute_list >> newline).maybe >>
+          block_header >>
             section_title(level).as(:title) >>
             contents.as(:contents).maybe
         end

data/lib/coradoc/asciidoc/parser/table.rb

@@ -41,10 +41,7 @@ module Coradoc
         # - "^e|" centered cell with emphasis style
 
         def table
-          element_id.maybe >>
-            (attribute_list >> newline).maybe >>
-            block_title.maybe >>
-            (attribute_list >> newline).maybe >>
+          block_header >>
             table_start.capture(:table_delim) >>
             line_ending >>
             table_rows.as(:rows) >>

data/lib/coradoc/asciidoc/parser/text.rb

@@ -113,9 +113,7 @@ module Coradoc
         # inline_image is defined in inline.rb for inline images (image:)
 
         def block_image
-          (element_id.maybe >>
-            block_title.maybe >>
-            (attribute_list >> newline).maybe >>
+          (block_header >>
             match('^i') >> str('mage::') >>
             file_path.as(:path) >>
             attribute_list(:attribute_list_macro) >>

data/lib/coradoc/asciidoc/parser.rb

@@ -5,6 +5,7 @@ module Coradoc
     module Parser
       autoload :Base, "#{__dir__}/parser/base"
       autoload :Cache, "#{__dir__}/parser/cache"
+      autoload :FrontmatterParser, "#{__dir__}/parser/frontmatter_parser"
     end
   end
 end

data/lib/coradoc/asciidoc/serializer/serializers/base.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'coradoc/asciidoc/serializer/serialization_context'
+require_relative '../serialization_context'
 
 module Coradoc
   module AsciiDoc

data/lib/coradoc/asciidoc/serializer/serializers/document.rb

@@ -21,6 +21,13 @@ module Coradoc
 
           def serialize_to_adoc
             parts = []
+            # Frontmatter prefix, if present. The raw YAML text is
+            # already canonical (single source of truth is Codec), so we
+            # only wrap it with `---` delimiters.
+            if @model.frontmatter && !@model.frontmatter.strip.empty?
+              parts << "---\n#{@model.frontmatter.chomp}\n---\n\n"
+            end
+
             # Only add leading newline if we have sections but no header
             parts << "\n" if @model.sections && !@model.sections.empty? && !@model.header
 

data/lib/coradoc/asciidoc/serializer/serializers/list/definition.rb

@@ -8,7 +8,9 @@ module Coradoc
           class Definition < Base
             def to_adoc(model, _options = {})
               @model = model
-              content = +"\n"
+              _attrs = @model.attrs.to_adoc(show_empty: false).to_s
+              prefix = _attrs.empty? ? '' : "#{_attrs}\n"
+              content = "\n#{prefix}"
               @model.items.each do |item|
                 # Pass delimiter to item serialization
                 serialized = serialize_child_with_options(item, delimiter: @model.delimiter)

data/lib/coradoc/asciidoc/serializer/serializers/list/definition_item.rb

@@ -8,7 +8,8 @@ module Coradoc
           class DefinitionItem < Base
             def to_adoc(model, options_or_context = {})
               context = normalize_context(options_or_context)
-              delimiter = context.option(:delimiter, '')
+              delimiter = model.delimiter.to_s
+              delimiter = context.option(:delimiter, '::') if delimiter.empty?
               _anchor = model.anchor.nil? ? '' : serialize_child(model.anchor, context)
               content = +''
 
@@ -26,6 +27,25 @@ module Coradoc
 
               d = model.contents ? serialize_children(model.contents, context) : ''
               content << "#{d}\n"
+
+              nested_delimiter = "#{delimiter}:"
+              Array(model.nested).each do |nested_list|
+                next unless nested_list.is_a?(Coradoc::AsciiDoc::Model::List::Definition)
+
+                nested_list.items.each do |nested_item|
+                  content << serialize_with_options(nested_item, delimiter: nested_delimiter)
+                end
+              end
+
+              content
+            end
+
+            private
+
+            def serialize_with_options(child, options = {})
+              serializer_class = ElementRegistry.lookup(child.class)
+              serializer = serializer_class.new
+              serializer.to_adoc(child, options)
             end
           end
         end

data/lib/coradoc/asciidoc/transform/element_transformers/block_transformer.rb

@@ -62,7 +62,16 @@ module Coradoc
               has_nested_blocks = lines.any?(Coradoc::AsciiDoc::Model::Block::Core)
 
               if has_nested_blocks
-                children = lines.map { |line| ToCoreModel.transform(line) }
+                children = lines.filter_map do |line|
+                  result = ToCoreModel.transform(line)
+                  next nil if result.nil?
+                  next result if result.is_a?(Coradoc::CoreModel::Base)
+
+                  text = ToCoreModel.extract_text_content(result)
+                  next nil if text.nil? || text.strip.empty?
+
+                  Coradoc::CoreModel::TextContent.new(text: text)
+                end
                 klass.new(
                   id: block.id,
                   title: ToCoreModel.extract_title_text(block.title),

data/lib/coradoc/asciidoc/transform/element_transformers/document_transformer.rb

@@ -9,14 +9,28 @@ module Coradoc
             def transform_document(doc)
               title_text = ToCoreModel.extract_title_text(doc.header&.title)
               attributes = ToCoreModel.extract_document_attributes(doc)
+              children = ToCoreModel.transform(doc.sections || doc.contents || [])
+              children = prepend_frontmatter(children, doc.frontmatter)
+
               Coradoc::CoreModel::DocumentElement.new(
                 id: doc.id,
                 title: title_text,
                 attributes: attributes,
-                children: ToCoreModel.transform(doc.sections || doc.contents || [])
+                children: children
               )
             end
 
+            # If the AsciiDoc document carried raw frontmatter text, parse
+            # it via Codec into a typed FrontmatterBlock and prepend it so
+            # it participates in the standard block pipeline. Codec is the
+            # single source of truth for YAML parsing (DRY/MECE).
+            def prepend_frontmatter(children, frontmatter_text)
+              return children if frontmatter_text.nil? || frontmatter_text.strip.empty?
+
+              block = Coradoc::CoreModel::FrontmatterBlock::Codec.from_yaml(frontmatter_text)
+              [block, *children]
+            end
+
             def transform_section(section, parent_id: nil)
               title_text = ToCoreModel.extract_title_text(section.title)
               section_id = section.id || Coradoc::CoreModel::IdGenerator.generate_from_title(

data/lib/coradoc/asciidoc/transform/element_transformers/list_transformer.rb

@@ -48,6 +48,12 @@ module Coradoc
                 definition_children: def_children
               )
               di.id = item.id if item.id
+
+              nested_adoc = Array(item.nested).find do |n|
+                n.is_a?(Coradoc::AsciiDoc::Model::List::Definition) && n.items.any?
+              end
+              di.nested = transform_list(nested_adoc, 'definition') if nested_adoc
+
               di
             end
 

data/lib/coradoc/asciidoc/transform/element_transformers/other_transformer.rb

@@ -25,8 +25,10 @@ module Coradoc
             end
 
             def transform_image(image)
+              src = image.src.to_s
+              src = src[1..] if src.start_with?(':')
               Coradoc::CoreModel::Image.new(
-                src: image.src,
+                src: src,
                 alt: image.title&.to_s,
                 width: image.attributes&.[]('width'),
                 height: image.attributes&.[]('height')

data/lib/coradoc/asciidoc/transform/from_core_model.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'from_core_model_registrations'
-
 module Coradoc
   module AsciiDoc
     module Transform
@@ -9,8 +7,18 @@ module Coradoc
       class FromCoreModel
         include Coradoc::Transform::Base
 
+        @registered = false
+
         class << self
+          def register!
+            return if @registered
+
+            Transform::FromCoreModelRegistrations.register_all!
+            @registered = true
+          end
+
           def transform(model)
+            register!
             return model.map { |item| transform(item) } if model.is_a?(Array)
             return model unless model.is_a?(Coradoc::CoreModel::Base)
 
@@ -32,10 +40,13 @@ module Coradoc
                          Coradoc::AsciiDoc::Model::Header.new(title: '')
                        end
 
+              sections, frontmatter = extract_frontmatter(Array(element.children))
+
               Coradoc::AsciiDoc::Model::Document.new(
                 id: element.id,
                 header: header,
-                sections: transform(element.children)
+                sections: transform(sections),
+                frontmatter: frontmatter
               )
             when CoreModel::SectionElement
               Coradoc::AsciiDoc::Model::Section.new(
@@ -77,6 +88,7 @@ module Coradoc
               Coradoc::AsciiDoc::Model::Block::SourceCode.new(
                 id: block.id,
                 title: block.title,
+                lang: block.language,
                 lines: content_text.split("\n"),
                 attributes: build_attributes(block)
               )
@@ -298,22 +310,29 @@ module Coradoc
             )
           end
 
-          def transform_definition_list(definition_list)
+          def transform_definition_list(definition_list, depth = 1)
+            delimiter = ':' * (depth + 1)
             items = Array(definition_list.items).map do |item|
-              transform_definition_item(item)
+              transform_definition_item(item, depth)
             end
-            Coradoc::AsciiDoc::Model::List::Definition.new(items: items)
+            list = Coradoc::AsciiDoc::Model::List::Definition.new(items: items)
+            list.delimiter = delimiter
+            list
           end
 
-          def transform_definition_item(item)
+          def transform_definition_item(item, depth = 1)
+            delimiter = ':' * (depth + 1)
             term = Coradoc::AsciiDoc::Model::Term.new(term: item.term.to_s)
             contents = Array(item.definitions).map do |defn|
               Coradoc::AsciiDoc::Model::TextElement.new(content: defn.to_s)
             end
-            Coradoc::AsciiDoc::Model::List::DefinitionItem.new(
+            di = Coradoc::AsciiDoc::Model::List::DefinitionItem.new(
               terms: [term],
-              contents: contents
+              contents: contents,
+              delimiter: delimiter
             )
+            di.nested << transform_definition_list(item.nested, depth + 1) if item.nested&.items&.any?
+            di
           end
 
           def transform_toc(_toc)
@@ -328,8 +347,26 @@ module Coradoc
             )
           end
 
+          def transform_comment_line(comment)
+            Coradoc::AsciiDoc::Model::CommentLine.new(
+              text: comment.text.to_s
+            )
+          end
+
           private
 
+          # If the first CoreModel child is a FrontmatterBlock, serialize
+          # it to YAML text via Codec (single source of truth) and pop it
+          # from the children list. Returns [remaining_children,
+          # frontmatter_text].
+          def extract_frontmatter(children)
+            first = children.first
+            return [children, nil] unless first.is_a?(CoreModel::FrontmatterBlock)
+
+            yaml = CoreModel::FrontmatterBlock::Codec.to_yaml(first)
+            [children.drop(1), yaml.nil? || yaml.empty? ? nil : yaml]
+          end
+
           def resolve_semantic_type(block)
             semantic = block.resolve_semantic_type
             return semantic if semantic

data/lib/coradoc/asciidoc/transform/from_core_model_registrations.rb

@@ -115,6 +115,11 @@ module Coradoc
               Coradoc::CoreModel::BibliographyEntry,
               ->(model) { FromCoreModel.transform_bibliography_entry(model) }
             )
+
+            Registry.register(
+              Coradoc::CoreModel::CommentLine,
+              ->(model) { FromCoreModel.transform_comment_line(model) }
+            )
           end
         end
       end
@@ -123,4 +128,3 @@ module Coradoc
 end
 
 # Auto-register when this file is loaded
-Coradoc::AsciiDoc::Transform::FromCoreModelRegistrations.register_all!

data/lib/coradoc/asciidoc/transform/frontmatter_attribute_map.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Transform
+      # OCP opt-in bridge mapping AsciiDoc document attributes
+      # (`:author:`, `:revdate:`, etc.) to/from FrontmatterBlock data.
+      #
+      # NOT auto-registered. Users opt in by invoking the bridge methods
+      # from their pipeline (e.g., from a custom transformer extension
+      # or rake task). This honors OCP: core conversion never silently
+      # rewrites data; opt-in extensions add behavior explicitly.
+      #
+      # MECE: lives in its own file, dispatches on `attribute_name` /
+      # `frontmatter_key` pairs. Does not touch FrontmatterBlock::Codec
+      # (YAML I/O) or SchemaResolver (validation).
+      #
+      # Mappings (bidirectional):
+      #
+      #   | Frontmatter key | AsciiDoc attribute | Notes              |
+      #   |-----------------|--------------------|--------------------|
+      #   | author          | author             |                    |
+      #   | date            | revdate            |                    |
+      #   | tags            | tags               | Array <-> space str|
+      #   | categories      | categories         | Array <-> space str|
+      module FrontmatterAttributeMap
+        # Single source of truth for the attribute <-> frontmatter
+        # mapping. Each tuple: [attribute_name(String), front_key(String),
+        # kind(:scalar | :array)]
+        MAPPINGS = [
+          ['author', 'author', :scalar],
+          ['revdate', 'date', :scalar],
+          ['tags', 'tags', :array],
+          ['categories', 'categories', :array]
+        ].freeze
+
+        class << self
+          # Build a frontmatter data hash from an AsciiDoc document
+          # attributes Hash. Skips unknown keys and empty values.
+          #
+          # @param attributes [Hash{String=>Object}] AsciiDoc document
+          #   attributes (e.g., from DocumentAttributes#to_hash)
+          # @return [Hash{String=>Object}] frontmatter data hash
+          def entries_from_attributes(attributes)
+            attributes = normalize_hash(attributes)
+            MAPPINGS.each_with_object({}) do |(attr_name, front_key, kind), h|
+              raw = attributes[attr_name]
+              next if raw.nil? || raw.to_s.strip.empty?
+
+              h[front_key] = build_value(raw, kind)
+            end
+          end
+
+          # Reverse: walk a FrontmatterBlock's data and produce a Hash
+          # of AsciiDoc document attributes. Unknown entry keys are
+          # dropped (only mapped keys are translated).
+          #
+          # @param block [Coradoc::CoreModel::FrontmatterBlock]
+          # @return [Hash{String=>String}]
+          def attributes_from_block(block)
+            result = {}
+            return result unless block&.data
+
+            MAPPINGS.each do |(_, front_key, _)|
+              value = block.data[front_key]
+              next if value.nil?
+
+              attr_name = front_key_to_attribute(front_key)
+              next unless attr_name
+
+              result[attr_name] = serialize_value(value)
+            end
+            result
+          end
+
+          private
+
+          def normalize_hash(attributes)
+            return {} unless attributes.is_a?(Hash)
+
+            attributes.each_with_object({}) do |(k, v), h|
+              h[k.to_s] = v
+            end
+          end
+
+          def build_value(raw, kind)
+            case kind
+            when :array
+              raw.to_s.split(/\s+/).reject(&:empty?)
+            else
+              raw.to_s
+            end
+          end
+
+          def serialize_value(value)
+            case value
+            when Array
+              value.map(&:to_s).join(' ')
+            else
+              value.to_s
+            end
+          end
+
+          def front_key_to_attribute(front_key)
+            mapping = MAPPINGS.find { |_, fk, _| fk == front_key.to_s }
+            mapping&.first
+          end
+        end
+      end
+    end
+  end
+end