coradoc-adoc 2.0.9 → 2.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed044cb4af9fd1e18a9cb2c34ddc5c322d801fd24962058a5b6ec55e7a3a9c43
-  data.tar.gz: 751978667c8663723085bf0a79d5908cf4a3368e827366a1d703c2602671fcb3
+  metadata.gz: 791dca3b794e199e6d856458c3399946545f54a26a98cc4e8aee07de8b7aa21f
+  data.tar.gz: 6fd4f6457098075c4ad3f98238ab56c4eb5359271f2024e3b75b0caee3791372
 SHA512:
-  metadata.gz: caf485068682d2b714078ff0ec934601a35498fb546d5a97677cbae3b08aa237b598768ca7bafb3f1075868ae5524a01ab20a9fede25d2e4a374d8e67390baca
-  data.tar.gz: cf951b3c317c1a40ac4b2d170dba913b4a83d375aa60a8a7a8a16e47865d3ebe7609b61630436d90726fe682e3d78412beadac3ced3589bf642b865ad7250628
+  metadata.gz: d8c7eb7672609651c3152ce468727f638cd5e9b5bd73b25b1334697710b8083391db13e9d6d030f97a288a7fe28e33567a2dd934b6a455c0e5279fe4fe183455
+  data.tar.gz: 003e62344acf12212216306ad211330464866862dc5876d2caf7a4812c3c120a041b1da11d7ae83668b15e4a0c96a80e08984b9b7a3686de451fa548c444b0e0

data/lib/coradoc/asciidoc/model/bibliography_entry.rb

@@ -32,6 +32,24 @@ module Coradoc
         attribute :document_id, :string
         attribute :ref_text, :string
         attribute :line_break, :string, default: -> { '' }
+
+        # Coerce a raw parser AST value into the canonical ref_text string.
+        # Accepts the shapes produced by Parser::Bibliography for `:ref_text`:
+        # nil, Parslet::Slice, plain String, single Model::Base, or an Array
+        # of any of these. Keeping this coercion on the model that owns
+        # ref_text (rather than in a transformer rule) keeps the transformer
+        # declarative and lets callers build entries from any source shape.
+        # @param raw [Object, nil]
+        # @return [String]
+        def self.coerce_ref_text(raw)
+          return '' if raw.nil?
+
+          case raw
+          when Array then raw.map { |e| coerce_ref_text(e) }.join
+          when String then raw
+          else raw.to_s
+          end
+        end
       end
     end
   end

data/lib/coradoc/asciidoc/model/document.rb

@@ -69,6 +69,15 @@ module Coradoc
                     Coradoc::AsciiDoc::Model::Video
                   ]
 
+        # Raw YAML frontmatter text, or nil if absent.
+        #
+        # AsciiDoc treats frontmatter as opaque text — the YAML is only
+        # parsed/emitted at the CoreModel boundary by
+        # CoreModel::FrontmatterBlock::Codec (single source of truth).
+        # Storing raw text keeps the AsciiDoc parser/serializer symmetric
+        # without dragging YAML semantics into the AsciiDoc model (MECE).
+        attribute :frontmatter, :string
+
         # @param [Integer] index The index of the section to retrieve
         # @return [Coradoc::AsciiDoc::Model::Base] The section at the specified index
         def [](index)

data/lib/coradoc/asciidoc/model/glossaries.rb

@@ -4,7 +4,7 @@ module Coradoc
   module AsciiDoc
     module Model
       class Glossaries < Base
-        attribute :items, :string, collection: true
+        attribute :items, :string, collection: true, initialize_empty: true
       end
     end
   end

data/lib/coradoc/asciidoc/model/list/base.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      module List
+        # Shared base class for all list container types.
+        #
+        # Every list flavor (Core, Definition, and any future ones) inherits
+        # the universal list-level attributes from this class:
+        #
+        #   - +id+    optional anchor identifier (inherited from Model::Base)
+        #   - +attrs+ block attribute list, e.g. +[%hardbreaks]+ or +[#my-id]+
+        #
+        # Subclasses declare their own +items+ with the appropriate item type
+        # (List::Item for ordered/unordered, List::DefinitionItem for definition)
+        # plus any flavor-specific attributes (marker, prefix, delimiter, ...).
+        #
+        # @!attribute [r] attrs
+        #   @return [Coradoc::AsciiDoc::Model::AttributeList] Additional list
+        #     attributes parsed from the +[...]+ block header preceding the list
+        class Base < Coradoc::AsciiDoc::Model::Base
+          include Coradoc::AsciiDoc::Model::Anchorable
+
+          attribute :attrs,
+                    Coradoc::AsciiDoc::Model::AttributeList,
+                    default: -> { Coradoc::AsciiDoc::Model::AttributeList.new }
+
+          asciidoc do
+            map_attribute 'id', to: :id
+            map_attribute 'attrs', to: :attrs
+          end
+
+          def block_level?
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/asciidoc/model/list/core.rb

