coradoc 2.0.27 → 2.0.29

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/registry.rb

@@ -102,24 +102,24 @@ module Coradoc
     #
     # @yield [Symbol, Object] name and item
     # @return [Enumerator]
-    def each(&block)
-      @items.each(&block)
+    def each(&)
+      @items.each(&)
     end
 
     # Iterate over item values
     #
     # @yield [Object]
     # @return [Enumerator]
-    def each_value(&block)
-      @items.each_value(&block)
+    def each_value(&)
+      @items.each_value(&)
     end
 
     # Iterate over item names
     #
     # @yield [Symbol]
     # @return [Enumerator]
-    def each_key(&block)
-      @items.each_key(&block)
+    def each_key(&)
+      @items.each_key(&)
     end
 
     # Find an item whose processor_match? returns true for the given filename

data/lib/coradoc/resolve_includes.rb

@@ -24,8 +24,8 @@ module Coradoc
     DEFAULT_MAX_DEPTH = 64
 
     class << self
-      def call(core, resolver:, base_dir:, **opts)
-        new(resolver: resolver, base_dir: base_dir, **opts).call(core)
+      def call(core, resolver:, base_dir:, **)
+        new(resolver: resolver, base_dir: base_dir, **).call(core)
       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
@@ -600,8 +640,8 @@ module Coradoc
       #
       # @yield Schema definition block
       # @return [Schema] The defined schema
-      def define(&block)
-        Schema.define(&block)
+      def define(&)
+        Schema.define(&)
       end
 
       # Generate a validation schema from a CoreModel class
@@ -614,8 +654,8 @@ module Coradoc
       #   schema = Coradoc::Validation.auto_schema(Coradoc::CoreModel::Block)
       #   result = schema.validate(document)
       #
-      def auto_schema(model_class, **options)
-        SchemaGenerator.generate(model_class, **options)
+      def auto_schema(model_class, **)
+        SchemaGenerator.generate(model_class, **)
       end
 
       # Validate a document with default schema

data/lib/coradoc/version.rb

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

data/lib/coradoc.rb

@@ -30,9 +30,9 @@
 #   Coradoc.serialize(doc, to: :html)
 
 require_relative 'coradoc/coradoc'
-require_relative 'coradoc/version'
 
 module Coradoc
+  autoload :VERSION, 'coradoc/version'
   autoload :CLI, 'coradoc/cli'
   autoload :Visitor, 'coradoc/visitor'
   autoload :LinkRewriter, 'coradoc/link_rewriter'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coradoc
 version: !ruby/object:Gem::Version
-  version: 2.0.27
+  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
@@ -144,6 +187,7 @@ metadata:
   homepage_uri: https://github.com/lutaml/coradoc
   source_code_uri: https://github.com/lutaml/coradoc
   changelog_uri: https://github.com/lutaml/coradoc/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib