coradoc 2.0.22 → 2.0.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a33595a0aa6205f5a5d1adabd8ede0dc8f3d4237c2376a910800822400af2f59
-  data.tar.gz: ecb898a27a6cb1540b553fdb3aa97bef73077a85a13175099738fefe3307faf2
+  metadata.gz: 7370b3dabd4535faf0592e455d0bfd13c582b37941c411a0c4c7b86528843896
+  data.tar.gz: c61e126d88a2dc69c507657201b9b3e7875a7d6beffac957d5b805a81ffcc6d5
 SHA512:
-  metadata.gz: db01c4272054b9f2907ba0af6444e741c6d3151bf916f22aeb11dc25380ea7b0a9d63f88ba2fe2eeacd07bfcf08e50a30b8eeac914605ac394d4bccc9d3d282a
-  data.tar.gz: c40699fd199f0f74a8f657ff7ee26036703e0865862919f2787acd52f532e40c825687cd52c4ef4c4a01337f3819121813f6f291dcd76d264c27bd916f1bc823
+  metadata.gz: 548b69fbd08a23cabf10e60ed599bafb904c87e857678bd539f820fc824ff2d407761728c10a2c6be2359a40b8d6973211adaf7c41171e7928c83a8816f43360
+  data.tar.gz: 04e7b4f63d935208df375f2ecf979104db5b0b7de9e95b6c04d77939d1a293114f2c285ccea7cc7a7e0709e364d7fe1c58d2038e2b6adc923591421be4d2ade8

data/lib/coradoc/coradoc.rb

@@ -170,6 +170,33 @@ module Coradoc
       )
     end
 
+    # Rewrite every link/xref target in a parsed document.
+    #
+    # Walks the document tree and invokes the supplied rewriter for each
+    # link and cross-reference target. The original document is never
+    # mutated — a NEW document is returned.
+    #
+    # Verbatim blocks (+SourceBlock+, +ListingBlock+, +LiteralBlock+,
+    # +PassBlock+, +StemBlock+) are skipped entirely so link-shaped text
+    # inside code/math bodies is never rewritten.
+    #
+    # The rewriter responds to +#call(target:, kind:, context:)+ and
+    # returns the new target String. +kind+ is +:link+ or +:xref+; the
+    # block form is supported for one-liners.
+    #
+    # @param document [Coradoc::CoreModel::Base] parsed document
+    # @param rewriter [#call, nil] callable rewriter; ignored when a block is given
+    # @return [Coradoc::CoreModel::Base] new document with rewritten targets
+    #
+    # @example Canonicalize snake_case targets to kebab-case
+    #   doc = Coradoc.parse(adoc, format: :asciidoc)
+    #   rewritten = Coradoc.rewrite_links(doc) do |target:, kind:, **|
+    #     target.tr('_', '-')
+    #   end
+    def rewrite_links(document, rewriter: nil, &block)
+      Coradoc::LinkRewriter.rewrite(document, rewriter: rewriter, &block)
+    end
+
     # Convert document text from one format to another
     #
     # This is the main entry point for format conversion. It handles the

data/lib/coradoc/core_model/base.rb

@@ -41,6 +41,28 @@ module Coradoc
       #   @return [Array<MetadataEntry>] additional metadata entries
       attribute :metadata_entries, MetadataEntry, collection: true
 
+      # Construct an instance and yield it for in-place mutation.
+      #
+      # This is the programmatic-construction entry point for CoreModel
+      # nodes. It calls +new+ exactly as a caller would, then yields
+      # the resulting instance for append-style construction. No new
+      # class hierarchy, no +method_missing+ — the block operates on
+      # the real model object.
+      #
+      # Per-class fluent helpers (e.g., +ListBlock#add_item+,
+      # +ListItem#add_text+) compose naturally with +build+:
+      #
+      #   list = ListBlock.build do |ul|
+      #     children.each { |c| ul.add_item { |li| li.add_link(c[:slug], text: c[:title]) } }
+      #   end
+      #
+      # Without a block, +build(**attrs)+ is identical to +new(**attrs)+.
+      def self.build(**attrs)
+        instance = new(**attrs)
+        yield instance if block_given?
+        instance
+      end
+
       # Get all metadata as a hash, or a specific metadata value by key
       # @overload metadata
       #   @return [Hash] All metadata as key-value pairs
@@ -145,6 +167,23 @@ module Coradoc
         visitor.visit(self)
       end
 
