coradoc 2.0.27 → 2.0.29

data/lib/coradoc/reference/catalog.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    # Externally-built index from Address → Content. coradoc queries
+    # catalogs; it never owns the collection truth.
+    #
+    # A Catalog is any object responding to +lookup+, +each_pair+, and
+    # +recognizes_scheme?+. Built-in catalogs share an in-memory index
+    # (MemoryIndex) for implementation. Catalogs compose via CompositeCatalog.
+    module Catalog
+      autoload :MemoryIndex, "#{__dir__}/catalog/memory_index"
+      autoload :Local, "#{__dir__}/catalog/local"
+      autoload :Composite, "#{__dir__}/catalog/composite"
+
+      # Protocol methods every Catalog must answer. Implementations may
+      # include this module for documentation only; the protocol is
+      # duck-typed but explicit at the type-check sites via these method
+      # names.
+      module Protocol
+        # Resolve +address+ to a Content node (CoreModel::Base) or nil.
+        def lookup(address) = raise(NotImplementedError)
+
+        # Enumerate every (Address, Content) pair this catalog knows.
+        def each_pair(&) = raise(NotImplementedError)
+
+        # Does this catalog index addresses of the given scheme? Used by
+        # composite catalogs to skip irrelevant children.
+        def recognizes_scheme?(scheme) = raise(NotImplementedError)
+      end
+    end
+  end
+end

data/lib/coradoc/reference/edge/citation_options.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Edge < Lutaml::Model::Serializable
+      # Options for citation edges (bib references). Style is the
+      # citation style name (e.g. "ieee", "apa", "chicago"); locality
+      # is the optional page/section reference carried separately on
+      # Address.fragment, not here.
+      class CitationOptions < Edge::Options
+        attribute :style, :string
+        attribute :suppress_author, :boolean, default: -> { false }
+      end
+    end
+  end
+end

data/lib/coradoc/reference/edge/footnote_ref_options.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Edge < Lutaml::Model::Serializable
+      # Options for footnote references. The footnote body lives in
+      # the catalog as a Content node; the Edge points at it.
+      class FootnoteRefOptions < Edge::Options
+        attribute :footnote_id, :string
+      end
+    end
+  end
+end

data/lib/coradoc/reference/edge/image_ref_options.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Edge < Lutaml::Model::Serializable
+      # Options for image references.
+      class ImageRefOptions < Edge::Options
+        attribute :alt_text, :string
+        attribute :width, :string
+        attribute :height, :string
+        attribute :role, :string
+      end
+    end
+  end
+end

data/lib/coradoc/reference/edge/include_options.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Edge < Lutaml::Model::Serializable
+      # Options for include edges: embeds the canonical
+      # CoreModel::IncludeOptions — the include directive's typed
+      # selectors (tags/wildcards, lines, typed leveloffset, indent,
+      # encoding). One typed form, never a re-flattened mirror.
+      class IncludeOptions < Edge::Options
+        attribute :include_options, Coradoc::CoreModel::IncludeOptions
+      end
+    end
+  end
+end

