coradoc-markdown 1.0.0 → 1.0.3

data/lib/coradoc/markdown/serializer/builder.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative 'config'
+require_relative 'context'
+require_relative 'registry'
+require_relative 'registrations'
+require_relative 'runner'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Fluent builder for a configured serializer runner.
+      #
+      # Usage:
+      #
+      #   Serializer.build(:gfm) do |config|
+      #     config.admonition_style = :container
+      #     config.suppress_comments = false
+      #   end.call(element)
+      #
+      # The block yields the Builder itself; assignments accumulate as
+      # overrides and are frozen into a Config when `runner` (or `call`)
+      # is invoked.
+      class Builder
+        attr_reader :flavor, :overrides
+
+        def initialize(flavor = Flavor::DEFAULT_FLAVOR)
+          @flavor = flavor
+          @overrides = {}
+        end
+
+        Config::ATTRIBUTES.each do |attr|
+          define_method("#{attr}=") do |value|
+            @overrides[attr] = value
+          end
+        end
+
+        def apply(hash)
+          hash.each { |k, v| @overrides[k.to_sym] = v }
+          self
+        end
+
+        def config
+          @config ||= Config.new(flavor: flavor, **overrides)
+        end
+
+        def runner
+          @runner ||= Runner.new(config: config, registry: Registrations.default_registry)
+        end
+
+        def call(element)
+          runner.call(element)
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/config.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative 'flavor'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Immutable serialization configuration.
+      #
+      # Created via `Serializer.build` with a flavor and overrides. Once
+      # built, the Config is frozen and resolves capability strategies
+      # (admonitions, autolinks, comments, etc.) by combining flavor
+      # defaults with caller overrides.
+      #
+      # SSOT: the 5 spec-mandated options live here and nowhere else.
+      # Strategy classes read their mode via `config.strategy_for(:capability)`.
+      class Config
+        ATTRIBUTES = %i[
+          markdown_flavor
+          admonition_style
+          definition_list_nested
+          suppress_comments
+          autolinks
+        ].freeze
+
+        attr_reader(*ATTRIBUTES)
+
+        def initialize(flavor: :gfm, **overrides)
+          unless Flavor.known?(flavor)
+            raise ArgumentError, "Unknown markdown_flavor: #{flavor.inspect}. " \
+                                 "Known: #{Flavor.names.inspect}"
+          end
+
+          resolved = Flavor.resolve(flavor).merge(symbolize(overrides))
+          validate_options!(resolved)
+
+          @markdown_flavor = resolved.fetch(:markdown_flavor)
+          @admonition_style = resolved.fetch(:admonition_style)
+          @definition_list_nested = resolved.fetch(:definition_list_nested)
+          @suppress_comments = resolved.fetch(:suppress_comments)
+          @autolinks = resolved.fetch(:autolinks)
+
+          freeze
+        end
+
+        def to_h
+          ATTRIBUTES.to_h { |k| [k, public_send(k)] }
+        end
+
+        def with(overrides)
+          self.class.new(**to_h.merge(symbolize(overrides)))
+        end
+
+        private
+
+        def symbolize(hash)
+          hash.to_h { |k, v| [k.to_sym, v] }
+        end
+
+        def validate_options!(resolved)
+          unless %i[github container html gfm_alert].include?(resolved.fetch(:admonition_style))
+            raise ArgumentError, "Unknown admonition_style: #{resolved[:admonition_style].inspect}"
+          end
+          unless %i[html flatten].include?(resolved.fetch(:definition_list_nested))
+            raise ArgumentError, "Unknown definition_list_nested: #{resolved[:definition_list_nested].inspect}"
+          end
+          unless [true, false].include?(resolved.fetch(:suppress_comments))
+            raise ArgumentError, 'suppress_comments must be boolean'
+          end
+          return if [true, false].include?(resolved.fetch(:autolinks))
+
+          raise ArgumentError, 'autolinks must be boolean'
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/context.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Per-document mutable state threaded through every serializer call,
+      # AND the single dispatch interface element serializers use to
+      # recurse into child elements.
+      #
+      # Threading dispatch through the context (not the runner) means
+      # serializers stay stateless and don't need a back-reference to
+      # the runner — they call `ctx.serialize(child)` and `ctx.serialize_inline(child)`.
+      #
+      # Holds counters (footnotes, link references) and accumulators
+      # (footnote definitions emitted at document end, etc.). Created
+      # fresh per top-level `call` — never shared between documents.
+      class Context
+        attr_reader :config, :registry, :runner,
+                    :footnote_defs, :link_refs,
+                    :footnote_counter, :link_counter
+
+        def initialize(config:, registry:, runner:)
+          @config = config
+          @registry = registry
+          @runner = runner
+          @footnote_defs = []
+          @link_refs = []
+          @footnote_counter = 0
+          @link_counter = 0
+        end
+
+        def serialize(element)
+          runner.serialize(element, self)
+        end
+
+        def serialize_inline(element)
+          runner.serialize_inline(element, self)
+        end
+
+        def serialize_inline_join(elements)
+          Array(elements).map { |e| serialize_inline(e) }.join
+        end
+
+        def next_footnote_id
+          @footnote_counter += 1
+          "fn#{@footnote_counter}"
+        end
+
+        def next_link_ref_id
+          @link_counter += 1
+          @link_counter.to_s
+        end
+
+        def register_footnote_def(definition_text)
+          @footnote_defs << definition_text unless @footnote_defs.include?(definition_text)
+        end
+
+        def register_link_ref(id, url, title: nil)
+          @link_refs << LinkRef.new(id: id, url: url, title: title)
+        end
+
+        LinkRef = Struct.new(:id, :url, :title)
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/element_serializer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Base class for element serializers. Subclasses declare:
+      # - `handles_type TypeClass` — the model class (or ancestor) they accept
+      # - `call(element, ctx)` — the actual serialization
+      #
+      # `handles?` defaults to `is_a?(handles_type)`; override for finer
+      # conditional dispatch (e.g. "I handle DefinitionList only when nested").
+      class ElementSerializer
+        class << self
+          def handles_type(klass = nil)
+            if klass
+              @handles_type = klass
+              self
+            else
+              @handles_type || (superclass.respond_to?(:handles_type) ? superclass.handles_type : nil)
+            end
+          end
+
+          def handles?(_element)
+            true
+          end
+
+          def call(...)
+            new.call(...)
+          end
+        end
+
+        def call(_element, _ctx)
+          raise NotImplementedError, "#{self.class.name}#call not implemented"
+        end
+
+        def handles?(element)
+          self.class.handles?(element)
+        end
+
+        def handles_type
+          self.class.handles_type
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/flavor.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Named Markdown flavor profiles.
+      #
+      # Each flavor bundles sensible defaults for the 5 spec options.
+      # Callers can override any option via `Serializer.build`.
+      #
+      # Adding a new flavor = adding one entry here. No serializer code
+      # needs to change — Open/Closed.
+      module Flavor
+        PROFILES = {
+          commonmark: {
+            markdown_flavor: :commonmark,
+            admonition_style: :html,
+            definition_list_nested: :html,
+            suppress_comments: true,
+            autolinks: true
+          },
+          gfm: {
+            markdown_flavor: :gfm,
+            admonition_style: :github,
+            definition_list_nested: :html,
+            suppress_comments: true,
+            autolinks: true
+          },
+          kramdown: {
+            markdown_flavor: :kramdown,
+            admonition_style: :html,
+            definition_list_nested: :html,
+            suppress_comments: true,
+            autolinks: true
+          },
+          pandoc: {
+            markdown_flavor: :pandoc,
+            admonition_style: :html,
+            definition_list_nested: :html,
+            suppress_comments: true,
+            autolinks: true
+          },
+          vitepress: {
+            markdown_flavor: :vitepress,
+            admonition_style: :container,
+            definition_list_nested: :html,
+            suppress_comments: true,
+            autolinks: true
+          },
+          php_markdown_extra: {
+            markdown_flavor: :php_markdown_extra,
+            admonition_style: :html,
+            definition_list_nested: :html,
+            suppress_comments: true,
+            autolinks: true
+          }
+        }.freeze
+
+        DEFAULT_FLAVOR = :gfm
+
+        class << self
+          def names
+            PROFILES.keys
+          end
+
+          def known?(name)
+            PROFILES.key?(name.to_sym)
+          end
+
+          def resolve(name)
+            profile = PROFILES[name.to_sym] || PROFILES[DEFAULT_FLAVOR]
+            profile.dup
+          end
+
+          def default
+            PROFILES[DEFAULT_FLAVOR]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/registrations.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require_relative 'registry'
+require_relative 'serializers/document'
+require_relative 'serializers/heading'
+require_relative 'serializers/paragraph'
+require_relative 'serializers/list'
+require_relative 'serializers/code_block'
+require_relative 'serializers/blockquote'
+require_relative 'serializers/link'
+require_relative 'serializers/image'
+require_relative 'serializers/horizontal_rule'
+require_relative 'serializers/table'
+require_relative 'serializers/emphasis'
+require_relative 'serializers/strong'
+require_relative 'serializers/code'
+require_relative 'serializers/strikethrough'
+require_relative 'serializers/highlight'
+require_relative 'serializers/subscript'
+require_relative 'serializers/superscript'
+require_relative 'serializers/underline'
+require_relative 'serializers/cross_reference'
+require_relative 'serializers/attribute_list'
+require_relative 'serializers/math'
+require_relative 'serializers/extension'
+require_relative 'serializers/definition_list'
+require_relative 'serializers/footnote'
+require_relative 'serializers/footnote_reference'
+require_relative 'serializers/abbreviation'
+require_relative 'serializers/comment'
+require_relative 'serializers/admonition'
+require_relative 'serializers/example_block'
+require_relative 'serializers/open_block'
+require_relative 'serializers/sidebar'
+require_relative 'serializers/verse'
+require_relative 'serializers/pass'
+require_relative 'serializers/literal'
+require_relative 'serializers/hard_line_break'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Auto-registers all built-in element serializers into a fresh
+      # Registry. Called once per Runner (cached via `default_registry`).
+      #
+      # Adding a new element serializer = appending one entry here. No
+      # lookup code changes — Open/Closed.
+      module Registrations
+        SERIALIZEABLE = [
+          Serializers::Document,
+          Serializers::Heading,
+          Serializers::Paragraph,
+          Serializers::List,
+          Serializers::CodeBlock,
+          Serializers::Blockquote,
+          Serializers::Link,
+          Serializers::Image,
+          Serializers::HorizontalRule,
+          Serializers::Table,
+          Serializers::Emphasis,
+          Serializers::Strong,
+          Serializers::Code,
+          Serializers::Strikethrough,
+          Serializers::Highlight,
+          Serializers::Subscript,
+          Serializers::Superscript,
+          Serializers::Underline,
+          Serializers::CrossReference,
+          Serializers::AttributeList,
+          Serializers::Math,
+          Serializers::Extension,
+          Serializers::DefinitionList,
+          Serializers::Footnote,
+          Serializers::FootnoteReference,
+          Serializers::Abbreviation,
+          Serializers::Comment,
+          Serializers::Admonition,
+          Serializers::ExampleBlock,
+          Serializers::OpenBlock,
+          Serializers::Sidebar,
+          Serializers::Verse,
+          Serializers::Pass,
+          Serializers::Literal,
+          Serializers::HardLineBreak
+        ].freeze
+
+        @mutex = Mutex.new
+        @default = nil
+
+        class << self
+          def default_registry
+            @mutex.synchronize do
+              @default ||= register_all(Registry.new)
+            end
+          end
+
+          def fresh_registry
+            register_all(Registry.new)
+          end
+
+          private
+
+          def register_all(registry)
+            SERIALIZEABLE.each { |klass| registry.register(klass.new) }
+            registry
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/registry.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Type-keyed dispatch table for element serializers.
+      #
+      # Each entry is a tuple of (serializer_instance, priority). Dispatch
+      # resolves the highest-priority entry whose declared `handles?` predicate
+      # accepts the element. This lets specialized serializers (e.g. one that
+      # targets a specific CoreModel subclass) override generic ones without
+      # modifying the registry lookup logic — Open/Closed.
+      class Registry
+        class Entry < Struct.new(:serializer, :priority)
+          include Comparable
+
+          def <=>(other)
+            priority <=> other.priority
+          end
+        end
+
+        def initialize
+          @entries = Hash.new { |h, k| h[k] = [] }
+        end
+
+        def register(serializer, priority: 0)
+          klass = serializer.handles_type
+          raise ArgumentError, "Serializer #{serializer.class} declares no handles_type" unless klass
+
+          @entries[klass] << Entry.new(serializer, priority)
+          @entries[klass].sort!
+          serializer
+        end
+
+        def lookup(element)
+          each_candidate(element).first&.serializer
+        end
+
+        def lookup!(element)
+          lookup(element) || raise(ArgumentError,
+                                   "Unknown element type for serialization: #{element.class}. " \
+                                     'Expected a known Markdown model type.')
+        end
+
+        private
+
+        def each_candidate(element)
+          return enum_for(:each_candidate, element) unless block_given?
+
+          walked = element.class.ancestors
+          walked.each do |klass|
+            @entries[klass].sort_by { |e| -e.priority }.each do |entry|
+              next unless entry.serializer.handles?(element)
+
+              yield entry
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/runner.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative 'context'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      # Stateful runner: holds a frozen Config + Registry, exposes `#call`.
+      # Each top-level `call` creates a fresh Context (per-document mutable
+      # state) so the same runner can serialize multiple documents without
+      # cross-document leakage.
+      class Runner
+        attr_reader :config, :registry
+
+        def initialize(config:, registry:)
+          @config = config
+          @registry = registry
+        end
+
+        def call(element)
+          ctx = Context.new(config: config, registry: registry, runner: self)
+          result = serialize(element, ctx)
+          result = append_link_refs(result, ctx)
+          append_footnote_defs(result, ctx).to_s
+        end
+
+        def serialize(element, ctx = nil)
+          ctx ||= Context.new(config: config, registry: registry, runner: self)
+          case element
+          when String
+            element
+          when nil
+            ''
+          when Array
+            element.map { |e| serialize(e, ctx) }.join
+          else
+            serializer = registry.lookup(element)
+            if serializer
+              serializer.call(element, ctx)
+            else
+              raise ArgumentError,
+                    "Unknown element type for serialization: #{element.class}. " \
+                      'Expected a known Markdown model type.'
+            end
+          end
+        end
+
+        def serialize_inline(element, ctx)
+          case element
+          when String
+            element
+          when nil
+            ''
+          when ::Coradoc::Markdown::Base, ::Coradoc::Markdown::Document
+            serialize(element, ctx)
+          when Array
+            element.map { |e| serialize_inline(e, ctx) }.join
+          else
+            raise ArgumentError,
+                  "Cannot serialize inline content of type #{element.class}. " \
+                  'Expected String, known inline model, or Base subclass.'
+          end
+        end
+
+        private
+
+        def append_link_refs(result, ctx)
+          return result if ctx.link_refs.empty?
+
+          refs = ctx.link_refs.map do |ref|
+            "[#{ref.id}]: #{ref.url}#{ref.title ? " \"#{ref.title}\"" : ''}"
+          end.join("\n")
+          "#{result}\n\n#{refs}"
+        end
+
+        def append_footnote_defs(result, ctx)
+          return result if ctx.footnote_defs.empty?
+
+          "#{result}\n\n#{ctx.footnote_defs.join("\n")}"
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/abbreviation.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class Abbreviation < ElementSerializer
+          handles_type ::Coradoc::Markdown::Abbreviation
+
+          def call(element, _ctx)
+            "*[#{element.term}]: #{element.definition}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/admonition.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+require_relative '../strategies/admonition/registry'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class Admonition < ElementSerializer
+          handles_type ::Coradoc::Markdown::Admonition
+
+          def call(element, ctx)
+            Strategies::Admonition::Registry.render(element, ctx: ctx)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/attribute_list.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class AttributeList < ElementSerializer
+          handles_type ::Coradoc::Markdown::AttributeList
+
+          def call(element, _ctx)
+            return '' if element.empty?
+
+            parts = []
+            parts << "##{element.id}" if element.id
+            parts += element.classes.map { |c| ".#{c}" }
+            parts += element.attributes.map { |nv| %(#{nv.name}="#{nv.value}") }
+            "{:#{parts.join(' ')}}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/blockquote.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class Blockquote < ElementSerializer
+          handles_type ::Coradoc::Markdown::Blockquote
+
+          def call(element, _ctx)
+            element.content.to_s.lines.map { |line| "> #{line}" }.join
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/markdown/serializer/serializers/code.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../element_serializer'
+
+module Coradoc
+  module Markdown
+    class Serializer
+      module Serializers
+        class Code < ElementSerializer
+          handles_type ::Coradoc::Markdown::Code
+
+          def call(element, _ctx)
+            "`#{element.text}`"
+          end
+        end
+      end
+    end
+  end
+end