coradoc 1.1.6 → 2.0.1

data/Rakefile

@@ -1,17 +1,57 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
 
-if File.exist?(".codeclimate")
-  ENV["CODECLIMATE_REPO_TOKEN"] = File.read(".codeclimate").strip
-end
+ENV['CODECLIMATE_REPO_TOKEN'] = File.read('.codeclimate').strip if File.exist?('.codeclimate')
+
+require 'rspec/core/rake_task'
 
-require "rspec/core/rake_task"
+# Monorepo gems
+GEMS = %w[coradoc coradoc-adoc coradoc-html coradoc-markdown coradoc-docx].freeze
 
+# Main gem spec task
 RSpec::Core::RakeTask.new(:spec)
-task default: :spec
 
-desc "Open an irb session preloaded with this library"
+# Individual gem spec tasks
+namespace :spec do
+  GEMS.each do |gem_name|
+    next if gem_name == 'coradoc'
+
+    gem_dir = File.dirname(__FILE__) + "/#{gem_name}"
+
+    next unless File.directory?("#{gem_dir}/spec")
+
+    desc "Run specs for #{gem_name}"
+    RSpec::Core::RakeTask.new(gem_name.tr('-', '_').to_sym) do |t|
+      t.pattern = "#{gem_dir}/spec/**/*_spec.rb"
+      t.rspec_opts = '--format progress'
+    end
+  end
+end
+
+# Task to run all gem specs
+desc 'Run specs for all gems in the monorepo'
+task :spec_all do
+  success = true
+
+  GEMS.each do |gem_name|
+    gem_dir = File.dirname(__FILE__) + "/#{gem_name}"
+    next unless File.directory?("#{gem_dir}/spec")
+
+    puts "\n=== Running specs for #{gem_name} ==="
+    result = system("bundle exec rspec #{gem_dir}/spec --format progress")
+    success = false unless result
+  end
+
+  raise 'Some specs failed' unless success
+end
+
+task default: :spec_all
+
+desc 'Open an irb session preloaded with this library'
 task :console do
-  sh "irb -Ilib -rcoradoc -rcoradoc/reverse_adoc"
+  sh 'irb -Ilib -rcoradoc'
 end
+
+require 'bundler/audit/task'
+Bundler::Audit::Task.new

data/TODO.audit-2/07-remove-dead-to-core-model.md

@@ -0,0 +1,18 @@
+# TODO 07: Remove dead code from ToCoreModel
+
+Status: DONE
+
+## Problem
+`ToCoreModel#transform_with_case` (83 lines) and `determine_block_type` (20 lines) are dead code.
+All AsciiDoc model types are registered via `ToCoreModelRegistrations`, so the case-statement
+fallback is never reached. `determine_block_type` is never called anywhere.
+
+## Files
+- `coradoc-adoc/lib/coradoc/asciidoc/transform/to_core_model.rb` — remove lines 42-147
+- `coradoc-adoc/spec/coradoc/asciidoc/transform/to_core_model_spec.rb` — add spec for error on unregistered type
+
+## Changes
+1. Remove `transform_with_case` method entirely
+2. Remove `determine_block_type` method entirely
+3. In `transform`, raise `TransformationError` instead of falling back to case statement
+4. Add spec verifying `TransformationError` is raised for unregistered types

data/TODO.audit-2/08-remove-dead-from-core-model.md

@@ -0,0 +1,16 @@
+# TODO 08: Remove dead code from FromCoreModel
+
+Status: DONE
+
+## Problem
+`FromCoreModel#transform_with_case` (44 lines) is dead code. All CoreModel types are registered
+via `FromCoreModelRegistrations`, so the case-statement fallback is never reached.
+
+## Files
+- `coradoc-adoc/lib/coradoc/asciidoc/transform/from_core_model.rb` — remove lines 42-86
+- `coradoc-adoc/spec/coradoc/asciidoc/transform/from_core_model_spec.rb` — add spec for error
+
+## Changes
+1. Remove `transform_with_case` method entirely
+2. In `transform`, raise `TransformationError` instead of falling back
+3. Add spec verifying `TransformationError` is raised for unregistered types

data/TODO.audit-2/09-transform-inline-content-dry.md