data/lib/coradoc/reference/edge/kind.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Edge < Lutaml::Model::Serializable
+      # Registry mapping kind symbol → Entry(name, options_class).
+      # Built-in kinds are registered lazily on first access. External
+      # gems add kinds via +Edge.register_kind+ (OCP).
+      #
+      # +register+ always forces builtin registration first, so an
+      # external registration made before first use is never clobbered
+      # by the lazy builtin pass.
+      module Kind
+        @entries = {}
+        @builtins_registered = false
+        @registering_builtins = false
+
+        MUTEX = Mutex.new
+        private_constant :MUTEX
+
+        Entry = Struct.new(:name, :options_class)
+        private_constant :Entry
+
+        class << self
+          def register(name, options_class: nil)
+            ensure_builtins_registered! unless @registering_builtins
+            @entries[name.to_sym] = Entry.new(name.to_sym, options_class)
+          end
+
+          def names
+            ensure_builtins_registered!
+            @entries.keys
+          end
+
+          def options_class_for(name)
+            ensure_builtins_registered!
+            @entries[name.to_sym]&.options_class
+          end
+
+          def entry_for(name)
+            ensure_builtins_registered!
+            @entries[name.to_sym]
+          end
+
+          def reset!
+            @entries.clear
+            @builtins_registered = false
+          end
+
+          def ensure_builtins_registered!
+            MUTEX.synchronize do
+              return if @builtins_registered
+
+              @registering_builtins = true
+              begin
+                register(:navigation, options_class: Edge::NavigationOptions)
+                register(:citation, options_class: Edge::CitationOptions)
+                register(:link, options_class: Edge::LinkOptions)
+                register(:include, options_class: Edge::IncludeOptions)
+                register(:image_ref, options_class: Edge::ImageRefOptions)
+                register(:footnote_ref, options_class: Edge::FootnoteRefOptions)
+                @builtins_registered = true
+              ensure
+                @registering_builtins = false
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/edge/link_options.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Edge < Lutaml::Model::Serializable
+      # Options for hyperlink edges.
+      class LinkOptions < Edge::Options
+        attribute :role, :string
+      end
+    end
+  end
+end

data/lib/coradoc/reference/edge/navigation_options.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Edge < Lutaml::Model::Serializable
+      # Options specific to navigation edges (xref, anchor).
+      class NavigationOptions < Edge::Options
+        attribute :tooltip, :string
+      end
+    end
+  end
+end

data/lib/coradoc/reference/edge/options.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    class Edge < Lutaml::Model::Serializable
+      # Options base class. Subclasses are typed value objects per kind —
+      # never +:hash+. Value equality (==/eql?/hash) comes from
+      # Lutaml::Model: class-aware, all attributes compared.
+      class Options < Lutaml::Model::Serializable
+      end
+    end
+  end
+end

