coradoc 2.0.28 → 2.0.30

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f0dbc8feba7133bc83baf88a6458774f364f7266b79625a0afc50434beeac89
-  data.tar.gz: f4fe999b18666604d2b615545acb073e1b6f74d7b26c3ff8fa8fd403ee45ec5d
+  metadata.gz: 9ebca4a6342273f099bbbd2b47471ea28416669106fe33ee08dc929387019334
+  data.tar.gz: ee9464a2876d263910ff6f03694a3370dc259a6d040fc7ea27e9ef7a13d66430
 SHA512:
-  metadata.gz: c4c0f7a479cfdf622faa4a26cad085c60b4e943d3ba30348e5d0426ebb10c9fbd417ceb5d069225f1e72dd9ff0960ca5e5304572d6d6cf4018236a579c4c391c
-  data.tar.gz: 6e4e649b83732a5cbf77c1edf16c70fb04a167d2d3b7ad3c3c657a029ebea5b079408dc78641f432241ac8737afb2a46fc1d3b6e2113c01075c332c2efadde9e
+  metadata.gz: a0df65e13a8ef23c1a09b31fe9872cf1b5fec5b71528765c4c09651eb63edc9d4ec18d88b64b4276e881a6de04ce1cf8fd75c3b88ab45d2516c5da1fd5160eee
+  data.tar.gz: d1ee6224713d08bbd2270917c59f7106235216d2253a0a5639c6079497649561dee38cb6962fc8515ee6688619e71ce745fe365132c9334fd5484796fd1188b4

data/lib/coradoc/cli.rb

@@ -32,6 +32,9 @@ module Coradoc
                                default: 64
     option :allow_unsafe_includes, desc: 'Disable path-traversal protection (asciidoctor :unsafe mode)',
                                    type: :boolean, default: false
+    option :allow_unresolved_includes, desc: 'Allow serialization with unresolved includes ' \
+                                             '(formats that cannot represent them drop them)',
+                                       type: :boolean, default: false
     def convert(file)
       source_format = resolve_format(file, :from)
       target_format = options[:to] ? Coradoc.normalize_format(options[:to]) : Coradoc.resolve_output_format(options[:output])
@@ -213,7 +216,7 @@ module Coradoc
 
     CONVERT_OPTIONS = %i[
       toc toc_levels section_numbers section_number_levels
-      lang theme asset_delivery
+      lang theme asset_delivery allow_unresolved_includes
     ].freeze
     private_constant :CONVERT_OPTIONS
 

data/lib/coradoc/coradoc.rb

@@ -70,6 +70,8 @@ module Coradoc
 
     def resolve_includes(document, **) = Pipeline.resolve_includes(document, **)
 
+    def resolve_references(document, **) = Pipeline.resolve_references(document, **)
+
     def rewrite_links(...) = Pipeline.rewrite_links(...)
 
     def convert(text, **) = Pipeline.convert(text, **)
@@ -150,6 +152,7 @@ module Coradoc
   autoload :FormatCatalog, "#{__dir__}/format_catalog"
   autoload :Introspection, "#{__dir__}/introspection"
   autoload :Dispatch, "#{__dir__}/dispatch"
+  autoload :Reference, "#{__dir__}/reference"
 end
 
 # Format gems self-register via Coradoc.register_format when they are required.

data/lib/coradoc/core_model/list_block.rb

@@ -2,57 +2,6 @@
 
 module Coradoc
   module CoreModel