@@ -0,0 +1,20 @@
+# TODO 09: Eliminate DRY violation in transform_inline_content
+
+Status: DONE
+
+## Problem
+Inline types are known in FOUR places: registrations, transform_with_case (dead),
+transform_inline_content (70 lines of duplication), and extract_text_content (77 lines).
+Adding a new inline type requires updating all four. Worse, transform_inline_content
+has subtle bugs vs registered transformers:
+- Link: missing `|| content.path` fallback for content
+- Stem: missing `stem_type` attribute
+
+## Files
+- `coradoc-adoc/lib/coradoc/asciidoc/transform/to_core_model.rb` — refactor transform_inline_content
+
+## Changes
+1. Refactor `transform_inline_content` to delegate to `transform()` via Registry for all
+   AsciiDoc model types, keeping only structural cases (String, Array, TextElement)
+2. Fix Link content fallback and Stem stem_type in registered transformers
+3. Register Inline::AttributeReference if used in inline content

data/TODO.audit-2/10-document-builder-list-state.md

@@ -0,0 +1,17 @@
+# TODO 10: DocumentBuilder fragile list state
+
+Status: DONE
+
+## Problem
+`@list_items` and `@list_type` are instance variables that live between list construction
+and cleanup. If an exception occurs, state leaks. `item` silently returns self if called
+outside a list block.
+
+## Files
+- `lib/coradoc/document_builder.rb` — refactor list/item methods
+- `spec/coradoc/document_builder_spec.rb` — add edge case specs
+
+## Changes
+1. Replace `@list_items`/`@list_type` with local variable captured by closure
+2. Raise ArgumentError if `item` called outside list context
+3. Add specs for error case and nested lists

data/TODO.audit-2/11-hooks-strict-mode.md

@@ -0,0 +1,16 @@
+# TODO 11: Hooks strict mode for failures
+
+Status: DONE
+
+## Problem
+`invoke_hook` rescues StandardError and only logs a warning. Hook typos silently produce
+wrong output. No way to detect broken hooks in tests.
+
+## Files
+- `lib/coradoc/hooks.rb` — add strict mode configuration
+- `spec/hooks_spec.rb` — add spec for strict mode
+
+## Changes
+1. Add `Hooks.strict_mode = true/false` class-level setting (default: false)
+2. In `invoke_hook`, re-raise when strict mode is enabled
+3. Add spec for strict mode behavior

data/TODO.audit-2/12-missing-spec-coverage.md

@@ -0,0 +1,22 @@
+# TODO 12: Add missing spec coverage
+
+Status: DONE
+
+## Problem
+Critical paths lack direct unit test coverage:
+- `transform_inline_content` — only tested indirectly via paragraph transform
+- `extract_text_content` — no direct specs
+- ToCoreModel/FromCoreModel error on unregistered types — no specs
+- DocumentBuilder edge cases — missing to_asciidoc, error on item outside list
+- FromCoreModel#transform_inline format_type exhaustiveness — not tested
+
+## Files
+- `coradoc-adoc/spec/coradoc/asciidoc/transform/to_core_model_spec.rb`
+- `coradoc-adoc/spec/coradoc/asciidoc/transform/from_core_model_spec.rb`
+- `spec/coradoc/document_builder_spec.rb`
+
+## Changes
+1. Add direct unit specs for `transform_inline_content` with each inline type
+2. Add direct unit specs for `extract_text_content` with each content type
+3. Add specs for TransformationError on unregistered types
+4. Add DocumentBuilder edge case specs

data/coradoc-adoc/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format documentation
+--color

data/coradoc-adoc/coradoc-adoc.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'lib/coradoc/asciidoc/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'coradoc-adoc'
+  spec.version = Coradoc::AsciiDoc::VERSION
+  spec.authors = ['Ribose Inc.']
+  spec.email = ['open.source@ribose.com']
+
+  spec.summary = 'AsciiDoc support for Coradoc'
+  spec.description = 'AsciiDoc Document Model, Parser, and Serializer for the ' \
+                     'Coradoc document transformation framework. Provides ' \
+                     'bidirectional transformation between AsciiDoc and CoreModel.'
+  spec.homepage = 'https://github.com/lutaml/coradoc'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f == __FILE__ || f.match(%r{\A(?:test|spec|features)/})
+    end
+  end
+
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'coradoc'
+  spec.add_dependency 'lutaml-model', '~> 0.7'
+  spec.add_dependency 'parslet'
+
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
+end