data/lib/coradoc/reference/edge.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Coradoc
+  module Reference
+    # Directed edge: a Content node references another Content via an Address.
+    #
+    # Every reference in coradoc — navigation, citation, hyperlink,
+    # include, image, footnote — is one Edge with a different +kind+.
+    # The kind is a label for materialization; resolution is kind-agnostic.
+    #
+    #   Edge.new(
+    #     kind: :navigation,
+    #     address: Address.parse("ELF-5005-1#sec-3"),
+    #     source_id: "para-42",
+    #     label: "Section 3"
+    #   )
+    class Edge < Lutaml::Model::Serializable
+      autoload :Kind, "#{__dir__}/edge/kind"
+      autoload :Options, "#{__dir__}/edge/options"
+      autoload :NavigationOptions,
+               "#{__dir__}/edge/navigation_options"
+      autoload :CitationOptions,
+               "#{__dir__}/edge/citation_options"
+      autoload :LinkOptions, "#{__dir__}/edge/link_options"
+      autoload :IncludeOptions, "#{__dir__}/edge/include_options"
+      autoload :ImageRefOptions, "#{__dir__}/edge/image_ref_options"
+      autoload :FootnoteRefOptions,
+               "#{__dir__}/edge/footnote_ref_options"
+
+      attribute :kind, :string
+      attribute :address, Coradoc::Reference::Address
+      attribute :source_id, :string
+      attribute :label, :string
+      attribute :options, Coradoc::Reference::Edge::Options
+
+      class << self
+        # Build an Edge with the given kind. Options are coerced to the
+        # kind's options class (if any) via the Kind registry — never
+        # hand-rolled. Raises UnknownKindError for kinds that were never
+        # registered — external kinds register via +register_kind+ (OCP).
+        def build(kind:, address:, source_id: nil, label: nil, options: nil)
+          entry = Kind.entry_for(kind)
+          unless entry
+            raise Coradoc::Reference::UnknownKindError,
+                  "Unknown reference kind #{kind.inspect} — " \
+                  'register it via Edge.register_kind'
+          end
+
+          new(
+            kind: kind.to_s,
+            address: address,
+            source_id: source_id,
+            label: label,
+            options: coerce_options(options, entry.options_class)
+          )
+        end
+
+        def register_kind(name, options_class: nil)
+          Kind.register(name, options_class: options_class)
+        end
+
+        def kinds
+          Kind.names
+        end
+
+        private
+
+        def coerce_options(value, options_class)
+          klass = options_class || Options
+          return klass.new if value.nil?
+          return value if value.is_a?(klass)
+
+          klass.new(value)
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/edge_search.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    # Walks a CoreModel tree and yields every Edge found in it. For
+    # Phase 1, Edges are wrapped inside existing node types —
+    # +CrossReferenceElement+, +LinkElement+, +Image+, +Include+,
+    # +FootnoteElement+. The Phase 3 migration will move Edges to
+    # first-class attributes; this module abstracts the extraction so
+    # the rest of the resolver doesn't change.
+    #
+    # The walker is read-only: it never mutates the input tree.
+    module EdgeSearch
+      module_function
+
+      # Yields (parent_node, edge) for every Edge found in the tree.
+      # The parent_node is the node that owns the edge — the
+      # materializer replaces the edge in-place inside parent_node's
+      # children list.
+      def each_edge(root)
+        return to_enum(:each_edge, root) unless block_given?
+
+        walk(root) { |node| edges_for(node).each { |edge| yield node, edge } }
+      end
+
+      # Walk tree, yield each Base node. Stops at inline leaves.
+      def walk(node, &block)
+        return unless node.is_a?(Coradoc::CoreModel::Base)
+        return unless block
+
+        yield(node)
+        return unless node.is_a?(Coradoc::CoreModel::HasChildren)
+
+        children = node.children
+        return unless children
+
+        children.each { |child| walk(child, &block) }
+      end
+
+      # Extract every Edge the given node owns. Pure function of node.
+      def edges_for(node)
+        edge_extractor = EDGE_EXTRACTORS[node.class]
+        return [] unless edge_extractor
+
+        edge = edge_extractor.call(node)
+        edge ? [edge] : []
+      end
+
+      def edge_from_cross_reference(node)
+        Edge.build(
+          kind: :navigation,
+          address: parse_address(node.target, hint: xref_hint(node.target)),
+          source_id: node.id,
+          label: node.content
+        )
+      end
+
+      def edge_from_link(node)
+        Edge.build(
+          kind: :link,
+          address: parse_address(node.target),
+          source_id: node.id,
+          label: node.content
+        )
+      end
+
+      def edge_from_include(node)
+        Edge.build(
+          kind: :include,
+          address: parse_address(node.target, hint: path_or_url_hint(node.target)),
+          source_id: node.id,
+          options: { include_options: node.options }
+        )
+      end
+
+      def edge_from_image(node)
+        Edge.build(
+          kind: :image_ref,
+          address: parse_address(node.src, hint: path_or_url_hint(node.src)),
+          source_id: node.id,
+          label: node.alt,
+          options: { alt_text: node.alt }
+        )
+      end
+
+      def edge_from_footnote(node)
+        Edge.build(
+          kind: :footnote_ref,
+          address: parse_address(node.target || node.id, hint: :anchor),
+          source_id: node.id,
+          options: { footnote_id: node.id }
+        )
+      end
+
+      # Xrefs are document-internal by definition (AsciiDoc): bare
+      # targets are anchors, even uppercase document-ID-shaped ones
+      # ("SEC-2"). Only an explicit "document#fragment" shape or a URL
+      # points outside the current document.
+      def xref_hint(target)
+        raw = target.to_s
+        return :url if Coradoc::Reference::Address::Url.matches?(raw)
+        return :path if raw.include?('#') && !raw.start_with?('#')
+
+        :anchor
+      end
+
+      # File-like targets (include, image): URLs stay urls, everything
+      # else is a path — including bare filenames ("foo.png") that the
+      # anchor bareword heuristic would otherwise claim.
+      def path_or_url_hint(target)
+        Coradoc::Reference::Address::Url.matches?(target.to_s) ? :url : :path
+      end
+
+      def parse_address(target, hint: nil)
+        Coradoc::Reference::Address.parse(target.to_s, hint: hint)
+      end
+
+      EDGE_EXTRACTORS = {
+        Coradoc::CoreModel::CrossReferenceElement => method(:edge_from_cross_reference),
+        Coradoc::CoreModel::LinkElement => method(:edge_from_link),
+        Coradoc::CoreModel::Include => method(:edge_from_include),
+        Coradoc::CoreModel::Image => method(:edge_from_image),
+        Coradoc::CoreModel::FootnoteElement => method(:edge_from_footnote)
+      }.freeze
+      private_constant :EDGE_EXTRACTORS
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Materializer
+      # Protocol base. Subclasses declare their (kind, presentation,
+      # format) tuple via class-level +.kind+, +.presentation+, +.format+
+      # methods, then implement +#materialize+ to produce a
+      # CoreModel::InlineElement subtree.
+      #
+      # Materializers consume Results — they never touch the catalog
+      # directly. The Presentation tells them where the target lives.
+      class Base
+        class << self
+          def kind
+            nil
+          end
+
+          def presentation
+            :any
+          end
+
+          def format
+            :any
+          end
+        end
+
+        # Render one resolved edge.
+        #
+        # @param edge [Edge]
+        # @param result [Result::Base] the resolved outcome
+        # @param node [CoreModel::Base] the original edge-bearing node;
+        #   return it unchanged to keep the node as authored
+        # @param presentation [Presentation::Base]
+        # @param pages [Array<Presentation::Page>]
+        # @return [CoreModel::Base, nil] replacement node, the original
+        #   +node+ to keep it, or nil to drop it from the tree
+        def materialize(edge:, result:, node:, presentation:, pages:)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/materializer/passthrough.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Materializer
+      # Default fallback. Returns the original edge-bearing node
+      # unchanged — an unresolvable or unrenderable reference survives
+      # materialization exactly as authored, so round-tripping is
+      # always safe and no content is ever lost.
+      class Passthrough < Base
+        class << self
+          def kind
+            :any
+          end
+
+          def presentation
+            :any
+          end
+
+          def format
+            :any
+          end
+        end
+
+        def materialize(node:, **)
+          node
+        end
+      end
+    end
+  end
+end