+      # True when this node counts as "real body content" for the
+      # purposes of empty-document detection and similar structural
+      # queries. Default is true; metadata and ephemeral nodes
+      # (FrontmatterBlock, CommentBlock, CommentLine) override to
+      # false. Polymorphic dispatch keeps the predicate open for
+      # future "skip-me" types — no central walker to edit (OCP).
+      def body_content?
+        true
+      end
+
+      # True when this node is structurally present but carries no
+      # visible characters. Default is false; inline text and
+      # paragraph blocks override to inspect their text content.
+      def whitespace_only?
+        false
+      end
+
       private
 
       # List of attributes to compare for semantic equivalence

data/lib/coradoc/core_model/comment_block.rb

@@ -7,6 +7,10 @@ module Coradoc
       def self.semantic_type
         :comment
       end
+
+      def body_content?
+        false
+      end
     end
   end
 end

data/lib/coradoc/core_model/comment_line.rb

@@ -13,6 +13,10 @@ module Coradoc
         :comment_line
       end
 
+      def body_content?
+        false
+      end
+
       attribute :text, :string
     end
   end

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

@@ -10,42 +10,89 @@ module Coradoc
       # No other code in any gem may call YAML directly for frontmatter.
       # This isolates permitted-classes configuration and error handling
       # in one MECE location (DRY).
+      #
+      # The Codec emits flat YAML — values rendered with their natural
+      # YAML type. This is what Jekyll, Hugo, VitePress, VuePress, 11ty
+      # and every SSG expects: +title: Foo+ / +date: 2024-01-01+.
+      # Round-trip fidelity for typed values (Date, Time, Symbol) is
+      # preserved by Psych's permitted-classes mechanism, not by a
+      # custom discriminator scheme.
+      #
+      # For the typed-tree representation used by the coradoc-mirror JSON
+      # pipeline, see +Coradoc::Mirror::Node::FrontmatterValue+ and
+      # +Coradoc::Mirror::Handlers::Frontmatter+. The typed-tree concern
+      # lives in the mirror gem; this Codec stays focused on YAML.
       module Codec
         PERMITTED_CLASSES = [Date, Time, DateTime, Symbol].freeze
 
         class << self
-          # Parse a YAML string into a FrontmatterBlock.
-          # Returns an empty FrontmatterBlock on malformed YAML (graceful
-          # degradation — body parsing continues).
+          # Parse YAML text into a FrontmatterBlock. Returns an empty
+          # FrontmatterBlock on malformed YAML or non-Hash payload.
+          # Logs a warning so the conversion pipeline can surface the
+          # skip rather than silently dropping user-authored content.
           def from_yaml(yaml_text)
             return FrontmatterBlock.new if yaml_text.nil? || yaml_text.strip.empty?
 
-            parsed = YAML.safe_load(
-              yaml_text,
-              permitted_classes: PERMITTED_CLASSES,
-              aliases: true
-            )
-            return FrontmatterBlock.new unless parsed.is_a?(Hash)
-
-            schema = parsed['$schema']
-            data = parsed.except('$schema')
-            FrontmatterBlock.new(schema: schema&.to_s, data: data)
-          rescue YAML::SyntaxError, Psych::DisallowedClass
+            build_from_loaded(load_yaml(yaml_text))
+          rescue YAML::SyntaxError, Psych::DisallowedClass => e
+            Coradoc::Logger.warn("frontmatter parse failed: #{e.message}")
             FrontmatterBlock.new
           end
 
+          # Build a FrontmatterBlock from a Ruby hash with native-typed
+          # values (String, Integer, Date, …). Returns an empty block
+          # for non-Hash input.
+          def from_hash(hash)
+            return FrontmatterBlock.new unless hash.is_a?(Hash)
+
+            build_from_loaded(hash)
+          end
+
           # Serialize a FrontmatterBlock to canonical YAML text.
-          # Does NOT include leading/trailing `---` delimiters; the caller
-          # wraps the output.
+          # Does NOT include leading/trailing +---+ delimiters; the
+          # caller wraps the output. Returns +''+ for empty blocks.
           def to_yaml(block)
             return '' unless block.is_a?(FrontmatterBlock)
 
