glossarist 2.13.10 → 2.13.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16c44282632761dbbfeb3b63ff619b519648f0af7306ee5aa85fba1606244bd6
-  data.tar.gz: 37e8af5033c014195228ba11f50528b7aca8c06424533196ea0c318d5f78c7f0
+  metadata.gz: 91c65595f05c44c51808471afe8444211ea1f6dec412d8fe0ad74eee187b11b2
+  data.tar.gz: 9354da2e19de5935ed2e6415436f2b7344e8ad841520a7ee9b70be7c4ddd49da
 SHA512:
-  metadata.gz: 8dadb718f3a39e49167eb1d8aa8eeada22f826c049be68dcfe151cd0980edb0e80006a51b21f64912dcc9e9d4ef21ff47618002b6d7d1496b88669cb39932620
-  data.tar.gz: 29f66da8f1f743c7f5424e966bf4b19a94e83264146d9c3156243f0f0a39e728874fcc4cbf6f2a2d8c77bd4799406083162d27b5f675dd1fe0aa88246091222d
+  metadata.gz: a2288cbc327785082b55fa370c622877e7dd41e90545edb8db7063e3fd29d57d974b040197fb015e4a83a6bc99f1ce44c583fbe692aced5b5f2251dbd542382d
+  data.tar.gz: 919ec57825c62a7749afce56ec9bf5f49e7f18a89d537c60290d92e6bf35b97eeb4118f40369e81119113ebf945b371d0fccc942d4416df14e31d2af2359bd7d

data/lib/glossarist/mentions/invalid_mention_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Mentions
+    class InvalidMentionError < StandardError
+      attr_reader :raw, :reason, :position
+
+      def initialize(raw:, reason:, position: 0)
+        @raw = raw
+        @reason = reason
+        @position = position
+        super("Invalid mention at position #{position}: #{reason}")
+      end
+    end
+  end
+end

data/lib/glossarist/mentions/parser.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Mentions
+    # Scans a string for {{kind:target}} patterns and returns a mixed
+    # array of text segments and parsed mention objects.
+    #
+    # Invalid mentions raise InvalidMentionError — they are never
+    # silently passed through.
+    #
+    # @see concept-model docs/design/inline-mentions.md
+    module Parser
+      MENTION_REGEX = /\{\{([^}]+)\}\}/.freeze
+
+      KINDS = %w[concept cite fig table formula bib link image].freeze
+
+      module_function
+
+      # @param text [String] the source text to scan
+      # @return [Array<Hash>] segments — text and mention objects
+      # @raise [InvalidMentionError] on invalid mention syntax
+      def parse(text)
+        return [{ kind: "text", content: "" }] unless text.is_a?(String) && !text.empty?
+
+        segments = []
+        pos = 0
+
+        text.to_enum(:scan, MENTION_REGEX).each do |match|
+          raw_content = match[0]
+          match_start = Regexp.last_match.offset(0)[0]
+
+          if match_start > pos
+            segments << { kind: "text", content: text[pos...match_start] }
+          end
+
+          segment = parse_mention_content(
+            raw_content,
+            raw: "{{#{raw_content}}}",
+            position: match_start,
+          )
+          segments << segment
+          pos = Regexp.last_match.offset(0)[1]
+        end
+
+        segments << { kind: "text", content: text[pos..] } if pos < text.length
+        segments
+      end
+
+      def parse_mention_content(content, raw:, position:)
+        content = content.strip
+
+        unless content =~ /\A(\w+):(.*)\z/m
+          raise InvalidMentionError.new(
+            raw: raw,
+            position: position,
+            reason: "Missing kind prefix; use {{concept:DATASET:ID}} or " \
+                    "{{cite:DATASET:ID}} — got #{raw}",
+          )
+        end
+
+        kind = Regexp.last_match(1).downcase
+        rest = Regexp.last_match(2).strip
+
+        unless KINDS.include?(kind)
+          raise InvalidMentionError.new(
+            raw: raw,
+            position: position,
+            reason: "Unknown kind '#{kind}'; valid kinds: #{KINDS.join(', ')}",
+          )
+        end
+
+        target_str, label = split_target_and_label(rest)
+
+        target = parse_target(target_str, kind: kind, raw: raw, position: position)
+
+        validate_target!(kind, target, raw: raw, position: position)
+
+        {
+          kind: kind,
+          target: target,
+          label: strip_label(label),
+          raw: raw,
+          start: position,
+          end: position + raw.length,
+        }
+      end
+
+      def split_target_and_label(rest)
+        return [rest, nil] unless rest.include?(",")
+
+        parts = rest.split(",", 2)
+        [parts[0].strip, parts[1].to_s.strip]
+      end
+      private_class_method :split_target_and_label
+
+      def parse_target(target_str, kind:, raw:, position:)
+        case target_str
+        when /\Aurn:/i
+          { type: "urn", urn: target_str }
+        when /\Ahttps?:\/\//i
+          { type: "url", url: target_str }
+        when /\A[a-zA-Z][a-zA-Z0-9_-]*:[^:]+/
+          split_dataset_qualified(target_str)
+        when %r{\A[a-zA-Z0-9_./-]+\z}
+          if target_str.include?("/")
+            { type: "path", path: target_str }
+          else
+            { type: "entity_id", id: target_str }
+          end
+        else
+          { type: "entity_id", id: target_str }
+        end
+      end
+      private_class_method :parse_target
+
+      def split_dataset_qualified(target_str)
+        last_colon = target_str.rindex(":")
+        dataset = target_str[0...last_colon]
+        id = target_str[(last_colon + 1)..]
+        { type: "dataset_qualified", dataset: dataset, id: id }
+      end
+      private_class_method :split_dataset_qualified
+
+      def validate_target!(kind, target, raw:, position:)
+        type = target[:type]
+
+        case kind
+        when "concept", "cite"
+          unless %w[urn dataset_qualified].include?(type)
+            raise InvalidMentionError.new(
+              raw: raw,
+              position: position,
+              reason: "#{kind} target must be DATASET:ID or URN; " \
+                      "got #{type} #{target_value_for_error(target).inspect}",
+            )
+          end
+        when "fig", "table", "formula"
+          unless %w[entity_id urn].include?(type)
+            raise InvalidMentionError.new(
+              raw: raw,
+              position: position,
+              reason: "#{kind} target must be plain ID or URN; " \
+                      "got #{type} #{target_value_for_error(target).inspect}",
+            )
+          end
+        when "bib"
+          unless type == "entity_id"
+            raise InvalidMentionError.new(
+              raw: raw,
+              position: position,
+              reason: "bib target must be a plain ID (same-dataset); " \
+                      "got #{type} #{target_value_for_error(target).inspect}",
+            )
+          end
+        when "link"
+          unless type == "url"
+            raise InvalidMentionError.new(
+              raw: raw,
+              position: position,
+              reason: "link target must be https:// or http:// URL; " \
+                      "got #{target_value_for_error(target).inspect}",
+            )
+          end
+        when "image"
+          unless %w[path url].include?(type)
+            raise InvalidMentionError.new(
+              raw: raw,
+              position: position,
+              reason: "image target must be a path or URL; " \
+                      "got #{type} #{target_value_for_error(target).inspect}",
+            )
+          end
+        end
+      end
+      private_class_method :validate_target!
+
+      def target_value_for_error(target)
+        target[:urn] || target[:url] || target[:id] ||
+          target[:dataset] ? "#{target[:dataset]}:#{target[:id]}" : target[:path]
+      end
+      private_class_method :target_value_for_error
+
+      def strip_label(label)
+        label.nil? || label.empty? ? nil : label
+      end
+      private_class_method :strip_label
+    end
+  end
+end

