coradoc 2.0.28 → 2.0.30

data/lib/coradoc/reference/address.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require 'lutaml/model'
+
+module Coradoc
+  module Reference
+    # Scheme-aware locator targeting a Content node.
+    #
+    # An Address is one of six built-in schemes — +:anchor+, +:path+,
+    # +:scoped_path+, +:url+, +:doi+, +:isbn+ — selected by heuristic on
+    # parse or by an explicit +hint:+. External gems register additional
+    # schemes via +Address.register_scheme+ (OCP).
+    #
+    #   Address.parse("foo")               # => anchor "foo"
+    #   Address.parse("ELF-5005-1#sec-3")  # => path "ELF-5005-1", fragment "sec-3"
+    #   Address.parse("ELF:5005:1#sec-3")  # => scoped_path scope "ELF"
+    #   Address.parse("https://x.y/z")     # => url
+    #   Address.parse("10.1234/abc")       # => doi
+    #   Address.parse("ISBN 978-1-2-3")    # => isbn
+    #
+    # Addresses are value types: two addresses are equal iff every
+    # attribute matches. Round-trip via +to_s+.
+    class Address < Lutaml::Model::Serializable
+      class ParseError < Coradoc::Reference::Error; end
+      class UnknownSchemeError < Coradoc::Reference::Error; end
+
+      attribute :scheme, :string
+      attribute :target, :string
+      attribute :fragment, :string
+      attribute :scope, :string
+
+      autoload :Url, "#{__dir__}/address/url"
+      autoload :Doi, "#{__dir__}/address/doi"
+      autoload :Isbn, "#{__dir__}/address/isbn"
+      autoload :ScopedPath, "#{__dir__}/address/scoped_path"
+      autoload :Path, "#{__dir__}/address/path"
+      autoload :Anchor, "#{__dir__}/address/anchor"
+
+      BUILTIN_SCHEME_ORDER = %i[url doi isbn scoped_path path anchor].freeze
+
+      class << self
+        def parse(raw, hint: nil)
+          Scheme.ensure_builtins_registered!
+          mod = hint ? scheme_for_hint!(hint) : Scheme.match(raw)
+          unless mod
+            raise ParseError,
+                  "Cannot determine address scheme for #{raw.inspect}"
+          end
+          mod.parse(raw)
+        end
+
+        def register_scheme(mod)
+          Scheme.register(mod)
+        end
+
+        def scheme_names
+          Scheme.ensure_builtins_registered!
+          Scheme.names
+        end
+
+        private
+
+        def scheme_for_hint!(hint)
+          Scheme.for(hint) ||
+            raise(UnknownSchemeError,
+                  "Unknown address scheme #{hint.inspect}. " \
+                  "Registered: #{Scheme.names.inspect}")
+        end
+      end
+
+      # Value equality (==/eql?/hash) comes from Lutaml::Model — all
+      # attributes compared, class-aware, safe as Hash keys.
+
+      def to_s
+        Scheme.ensure_builtins_registered!
+        mod = Scheme.for(scheme)
+        unless mod
+          raise UnknownSchemeError,
+                "No registered scheme for #{scheme.inspect}. " \
+                "Registered: #{Scheme.names.inspect}"
+        end
+        mod.serialize(self)
+      end
+
+      # Registry of scheme modules. Each module provides:
+      #   scheme_name      -> Symbol
+      #   matches?(raw)    -> Boolean
+      #   parse(raw)       -> Address
+      #   serialize(addr)  -> String
+      #
+      # +register+ always forces builtin registration first, so an
+      # external scheme registered before first use is never clobbered
+      # by the lazy builtin pass. The catch-all anchor scheme is always
+      # tried LAST on match, so external schemes are never shadowed by
+      # it no matter when they register.
+      module Scheme
+        @registered = []
+        @builtins_registered = false
+        @registering_builtins = false
+
+        CATCH_ALL_SCHEME = :anchor
+        private_constant :CATCH_ALL_SCHEME
+
+        MUTEX = Mutex.new
+        private_constant :MUTEX
+
+        class << self
+          def register(mod)
+            ensure_builtins_registered! unless @registering_builtins
+            @registered.delete_if { |m| m.scheme_name == mod.scheme_name }
+            @registered << mod
+          end
+
+          def names
+            @registered.map(&:scheme_name)
+          end
+
+          def for(name)
+            @registered.find { |m| m.scheme_name == name.to_sym }
+          end
+
+          def match(raw)
+            catch_all, specific =
+              @registered.partition { |m| m.scheme_name == CATCH_ALL_SCHEME }
+            (specific + catch_all).find { |m| m.matches?(raw) }
+          end
+
+          def ensure_builtins_registered!
+            MUTEX.synchronize do
+              return if @builtins_registered
+
+              @registering_builtins = true
+              begin
+                BUILTIN_SCHEME_ORDER.each do |name|
+                  const_name = name.to_s.split('_').map(&:capitalize).join
+                  register(Address.const_get(const_name))
+                end
+                @builtins_registered = true
+              ensure
+                @registering_builtins = false
+              end
+            end
+          end
+
+          def reset!
+            @registered.clear
+            @builtins_registered = false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Catalog
+      # Composes multiple catalogs. Lookup asks EVERY child and merges
+      # the hits: exactly one hit returns the Content; several hits
+      # return an Array (which the Resolver surfaces per the
+      # +ambiguous:+ policy). Precedence between catalogs is a
+      # resolver/policy concern, not a lookup concern:
+      #
+      #   Composite.new(
+      #     Local.from_doc(doc),
+      #     Collection.from_manifest(...),
+      #     Remote.new(client: http_client)
+      #   )
+      class Composite
+        include Catalog::Protocol
+
+        attr_reader :children
+
+        def initialize(*children)
+          @children = children.flatten
+        end
+
+        def lookup(address)
+          results = []
+          children.each do |catalog|
+            result = catalog.lookup(address)
+            next if result.nil?
+
+            results.concat(Array(result))
+          end
+          return nil if results.empty?
+          return results.first if results.size == 1
+
+          results
+        end
+
+        def ambiguous?(address)
+          result = lookup(address)
+          result.is_a?(Array) && result.size > 1
+        end
+
+        def each_pair(&block)
+          return to_enum(:each_pair) unless block_given?
+
+          children.each do |catalog|
+            catalog.each_pair(&block)
+          end
+        end
+
+        def recognizes_scheme?(scheme)
+          children.any? { |catalog| catalog.recognizes_scheme?(scheme) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Catalog
+      # Indexes one CoreModel document. Walks the tree once at
+      # construction; indexes every node carrying an +id+ by its anchor
+      # Address, plus the document itself by an optional path Address.
+      #
+      #   catalog = Catalog::Local.from_doc(doc, path: "ELF-5005-1")
+      #   catalog.lookup(Address.parse("ELF-5005-1"))        # => doc
+      #   catalog.lookup(Address.parse("sec-3"))             # => section
+      class Local
+        include Catalog::Protocol
+
+        attr_reader :document, :document_path
+
+        def initialize(document:, document_path: nil, index: nil)
+          @document = document
+          @document_path = document_path
+          @index = index || MemoryIndex.new
+          populate! unless index
+        end
+
+        class << self
+          def from_doc(document, path: nil)
+            new(document: document, document_path: path)
+          end
+        end
+
+        def lookup(address)
+          @index.lookup(address)
+        end
+
+        def ambiguous?(address)
+          @index.ambiguous?(address)
+        end
+
+        def each_pair(&)
+          @index.each_pair(&)
+        end
+
+        def recognizes_scheme?(scheme)
+          return true if scheme.to_sym == :anchor
+          return true if scheme.to_sym == :path && document_path
+          return true if scheme.to_sym == :scoped_path && document_path&.include?(':')
+
+          @index.recognizes_scheme?(scheme)
+        end
+
+        private
+
+        def populate!
+          index_document_root!
+          walk(document)
+        end
+
+        def index_document_root!
+          return unless document_path
+
+          address = Coradoc::Reference::Address.parse(document_path, hint: path_hint)
+          @index.add(address, document)
+        end
+
+        def path_hint
+          document_path.include?(':') ? :scoped_path : :path
+        end
+
+        def walk(node)
+          return unless node.is_a?(Coradoc::CoreModel::Base)
+
+          index_node!(node)
+          walk_children(node)
+        end
+
+        def index_node!(node)
+          return unless node.id
+
+          address = Coradoc::Reference::Address.new(
+            scheme: 'anchor',
+            target: node.id
+          )
+          @index.add(address, node)
+        end
+
+        def walk_children(node)
+          return unless node.is_a?(Coradoc::CoreModel::HasChildren)
+
+          children = node.children
+          return if children.nil? || children.empty?
+
+          children.each { |child| walk(child) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Coradoc
+  module Reference
+    module Catalog
+      # Shared in-memory index. Built-in catalogs compose this rather
+      # than reimplementing the storage layer (DRY). The index is
+      # immutable from the outside — entries are added by the catalog
+      # during construction, then read-only.
+      class MemoryIndex
+        include Enumerable
+
+        def initialize
+          @by_address = {}
+          @schemes = Set.new
+        end
+
+        def add(address, content)
+          raise ArgumentError, 'address required' unless address.is_a?(Coradoc::Reference::Address)
+          raise ArgumentError, 'content required' unless content
+
+          @by_address[address] = Array(@by_address[address]) << content
+          @schemes << address.scheme.to_sym
+          self
+        end
+
+        def lookup(address)
+          entries = @by_address[address]
+          return nil unless entries
+          return entries.first if entries.size == 1
+
+          # Copy: callers must not be able to corrupt the index.
+          entries.dup
+        end
+
+        def ambiguous?(address)
+          entries = @by_address[address]
+          entries && entries.size > 1
+        end
+
+        def each_pair
+          return to_enum(:each_pair) unless block_given?
+
+          @by_address.each do |address, contents|
+            contents.each { |c| yield address, c }
+          end
+        end
+
+        def recognizes_scheme?(scheme)
+          @schemes.include?(scheme.to_sym)
+        end
+
+        def size
+          @by_address.size
+        end
+      end
+    end
+  end
+end

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