@@ -4,21 +4,17 @@ module Coradoc
   module AsciiDoc
     module Model
       module List
-        # Base class for list elements in AsciiDoc documents.
+        # Base class for ordered/unordered lists.
         #
-        # Lists are container elements that hold list items and provide
-        # functionality for different list types (ordered, unordered, definition).
+        # Inherits universal list attributes (id, attrs) from List::Base and
+        # adds the marker-related attributes specific to bulleted/numbered lists.
         #
-        # @!attribute [r] id
-        #   @return [String, nil] Optional identifier for the list
         # @!attribute [r] prefix
-        #   @return [String, nil] List marker prefix (e.g., "*", "*", "**", etc.)
+        #   @return [String, nil] List marker prefix (e.g., "*", "**", etc.)
         # @!attribute [r] items
         #   @return [Array<ListItem>] List items in this list
         # @!attribute [r] ol_count
         # @return [Integer] Ordered list nesting level
-        # @!attribute [r] attrs
-        #   @return [AttributeList] Additional list attributes
         # @!attribute [r] marker
         #   @return [String, nil] The marker character used for this list
         #
@@ -27,31 +23,15 @@ module Coradoc
         #   list.items << Coradoc::AsciiDoc::Model::List::Item.new("Item 1")
         #
         class Core < Nestable
-          include Coradoc::AsciiDoc::Model::Anchorable
-
-          def block_level?
-            true
-          end
-
-          attribute :id, :string
           attribute :prefix, :string
-          # attribute :anchor, Inline::Anchor, default: -> {
-          #   id.nil? ? nil : Inline::Anchor.new(id)
-          # }
           attribute :items, Coradoc::AsciiDoc::Model::List::Item, collection: true, initialize_empty: true
           attribute :ol_count, :integer, default: -> { 1 }
-          attribute :attrs, Coradoc::AsciiDoc::Model::AttributeList, default: lambda {
-            Coradoc::AsciiDoc::Model::AttributeList.new
-          }
           attribute :marker, :string
 
           asciidoc do
-            map_attribute 'id', to: :id
-            map_attribute 'anchor', to: :anchor
             map_attribute 'prefix', to: :prefix
             map_attribute 'items', to: :items
             map_attribute 'ol_count', to: :ol_count
-            map_attribute 'attrs', to: :attrs
             map_attribute 'marker', to: :marker
           end
         end

data/lib/coradoc/asciidoc/model/list/definition.rb

@@ -4,6 +4,13 @@ module Coradoc
   module AsciiDoc
     module Model
       module List
+        # Definition list container. Inherits universal list attributes
+        # (id, attrs) from List::Base.
+        #
+        # @!attribute [r] items
+        #   @return [Array<DefinitionItem>] Definition items in this list
+        # @!attribute [r] delimiter
+        #   @return [String] Delimiter indicating nesting depth ('::', ':::', ...)
         class Definition < Base
           attribute :items,
                     Coradoc::AsciiDoc::Model::Base,

data/lib/coradoc/asciidoc/model/list/definition_item.rb

@@ -26,7 +26,7 @@ module Coradoc
         #   item.terms << Coradoc::AsciiDoc::Model::Term.new(term: "API")
         #   item.contents << Coradoc::AsciiDoc::Model::TextElement.new("Application Programming Interface")
         #
-        class DefinitionItem < Base
+        class DefinitionItem < Coradoc::AsciiDoc::Model::Base
           include Coradoc::AsciiDoc::Model::Anchorable
 
           attribute :id, :string

data/lib/coradoc/asciidoc/model/list/item.rb

@@ -40,7 +40,7 @@ module Coradoc
         #   item.nested = Coradoc::AsciiDoc::Model::List::Unordered.new
         #   item.nested.items << Coradoc::AsciiDoc::Model::List::Item.new
         #
-        class Item < Base
+        class Item < Coradoc::AsciiDoc::Model::Base
           include Coradoc::AsciiDoc::Model::Anchorable
 
           attribute :id, :string