-    # Represents a single item within a list
-    #
-    # A list item can contain:
-    # - Simple text content
-    # - A nested list
-    # - Child elements (paragraphs, blocks, etc.)
-    #
-    # Note: The nested_list attribute type is set after ListBlock is defined
-    # to avoid circular dependency issues.
-    #
-    # @example Simple list item
-    #   item = ListItem.new(
-    #     marker: "*",
-    #     content: "Item text"
-    #   )
-    #
-    # @example List item with nested list
-    #   item = ListItem.new(
-    #     marker: "*",
-    #     content: "Parent item",
-    #     nested_list: nested_list_block
-    #   )
-    class ListItem < Base
-      # @!attribute marker
-      #   @return [String, nil] the marker character(s) for this item
-      #     (e.g., '*', '**', '.', '..', '-')
-      attribute :marker, :string
-
-      # @!attribute content
-      #   @return [String, nil] text content of the list item
-      attribute :content, :string
-
-      # @!attribute nested_list
-      #   @return [ListBlock, nil] nested list within this item
-      #   Note: Typed as string initially, retyped after ListBlock defined
-      attribute :nested_list, :string
-
-      private
-
-      # Attributes to compare for semantic equivalence
-      #
-      # List items are semantically equivalent if they have the same
-      # content, nested list, and children, regardless of the specific
-      # marker used.
-      #
-      # @return [Array<Symbol>] list of comparable attributes
-      def comparable_attributes
-        %i[content nested_list children]
-      end
-    end
-
     # Represents a list block with proper nesting support
     #
     # Handles all list types:
@@ -106,7 +55,7 @@ module Coradoc
 
       # @!attribute items
       #   @return [Array<ListItem>] collection of list items
-      attribute :items, ListItem, collection: true
+      attribute :items, 'Coradoc::CoreModel::ListItem', collection: true
 
       # -- Fluent construction helpers (paired with Base.build) --
 
@@ -138,15 +87,51 @@ module Coradoc
       end
     end
 
-    # Re-open ListItem to properly type nested_list now that ListBlock
-    # is defined
-    class ListItem
-      # Remove the temporary string-typed attribute
-      remove_method :nested_list if method_defined?(:nested_list)
-      remove_method :nested_list= if method_defined?(:nested_list=)
+    # Represents a single item within a list
+    #
+    # A list item can contain:
+    # - Simple text content
+    # - A nested list
+    # - Child elements (paragraphs, blocks, etc.)
+    #
+    # @example Simple list item
+    #   item = ListItem.new(
+    #     marker: "*",
+    #     content: "Item text"
+    #   )
+    #
+    # @example List item with nested list
+    #   item = ListItem.new(
+    #     marker: "*",
+    #     content: "Parent item",
+    #     nested_list: nested_list_block
+    #   )
+    class ListItem < Base
+      # @!attribute marker
+      #   @return [String, nil] the marker character(s) for this item
+      #     (e.g., '*', '**', '.', '..', '-')
+      attribute :marker, :string
+
+      # @!attribute content
+      #   @return [String, nil] text content of the list item
+      attribute :content, :string
+
+      # @!attribute nested_list
+      #   @return [ListBlock, nil] nested list within this item
+      attribute :nested_list, Coradoc::CoreModel::ListBlock
+
+      private
 
-      # Re-define with proper ListBlock type
-      attribute :nested_list, ListBlock
+      # Attributes to compare for semantic equivalence
+      #
+      # List items are semantically equivalent if they have the same
+      # content, nested list, and children, regardless of the specific
+      # marker used.
+      #
+      # @return [Array<Symbol>] list of comparable attributes
+      def comparable_attributes
+        %i[content nested_list children]
+      end
     end
   end
 end

data/lib/coradoc/errors.rb

@@ -295,6 +295,25 @@ module Coradoc
     end
   end
 
+  # Raised when a document still contains unresolved +include::+ edges
+  # at serialization time and the target format cannot represent them
+  # (it would silently drop the content). Resolve the graph first with
+  # +Coradoc.resolve_includes+, or opt out with
+  # +allow_unresolved_includes: true+.
+  class UnresolvedIncludesError < Error
+    attr_reader :targets
+
+    def initialize(targets)
+      @targets = targets
+      super(
+        "Document has #{targets.size} unresolved include directive(s): " \
+        "#{targets.join(', ')}. Resolve them before serializing with " \
+        'Coradoc.resolve_includes(doc, base_dir: ...), or pass ' \
+        'allow_unresolved_includes: true.'
+      )
+    end
+  end
+
   # Error raised when an include chain exceeds the configured depth limit.
   class IncludeDepthExceededError < Error
     attr_reader :depth, :target