data/coradoc-adoc/lib/coradoc/asciidoc/model/admonition.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      # Admonition block for AsciiDoc documents.
+      #
+      # Admonitions are special callout boxes that highlight important
+      # information: NOTE, TIP, WARNING, CAUTION, IMPORTANT.
+      #
+      # @!attribute [r] content
+      #   @return [String] The admonition text content
+      #
+      # @!attribute [r] type
+      #   @return [String] The admonition type (e.g., "NOTE", "TIP", "WARNING")
+      #
+      # @!attribute [r] line_break
+      #   @return [String] Line break character (default: "")
+      #
+      # @example Create a note admonition
+      #   admonition = Coradoc::AsciiDoc::Model::Admonition.new
+      #   admonition.type = "NOTE"
+      #   admonition.content = "This is important information"
+      #
+      # @example Create a warning admonition
+      #   admonition = Coradoc::AsciiDoc::Model::Admonition.new
+      #   admonition.type = "WARNING"
+      #   admonition.content = "Be careful!"
+      #
+      class Admonition < Attached
+        attribute :content, :string
+        attribute :type, :string
+        attribute :line_break, :string, default: -> { '' }
+      end
+    end
+  end
+end

data/coradoc-adoc/lib/coradoc/asciidoc/model/anchorable.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      # Mixin for elements that can have anchors (IDs and references).
+      #
+      # The Anchorable module provides functionality for elements that can
+      # be referenced from other parts of the document. It automatically
+      # creates an Inline::Anchor based on the element's id attribute.
+      #
+      # @example Including Anchorable in a class
+      #   class MyElement < Coradoc::AsciiDoc::Model::Base
+      #     include Coradoc::AsciiDoc::Model::Anchorable
+      #     attribute :id, :string
+      #   end
+      #
+      # @example Using the generated anchor
+      #   element = MyElement.new(id: "section1")
+      #   element.anchor.to_adoc # => "[[section1]]"
+      #
+      module Anchorable
+        # Hook called when module is included in a class
+        #
+        # Automatically adds the :anchor attribute to the including class.
+        #
+        # @param base [Class] The class including this module
+        def self.included(base)
+          base.class_eval do
+            attribute :anchor, :string
+          end
+        end
+
+        # Override initialize to set default anchor
+        def initialize(*args)
+          super
+          @anchor ||= default_anchor
+        end
+
+        # Generate the default anchor based on the element's id
+        #
+        # @return [String, nil] The anchor string, or nil if no id
+        def default_anchor
+          id.nil? ? nil : "[[#{id}]]"
+        end
+
+        # Generate the anchor string for serialization
+        #
+        # @param inline [Boolean] If true, don't add trailing newline
+        # @return [String] The serialized anchor string
+        def gen_anchor(inline: false)
+          return '' if anchor.nil?
+
+          anchor_str = anchor.to_adoc
+          if anchor_str.empty?
+            ''
+          else
+            "#{anchor_str}#{inline ? '' : "\n"}"
+          end
+        end
+      end
+    end
+  end
+end

data/coradoc-adoc/lib/coradoc/asciidoc/model/attached.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      # Base class for attached elements in AsciiDoc documents.
+      #
+      # Attached elements are those that can be attached to other elements
+      # such as list items or blocks. They include admonitions, paragraphs,
+      # and other block types.
+      #
+      # This class provides the foundation for elements that can be
+      # "attached" to parent elements in the document structure.
+      #
+      # @see Coradoc::AsciiDoc::Model::Admonition
+      # @see Coradoc::AsciiDoc::Model::Paragraph
+      # @see Coradoc::AsciiDoc::Model::Block::Core
+      #
+      class Attached < Base
+      end
+    end
+  end
+end

data/coradoc-adoc/lib/coradoc/asciidoc/model/attribute.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      class Attribute < Base
+        attribute :key, :string
+        attribute :value, :string, collection: true
+        attribute :line_break, :string, default: -> { "\n" }
+
+        private
+
+        # Build values from comma-separated string
+        # NOTE: This method allows for multiple values in format-specific attributes.
+        def build_values(value)
+          values = value.split(',').map(&:strip)
+          values.length > 1 ? values : values.first
+        end
+      end
+    end
+  end
+end