data/lib/coradoc/asciidoc/model/list/nestable.rb

@@ -4,9 +4,13 @@ module Coradoc
   module AsciiDoc
     module Model
       module List
-        # Mixin module for nestable list functionality.
-        # Provides common functionality for lists that can contain nested lists.
-        class Nestable < Coradoc::AsciiDoc::Model::Base
+        # Marker class for lists that can be nested inside a List::Item
+        # via its +nested+ attribute. Inherits universal list attributes
+        # (id, attrs) from List::Base.
+        #
+        # List::Definition does not extend Nestable because it has its own
+        # nesting model via List::DefinitionItem#nested.
+        class Nestable < Base
         end
       end
     end

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

@@ -6,16 +6,18 @@ module Coradoc
       # Namespace for all AsciiDoc list types and their items.
       #
       # List Architecture:
-      #   - List::Core - Common list functionality (base class)
+      #   - List::Base - Universal list attributes (id, attrs)
+      #   - List::Nestable - Marker class for lists nestable inside Item
+      #   - List::Core - Ordered/unordered list base (marker, prefix, ol_count)
       #   - List::Ordered - Numbered lists (1., 2., 3., etc.)
       #   - List::Unordered - Bulleted lists (*, **, etc.)
       #   - List::Definition - Labeled/definition lists (term:: definition)
       #   - List::Item - Item for ordered/unordered lists
       #   - List::DefinitionItem - Item for definition lists
-      #   - List::Nestable - Mixin for nesting support
       #
       module List
         # Autoload list types lazily
+        autoload :Base, 'coradoc/asciidoc/model/list/base'
         autoload :Core, 'coradoc/asciidoc/model/list/core'
         autoload :Nestable, 'coradoc/asciidoc/model/list/nestable'
         autoload :Ordered, 'coradoc/asciidoc/model/list/ordered'

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

@@ -11,6 +11,7 @@ module Coradoc
       autoload :AttributeList, 'coradoc/asciidoc/parser/attribute_list'
       autoload :Bibliography, 'coradoc/asciidoc/parser/bibliography'
       autoload :Block, 'coradoc/asciidoc/parser/block'
+      autoload :BlockHeader, 'coradoc/asciidoc/parser/block_header'
       autoload :Citation, 'coradoc/asciidoc/parser/citation'
       autoload :Content, 'coradoc/asciidoc/parser/content'
       autoload :DocumentAttributes, 'coradoc/asciidoc/parser/document_attributes'
@@ -18,6 +19,7 @@ module Coradoc
       autoload :Inline, 'coradoc/asciidoc/parser/inline'
       autoload :List, 'coradoc/asciidoc/parser/list'
       autoload :Paragraph, 'coradoc/asciidoc/parser/paragraph'
+      autoload :RuleDispatcher, 'coradoc/asciidoc/parser/rule_dispatcher'
       autoload :Section, 'coradoc/asciidoc/parser/section'
       autoload :Table, 'coradoc/asciidoc/parser/table'
       autoload :Term, 'coradoc/asciidoc/parser/term'
@@ -29,6 +31,7 @@ module Coradoc
         include AttributeList
         include Bibliography
         include Block
+        include BlockHeader
         include Citation
         include Content
         include DocumentAttributes
@@ -82,78 +85,15 @@ module Coradoc
           warn e.parse_failure_cause.ascii_tree
         end
 