data/lib/coradoc/reference/materializer/registry.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Materializer
+      # Registry of materializers keyed by [kind, presentation, format].
+      # Lookup falls back on +:any+ — so a materializer registered for
+      # +[:link, :any, :html]+ handles every presentation in HTML.
+      # Most specific key wins (concrete > :any).
+      #
+      # Format gems register their materializers process-wide via
+      # +.register_global+ (OCP): every registry instance picks them up
+      # on first use, and dispatch code never changes.
+      class Registry
+        # Core ships only the node-preserving fallback. Format-specific
+        # materializers live in the format gems (coradoc-html,
+        # coradoc-adoc, ...) and register globally at load time.
+        BUILTINS = [Materializer::Passthrough].freeze
+
+        @global_registrations = []
+
+        GLOBAL_MUTEX = Mutex.new
+        private_constant :GLOBAL_MUTEX
+
+        class << self
+          def register_global(klass)
+            GLOBAL_MUTEX.synchronize do
+              @global_registrations << klass unless @global_registrations.include?(klass)
+            end
+          end
+
+          def global_registrations
+            GLOBAL_MUTEX.synchronize { @global_registrations.dup }
+          end
+
+          def reset_globals!
+            GLOBAL_MUTEX.synchronize { @global_registrations.clear }
+          end
+        end
+
+        def initialize
+          @by_key = {}
+          @builtins_registered = false
+        end
+
+        def register(klass)
+          ensure_builtins_registered!
+          @by_key[EntryKey.new(klass.kind, klass.presentation, klass.format)] = klass
+        end
+
+        def lookup(kind:, presentation:, format:)
+          ensure_builtins_registered!
+          find_most_specific(kind, presentation, format) ||
+            find_most_specific(kind, presentation, :any) ||
+            find_most_specific(kind, :any, format) ||
+            find_most_specific(kind, :any, :any) ||
+            find_most_specific(:any, :any, :any)
+        end
+
+        def registered
+          ensure_builtins_registered!
+          @by_key.dup
+        end
+
+        def reset!
+          @by_key.clear
+          @builtins_registered = false
+        end
+
+        private
+
+        def find_most_specific(kind, presentation, format)
+          @by_key[EntryKey.new(kind.to_sym, presentation.to_sym, format.to_sym)]
+        end
+
+        def ensure_builtins_registered!
+          return if @builtins_registered
+
+          register_builtins!
+          @builtins_registered = true
+        end
+
+        def register_builtins!
+          (BUILTINS + self.class.global_registrations).each do |k|
+            @by_key[EntryKey.new(k.kind, k.presentation, k.format)] = k
+          end
+        end
+
+        # Internal composite key for the registry. Equality based on
+        # the three symbol values so two equivalent tuples compare equal.
+        class EntryKey
+          attr_reader :kind, :presentation, :format
+
+          def initialize(kind, presentation, format)
+            @kind = kind.to_sym
+            @presentation = presentation.to_sym
+            @format = format.to_sym
+          end
+
+          def ==(other)
+            other.is_a?(EntryKey) &&
+              kind == other.kind &&
+              presentation == other.presentation &&
+              format == other.format
+          end
+          alias eql? ==
+
+          def hash
+            [kind, presentation, format].hash
+          end
+        end
+        private_constant :EntryKey
+      end
+    end
+  end
+end

