coradoc 2.0.28 → 2.0.30

data/lib/coradoc/reference/resolution.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    # Orchestrator: resolves every Edge in the tree via the Resolver,
+    # enforces the missing/ambiguous policies, and — only when asked
+    # to materialize — rebuilds the tree with rendered inline nodes
+    # via the Presentation layout and the Materializer registry.
+    #
+    # Two-step contract:
+    # - +materialize: false+ validates references and returns the
+    #   INPUT document (never mutated, never copied).
+    # - +materialize: true+ returns a NEW document. Untouched subtrees
+    #   are shared with the input (structural sharing) — treat both as
+    #   immutable.
+    #
+    # Wired from the public API +Coradoc.resolve_references+.
+    class Resolution
+      attr_reader :catalog, :presentation, :resolver, :missing_policy,
+                  :ambiguous_policy, :materialize_policy, :format,
+                  :materializer_registry
+
+      def initialize(catalog:, presentation:, missing:, ambiguous:,
+                     materialize:, resolver: nil, format: nil,
+                     materializer_registry: default_registry)
+        @catalog = catalog
+        @presentation = presentation
+        @missing_policy = missing
+        @ambiguous_policy = ambiguous
+        @materialize_policy = materialize
+        @format = format
+        @materializer_registry = materializer_registry
+        @resolver = resolver || Resolver::Catalog.new(
+          catalog: catalog, ambiguous: ambiguous, missing: missing
+        )
+      end
+
+      def call(document)
+        results = resolve_all_edges(document)
+        report_missing(results)
+        return document unless materialize_policy
+
+        materialize_tree(document, results)
+      end
+
+      private
+
+      # Keyed by the Edge itself (value equality), so every distinct
+      # edge gets its own Result while identical edges resolve once.
+      def resolve_all_edges(document)
+        results = {}
+        EdgeSearch.each_edge(document) do |_parent, edge|
+          results[edge] = resolver.resolve(edge)
+        end
+        results
+      end
+
+      def report_missing(results)
+        results.each_value do |result|
+          next unless result.missing?
+
+          case missing_policy
+          when :error
+            raise Coradoc::Reference::MissingReferenceError.new(
+              address: result.address
+            )
+          when :warn
+            Coradoc::Logger.warn("Reference not found: #{result.address}")
+          end
+        end
+      end
+
+      def materialize_tree(document, results)
+        pages = presentation.layout(document)
+        ReplaceWalker.new(
+          pages: pages,
+          results: results,
+          presentation: presentation,
+          registry: materializer_registry,
+          missing_policy: missing_policy,
+          format: format
+        ).visit(document)
+      end
+
+      def default_registry
+        Materializer::Registry.new
+      end
+
+      # Rebuilds the tree, replacing every Edge-bearing node with the
+      # materializer's output. The walker is single-purpose and only
+      # lives inside Resolution — no need for a separate file.
+      class ReplaceWalker
+        attr_reader :pages, :results, :presentation, :registry,
+                    :missing_policy, :format
+
+        def initialize(pages:, results:, presentation:, registry:,
+                       missing_policy:, format:)
+          @pages = pages
+          @results = results
+          @presentation = presentation
+          @registry = registry
+          @missing_policy = missing_policy
+          @format = format
+        end
+
+        def visit(node)
+          return node unless node.is_a?(Coradoc::CoreModel::Base)
+
+          replaced = replace_node(node)
+          return replaced unless replaced.is_a?(Coradoc::CoreModel::HasChildren)
+
+          rebuild_children_of(replaced)
+        end
+
+        private
+
+        def replace_node(node)
+          edges = EdgeSearch.edges_for(node)
+          return node if edges.empty?
+
+          materialize_edge(node, edges.first)
+        end
+
+        def materialize_edge(node, edge)
+          result = results[edge]
+          return drop_or_keep(node) if result.nil? || result.missing?
+
+          invoke_materializer(node, edge, result)
+        end
+
+        # :silent drops the unresolved node; :warn (already logged) and
+        # :passthrough keep the original node so round-tripping is safe.
+        def drop_or_keep(node)
+          return nil if missing_policy == :silent
+
+          node
+        end
+
+        def invoke_materializer(node, edge, result)
+          klass = lookup_materializer(edge)
+          return node unless klass
+
+          klass.new.materialize(
+            edge: edge,
+            result: result,
+            node: node,
+            presentation: presentation,
+            pages: pages
+          )
+        end
+
+        def lookup_materializer(edge)
+          registry.lookup(
+            kind: edge.kind.to_sym,
+            presentation: presentation.key,
+            format: format || :any
+          )
+        end
+
+        def rebuild_children_of(node)
+          children = node.children
+          return node unless children
+          return node if children.empty?
+
+          new_children = children.filter_map { |c| visit(c) }
+          rebuild_with(node, new_children)
+        end
+
+        def rebuild_with(node, new_children)
+          return node if identical_children?(new_children, node.children)
+
+          duplicate = node.dup
+          duplicate.children = new_children
+          duplicate
+        end
+
+        def identical_children?(new_children, old_children)
+          new_children.length == old_children.length &&
+            new_children.each_with_index.all? { |c, i| c.equal?(old_children[i]) }
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/resolver/base.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Resolver
+      # Protocol base. Concrete resolvers implement +#resolve(edge)+
+      # and return a Result sum type instance — never +nil+.
+      class Base
+        def resolve(edge)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/resolver/caching.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Resolver
+      # Wraps another resolver with an address-keyed memoization cache.
+      # Addresses are value types, so cache keys are stable across calls.
+      # Use to avoid re-asking the catalog for the same Edge.address.
+      class Caching < Resolver::Base
+        attr_reader :inner
+
+        def initialize(inner:)
+          super()
+          @inner = inner
+          @cache = {}
+        end
+
+        def resolve(edge)
+          cached = if @cache.key?(edge.address)
+                     @cache[edge.address]
+                   else
+                     @cache[edge.address] = @inner.resolve(edge)
+                   end
+          cached.for_edge(edge)
+        end
+
+        def clear!
+          @cache.clear
+        end
+
+        def size
+          @cache.size
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Resolver
+      # Asks one catalog. Applies the +ambiguous:+ policy in-line.
+      # Does NOT apply the +missing:+ policy — that's the caller's
+      # call (Resolution orchestrator) — but it does surface the
+      # Missing Result so the caller can decide.
+      class Catalog < Resolver::Base
+        attr_reader :catalog, :ambiguous_policy, :missing_policy
+
+        def initialize(catalog:, ambiguous: :disambiguate, missing: :warn)
+          super()
+          @catalog = catalog
+          @ambiguous_policy = ambiguous
+          @missing_policy = missing
+        end
+
+        def resolve(edge)
+          address = edge.address
+          return missing_for(edge, address) unless catalog.recognizes_scheme?(address.scheme)
+
+          result = catalog.lookup(address)
+          return missing_for(edge, address) if result.nil?
+
+          return resolved_for(edge, address, result) unless result.is_a?(Array)
+
+          resolve_ambiguous(edge, address, result)
+        end
+
+        private
+
+        def resolved_for(edge, address, target)
+          Coradoc::Reference::Result::Resolved.build(
+            edge: edge, address: address, target: target
+          )
+        end
+
+        def resolve_ambiguous(edge, address, candidates)
+          return ambiguous_error(address, candidates) if ambiguous_policy == :error
+          return resolved_for(edge, address, candidates.first) if ambiguous_policy == :first
+
+          # :disambiguate — warn, then deterministically take the first
+          Coradoc::Logger.warn(
+            "Reference #{address} is ambiguous " \
+            "(#{candidates.size} candidates); using first"
+          )
+          resolved_for(edge, address, candidates.first)
+        end
+
+        def ambiguous_error(address, candidates)
+          raise Coradoc::Reference::AmbiguousReferenceError,
+                "Address #{address} matched #{candidates.size} candidates"
+        end
+
+        def missing_for(edge, address)
+          case missing_policy
+          when :error
+            raise Coradoc::Reference::MissingReferenceError,
+                  "Address #{address} not found"
+          else
+            Coradoc::Reference::Result::Missing.build(edge: edge, address: address)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/resolver/chain.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Resolver
+      # Tries each child resolver in order. First non-Missing result
+      # wins (Resolved or Ambiguous short-circuit). Use to combine a
+      # local catalog with a remote one without composite catalog
+      # indirection.
+      class Chain < Resolver::Base
+        attr_reader :resolvers
+
+        def initialize(*resolvers)
+          super()
+          @resolvers = resolvers.flatten
+        end
+
+        def resolve(edge)
+          last = nil
+          @resolvers.each do |resolver|
+            result = resolver.resolve(edge)
+            return result unless result.is_a?(Coradoc::Reference::Result::Missing)
+
+            last = result
+          end
+          last || Coradoc::Reference::Result::Missing.build(
+            edge: edge, address: edge.address
+          )
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/resolver.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    # Kind-agnostic resolver: given an Edge, ask the catalog, return a
+    # Result. Never materializes, never slices, never orders.
+    #
+    #   resolver = Resolver::Catalog.new(catalog: catalog, ambiguous: :first, missing: :warn)
+    #   case resolver.resolve(edge)
+    #   in Result::Resolved => r ; use_target(r.target)
+    #   in Result::Missing   ; warn("could not resolve #{edge.address}")
+    #   end
+    module Resolver
+      autoload :Base, "#{__dir__}/resolver/base"
+      autoload :Catalog, "#{__dir__}/resolver/catalog"
+      autoload :Chain, "#{__dir__}/resolver/chain"
+      autoload :Caching, "#{__dir__}/resolver/caching"
+    end
+  end
+end