-        def rule_dispatch(rule_name, *args, **kwargs)
-          @dispatch_data ||= {}
-          dispatch_key = [rule_name, args, kwargs.to_a.sort]
-          dispatch_hash = dispatch_key.hash.abs
-          unless @dispatch_data.key?(dispatch_hash)
-            alias_name = :"#{rule_name}_#{dispatch_hash}"
-            Coradoc::AsciiDoc::Parser::Base.class_exec do
-              rule(alias_name) do
-                public_send(rule_name, *args, **kwargs)
-              end
-            end
-            @dispatch_data[dispatch_hash] = alias_name
-          end
-          dispatch_method = @dispatch_data[dispatch_hash]
-          public_send(dispatch_method)
-        end
-
-        def self.config(key)
-          # NOTE: These are internal dispatch configuration options for the parser:
-          # - add_dispatch: Enables automatic method dispatching
-          # - with_params: Supports parameterized rule invocation
-          c = {
-            add_dispatch: true,
-            with_params: true
-          }
-
-          raise ArgumentError, "Unknown config key: #{key}. Available keys: #{c.keys.join(', ')}" unless c.key?(key)
-
-          c[key]
-        end
-
-        # Collect parser methods from all parser modules (excluding Base, Cache, and FixFiles)
-        # Base is the parser class, Cache is a utility class, FixFiles is a utility module
-        parser_constants = Coradoc::AsciiDoc::Parser.constants - %i[Base Cache FixFiles]
-        parser_methods = parser_constants.each_with_object({}) do |const, acc|
-          rule_names = Coradoc::AsciiDoc::Parser.const_get(const).instance_methods
-          rule_names.each do |rule_name|
-            acc[rule_name] ||= []
-            acc[rule_name] << const
-          end
-        end
-
-        # Warn about duplicated parser methods:
-        parser_methods.each do |rule_name, defn_sites|
-          count = defn_sites.length
-          if count > 1
-            defn_site_constants = defn_sites.map { |const| Coradoc::AsciiDoc::Parser.const_get(const) }
-            Coradoc::Logger.warn "Parser method '#{rule_name}' is defined #{count} times in #{defn_site_constants.join(', ')}"
-          end
-        end
-
-        parser_methods.each_key do |rule_name|
-          params = Coradoc::AsciiDoc::Parser::Base.instance_method(rule_name).parameters
-          if config(:add_dispatch) && params == []
-            alias_name = :"alias_nondispatch_#{rule_name}"
-            Coradoc::AsciiDoc::Parser::Base.class_exec do
-              alias_method alias_name, rule_name
-              rule(rule_name) do
-                public_send(alias_name)
-              end
-            end
-          elsif config(:add_dispatch) && config(:with_params)
-            alias_name = :"alias_dispatch_#{rule_name}"
-            Coradoc::AsciiDoc::Parser::Base.class_exec do
-              alias_method alias_name, rule_name
-              define_method(rule_name) do |*args, **kwargs|
-                rule_dispatch(alias_name, *args, **kwargs)
-              end
-            end
-          end
+        def rule_dispatch(rule_name, *, **)
+          RuleDispatcher.dispatch(self, rule_name, *, **)
         end
       end
+
+      # Wrap every parser rule for Parslet memoization. Must run after all
+      # parser modules are included in Base so that instance_method(rule_name)
+      # finds the methods defined by every module.
+      RuleDispatcher.apply(Base)
     end
   end
 end

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

@@ -30,14 +30,6 @@ module Coradoc
           open_block(n_deep)).as(:block)
         end
 
-        def reviewer_note_block(_n_deep = 3)
-          # Match blocks with reviewer attribute
-          # This should only match when attribute_list contains reviewer=
-          # For now, we'll make it not match anything specific
-          # The block() method will handle these cases
-          str('').absent? # Never matches - placeholder for future implementation
-        end
-
         def example_block(n_deep)
           block_style(n_deep, '=', 4)
         end
@@ -83,6 +75,7 @@ module Coradoc
         end
 
         # Block delimiter: 4+ identical characters (or 2 for open block)
+        # Used by paragraph.rb to reject lines that look like block delimiters.
         # NOTE: repeat(4,) means 4 or more (not exactly 4)
         def block_delimiter
           line_start? >>
@@ -95,16 +88,6 @@ module Coradoc
             newline
         end
 
-        def element_attributes
-          block_title.maybe >>
-            element_id.maybe >>
-            (attribute_list >> newline).maybe >>
-            block_title.maybe >>
-            newline.maybe >>
-            (attribute_list >> newline).maybe >>
-            element_id.maybe
-        end
-
         # Block style parser with variable delimiter length
         # @param n_deep [Integer] Nesting depth for nested blocks
         # @param delimiter [String] The delimiter character ("=", "-", "_", "*", "+")
@@ -121,17 +104,27 @@ module Coradoc
             delim_str = c.captures[capture_key].to_s.strip
             closing_pattern = str(delim_str) >> newline
 
-            content = block_image
-            content |= block(n_deep - 1) if n_deep.positive?
-            content |= list
-            content |= text_line(false, unguarded: true, verbatim: verbatim)
-            content |= empty_line.as(:line_break)
+            # Verbatim blocks (source/listing) treat their body as literal
+            # text per the AsciiDoc spec — no substitutions, no nested
+            # blocks. Allowing nested block parsing here would consume
+            # shorter inner delimiters (e.g. `----` inside `------`) and
+            # strip the original structure when serializing back.
+            content = if verbatim
+                        text_line(false, unguarded: true, verbatim: true) |
+                          empty_line.as(:line_break)
+                      else
+                        c = block_image
+                        c |= block(n_deep - 1) if n_deep.positive?
+                        c |= list
+                        c |= text_line(false, unguarded: true)
+                        c |= empty_line.as(:line_break)
+                        c
+                      end
 
             (closing_pattern.absent? >> content).repeat(1)
           end
 