data/lib/glossarist/mentions/resolver.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Mentions
+    # Resolves parsed mention segments against a resolution context.
+    # The context provides lookup callables; the resolver dispatches
+    # by mention kind + target type.
+    module Resolver
+      module_function
+
+      # @param mention [Hash] a parsed mention from Parser.parse
+      # @param context [Hash] resolution context with lookup callables
+      # @return [Hash] resolved mention with :status
+      def resolve(mention, context)
+        return mention if mention[:kind] == "text"
+
+        case mention[:kind]
+        when "concept", "cite"
+          resolve_concept(mention, context)
+        when "fig", "table", "formula"
+          resolve_entity(mention, context)
+        when "bib"
+          resolve_bib(mention, context)
+        when "link"
+          { status: "external", kind: "link",
+            url: mention[:target][:url], label: mention[:label] }
+        when "image"
+          resolve_image(mention)
+        else
+          { status: "unresolved", kind: mention[:kind],
+            target: mention[:target], label: mention[:label] }
+        end
+      end
+
+      def resolve_all(mentions, context)
+        mentions.map { |m| resolve(m, context) }
+      end
+
+      def resolve_concept(mention, context)
+        target = mention[:target]
+        concept = lookup_concept(target, context)
+
+        return unresolved(mention) unless concept
+
+        result = {
+          status: "resolved",
+          kind: mention[:kind],
+          concept: concept,
+          label: mention[:label],
+        }
+
+        if mention[:kind] == "cite" && context[:concept]
+          result[:source] = find_matching_source(target, context[:concept])
+        end
+
+        result
+      end
+      private_class_method :resolve_concept
+
+      def resolve_entity(mention, context)
+        target = mention[:target]
+        entity = nil
+
+        case target[:type]
+        when "entity_id"
+          resolver = context[:resolve_entity]
+          entity = resolver&.call(mention[:kind], target[:id]) if resolver
+        when "urn"
+          entity = nil
+        end
+
+        if entity
+          { status: "resolved", kind: mention[:kind],
+            entity: entity, label: mention[:label] }
+        else
+          unresolved(mention)
+        end
+      end
+      private_class_method :resolve_entity
+
+      def resolve_bib(mention, context)
+        target = mention[:target]
+        entry = context[:resolve_bib_entry]&.call(target[:id])
+
+        if entry
+          { status: "resolved", kind: "bib",
+            entry: entry, label: mention[:label] }
+        else
+          unresolved(mention)
+        end
+      end
+      private_class_method :resolve_bib
+
+      def resolve_image(mention)
+        target = mention[:target]
+        if target[:type] == "url"
+          { status: "external_image", kind: "image",
+            url: target[:url], label: mention[:label] }
+        else
+          { status: "local_image", kind: "image",
+            path: target[:path], label: mention[:label] }
+        end
+      end
+      private_class_method :resolve_image
+
+      def lookup_concept(target, context)
+        resolver = context[:resolve_concept]
+        return nil unless resolver
+
+        case target[:type]
+        when "dataset_qualified"
+          resolver.call(dataset: target[:dataset], id: target[:id])
+        when "urn"
+          resolver.call(urn: target[:urn])
+        end
+      end
+      private_class_method :lookup_concept
+
+      def find_matching_source(target, concept)
+        sources = concept.respond_to?(:data) ? concept.data&.sources : concept.sources
+        return nil unless sources
+
+        case target[:type]
+        when "dataset_qualified"
+          sources.find do |s|
+            next unless s.respond_to?(:origin) && s.origin.respond_to?(:ref)
+            ref = s.origin.ref
+            ref && ref.source == target[:dataset] && ref.id == target[:id]
+          end
+        when "urn"
+          nil
+        end
+      end
+      private_class_method :find_matching_source
+
+      def unresolved(mention)
+        { status: "unresolved", kind: mention[:kind],
+          target: mention[:target], label: mention[:label] }
+      end
+      private_class_method :unresolved
+    end
+  end
+end

