coradoc 2.0.28 → 2.0.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f0dbc8feba7133bc83baf88a6458774f364f7266b79625a0afc50434beeac89
-  data.tar.gz: f4fe999b18666604d2b615545acb073e1b6f74d7b26c3ff8fa8fd403ee45ec5d
+  metadata.gz: 72d8a4fe9a86a7ed8f5dc806492ea147f321367f7a470b3c934747de9ea2b305
+  data.tar.gz: '042824f44538b6b64252c0667eb8d56f2ed059de0dab8866631c84394bee6a64'
 SHA512:
-  metadata.gz: c4c0f7a479cfdf622faa4a26cad085c60b4e943d3ba30348e5d0426ebb10c9fbd417ceb5d069225f1e72dd9ff0960ca5e5304572d6d6cf4018236a579c4c391c
-  data.tar.gz: 6e4e649b83732a5cbf77c1edf16c70fb04a167d2d3b7ad3c3c657a029ebea5b079408dc78641f432241ac8737afb2a46fc1d3b6e2113c01075c332c2efadde9e
+  metadata.gz: 6a603de0773f6b27449ccb511c3ec53860e6ec37aeb55a62f63f5902b7d0c4c0e74c5681dd1749b5f09411bd04ca34ff7bca45e4da4f9e8d4bd74f4cec3972b9
+  data.tar.gz: ebbc0d4ae30878f6793964a437dfd62a0ba79aafdfa57f3307d6e0b5c865650627bb6f025aa94f2c18813b16973819e3358a1458eecd3d6d9db5ac47af99efb8

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/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