-          element_attributes >>
-            (line_start? >> attribute_list >> newline).maybe >>
+          block_header >>
             line_start? >>
             current_delimiter.as(:delimiter) >> newline >>
             if type == :pass
@@ -165,8 +158,7 @@ module Coradoc
             (closing_pattern.absent? >> content).repeat(1)
           end
 
-          element_attributes >>
-            (line_start? >> attribute_list >> newline).maybe >>
+          block_header >>
             line_start? >>
             current_delimiter.as(:delimiter) >> newline >>
             if type == :pass

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

@@ -6,112 +6,31 @@ module Coradoc
       # Single Responsibility: Assemble block AST from metadata hints
       # Takes metadata analysis and input text, returns proper AST structure
       class BlockAssembler
-        # Main entry point: assemble block AST from input and metadata
+        # Main entry point: assemble block AST from input and metadata.
+        #
+        # The result hash always includes :delimiter and :lines. :title and
+        # :attribute_list are included only when present in the metadata.
+        # The previous 4-arm `case pattern` switch collapsed into this single
+        # method once it became clear the only difference between arms was
+        # which optional keys appeared in the result hash.
+        #
         # @param input [String] The input text to parse
-        # @param metadata_analysis [Hash] Analysis from MetadataDetector
-        # @return [Hash] AST hash {:block => {...}}
-        def self.assemble(input, metadata_analysis)
-          return nil unless metadata_analysis
-
-          pattern = metadata_analysis[:pattern]
-
-          # Delegate to pattern-specific methods (Open/Closed Principle)
-          case pattern
-          when :title_attr_delim
-            assemble_title_attr_delim(input, metadata_analysis)
-          when :title_delim
-            assemble_title_delim(input, metadata_analysis)
-          when :attr_delim
-            assemble_attr_delim(input, metadata_analysis)
-          when :plain_delim
-            assemble_plain_delim(input, metadata_analysis)
-          end
-        end
-
-        # Handle: Title + Attribute + Delimiter pattern
-        # @param input [String] The input text
-        # @param metadata [Hash] Metadata analysis
-        # @return [Hash] Complete block hash
-        def self.assemble_title_attr_delim(input, metadata)
-          lines = input.lines
-          delimiter_line = metadata[:delimiter_line]
-          delimiter = metadata[:delimiter][:delimiter]
-
-          # Extract components
-          title_text = metadata[:title][:text]
-          attr_list = parse_attribute_list(metadata[:attributes])
-
-          # Extract block content
-          block_lines = extract_block_lines(lines, delimiter_line, delimiter)
-
-          {
-            title: title_text,
-            attribute_list: attr_list,
-            delimiter: delimiter,
-            lines: block_lines
-          }
-        end
+        # @param metadata [Hash] Analysis from MetadataDetector
+        # @return [Hash, nil] AST hash, or nil if metadata is nil
+        def self.assemble(input, metadata)
+          return nil unless metadata
 
-        # Handle: Title + Delimiter pattern (no attributes)
-        # @param input [String] The input text
-        # @param metadata [Hash] Metadata analysis
-        # @return [Hash] Block hash without attributes
-        def self.assemble_title_delim(input, metadata)
           lines = input.lines
           delimiter_line = metadata[:delimiter_line]
           delimiter = metadata[:delimiter][:delimiter]
 