data/lib/coradoc/format_module.rb

@@ -30,6 +30,16 @@ module Coradoc
         true
       end
 
+      # Whether the serializer can represent unresolved include edges
+      # (graph-mode CoreModel::Include nodes) without losing them.
+      # Formats that round-trip the directive natively (asciidoc,
+      # mirror) or preserve it explicitly (markdown comments) override
+      # this to true; formats that would silently drop the content keep
+      # the default false, and the pipeline raises instead of losing it.
+      def preserves_unresolved_includes?
+        false
+      end
+
       # Parse a file to CoreModel, handling file-specific concerns like include resolution.
       # Format modules that support include directives or file-relative references
       # should override this method.

data/lib/coradoc/pipeline.rb

@@ -46,6 +46,63 @@ module Coradoc
         Coradoc::LinkRewriter.rewrite(document, rewriter: rewriter, &)
       end
 
+      # Resolve every reference (xref, citation, link, include, image,
+      # footnote) in a parsed document using a unified content-graph
+      # model. Mirrors +resolve_includes+ in shape: two-step, immutable.
+      #
+      # Step one always runs: every Edge is resolved through the
+      # Resolver and the +missing+/+ambiguous+ policies are enforced
+      # (raise or warn). Step two is opt-in: with +materialize: true+
+      # the tree is rebuilt with each Edge replaced by the output of
+      # the Materializer registered for its
+      # [kind, presentation, format] tuple.
+      #
+      # The input document is never mutated. With +materialize: false+
+      # the input document itself is returned; with +materialize: true+
+      # a new document is returned that structurally shares untouched
+      # subtrees with the input (treat both as immutable). Nodes whose
+      # kind has no registered materializer are preserved unchanged.
+      #
+      # @param document [CoreModel::Base] parsed document
+      # @param catalog [Reference::Catalog::*] index of addressable Content
+      # @param presentation [Reference::Presentation::Base] slicing and ordering
+      # @param resolver [Reference::Resolver::Base, nil] defaults to CatalogResolver
+      # @param missing [Symbol] :warn (default), :silent, :error, :passthrough
+      # @param ambiguous [Symbol] :disambiguate (default), :first, :error
+      # @param materialize [Boolean] when true, replace edges with rendered inlines
+      # @param format [Symbol, nil] target format for materializer lookup
+      #   (:html, :asciidoc, ...); nil matches format-agnostic materializers
+      # @return [CoreModel::Base] the input document (validation only) or
+      #   a new materialized document
+      #
+      # @example Resolve cross-references into HTML links
+      #   doc = Coradoc.parse(text, format: :asciidoc)
+      #   catalog = Coradoc::Reference::Catalog::Local.from_doc(doc)
+      #   presentation = Coradoc::Reference::Presentation::SingleDocument.new
+      #   resolved = Coradoc.resolve_references(
+      #     doc,
+      #     catalog: catalog,
+      #     presentation: presentation,
+      #     materialize: true,
+      #     format: :html
+      #   )
+      def resolve_references(document, catalog:, presentation:,
+                             resolver: nil,
+                             missing: :warn,
+                             ambiguous: :disambiguate,
+                             materialize: false,
+                             format: nil)
+        Coradoc::Reference::Resolution.new(
+          catalog: catalog,
+          presentation: presentation,
+          resolver: resolver,
+          missing: missing,
+          ambiguous: ambiguous,
+          materialize: materialize,
+          format: format
+        ).call(document)
+      end
+
       def convert(text, from:, to:, **)
         core = parse(text, format: from)
         serialize(core, to: to, **)
@@ -63,10 +120,12 @@ module Coradoc
         raise TransformationError, "No transformer found for #{model.class}"
       end
 
-      def serialize(model, to:, **)
+      def serialize(model, to:, allow_unresolved_includes: false, **)
         format_module = FormatCatalog.get_format(to)
         raise UnsupportedFormatError.new(to, available: FormatCatalog.registered_formats) unless format_module
 