data/lib/coradoc/reference/result/ambiguous.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Result
+      # Multiple candidates matched. The catalog returned an Array.
+      # Callers' +ambiguous:+ policy decides what to do.
+      class Ambiguous < Base
+        attribute :candidates, Coradoc::CoreModel::Base, collection: true
+
+        def self.build(edge:, address:, candidates:)
+          new(edge: edge, address: address, candidates: candidates)
+        end
+
+        private
+
+        def result_data
+          { candidates: candidates }
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/result/base.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Coradoc
+  module Reference
+    module Result
+      # Base class for resolution outcomes. Subclasses are value types.
+      # Every Result carries the Edge that asked — so callers can log,
+      # trace, and re-route without re-resolving.
+      class Base < Lutaml::Model::Serializable
+        attribute :edge, Coradoc::Reference::Edge
+        attribute :address, Coradoc::Reference::Address
+
+        def resolved?
+          is_a?(Result::Resolved)
+        end
+
+        def ambiguous?
+          is_a?(Result::Ambiguous)
+        end
+
+        def missing?
+          is_a?(Result::Missing)
+        end
+
+        # This Result as seen by +edge+. Returns self when the edge is
+        # value-equal to the one embedded; otherwise rebuilds the same
+        # outcome (target/candidates preserved) for the asking edge.
+        # Used by caching resolvers so two edges sharing an Address
+        # never see each other's identity.
+        def for_edge(edge)
+          return self if self.edge == edge
+
+          self.class.build(edge: edge, address: address, **result_data)
+        end
+
+        private
+
+        def result_data
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/result/missing.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Result
+      # No catalog knows this address. Caller's +missing:+ policy decides.
+      class Missing < Base
+        def self.build(edge:, address:)
+          new(edge: edge, address: address)
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/result/resolved.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Result
+      # Catalog knew the address; exactly one Content was returned.
+      class Resolved < Base
+        attribute :target, Coradoc::CoreModel::Base
+
+        def self.build(edge:, address:, target:)
+          new(edge: edge, address: address, target: target)
+        end
+
+        private
+
+        def result_data
+          { target: target }
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/result.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    # Sum type for resolution outcomes. Callers pattern-match on the
+    # concrete subclass — never check +nil+.
+    #
+    #   case resolver.resolve(edge)
+    #   in Result::Resolved => r   # have the target
+    #   in Result::Ambiguous => a  # multiple candidates
+    #   in Result::Missing => m    # catalog does not know
+    #   end
+    module Result
+      autoload :Base, "#{__dir__}/result/base"
+      autoload :Resolved, "#{__dir__}/result/resolved"
+      autoload :Ambiguous, "#{__dir__}/result/ambiguous"
+      autoload :Missing, "#{__dir__}/result/missing"
+    end
+  end
+end