data/lib/coradoc/reference/address.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Coradoc
+  module Reference
+    # Scheme-aware locator targeting a Content node.
+    #
+    # An Address is one of six built-in schemes — +:anchor+, +:path+,
+    # +:scoped_path+, +:url+, +:doi+, +:isbn+ — selected by heuristic on
+    # parse or by an explicit +hint:+. External gems register additional
+    # schemes via +Address.register_scheme+ (OCP).
+    #
+    #   Address.parse("foo")               # => anchor "foo"
+    #   Address.parse("ELF-5005-1#sec-3")  # => path "ELF-5005-1", fragment "sec-3"
+    #   Address.parse("ELF:5005:1#sec-3")  # => scoped_path scope "ELF"
+    #   Address.parse("https://x.y/z")     # => url
+    #   Address.parse("10.1234/abc")       # => doi
+    #   Address.parse("ISBN 978-1-2-3")    # => isbn
+    #
+    # Addresses are value types: two addresses are equal iff every
+    # attribute matches. Round-trip via +to_s+.
+    class Address < Lutaml::Model::Serializable
+      class ParseError < Coradoc::Reference::Error; end
+      class UnknownSchemeError < Coradoc::Reference::Error; end
+
+      attribute :scheme, :string
+      attribute :target, :string
+      attribute :fragment, :string
+      attribute :scope, :string
+
+      autoload :Url, "#{__dir__}/address/url"
+      autoload :Doi, "#{__dir__}/address/doi"
+      autoload :Isbn, "#{__dir__}/address/isbn"
+      autoload :ScopedPath, "#{__dir__}/address/scoped_path"
+      autoload :Path, "#{__dir__}/address/path"
+      autoload :Anchor, "#{__dir__}/address/anchor"
+
+      BUILTIN_SCHEME_ORDER = %i[url doi isbn scoped_path path anchor].freeze
+
+      class << self
+        def parse(raw, hint: nil)
+          Scheme.ensure_builtins_registered!
+          mod = hint ? scheme_for_hint!(hint) : Scheme.match(raw)
+          unless mod
+            raise ParseError,
+                  "Cannot determine address scheme for #{raw.inspect}"
+          end
+          mod.parse(raw)
+        end
+
+        def register_scheme(mod)
+          Scheme.register(mod)
+        end
+
+        def scheme_names
+          Scheme.ensure_builtins_registered!
+          Scheme.names
+        end
+
+        private
+
+        def scheme_for_hint!(hint)
+          Scheme.for(hint) ||
+            raise(UnknownSchemeError,
+                  "Unknown address scheme #{hint.inspect}. " \
+                  "Registered: #{Scheme.names.inspect}")
+        end
+      end
+
+      # Value equality (==/eql?/hash) comes from Lutaml::Model — all
+      # attributes compared, class-aware, safe as Hash keys.
+
+      def to_s
+        Scheme.ensure_builtins_registered!
+        mod = Scheme.for(scheme)
+        unless mod
+          raise UnknownSchemeError,
+                "No registered scheme for #{scheme.inspect}. " \
+                "Registered: #{Scheme.names.inspect}"
+        end
+        mod.serialize(self)
+      end
+
+      # Registry of scheme modules. Each module provides:
+      #   scheme_name      -> Symbol
+      #   matches?(raw)    -> Boolean
+      #   parse(raw)       -> Address
+      #   serialize(addr)  -> String
+      #
+      # +register+ always forces builtin registration first, so an
+      # external scheme registered before first use is never clobbered
+      # by the lazy builtin pass. The catch-all anchor scheme is always
+      # tried LAST on match, so external schemes are never shadowed by
+      # it no matter when they register.
+      module Scheme
+        @registered = []
+        @builtins_registered = false
+        @registering_builtins = false
+
+        CATCH_ALL_SCHEME = :anchor
+        private_constant :CATCH_ALL_SCHEME
+
+        MUTEX = Mutex.new
+        private_constant :MUTEX
+
+        class << self
+          def register(mod)
+            ensure_builtins_registered! unless @registering_builtins
+            @registered.delete_if { |m| m.scheme_name == mod.scheme_name }
+            @registered << mod
+          end
+
+          def names
+            @registered.map(&:scheme_name)
+          end
+
+          def for(name)
+            @registered.find { |m| m.scheme_name == name.to_sym }
+          end
+
+          def match(raw)
+            catch_all, specific =
+              @registered.partition { |m| m.scheme_name == CATCH_ALL_SCHEME }
+            (specific + catch_all).find { |m| m.matches?(raw) }
+          end
+
+          def ensure_builtins_registered!
+            MUTEX.synchronize do
+              return if @builtins_registered
+
+              @registering_builtins = true
+              begin
+                BUILTIN_SCHEME_ORDER.each do |name|
+                  const_name = name.to_s.split('_').map(&:capitalize).join
+                  register(Address.const_get(const_name))
+                end
+                @builtins_registered = true
+              ensure
+                @registering_builtins = false
+              end
+            end
+          end
+
+          def reset!
+            @registered.clear
+            @builtins_registered = false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/catalog/composite.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Catalog
+      # Composes multiple catalogs. Lookup asks EVERY child and merges
+      # the hits: exactly one hit returns the Content; several hits
+      # return an Array (which the Resolver surfaces per the
+      # +ambiguous:+ policy). Precedence between catalogs is a
+      # resolver/policy concern, not a lookup concern:
+      #
+      #   Composite.new(
+      #     Local.from_doc(doc),
+      #     Collection.from_manifest(...),
+      #     Remote.new(client: http_client)
+      #   )
+      class Composite
+        include Catalog::Protocol
+
+        attr_reader :children
+
+        def initialize(*children)
+          @children = children.flatten
+        end
+
+        def lookup(address)
+          results = []
+          children.each do |catalog|
+            result = catalog.lookup(address)
+            next if result.nil?
+
+            results.concat(Array(result))
+          end
+          return nil if results.empty?
+          return results.first if results.size == 1
+
+          results
+        end
+
+        def ambiguous?(address)
+          result = lookup(address)
+          result.is_a?(Array) && result.size > 1
+        end
+
+        def each_pair(&block)
+          return to_enum(:each_pair) unless block_given?
+
+          children.each do |catalog|
+            catalog.each_pair(&block)
+          end
+        end
+
+        def recognizes_scheme?(scheme)
+          children.any? { |catalog| catalog.recognizes_scheme?(scheme) }
+        end
+      end
+    end
+  end
+end