+            payload = flat_tree(block)
+            return '' if payload.empty?
+
+            YAML.dump(payload).delete_prefix("---\n").delete_suffix("\n...")
+          end
+
+          # Return the frontmatter as a native-typed Ruby hash.
+          # +$schema+ is included when present.
+          def to_hash(block)
+            return {} unless block.is_a?(FrontmatterBlock)
+
+            flat_tree(block)
+          end
+
+          private
+
+          def load_yaml(yaml_text)
+            YAML.safe_load(
+              yaml_text,
+              permitted_classes: PERMITTED_CLASSES,
+              aliases: true
+            )
+          end
+
+          def build_from_loaded(loaded)
+            return FrontmatterBlock.new unless loaded.is_a?(Hash)
+
+            schema = loaded['$schema']
+            FrontmatterBlock.new(
+              schema: schema&.to_s,
+              data: loaded.except('$schema')
+            )
+          end
+
+          def flat_tree(block)
             tree = {}
             tree['$schema'] = block.schema if block.schema
             tree.merge!(block.data || {})
-            return '' if tree.empty?
-
-            YAML.dump(tree).delete_prefix("---\n").delete_suffix("\n...")
+            tree
           end
         end
       end

data/lib/coradoc/core_model/frontmatter.rb

@@ -50,6 +50,10 @@ module Coradoc
         schema.nil? && (data.nil? || data.empty?)
       end
 
+      def body_content?
+        false
+      end
+
       # Sub-namespaces (Codec, SchemaResolver, FieldTransform, TextSplitter)
       # live under FrontmatterBlock and autoload lazily.
       autoload :Codec, "#{__dir__}/frontmatter/codec"

data/lib/coradoc/core_model/inline_element.rb

@@ -24,6 +24,18 @@ module Coradoc
         self.class.format_type || format_type
       end
 