data/lib/coradoc/reference.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'coradoc/errors'
+
+module Coradoc
+  # Unified content-graph reference resolution.
+  #
+  # Every referenceable thing in a document is a Content node; every
+  # reference is a directed Edge with a kind. The four primitives:
+  #
+  #   Content             — CoreModel::Base with an id (already on Base).
+  #   Document            — Content that contains Content (composite).
+  #   Reference::Edge     — directed {source Content, target Address, kind}.
+  #   Reference::Address  — scheme-aware locator (anchor, path, url, ...).
+  #
+  # Same Content graph → N Presentations → M Materializers. The public
+  # entry point is +Coradoc.resolve_references+.
+  module Reference
+    # Base class for reference-resolution errors. All subclasses inherit
+    # from here so callers can rescue the family with one +rescue+ clause.
+    class Error < Coradoc::Error; end
+
+    # Raised when no catalog knew the requested Address and the
+    # +missing:+ policy is :error.
+    class MissingReferenceError < Error
+      attr_reader :address
+
+      def initialize(message = nil, address: nil)
+        @address = address
+        super(message || "Reference not found: #{address}")
+      end
+    end
+
+    # Raised when multiple catalogs matched an Address and the
+    # +ambiguous:+ policy is :error.
+    class AmbiguousReferenceError < Error
+      attr_reader :address, :candidates
+
+      def initialize(message = nil, address: nil, candidates: nil)
+        @address = address
+        @candidates = candidates
+        super(message || "Reference is ambiguous: #{address}")
+      end
+    end
+
+    # Raised when the catalog index is malformed — a programmer
+    # error, not a runtime condition. Surfaces as a clear message
+    # rather than a vague NoMethodError.
+    class InvalidCatalogError < Error; end
+
+    # Raised when building an Edge whose kind was never registered.
+    # External kinds register via +Edge.register_kind+ (OCP).
+    class UnknownKindError < Error; end
+
+    autoload :Address, "#{__dir__}/reference/address"
+    autoload :Edge, "#{__dir__}/reference/edge"
+    autoload :Catalog, "#{__dir__}/reference/catalog"
+    autoload :Result, "#{__dir__}/reference/result"
+    autoload :Resolver, "#{__dir__}/reference/resolver"
+    autoload :Presentation, "#{__dir__}/reference/presentation"
+    autoload :Materializer, "#{__dir__}/reference/materializer"
+    autoload :EdgeSearch, "#{__dir__}/reference/edge_search"
+    autoload :Resolution, "#{__dir__}/reference/resolution"
+  end
+end