data/lib/glossarist/mentions.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # Inline mentions — fully declarative {{kind:target}} syntax per
+  # concept-model docs/design/inline-mentions.md.
+  #
+  # Every mention target is a CANONICAL IDENTIFIER. No magic
+  # combinations, no bare text, no procedural indirection. The parser
+  # REJECTS any non-declarative form with a clear error.
+  module Mentions
+    autoload :InvalidMentionError, "glossarist/mentions/invalid_mention_error"
+    autoload :Parser,              "glossarist/mentions/parser"
+    autoload :Resolver,            "glossarist/mentions/resolver"
+  end
+end

data/lib/glossarist/version.rb

@@ -4,5 +4,5 @@
 #
 
 module Glossarist
-  VERSION = "2.13.10"
+  VERSION = "2.13.11"
 end

data/lib/glossarist.rb

@@ -65,8 +65,7 @@ module Glossarist
   autoload :ManagedConcept,           "glossarist/managed_concept"
   autoload :ManagedConceptCollection, "glossarist/managed_concept_collection"
   autoload :ManagedConceptData,       "glossarist/managed_concept_data"
-  autoload :MentionParser,            "glossarist/mention_parser"
-  autoload :MentionKinds,             "glossarist/mention_parser"
+  autoload :Mentions,                "glossarist/mentions"
   autoload :NonVerbRep,               "glossarist/non_verb_rep"
   autoload :Pronunciation,            "glossarist/pronunciation"
   autoload :RelatedConcept,           "glossarist/related_concept"
@@ -109,12 +108,11 @@ module Glossarist
     end
   end
 
-  # Parse a single {{...}} mention into a canonical Hash. Defined here
-  # (rather than via autoload) so calling Glossarist.parse_mention(str)
-  # triggers the MentionParser autoload chain transparently — method
-  # calls do not fire autoloads on their own.
-  def self.parse_mention(text)
-    MentionParser.parse_mention(text)
+  # Parse all {{kind:target}} mentions in text. Returns an array of
+  # segments (text + mention objects) per concept-model inline-mentions spec.
+  # @see Glossarist::Mentions::Parser.parse
+  def self.parse_mentions(text)
+    Mentions::Parser.parse(text)
   end
 
   SCHEMA_VERSION = "3"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glossarist
 version: !ruby/object:Gem::Version
-  version: 2.13.10
+  version: 2.13.11
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-02 00:00:00.000000000 Z
+date: 2026-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -293,6 +293,10 @@ files:
 - lib/glossarist/managed_concept_collection.rb
 - lib/glossarist/managed_concept_data.rb
 - lib/glossarist/mention_parser.rb
+- lib/glossarist/mentions.rb
+- lib/glossarist/mentions/invalid_mention_error.rb
+- lib/glossarist/mentions/parser.rb
+- lib/glossarist/mentions/resolver.rb
 - lib/glossarist/non_concept_entity.rb
 - lib/glossarist/non_verb_rep.rb
 - lib/glossarist/non_verbal_reference.rb