coradoc 2.0.28 → 2.0.29

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.29'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coradoc
 version: !ruby/object:Gem::Version
-  version: 2.0.28
+  version: 2.0.29
 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