-          # Extract components
-          title_text = metadata[:title][:text]
-
-          # Extract block content
-          block_lines = extract_block_lines(lines, delimiter_line, delimiter)
-
-          {
-            title: title_text,
+          result = {
             delimiter: delimiter,
-            lines: block_lines
-          }
-        end
-
-        # Handle: Attribute + Delimiter pattern (no title)
-        # @param input [String] The input text
-        # @param metadata [Hash] Metadata analysis
-        # @return [Hash] Block hash without title
-        def self.assemble_attr_delim(input, metadata)
-          lines = input.lines
-          delimiter_line = metadata[:delimiter_line]
-          delimiter = metadata[:delimiter][:delimiter]
-
-          # Extract components
-          attr_list = parse_attribute_list(metadata[:attributes])
-
-          # Extract block content
-          block_lines = extract_block_lines(lines, delimiter_line, delimiter)
-
-          {
-            attribute_list: attr_list,
-            delimiter: delimiter,
-            lines: block_lines
-          }
-        end
-
-        # Handle: Just Delimiter pattern
-        # @param input [String] The input text
-        # @param metadata [Hash] Metadata analysis
-        # @return [Hash] Minimal block hash
-        def self.assemble_plain_delim(input, metadata)
-          lines = input.lines
-          delimiter_line = metadata[:delimiter_line]
-          delimiter = metadata[:delimiter][:delimiter]
-
-          # Extract block content
-          block_lines = extract_block_lines(lines, delimiter_line, delimiter)
-
-          {
-            delimiter: delimiter,
-            lines: block_lines
+            lines: extract_block_lines(lines, delimiter_line, delimiter)
           }
+          result[:title] = metadata[:title][:text] if metadata[:title]
+          result[:attribute_list] = parse_attribute_list(metadata[:attributes]) if metadata[:attributes]
+          result
         end
 
         # Helper: Extract content between delimiters
@@ -132,8 +51,16 @@ module Coradoc
             # Check if this is the closing delimiter
             break if line.strip == delimiter
 
-            # Handle empty lines vs content lines
-            if line.strip.empty?
+            stripped = line.strip
+            if nested_delimiter?(stripped) && stripped != delimiter
+              nested_delimiter = stripped
+              nested_lines = extract_block_lines(lines, i, nested_delimiter)
+
+              block_lines << { block: { delimiter: nested_delimiter, lines: nested_lines } }
+
+              i += nested_lines.length + 1
+            elsif line.strip.empty?
+              # Handle empty lines vs content lines
               block_lines << { line_break: "\n" }
             else
               # Remove trailing newline for processing
@@ -147,6 +74,16 @@ module Coradoc
           block_lines
         end
 
+        def self.nested_delimiter?(str)
+          return false if str.length < 2
+
+          char = str[0]
+          return false unless ['-', '*', '=', '_', '+'].include?(char)
+          return false unless str.chars.all? { |c| c == char }
+
+          (char == '-' && str.length == 2) || str.length >= 4
+        end
+
         # Parse attribute list to match expected AST structure
         # @param attr_meta [Hash] Attribute metadata from detector
         # @return [Hash] Properly formatted attribute_list hash

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Parser
+      # Single Responsibility: parse the optional header that precedes a block.
+      #
+      # Encapsulates the canonical AsciiDoc block-header grammar in one place
+      # (DRY, MECE, single source of truth). Before this module existed, every
+      # block-like rule (block, table, section, paragraph, block_image) inlined
+      # its own header rule with subtly different slot orderings — and several
+      # of them captured the same Parslet key more than once in a single
+      # sequence, which triggered Parslet's "Duplicate subtrees while merging
+      # result" warning and silently discarded one of the captured values.
+      #
+      # Canonical header shape, each component at most once:
+      #
+      #   block_title? >> element_id? >> attribute_blocks?
+      #
+      # `attribute_blocks` accepts one or more consecutive `[...]` attribute
+      # lists, captured as a Parslet sequence under the :attribute_list key.
+      # Real-world AsciiDoc often stacks attribute lists before a block:
+      #
+      #   [role=quote]
+      #   [source, ruby]
+      #   ----
+      #   code
+      #   ----
+      #
+      # Capturing the sequence (rather than one slot per `[...]`) preserves
+      # every attribute and lets the transformer merge them into a single
+      # Coradoc::AsciiDoc::Model::AttributeList downstream.
+      module BlockHeader
+        # Canonical block header rule. Single canonical order; each of title,
+        # id, and attribute_blocks is optional and matched at most once.
+        # @return [Parslet::Atoms::Base]
+        def block_header
+          block_title.maybe >>
+            element_id.maybe >>
+            attribute_blocks.maybe
+        end
+
+        # One or more consecutive attribute_list + newline sequences, captured
+        # as a Parslet sequence under :attribute_list. When multiple `[...]`
+        # blocks precede a delimiter, all of them reach the transformer; when
+        # only one appears, the sequence has a single element and the existing
+        # transformer rule handles it the same way as before.
+        # @return [Parslet::Atoms::Base]
+        def attribute_blocks
+          (attribute_list >> newline).repeat(1).as(:attribute_list)
+        end
+      end
+    end
+  end
+end