coradoc 2.0.27 → 2.0.29

data/lib/coradoc/reference/presentation/custom_hierarchy.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Presentation
+      # Caller-supplied hierarchy. The user provides a tree of node ids
+      # mapping to pages; the presentation lays out content accordingly.
+      # This is the presentation website builds use.
+      #
+      #   CustomHierarchy.new(hierarchy: [
+      #     { id: "intro", title: "Introduction", children: [...] },
+      #     { id: "chap1", title: "Chapter 1", children: [
+      #       { id: "chap1-1", title: "1.1" }
+      #     ] }
+      #   ])
+      class CustomHierarchy < Base
+        attr_reader :hierarchy
+
+        def self.key
+          :custom_hierarchy
+        end
+
+        def initialize(hierarchy:)
+          super()
+          @hierarchy = normalize_hierarchy(hierarchy)
+        end
+
+        def layout(resolved_graph)
+          pages = []
+          walk_hierarchy(@hierarchy, parent_id: nil, pages: pages, root: resolved_graph)
+          pages
+        end
+
+        def locate_page(_edge, target_content, pages:)
+          pages.find { |page| page.content.equal?(target_content) }
+        end
+
+        private
+
+        def normalize_hierarchy(tree)
+          Array(tree).map do |entry|
+            entry.merge(children: normalize_hierarchy(entry[:children]))
+          end
+        end
+
+        def walk_hierarchy(nodes, parent_id:, pages:, root:)
+          nodes.each do |entry|
+            content = find_content_by_id(root, entry[:id]) || root
+            pages << Page.new(
+              id: entry[:id],
+              title: entry[:title] || content.title,
+              content: content,
+              parent_id: parent_id,
+              order: pages.size
+            )
+            walk_hierarchy(entry[:children], parent_id: entry[:id], pages: pages, root: root)
+          end
+        end
+
+        def find_content_by_id(root, id)
+          return nil unless id
+
+          visitor = VisitorById.new(id)
+          visitor.visit(root)
+          visitor.found
+        end
+
+        # Single-purpose visitor: walks a CoreModel tree looking for
+        # one node by id. Cleaner than a recursive method on the
+        # presentation class itself.
+        class VisitorById
+          attr_reader :found
+
+          def initialize(target_id)
+            @target_id = target_id
+            @found = nil
+          end
+
+          def visit(node)
+            return @found if @found
+            return unless node.is_a?(Coradoc::CoreModel::Base)
+
+            @found = node if node.id == @target_id
+            return if @found
+
+            visit_children(node)
+          end
+
+          private
+
+          def visit_children(node)
+            return unless node.is_a?(Coradoc::CoreModel::HasChildren)
+
+            children = node.children
+            return unless children
+
+            children.each { |c| visit(c) }
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/presentation/page.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Coradoc
+  module Reference
+    module Presentation
+      # A page is the unit of output a Presentation produces. One HTML
+      # file, one PDF page, one EPUB chapter — same data, different
+      # materialization. The Materializer consumes Pages.
+      class Page < Lutaml::Model::Serializable
+        attribute :id, :string
+        attribute :title, :string
+        attribute :content, Coradoc::CoreModel::Base
+        attribute :parent_id, :string
+        attribute :order, :integer
+      end
+    end
+  end
+end

data/lib/coradoc/reference/presentation/single_document.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Presentation
+      # One page = the whole document. Use for fixed-structure output
+      # (single HTML, single PDF, EPUB chapter). Cross-references
+      # always resolve to the single page.
+      class SingleDocument < Base
+        def self.key
+          :single_document
+        end
+
+        def layout(resolved_graph)
+          [Page.new(
+            id: page_id_for(resolved_graph),
+            title: resolved_graph.title,
+            content: resolved_graph,
+            order: 0
+          )]
+        end
+
+        def locate_page(_edge, _target_content, pages:)
+          pages.first
+        end
+
+        private
+
+        def page_id_for(node)
+          node.id || 'root'
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/presentation/split_pages.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Presentation
+      # Splits the document by top-level section (or a configurable
+      # boundary). Each section becomes a Page. Cross-references are
+      # rewritten to point at whichever page the target content lives on.
+      #
+      #   SplitPages.new(split_at: :section)  # default
+      #   SplitPages.new(split_at: :chapter) # HeaderElement only
+      class SplitPages < Base
+        attr_reader :split_at
+
+        def self.key
+          :split_pages
+        end
+
+        def initialize(split_at: :section)
+          super()
+          @split_at = split_at.to_sym
+          @page_index = nil
+        end
+
+        def layout(resolved_graph)
+          children = read_children(resolved_graph)
+          return [single_page_for(resolved_graph)] if children.nil? || children.empty?
+
+          sections = children.select { |child| matches_split?(child) }
+          return [single_page_for(resolved_graph)] if sections.empty?
+
+          pages = sections.map.with_index { |section, idx| page_for(section, resolved_graph, idx) }
+          index_pages!(pages)
+          pages
+        end
+
+        def locate_page(_edge, target_content, pages:)
+          indexed = @page_index&.[](target_content)
+          return indexed if indexed
+
+          pages.find { |page| owns_target?(page, target_content) }
+        end
+
+        private
+
+        # O(1) target→page lookup, built once per layout instead of
+        # rescanning every page subtree per edge.
+        def index_pages!(pages)
+          @page_index = {}.compare_by_identity
+          pages.each { |page| index_node!(page.content, page) }
+        end
+
+        def index_node!(node, page)
+          @page_index[node] = page
+          return unless node.is_a?(Coradoc::CoreModel::HasChildren)
+
+          children = node.children
+          return unless children
+
+          children.each { |child| index_node!(child, page) }
+        end
+
+        def page_for(section, parent, idx)
+          Page.new(
+            id: section.id || "page-#{idx}",
+            title: section.title || "Page #{idx}",
+            content: section,
+            parent_id: parent.id,
+            order: idx
+          )
+        end
+
+        def read_children(node)
+          return nil unless node.is_a?(Coradoc::CoreModel::HasChildren)
+
+          node.children
+        end
+
+        def matches_split?(node)
+          return false unless node.is_a?(Coradoc::CoreModel::StructuralElement)
+
+          klass = boundary_class
+          node.is_a?(klass)
+        end
+
+        def boundary_class
+          split_at == :chapter ? Coradoc::CoreModel::HeaderElement : Coradoc::CoreModel::SectionElement
+        end
+
+        def single_page_for(node)
+          Page.new(
+            id: node.id || 'root',
+            title: node.title,
+            content: node,
+            order: 0
+          )
+        end
+
+        def owns_target?(page, target)
+          return true if page.content.equal?(target)
+
+          descendant_of?(page.content, target)
+        end
+
+        def descendant_of?(ancestor, target)
+          return false unless ancestor.is_a?(Coradoc::CoreModel::HasChildren)
+
+          children = ancestor.children
+          return false unless children
+
+          children.any? do |child|
+            child.equal?(target) || descendant_of?(child, target)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/presentation.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    # Model-View boundary. Same Content graph → N Presentations. A
+    # Presentation defines slicing, page boundaries, ordering, and
+    # hierarchy — never the rendering (that's the Materializer's job).
+    module Presentation
+      autoload :Base, "#{__dir__}/presentation/base"
+      autoload :Page, "#{__dir__}/presentation/page"
+      autoload :SingleDocument, "#{__dir__}/presentation/single_document"
+      autoload :SplitPages, "#{__dir__}/presentation/split_pages"
+      autoload :CustomHierarchy, "#{__dir__}/presentation/custom_hierarchy"
+    end
+  end
+end

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