data/lib/coradoc/validation.rb

@@ -28,6 +28,46 @@ module Coradoc
   #   end
   #
   module Validation
+    module_function
+
+    # Targets of every unresolved +include::+ edge in the tree
+    # (deduplicated, in document order). A document is "unresolved"
+    # when it was parsed in graph mode and never went through
+    # +Coradoc.resolve_includes+.
+    def unresolved_include_targets(model)
+      targets = []
+      walk_nodes(model) do |node|
+        targets << node.target if node.is_a?(Coradoc::CoreModel::Include)
+      end
+      targets.uniq
+    end
+
+    # Serialization boundary check: formats that cannot represent an
+    # unresolved include edge (FormatModule::Interface
+    # #preserves_unresolved_includes? == false) must not silently drop
+    # the content — raise UnresolvedIncludesError instead, pointing at
+    # the hydration step (resolve_includes).
+    def guard_unresolved_includes!(model, format_module)
+      return if format_module.preserves_unresolved_includes?
+
+      targets = unresolved_include_targets(model)
+      return if targets.empty?
+
+      raise Coradoc::UnresolvedIncludesError, targets
+    end
+
+    def walk_nodes(node, &block)
+      return unless node.is_a?(Coradoc::CoreModel::Base)
+
+      yield node
+      return unless node.is_a?(Coradoc::CoreModel::HasChildren)
+
+      children = node.children
+      return unless children
+
+      children.each { |child| walk_nodes(child, &block) }
+    end
+
     # A single validation error
     class Error
       attr_reader :path, :message, :code, :element