data/lib/coradoc/reference/materializer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    # Render an Edge per (kind, presentation, format). Registry-based:
+    # adding a new output format or citation style is registering a
+    # new materializer, not editing switch statements.
+    module Materializer
+      autoload :Base, "#{__dir__}/materializer/base"
+      autoload :Registry, "#{__dir__}/materializer/registry"
+      autoload :Passthrough, "#{__dir__}/materializer/passthrough"
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Presentation
+      # Protocol base. Subclasses implement +#layout+ (resolved graph →
+      # Pages) and +#locate_page+ (find which page a target lives on).
+      #
+      # A Presentation NEVER reads the original document — it consumes
+      # the resolved graph produced by the Resolver. It never renders.
+      class Base
+        # Registry key used in materializer lookup tuples
+        # [kind, presentation, format]. Subclasses override so
+        # materializers can target a specific layout.
+        def self.key
+          :any
+        end
+
+        def key
+          self.class.key
+        end
+
+        # Lay out the resolved graph as a tree of Pages. Subclasses
+        # decide slicing, ordering, hierarchy.
+        #
+        # @param resolved_graph [CoreModel::Base] the document the
+        #   caller wants to present. Already resolved (edges → targets).
+        # @return [Array<Page>]
+        def layout(resolved_graph)
+          raise NotImplementedError
+        end
+
+        # Given an Edge and its resolved target, find the Page where
+        # the target lives. This is what makes cross-references
+        # survive re-pagination.
+        #
+        # @param edge [Edge]
+        # @param target_content [CoreModel::Base]
+        # @param pages [Array<Page>]
+        # @return [Page, nil]
+        def locate_page(edge, target_content, pages:)
+          raise NotImplementedError
+        end
+      end
+    end
+  end
+end