+      # Polymorphic classification used by LinkRewriter::Visitor. Returns
+      # :link / :xref when this node carries a rewrite-able target, nil
+      # otherwise. Generic InlineElement instances defer to their
+      # resolved format_type; typed subclasses override with a literal.
+      # Keeps the visitor free of class-keyed case/when (OCP).
+      def link_kind
+        case resolve_format_type
+        when 'link' then :link
+        when 'xref' then :xref
+        end
+      end
+
       FORMAT_TYPES = %w[
         bold italic monospace underline strikethrough
         subscript superscript highlight
@@ -99,12 +111,20 @@ module Coradoc
       def self.format_type
         'link'
       end
+
+      def link_kind
+        :link
+      end
     end
 
     class CrossReferenceElement < InlineElement
       def self.format_type
         'xref'
       end
+
+      def link_kind
+        :xref
+      end
     end
 
     class StemElement < InlineElement

data/lib/coradoc/core_model/list_block.rb

@@ -108,6 +108,23 @@ module Coradoc
       #   @return [Array<ListItem>] collection of list items
       attribute :items, ListItem, collection: true
 
+      # -- Fluent construction helpers (paired with Base.build) --
+
+      # Append a new ListItem, built via ListItem.build. The block
+      # (if given) is yielded the new item so callers can chain
+      # +add_text+ / +add_link+ on it inline:
+      #
+      #   ListBlock.build do |ul|
+      #     children.each { |c| ul.add_item { |li| li.add_link(c[:slug], text: c[:title]) } }
+      #   end
+      #
+      # Returns self for chaining at the list level.
+      def add_item(marker: self.marker_type == 'ordered' ? '.' : '*')
+        item = ListItem.build(marker: marker) { |li| yield li if block_given? }
+        self.items = Array(items) + [item]
+        self
+      end
+
       private
 
       # Attributes to compare for semantic equivalence

data/lib/coradoc/core_model/list_item.rb

@@ -109,6 +109,27 @@ module Coradoc
         true
       end
 
+      # -- Fluent construction helpers (paired with Base.build) --
+
+      # Append a plain-text inline to this item's children. Returns
+      # self for chaining. Pairs naturally with ListItem.build:
+      #
+      #   ListItem.build do |li|
+      #     li.add_text("See ")
+      #     li.add_link("foo.adoc", text: "Foo")
+      #   end
+      def add_text(text)
+        self.children = Array(children) + [TextContent.new(text: text)]
+        self
+      end
+
+      # Append a +link:+ inline to this item's children. +text+ becomes
+      # the link's visible label; +target+ is the URL/anchor.
+      def add_link(target, text: nil)
+        self.children = Array(children) + [LinkElement.new(target: target, content: text)]
+        self
+      end
+
       private
 
       # Compare two list blocks for equivalence

data/lib/coradoc/core_model/output_artifact.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # Output-side state object for host-system emitters (VitePress, Hugo,
+    # Astro, plain ERB, etc.).
+    #
+    # coradoc's source side has +IncludeResolver::Filesystem+ to resolve
+    # include targets without coupling to a storage layer. The output side
+    # has no analogous state object — until now. +OutputArtifact+ captures
+    # the three pieces of state coradoc genuinely needs to hand to a
+    # downstream emitter:
+    #
+    # - +output_key+ — site-relative key (e.g. "author/iso/ref/foo")
+    # - +frontmatter_block+ — parsed YAML frontmatter (may be empty)
+    # - +core_document+ — the canonical CoreModel document
+    #
+    # The consumer takes these and renders whatever wrapper it needs in
+    # its host system's native template language. coradoc does not know
+    # about VitePress, ERB, or Liquid. Symmetric with the source side:
+    # minimal protocol object, not an engine.
+    #
+    # A mirror-tree document is deliberately NOT bundled here. coradoc
+    # core has no runtime dependency on coradoc-mirror; consumers that
+    # target the mirror JSON pipeline pair an +OutputArtifact+ with a
+    # separately-computed +Coradoc::Mirror.transform(core)+ result.
+    class OutputArtifact < Base
+      # @!attribute output_key
+      #   @return [String, nil] site-relative key with no leading slash
+      #     and no trailing extension. SSGs map this to their URL space.
+      attribute :output_key, :string
+
+      # @!attribute frontmatter_block
+      #   @return [FrontmatterBlock, nil] parsed YAML frontmatter
+      attribute :frontmatter_block, FrontmatterBlock
+
+      # @!attribute core_document
+      #   @return [DocumentElement, nil] canonical CoreModel document
+      attribute :core_document, DocumentElement
+
+      private
+
+      def comparable_attributes
+        %i[output_key frontmatter_block core_document]
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/paragraph_block.rb

@@ -7,6 +7,10 @@ module Coradoc
       def self.semantic_type
         :paragraph
       end
+
+      def whitespace_only?
+        flat_text.strip.empty?
+      end
     end
   end
 end

data/lib/coradoc/core_model/stem_block.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module CoreModel
+    # STEM block — mathematical/scientific content authored in LaTeX,
+    # AsciiMath, or another STEM markup. Carries a +language+ attribute so
+    # downstream renderers know which interpreter to invoke.
+    #
+    # AsciiDoc surface forms:
+    #   [stem]\n++++\nx^2\n++++        # language: "latex" (default)
+    #   [latexmath]\n++++\nx^2\n++++   # language: "latex"
+    #   [asciimath]\n++++\nx^2\n++++   # language: "asciimath"
+    class StemBlock < Block
+      attribute :language, :string, default: -> { 'latex' }
+
+      def self.semantic_type
+        :stem
+      end
+    end
+  end
+end

data/lib/coradoc/core_model/structural_element.rb

@@ -52,6 +52,38 @@ module Coradoc
         false
       end
 
+      # Override in subclasses that carry document-title semantics.
+      # HeaderElement at level 0 represents the document title (`= Title`
+      # in AsciiDoc). Consumers that walk the body — TOC builders,
+      # section numbering — skip these so the title is not counted as
+      # "section 1". Polymorphic dispatch (vs. an is_a? guard at the
+      # call site) keeps the predicate open for future subclasses.
+      def document_title?
+        false
+      end
+
+      # Children that count as body content and aren't whitespace-only.
+      # Derived from per-node {#body_content?} and {#whitespace_only?}
+      # predicates — no central walker, no is_a? switch to maintain.
+      def visible_children
+        Array(children).select(&:body_content?).reject(&:whitespace_only?)
+      end
+
+      # True when the body has no visible content anywhere in its subtree.
+      # A document with only frontmatter + comments returns true; a
+      # document with one non-whitespace paragraph returns false.
+      def empty_body?
+        return true if children.nil? || children.empty?
+
+        children.all? do |child|
+          next true unless child.body_content?
+          next true if child.whitespace_only?
+          next child.empty_body? if child.is_a?(StructuralElement)
+
+          false
+        end
+      end
+
       # Derived element_type string for backward compatibility with
       # templates and legacy consumers. Subclasses override this.
       def element_type
@@ -108,6 +140,15 @@ module Coradoc
         true
       end
 
+      # A level-0 HeaderElement represents the document title (the `= Title`
+      # line in AsciiDoc, the `<h1>` in HTML). It is structurally part of
+      # the body but semantically the document's title, not a section —
+      # section numbering, TOC builders, and other section-aware logic
+      # skip these so the title is not counted as "section 1".
+      def document_title?
+        level.to_i.zero?
+      end
+
       def self.element_type_name
         'header'
       end

data/lib/coradoc/core_model/text_content.rb

@@ -17,6 +17,10 @@ module Coradoc
       def to_s
         text.to_s
       end
+
+      def whitespace_only?
+        text.to_s.strip.empty?
+      end
     end
   end
 end

data/lib/coradoc/core_model.rb

@@ -70,6 +70,7 @@ module Coradoc
     autoload :SidebarBlock, "#{__dir__}/core_model/sidebar_block"
     autoload :LiteralBlock, "#{__dir__}/core_model/literal_block"
     autoload :PassBlock, "#{__dir__}/core_model/pass_block"
+    autoload :StemBlock, "#{__dir__}/core_model/stem_block"
     autoload :ListingBlock, "#{__dir__}/core_model/listing_block"
     autoload :OpenBlock, "#{__dir__}/core_model/open_block"
     autoload :VerseBlock, "#{__dir__}/core_model/verse_block"
@@ -82,5 +83,6 @@ module Coradoc
     autoload :Include, "#{__dir__}/core_model/include"
     autoload :IncludeOptions, "#{__dir__}/core_model/include_options"
     autoload :IncludeLevelOffset, "#{__dir__}/core_model/include_level_offset"
+    autoload :OutputArtifact, "#{__dir__}/core_model/output_artifact"
   end
 end

data/lib/coradoc/link_rewriter/identity.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module LinkRewriter
+    # Default no-op rewriter. Returns every target unchanged. Used when
+    # the caller only wants the visitor's immutable-copy guarantee.
+    class Identity
+      def call(target:, **)
+        target
+      end
+    end
+  end
+end

data/lib/coradoc/link_rewriter/visitor.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module LinkRewriter
+    # Focused rewriting visitor for the CoreModel tree.
+    #
+    # The set of node types that carry link/xref targets is closed and
+    # small: +LinkElement+, +CrossReferenceElement+, plus generic
+    # +InlineElement+ instances whose +format_type+ is +'link'+ or
+    # +'xref'+. That classification is owned polymorphically by
+    # +InlineElement#link_kind+ — the visitor just calls it. Adding a
+    # new link-bearing subclass means overriding +link_kind+ on it,
+    # not editing a case/when here (OCP).
+    #
+    # Verbatim block types are also closed: +SourceBlock+, +ListingBlock+,
+    # +LiteralBlock+, +PassBlock+, +StemBlock+. The visitor returns them
+    # unchanged so the rewriter never sees link-shaped text that is, in
+    # fact, raw code/math.
+    #
+    # Dispatch is class-based (no +respond_to?+ duck-typing). Unrecognized
+    # classes are returned unchanged — the visitor is closed by design.
+    class Visitor
+      # Verbatim block classes — content is raw, no link semantics.
+      VERBATIM_TYPES = [
+        Coradoc::CoreModel::SourceBlock,
+        Coradoc::CoreModel::ListingBlock,
+        Coradoc::CoreModel::LiteralBlock,
+        Coradoc::CoreModel::PassBlock,
+        Coradoc::CoreModel::StemBlock
+      ].freeze
+
+      # Structural/container classes that own a child collection. Each
+      # entry maps the class to the reader method that exposes its
+      # children. MECE — every "recurse into the children" case lands
+      # in this table. Exposed as a public constant so spec helpers
+      # and other visitors can mirror the same paths without restating
+      # the dispatch (DRY).
+      CONTAINER_TYPES = {
+        Coradoc::CoreModel::DocumentElement => :children,
+        Coradoc::CoreModel::SectionElement => :children,
+        Coradoc::CoreModel::PreambleElement => :children,
+        Coradoc::CoreModel::HeaderElement => :children,
+        Coradoc::CoreModel::Block => :children,
+        Coradoc::CoreModel::ListBlock => :items,
+        Coradoc::CoreModel::ListItem => :children,
+        Coradoc::CoreModel::Table => :rows,
+        Coradoc::CoreModel::TableRow => :cells,
+        Coradoc::CoreModel::TableCell => :children,
+        Coradoc::CoreModel::DefinitionList => :items,
+        Coradoc::CoreModel::Toc => :entries,
+        Coradoc::CoreModel::Bibliography => :entries,
+        Coradoc::CoreModel::AnnotationBlock => :children
+      }.freeze
+
+      def initialize(rewriter)
+        @rewriter = rewriter
+      end
+
+      # Entry point. Always returns a NEW root node — even Identity
+      # callers can rely on object identity to confirm the rewrite ran.
+      def visit_document(document)
+        return document unless document.is_a?(Coradoc::CoreModel::Base)
+
+        result = visit_subtree(document)
+        result.equal?(document) ? document.dup : result
+      end
+
+      private
+
+      def visit_subtree(node)
+        return node if VERBATIM_TYPES.any? { |type| node.is_a?(type) }
+        return rewrite_inline(node) if node.is_a?(Coradoc::CoreModel::InlineElement)
+
+        reader = reader_for(node)
+        return node unless reader
+
+        rewrite_collection(node, reader)
+      end
+
+      # Look up the children-reader method for +node+. Returns nil for
+      # unrecognized classes (no duck-typing — the CONTAINER_TYPES
+      # table is the single source of truth).
+      def reader_for(node)
+        CONTAINER_TYPES.each do |klass, reader|
+          return reader if node.is_a?(klass)
+        end
+        nil
+      end
+
+      def rewrite_collection(node, attr_name)
+        original = node.public_send(attr_name)
+        return node if original.nil? || original.empty?
+
+        rewritten = original.map { |child| visit_subtree(child) }
+        return node if unchanged?(rewritten, original)
+
+        rebuild_with(node, attr_name => rewritten)
+      end
+
+      # Inline dispatch. Typed LinkElement / CrossReferenceElement are
+      # always candidates; generic InlineElement instances must declare a
+      # matching format_type. Other typed subclasses (Bold, Italic, …)
+      # are walked for nested inlines instead of being rewritten.
+      def rewrite_inline(inline)
+        kind = inline.link_kind
+
+        rewritten_target = rewrite_target(inline, kind)
+        rewritten_nested = rewrite_nested(inline)
+
+        return inline if rewritten_target.nil? && rewritten_nested.nil?
+
+        overrides = {}
+        overrides[:target] = rewritten_target unless rewritten_target.nil?
+        overrides[:nested_elements] = rewritten_nested unless rewritten_nested.nil?
+        rebuild_with(inline, overrides)
+      end
+
+      def rewrite_target(inline, kind)
+        return nil unless kind
+
+        target = inline.target
+        return nil if target.nil? || target.empty?
+
+        new_target = @rewriter.call(
+          target: target,
+          kind: kind,
+          context: { in_verbatim: false }
+        )
+        return nil if new_target == target
+
+        new_target
+      end
+
+      def rewrite_nested(inline)
+        nested = inline.nested_elements
+        return nil if nested.nil? || nested.empty?
+
+        rewritten = nested.map { |child| visit_subtree(child) }
+        return nil if unchanged?(rewritten, nested)
+
+        rewritten
+      end
+
+      def rebuild_with(node, overrides)
+        duplicate = node.dup
+        overrides.each { |key, value| duplicate.public_send("#{key}=", value) }
+        duplicate
+      end
+
+      def unchanged?(rewritten, original)
+        return false unless rewritten.length == original.length
+
+        rewritten.each_with_index.all? { |node, i| node.equal?(original[i]) }
+      end
+    end
+  end
+end

data/lib/coradoc/link_rewriter.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Post-parse link/xref rewriting.
+  #
+  # Consumers that need to canonicalize link and xref targets (snake→kebab,
+  # strip +.adoc+, redirect maps, dialect translation) get a single
+  # immutable entry point: +Coradoc.rewrite_links(doc, rewriter:, &)+.
+  # The visitor walks the parsed CoreModel, invokes the supplied rewriter
+  # for every link/xref target, and returns a NEW document. Verbatim
+  # blocks (source, listing, literal, pass, stem) are skipped entirely —
+  # coradoc owns the parse and guarantees those bodies never reach the
+  # rewriter, removing the "track parser state to avoid verbatim bodies"
+  # footgun that plagues regex-based rewriting.
+  #
+  # Two-step API mirrors +Coradoc.resolve_includes+: parse produces the
+  # document, rewrite is a separate explicit step the caller controls.
+  module LinkRewriter
+    autoload :Identity, "#{__dir__}/link_rewriter/identity"
+    autoload :Visitor, "#{__dir__}/link_rewriter/visitor"
+
+    class << self
+      # Rewrite every link/xref target in +doc+.
+      #
+      # +rewriter+ responds to +#call(target:, kind:, context:)+ and returns
+      # the new target String. If a block is given it is used as the
+      # rewriter. Omitting both falls back to {Identity} (no-op) — useful
+      # for "give me a structurally identical copy" cases.
+      #
+      # Returns a NEW document; the input is never mutated.
+      def rewrite(doc, rewriter: nil, &block)
+        callable = rewriter || block || Identity.new
+        Visitor.new(callable).visit_document(doc)
+      end
+    end
+  end
+end

data/lib/coradoc/relative_path.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Coradoc
+  # Pure-function module for relative-path arithmetic across output keys.
+  #
+  # Every SSG wrapper (VitePress, Hugo, Astro) needs to compute "how many
+  # directories up do I walk to reach the site root from this output?".
+  # The answer is the segment count of the source output_key. Everything
+  # else (template, imports) is host-system-specific; this module owns
+  # only the one piece of arithmetic that is genuinely shared.
+  #
+  # No state. No class. No knowledge of any specific SSG.
+  #
+  # @example Compute a VitePress import path
+  #   Coradoc::RelativePath.from("author/iso/ref/foo", to: ".vitepress/theme")
+  #   # => "../../../.vitepress/theme"
+  module RelativePath
+    module_function
+
+    # Compute a relative path from an output_key to a site-root-relative
+    # target.
+    #
+    # @param output_key [String, nil] site-relative key for the source
+    #   page (e.g. "author/iso/ref/foo"). No leading slash, no extension.
+    # @param to [String] destination path relative to the site root.
+    # @return [String] the composed relative path.
+    def from(output_key, to:)
+      depth = output_key.to_s.count('/')
+      ('../' * depth) + to.to_s
+    end
+  end
+end

data/lib/coradoc/version.rb

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

data/lib/coradoc.rb

@@ -43,4 +43,6 @@ module Coradoc
   autoload :DocumentManipulator, 'coradoc/document_manipulator'
   autoload :Visitor, 'coradoc/visitor'
   autoload :Serializer, 'coradoc/serializer/registry'
+  autoload :LinkRewriter, 'coradoc/link_rewriter'
+  autoload :RelativePath, 'coradoc/relative_path'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coradoc
 version: !ruby/object:Gem::Version
-  version: 2.0.22
+  version: 2.0.23
 platform: ruby
 authors:
 - Ribose Inc.
@@ -90,6 +90,7 @@ files:
 - lib/coradoc/core_model/literal_block.rb
 - lib/coradoc/core_model/metadata.rb
 - lib/coradoc/core_model/open_block.rb
+- lib/coradoc/core_model/output_artifact.rb
 - lib/coradoc/core_model/paragraph_block.rb
 - lib/coradoc/core_model/pass_block.rb
 - lib/coradoc/core_model/quote_block.rb
@@ -97,6 +98,7 @@ files:
 - lib/coradoc/core_model/reviewer_block.rb
 - lib/coradoc/core_model/sidebar_block.rb
 - lib/coradoc/core_model/source_block.rb
+- lib/coradoc/core_model/stem_block.rb
 - lib/coradoc/core_model/structural_element.rb
 - lib/coradoc/core_model/table.rb
 - lib/coradoc/core_model/term.rb
@@ -117,12 +119,16 @@ files:
 - lib/coradoc/include_selectors/lines.rb
 - lib/coradoc/include_selectors/tags.rb
 - lib/coradoc/input.rb
+- lib/coradoc/link_rewriter.rb
+- lib/coradoc/link_rewriter/identity.rb
+- lib/coradoc/link_rewriter/visitor.rb
 - lib/coradoc/logger.rb
 - lib/coradoc/output.rb
 - lib/coradoc/performance_regression.rb
 - lib/coradoc/processor_registry.rb
 - lib/coradoc/query.rb
 - lib/coradoc/registry.rb
+- lib/coradoc/relative_path.rb
 - lib/coradoc/resolve_includes.rb
 - lib/coradoc/serializer/registry.rb
 - lib/coradoc/transform.rb