data/coradoc-adoc/lib/coradoc/asciidoc/model/attribute_list/matchers.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      class AttributeList < Base
+        module Matchers
+          def one(*args)
+            One.new(*args)
+          end
+
+          class One
+            def initialize(*possibilities)
+              @possibilities = possibilities
+            end
+
+            def ===(other)
+              @possibilities.any? { |i| i === other }
+            end
+          end
+
+          def many(*args)
+            Many.new(*args)
+          end
+
+          # NOTE: The Many matcher validates that all values in an array/string match
+          # one of the specified possibilities. Currently accepts all matching values
+          # without selective rejection - this may be enhanced in future versions.
+          class Many
+            def initialize(*possibilities)
+              @possibilities = possibilities
+            end
+
+            def ===(other)
+              other = other.split(',') if other.is_a?(String)
+
+              other.is_a?(Array) &&
+                other.all? { |i| @possibilities.any? { |p| p === i } }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/coradoc-adoc/lib/coradoc/asciidoc/model/attribute_list.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      # Attribute list for AsciiDoc elements.
+      #
+      # Attribute lists represent the square-bracket attribute syntax in AsciiDoc:
+      # [positional1, pos2, name1=value1, name2=value2]
+      #
+      # This class manages both positional and named attributes, with support
+      # for validation and rejection of invalid values.
+      #
+      # @!attribute [r] positional
+      #   @return [Array<Coradoc::AsciiDoc::Model::AttributeListAttribute>] Positional attributes (by position)
+      #
+      # @!attribute [r] named
+      #   @return [Array<Coradoc::AsciiDoc::Model::NamedAttribute>] Named attributes (key-value pairs)
+      #
+      # @!attribute [r] rejected_positional
+      #   @return [Array<Coradoc::AsciiDoc::Model::RejectedPositionalAttribute>] Rejected positional attributes
+      #
+      # @!attribute [r] rejected_named
+      #   @return [Array<Coradoc::AsciiDoc::Model::NamedAttribute>] Rejected named attributes
+      #
+      # @example Create an attribute list
+      #   attrs = Coradoc::AsciiDoc::Model::Coradoc::AsciiDoc::Model::AttributeList.new
+      #   attrs.add_positional("value1")
+      #   attrs.add_named("option", "value")
+      #   attrs.to_adoc # => "[value1,option=value]\n"
+      #
+      # @example Empty attribute list
+      #   attrs = Coradoc::AsciiDoc::Model::Coradoc::AsciiDoc::Model::AttributeList.new
+      #   attrs.to_adoc # => "[]"
+      #
+      # @example Hide empty attribute list
+      #   attrs = Coradoc::AsciiDoc::Model::Coradoc::AsciiDoc::Model::AttributeList.new
+      #   attrs.to_adoc(show_empty: false) # => ""
+      #
+      class AttributeList < Base
+        # Autoload Matchers module
+        autoload :Matchers, 'coradoc/asciidoc/model/attribute_list/matchers'
+
+        # Include Matchers module for validation methods
+        include Matchers
+
+        attribute :positional,
+                  Coradoc::AsciiDoc::Model::AttributeListAttribute,
+                  collection: true,
+                  initialize_empty: true
+        attribute :named, Coradoc::AsciiDoc::Model::NamedAttribute, collection: true, initialize_empty: true
+        attribute :rejected_positional,
+                  Coradoc::AsciiDoc::Model::RejectedPositionalAttribute,
+                  collection: true,
+                  initialize_empty: true
+        attribute :rejected_named,
+                  Coradoc::AsciiDoc::Model::NamedAttribute,
+                  collection: true,
+                  initialize_empty: true
+
+        # Add positional attributes to this list
+        #
+        # @param attr [Array<Object>] Values to add as positional attributes
+        #
+        # @example Adding positional attributes
+        #   attrs.add_positional("value1", "value2")
+        #
+        def add_positional(*attr)
+          attr.each do |a|
+            @positional << AttributeListAttribute.new(value: a)
+          end
+        end
+
+        # Add a named attribute to this list
+        #
+        # @param name [String, Symbol] The attribute name
+        # @param value [Object] The attribute value (will be converted to array)
+        #
+        # @example Adding named attributes
+        #   attrs.add_named("title", "My Title")
+        #   attrs.add_named("cols", "3,2,1")
+        #
+        def add_named(name, value)
+          @named << NamedAttribute.new(
+            name:,
+            value: value.is_a?(Array) ? value : [value]
+          )
+        end
+
+        # Validate named attributes against validators
+        #
+        # @param validators [Hash] Hash of name => matcher pairs
+        # @yield [name, value] Block called for each invalid attribute
+        #
+        # @example Validate with custom validator
+        #   attrs.validate_named(title: /./) do |name, value|
+        #     puts "Invalid #{name}: #{value}"
+        #   end
+        #
+        def validate_named(validators: {})
+          named.each_with_index do |named_attribute, _i|
+            name = named_attribute.name.to_sym
+            value = named_attribute.value
+
+            matcher = validators[name]
+
+            next if matcher && matcher === value
+
+            # Previous implementation would remove the value from the list
+            # named.delete(name)
+            rejected_named << named_attribute.dup
+            yield(name, value) if block_given?
+          end
+        end
+
+        # Validate positional attributes against validators
+        #
+        # @param validators [Array] Array of [position, matcher] pairs
+        # @yield [position, value] Block called for each invalid attribute
+        #
+        # @example Validate positional attributes
+        #   attrs.validate_positional([[0, /./], [1, Integer]])
+        #
+        def validate_positional(validators: [])
+          positional.each_with_index do |positional_attribute, i|
+            matcher = validators[i][1]
+            value = positional_attribute.value
+
+            next unless matcher && !(matcher === value)
+
+            warn "#{value} does not match #{matcher}"
+            # Previous implementation would remove the value from the list
+            # positional[i] = nil
+            rejected_positional << RejectedPositionalAttribute.new(
+              position: i, value:
+            )
+            yield(i, value) if block_given?
+          end
+        end
+
+        # To be overridden in subclasses.
+        # @return [Array] Array of positional validators
+        def positional_validators
+          []
+        end
+
+        # To be overridden in subclasses.
+        # @return [Hash] Hash of named validators
+        def named_validators
+          {}
+        end
+
+        # Validate this attribute list
+        #
+        # @return [Array<Lutaml::Model::Error>] Validation errors (empty if valid)
+        def validate
+          errors = super
+
+          validate_positional(positional_validators) do |i, value|
+            errors << Lutaml::Model::Error.new(
+              "Positional attribute at position #{i} with value '#{value}' is not valid"
+            )
+          end
+
+          validate_named(named_validators) do |name, value|
+            errors << Lutaml::Model::Error.new(
+              "Named attribute #{name} with value '#{value}' is not valid"
+            )
+          end
+
+          errors
+        end
+
+        # Serialize this attribute list to AsciiDoc
+        #
+        # Generates the square-bracket syntax with valid attributes only.
+        #
+        # @param show_empty [Boolean] If true, show "[]" for empty lists (default: true)
+        # @return [String] AsciiDoc representation of this attribute list
+        #
+        # @example Serialize with options
+        #   attrs.to_adoc(show_empty: true)  # => "[value1,name=val]"
+        #   attrs.to_adoc(show_empty: false) # => "[value1,name=val]"
+        #   empty.to_adoc                     # => "[]"
+        #   empty.to_adoc(show_empty: false) # => ""
+        #
+        def to_adoc(show_empty: true)
+          valid_positional = positional.reject.with_index do |_p, i|
+            rejected_positional.any? { |r| r.position == i }
+          end
+
+          valid_named = named.reject do |n|
+            rejected_named.any? { |r| r.name == n.name }
+          end
+
+          adoc = [valid_positional,
+                  valid_named].flatten.map(&:to_adoc).join(',')
+
+          if adoc.empty? && show_empty
+            '[]'
+          elsif adoc.empty?
+            ''
+          else
+            "[#{adoc}]"
+          end
+        end
+
+        def empty?
+          positional.empty? && named.empty?
+        end
+
+        # Get a named attribute value by name
+        # @param name [String, Symbol] The attribute name
+        # @return [Object, nil] The attribute value or nil if not found
+        def [](name)
+          name_str = name.to_s
+          named.find { |n| n.name.to_s == name_str }&.value
+        end
+
+        # Get a named attribute value with default
+        # @param name [String, Symbol] The attribute name
+        # @param default [Object] The default value if not found
+        # @return [Object] The attribute value or default
+        def fetch(name, default = nil)
+          self[name] || default
+        end
+      end
+    end
+  end
+end

data/coradoc-adoc/lib/coradoc/asciidoc/model/attribute_list_attribute.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module AsciiDoc
+    module Model
+      class AttributeListAttribute < Base
+        attribute :value, :string
+      end
+    end
+  end
+end