+        Coradoc::Validation.guard_unresolved_includes!(model, format_module) unless allow_unresolved_includes
+
         model = Hooks.invoke(:before_serialize, model, format: to)
         result = format_module.serialize(model, **)
         Hooks.invoke(:after_serialize, result, format: to)

data/lib/coradoc/reference/address/anchor.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Address < Lutaml::Model::Serializable
+      # In-document anchor — the most common navigation target.
+      # Matches raw strings starting with "#" plus bareword names that
+      # don't look like document IDs or external URLs.
+      #
+      #   "#intro"     => anchor target "intro"
+      #   "intro"      => anchor target "intro"
+      #   "footnote-1" => anchor target "footnote-1"
+      module Anchor
+        module_function
+
+        def scheme_name
+          :anchor
+        end
+
+        def matches?(raw)
+          return false if raw.nil? || raw.empty?
+
+          stripped = raw.to_s
+          return false if stripped == '#'
+          return true if stripped.start_with?('#')
+
+          stripped.match?(/\A[\w.\-]+\z/)
+        end
+
+        def parse(raw)
+          target = raw.to_s.delete_prefix('#')
+          new_address(target: target)
+        end
+
+        def serialize(address)
+          target = address.target
+          return '' if target.nil? || target.empty?
+
+          "##{target}"
+        end
+
+        def new_address(target:)
+          Address.new(scheme: 'anchor', target: target)
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/address/doi.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Address < Lutaml::Model::Serializable
+      # DOI — Digital Object Identifier. Regex per the DOI handbook.
+      module Doi
+        module_function
+
+        DOI_PATTERN = %r{\A(10\.\d{4,}/[^\s#]+)(?:#(.*))?\z}
+
+        def scheme_name
+          :doi
+        end
+
+        def matches?(raw)
+          return false if raw.nil? || raw.empty?
+
+          DOI_PATTERN.match?(raw.to_s)
+        end
+
+        def parse(raw)
+          match = DOI_PATTERN.match(raw.to_s)
+          raise Address::ParseError, "Invalid DOI: #{raw.inspect}" unless match
+
+          target = match[1]
+          fragment = match[2]
+          Address.new(scheme: 'doi', target: target, fragment: fragment)
+        end
+
+        def serialize(address)
+          base = address.target.to_s
+          return base unless address.fragment && !address.fragment.empty?
+
+          "#{base}##{address.fragment}"
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/address/isbn.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Address < Lutaml::Model::Serializable
+      # ISBN — book identifier. Recognizes an optional "ISBN" prefix
+      # (case insensitive) and either ISBN-10 or ISBN-13 digits. Bare
+      # numbers must be long enough to be ISBN-shaped so short numeric
+      # anchors are not claimed.
+      module Isbn
+        module_function
+
+        ISBN_PATTERN = /\A(?:ISBN\s+)?(\d[\d\-Xx]{8,16})\z/i
+
+        def scheme_name
+          :isbn
+        end
+
+        def matches?(raw)
+          return false if raw.nil? || raw.empty?
+
+          ISBN_PATTERN.match?(raw.to_s)
+        end
+
+        def parse(raw)
+          match = ISBN_PATTERN.match(raw.to_s)
+          raise Address::ParseError, "Invalid ISBN: #{raw.inspect}" unless match
+
+          target = match[1]
+          Address.new(scheme: 'isbn', target: target)
+        end
+
+        def serialize(address)
+          "ISBN #{address.target}"
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/address/path.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Address < Lutaml::Model::Serializable
+      # Inter-document path — a document identifier plus optional fragment.
+      # Matches document-ID-shaped barewords (uppercase + dash + digit,
+      # e.g. "ELF-5005-1") and relative/absolute file paths
+      # ("images/foo.png", "../shared/common.adoc"). Locality is carried
+      # in fragment.
+      #
+      #   "ELF-5005-1"          => path target "ELF-5005-1"
+      #   "ELF-5005-1#sec-3"    => path target "ELF-5005-1", fragment "sec-3"
+      #   "images/foo.png"      => path target "images/foo.png"
+      module Path
+        module_function
+
+        # Doc-ID pattern: uppercase-led bareword ("ELF-5005-1"). Used
+        # together with a separate digit scan — two linear passes, no
+        # ambiguous adjacent quantifiers (polynomial-ReDoS-safe).
+        DOC_ID_PATTERN = /\A[A-Z][A-Z0-9_\-]*\z/
+        # Loose pattern used by +parse+ when the scheme is already chosen
+        # (via hint). Accepts any non-empty target plus optional fragment.
+        LOOSE_PATTERN = /\A([^#]+)(?:#(.*))?\z/
+
+        def scheme_name
+          :path
+        end
+
+        def matches?(raw)
+          return false if raw.nil? || raw.empty?
+
+          value = raw.to_s
+          return true if value.include?('/')
+
+          # Document IDs are uppercase-led and contain at least one digit
+          # (what distinguishes them from anchors like "SECTION").
+          id_part = value.split('#', 2).first
+          DOC_ID_PATTERN.match?(id_part) && id_part.match?(/\d/)
+        end
+
+        def parse(raw)
+          match = LOOSE_PATTERN.match(raw.to_s)
+          raise Address::ParseError, "Invalid path: #{raw.inspect}" unless match
+
+          Address.new(
+            scheme: 'path',
+            target: match[1],
+            fragment: normalize_fragment(match[2])
+          )
+        end
+
+        def serialize(address)
+          base = address.target.to_s
+          return base unless address.fragment && !address.fragment.empty?
+
+          "#{base}##{address.fragment}"
+        end
+
+        def normalize_fragment(fragment)
+          fragment&.empty? ? nil : fragment
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/address/scoped_path.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Address < Lutaml::Model::Serializable
+      # Scoped path — a path within a collection's namespace. The scope
+      # identifies the collection (e.g. "ELF"); the target is the path
+      # inside it ("5005:1"); the fragment is locality within that doc.
+      #
+      #   "ELF:5005:1#sec-3"  => scope "ELF", target "5005:1", fragment "sec-3"
+      module ScopedPath
+        module_function
+
+        SCOPED_PATTERN = /\A([A-Z][A-Z0-9_\-]*):([\d:]+)(?:#(.*))?\z/
+
+        def scheme_name
+          :scoped_path
+        end
+
+        def matches?(raw)
+          return false if raw.nil? || raw.empty?
+
+          SCOPED_PATTERN.match?(raw.to_s)
+        end
+
+        def parse(raw)
+          match = SCOPED_PATTERN.match(raw.to_s)
+          raise Address::ParseError, "Invalid scoped path: #{raw.inspect}" unless match
+
+          Address.new(
+            scheme: 'scoped_path',
+            scope: match[1],
+            target: match[2],
+            fragment: match[3]
+          )
+        end
+
+        def serialize(address)
+          base = "#{address.scope}:#{address.target}"
+          return base unless address.fragment && !address.fragment.empty?
+
+          "#{base}##{address.fragment}"
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/address/url.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Address < Lutaml::Model::Serializable
+      # Absolute URL — anything with a recognized URL scheme prefix.
+      # Fragment is the optional "#..." suffix.
+      module Url
+        module_function
+
+        URL_PATTERN = %r{\A([a-z][a-z0-9+\-.]*)://([^#]+)(?:#(.*))?\z}i
+
+        def scheme_name
+          :url
+        end
+
+        def matches?(raw)
+          return false if raw.nil? || raw.empty?
+
+          URL_PATTERN.match?(raw.to_s)
+        end
+
+        def parse(raw)
+          match = URL_PATTERN.match(raw.to_s)
+          raise Address::ParseError, "Invalid URL: #{raw.inspect}" unless match
+
+          target = "#{match[1]}://#{match[2]}"
+          fragment = match[3]
+          Address.new(scheme: 'url', target: target, fragment: fragment)
+        end
+
+        def serialize(address)
+          base = address.target.to_s
+          return base unless address.fragment && !address.fragment.empty?
+
+          "#{base}##{address.fragment}"
+        end
+      end
+    end
+  end
+end