data/lib/coradoc/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coradoc
 version: !ruby/object:Gem::Version
-  version: 2.0.28
+  version: 2.0.30
 platform: ruby
 authors:
 - Ribose Inc.
@@ -131,6 +131,49 @@ files:
 - lib/coradoc/performance_regression.rb
 - lib/coradoc/pipeline.rb
 - lib/coradoc/query.rb
+- lib/coradoc/reference.rb
+- lib/coradoc/reference/address.rb
+- lib/coradoc/reference/address/anchor.rb
+- lib/coradoc/reference/address/doi.rb
+- lib/coradoc/reference/address/isbn.rb
+- lib/coradoc/reference/address/path.rb
+- lib/coradoc/reference/address/scoped_path.rb
+- lib/coradoc/reference/address/url.rb
+- lib/coradoc/reference/catalog.rb
+- lib/coradoc/reference/catalog/composite.rb
+- lib/coradoc/reference/catalog/local.rb
+- lib/coradoc/reference/catalog/memory_index.rb
+- lib/coradoc/reference/edge.rb
+- lib/coradoc/reference/edge/citation_options.rb
+- lib/coradoc/reference/edge/footnote_ref_options.rb
+- lib/coradoc/reference/edge/image_ref_options.rb
+- lib/coradoc/reference/edge/include_options.rb
+- lib/coradoc/reference/edge/kind.rb
+- lib/coradoc/reference/edge/link_options.rb
+- lib/coradoc/reference/edge/navigation_options.rb
+- lib/coradoc/reference/edge/options.rb
+- lib/coradoc/reference/edge_search.rb
+- lib/coradoc/reference/materializer.rb
+- lib/coradoc/reference/materializer/base.rb
+- lib/coradoc/reference/materializer/passthrough.rb
+- lib/coradoc/reference/materializer/registry.rb
+- lib/coradoc/reference/presentation.rb
+- lib/coradoc/reference/presentation/base.rb
+- lib/coradoc/reference/presentation/custom_hierarchy.rb
+- lib/coradoc/reference/presentation/page.rb
+- lib/coradoc/reference/presentation/single_document.rb
+- lib/coradoc/reference/presentation/split_pages.rb
+- lib/coradoc/reference/resolution.rb
+- lib/coradoc/reference/resolver.rb
+- lib/coradoc/reference/resolver/base.rb
+- lib/coradoc/reference/resolver/caching.rb
+- lib/coradoc/reference/resolver/catalog.rb
+- lib/coradoc/reference/resolver/chain.rb
+- lib/coradoc/reference/result.rb
+- lib/coradoc/reference/result/ambiguous.rb
+- lib/coradoc/reference/result/base.rb
+- lib/coradoc/reference/result/missing.rb
+- lib/coradoc/reference/result/resolved.rb
 - lib/coradoc/registry.rb
 - lib/coradoc/relative_path.rb
 - lib/coradoc/resolve_includes.rb