glossarist 2.13.6 → 2.13.7

data/lib/glossarist/tasks/sync.rake

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
-require_relative "../tasks/sync_model"
+# Entry-point require triggers the autoload chain
+# (Glossarist → Tasks → SyncModel) defined in lib/glossarist.rb.
+# Internal-path requires are forbidden by the autoload rule.
+require "glossarist"
 
 namespace :glossarist do
   namespace :sync do

data/lib/glossarist/tasks.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # Rake-task namespace for vendored-data sync + SHACL validation.
+  # Loaded lazily via autoload from lib/glossarist.rb.
+  module Tasks
+    autoload :SyncModel, "glossarist/tasks/sync_model"
+  end
+end

data/lib/glossarist/transforms/concept_to_gloss_transform.rb

@@ -33,18 +33,20 @@ module Glossarist
         Designation::Symbol => :build_gloss_symbol,
       }.freeze
 
-      def self.transform(managed_concept, options = {})
-        new(managed_concept, options).build
+      def self.transform(managed_concept, relations: [], **options)
+        new(managed_concept, relations: relations, **options).build
       end
 
-      def self.transform_document(concepts, figures: [], tables: [],
+      def self.transform_document(concepts, relations: [], figures: [], tables: [],
                                   formulas: [], **options)
-        new(nil, options).build_document(concepts, figures: figures,
-                                                   tables: tables, formulas: formulas)
+        new(nil, relations: relations, **options).build_document(
+          concepts, figures: figures, tables: tables, formulas: formulas
+        )
       end
 
-      def initialize(managed_concept, options = {})
+      def initialize(managed_concept, relations: [], **options)
         @concept = managed_concept
+        @relations = Array(relations)
         @options = options
       end
 
@@ -63,7 +65,7 @@ module Glossarist
         Rdf::GlossDocument.to_turtle(doc)
       end
 
-      def to_turtle(concepts_or_concept = nil, figures: [], tables: [],
+      def to_turtle(concepts_or_concept = nil, relations: nil, figures: [], tables: [],
                     formulas: [])
         if concepts_or_concept.is_a?(Array)
           build_document(concepts_or_concept, figures: figures,
@@ -72,12 +74,12 @@ module Glossarist
           target = concepts_or_concept || @concept
           return "" unless target
 
-          gc = build_gloss_concept(target)
+          gc = build_gloss_concept(target, relations: relations)
           Rdf::GlossConcept.to_turtle(gc)
         end
       end
 
-      def to_jsonld(concepts_or_concept = nil, figures: [], tables: [],
+      def to_jsonld(concepts_or_concept = nil, relations: nil, figures: [], tables: [],
                     formulas: [])
         if concepts_or_concept.is_a?(Array)
           gloss_concepts = concepts_or_concept.map do |c|
@@ -94,7 +96,7 @@ module Glossarist
           target = concepts_or_concept || @concept
           return "" unless target
 
-          gc = build_gloss_concept(target)
+          gc = build_gloss_concept(target, relations: relations)
           Rdf::GlossConcept.to_jsonld(gc)
         end
       end
@@ -108,9 +110,10 @@ module Glossarist
 
       private
 
-      attr_reader :concept, :options
+      attr_reader :concept, :relations, :options
 
-      def build_gloss_concept(managed_concept)
+      def build_gloss_concept(managed_concept, relations: nil)
+        relation_list = relations || @relations
         identifier = managed_concept.data&.id || managed_concept.identifier
 
         localizations = managed_concept.localizations.each_value.map do |l10n|
@@ -130,46 +133,66 @@ module Glossarist
           domains: build_gloss_domains(managed_concept.data&.domains,
                                        identifier),
           dates: build_gloss_dates(managed_concept.dates, identifier),
-          partitive_relations: build_gloss_partitive_relations(
-            v3_partitive_relations(managed_concept), identifier
+          partitive_relations: build_gloss_hyperedges(
+            relation_list, V3::PartitiveHyperedge,
+            :build_gloss_partitive_member, :partitive_member_ids,
+            :partitive_members, Rdf::GlossPartitiveRelation, identifier,
+          ),
+          generic_relations: build_gloss_hyperedges(
+            relation_list, V3::GenericHyperedge,
+            :build_gloss_generic_member, :generic_member_ids,
+            :generic_members, Rdf::GlossGenericRelation, identifier,
           ),
           **rel_targets,
         )
       end
 
-      # PartitiveRelations are a V3-only attribute. The transform
-      # accepts both V1/V2 and V3 concepts; for V1/V2 concepts the
-      # relation list is always empty.
-      def v3_partitive_relations(managed_concept)
-        return [] unless managed_concept.is_a?(V3::ManagedConcept)
-
-        managed_concept.partitive_relations
+      # Type-blind hyperedge builder. Dispatches via HyperedgeRegistry;
+      # the only per-type data (member class, RDF view attribute names,
+      # RDF view class) is passed in. Adding a new hyperedge type means
+      # adding one entry to the calling sites above; no edit to this
+      # method.
+      def build_gloss_hyperedges(relations, hyperedge_class, member_builder,
+                                  member_ids_attr, members_attr,
+                                  gloss_relation_class, identifier)
+        Array(relations)
+          .select { |rel| rel.is_a?(hyperedge_class) }
+          .map { |rel| build_one_gloss_hyperedge(rel, member_builder, member_ids_attr, members_attr, gloss_relation_class, identifier) }
+      end
+
+      def build_one_gloss_hyperedge(rel, member_builder, member_ids_attr,
+                                     members_attr, gloss_relation_class, identifier)
+        source_members = Array(rel.members)
+        gloss_members = source_members.map { |m| send(member_builder, m) }
+        member_uris = source_members
+          .select { |m| m.ref.is_a?(Glossarist::ConceptRef) }
+          .map { |m| concept_ref_uri(m.ref) }
+
+        gloss_relation_class.new(
+          identifier: identifier.to_s,
+          comprehensive_uri: concept_ref_uri(rel.comprehensive),
+          member_ids_attr => member_uris,
+          members_attr => gloss_members,
+          completeness: rel.completeness,
+          criterion: rel.criterion,
+        )
       end
 
-      def build_gloss_partitive_relations(relations, identifier)
-        return [] unless relations
-
-        Array(relations).map do |rel|
-          source_members = Array(rel.partitives)
-          gloss_members = source_members.map { |m| build_gloss_partitive_member(m) }
-          member_uris = source_members
-            .select { |m| m.is_a?(V3::PartitiveMember) && m.ref.is_a?(Glossarist::ConceptRef) }
-            .map { |m| concept_ref_uri(m.ref) }
+      def build_gloss_partitive_member(member)
+        return Rdf::GlossPartitiveMember.new unless member.is_a?(V3::PartitiveMember)
 
-          Rdf::GlossPartitiveRelation.new(
-            identifier: identifier.to_s,
-            comprehensive_uri: concept_ref_uri(rel.comprehensive),
-            partitive_member_ids: member_uris,
-            partitive_members: gloss_members,
-            completeness: rel.completeness,
-            criterion: rel.criterion,
-          )
-        end
+        build_gloss_nary_member(Rdf::GlossPartitiveMember, member)
       end
 
-      def build_gloss_partitive_member(member)
-        return Rdf::GlossPartitiveMember.new unless member.is_a?(V3::PartitiveMember)
+      def build_gloss_generic_member(member)
+        return Rdf::GlossGenericMember.new unless member.is_a?(V3::GenericMember)
 
+        build_gloss_nary_member(Rdf::GlossGenericMember, member)
+      end
+
+      # Shared member builder. Per-class metadata (the rdf view class
+      # is dispatched by the caller) keeps the duplication to one place.
+      def build_gloss_nary_member(gloss_member_class, member)
         ref = member.ref
         ref_attrs = if ref.is_a?(Glossarist::ConceptRef)
                       { ref_id: ref.id, ref_source: ref.source, ref_text: ref.text }
@@ -177,7 +200,7 @@ module Glossarist
                       {}
                     end
 
-        Rdf::GlossPartitiveMember.new(
+        gloss_member_class.new(
           **ref_attrs,
           presence: member.presence,
           count: member.count,
@@ -185,19 +208,16 @@ module Glossarist
         )
       end
 
-      # Single SSOT for ConceptRef → concept URI. Handles all four
-      # ref shapes (source+id, id-only, source+text, text-only) and
-      # mirrors GlossCitation.slug's `[source, id].compact.join("/")`
-      # convention so external ConceptRefs don't collide with local
-      # ones of the same id.
+      # Single SSOT for ConceptRef → concept URI. Uses
+      # Glossarist::ConceptRef.qualified_id for the [source, id] string
+      # so external ConceptRefs don't collide with local ones of the
+      # same id.
       def concept_ref_uri(ref)
-        return nil unless ref.is_a?(Glossarist::ConceptRef)
-
-        slug = [ref.source, ref.id || ref.text].compact.reject(&:empty?)
-        return nil if slug.empty?
+        qualified = Glossarist::ConceptRef.qualified_id(ref)
+        return nil if qualified.nil?
 
         Glossarist::Rdf::Namespaces::GlossaristNamespace.uri +
-          "concept/#{slug.join('/')}"
+          "concept/#{qualified.split(':', 2).join('/')}"
       end
 
       def build_gloss_localized_concept(l10n, concept_id)

data/lib/glossarist/v3/abstract_hyperedge.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Glossarist
+  module V3
+    # AbstractHyperedge — abstract base shape for all n-ary
+    # concept-system relations (PartitiveHyperedge, GenericHyperedge,
+    # future AssociativeRelation, SequentialRelation).
+    #
+    # Carries the shared fields: comprehensive, members[2..*],
+    # completeness, criterion, sources, notes, status.
+    #
+    # Concrete leaves override `members` to specify the typed member
+    # class. Shared validations live here.
+    class AbstractHyperedge < Lutaml::Model::Serializable
+      DEFAULT_COMPLETENESS = "complete"
+
+      attribute :comprehensive, ConceptRef
+      attribute :members, HyperedgeMember, collection: true
+      attribute :completeness, :string,
+                values: Glossarist::GlossaryDefinition::COMPLETENESS_VALUES,
+                default: -> { DEFAULT_COMPLETENESS }
+      attribute :criterion, :hash
+      attribute :sources, ConceptSource, collection: true
+      attribute :notes, :hash
+      attribute :status, :string,
+                values: Glossarist::GlossaryDefinition::CONCEPT_STATUSES
+
+      # Per-file identity — set by RelationLoader on parse, used by
+      # HyperedgeWriter on serialize. The wire field is `$id` (JSON
+      # Schema convention); the value is `<comp-id>/<criterion-slug>`.
+      # Not in key_value because lutaml::Model key_value does not
+      # natively express `$`-prefixed keys; handled via custom
+      # round-trip in HyperedgeWriter / RelationLoader.
+      attr_accessor :file_id
+
+      key_value do
+        map :comprehensive, to: :comprehensive
+        map :members, to: :members
+        map :completeness, to: :completeness
+        map :criterion, to: :criterion
+        map :sources, to: :sources
+        map :notes, to: :notes
+        map :status, to: :status
+      end
+
+      def initialize(*)
+        if instance_of?(AbstractHyperedge)
+          raise NotImplementedError,
+                "AbstractHyperedge is abstract; instantiate " \
+                "PartitiveHyperedge or GenericHyperedge instead"
+        end
+
+        super
+      end
+
+      def validate!
+        validate_comprehensive!
+        validate_members!
+        validate_self_loop!
+        validate_completeness!
+        self
+      end
+
+      def complete?
+        completeness == "complete"
+      end
+
+      def partial?
+        completeness == "partial"
+      end
+
+      # ISO 704: a rake connects to two or more members. A single
+      # binary edge is not an n-ary relation.
+      def coordinate?
+        members.length >= 2
+      end
+
+      # Per-file identity derived from comprehensive + criterion.
+      # Format: `<comprehensive-id-dir>/<criterion-slug>` where the
+      # dir is `<source>-<id>` (downcased, kebab-case) and the slug
+      # is the English criterion (kebab-case) or a structural
+      # fallback. Stable across runs for the same content.
+      #
+      # Returns nil if comprehensive is empty.
+      def derived_file_id
+        return nil unless comprehensive.is_a?(ConceptRef) && comprehensive.id
+
+        comp_dir = comprehensive_dir_name
+        return nil unless comp_dir
+
+        slug = criterion_slug
+        "#{comp_dir}/#{slug}"
+      end
+
+      # File path under `relations/` directory. Uses #derived_file_id
+      # unless #file_id was explicitly set (e.g., by RelationLoader
+      # preserving the source path on parse).
+      def file_path(relations_dir)
+        id = file_id || derived_file_id
+        return nil unless id
+
+        File.join(relations_dir, "#{id}.yaml")
+      end
+
+      # Comprehensive concept as a directory-safe name:
+      # `<source>-<id>` lowercased, kebab-case, special chars
+      # (including dots) replaced with dashes. Matches the concept-model
+      # fixtures (vim-112-02-09, oiml-5-1, example-116-01-01).
+      def comprehensive_dir_name
+        return nil unless comprehensive.is_a?(ConceptRef)
+
+        parts = [comprehensive.source, comprehensive.id].compact.reject(&:empty?)
+        return nil if parts.empty?
+
+        parts.join("-").downcase.gsub(/[^a-z0-9\-]/, "-")
+             .gsub(/-{2,}/, "-").gsub(/\A-|-\z/, "")
+      end
+
+      # Kebab-case slug derived from the English criterion. Falls back
+      # to "decomposition-N" when no English criterion exists (N is
+      # derived from the criterion hash for stability).
+      def criterion_slug
+        eng = criterion.is_a?(Hash) ? (criterion["eng"] || criterion[:eng]) : nil
+        return "decomposition-#{criterion_hash}" if eng.nil? || eng.to_s.empty?
+
+        eng.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-\z/, "")
+      end
+
+      private
+
+      def criterion_hash
+        return "0" unless criterion.is_a?(Hash) && !criterion.empty?
+
+        Digest::MD5.hexdigest(criterion.sort.to_h.inspect)[0..5]
+      end
+
+      def validate_comprehensive!
+        return if comprehensive.is_a?(ConceptRef) &&
+          (comprehensive.source || comprehensive.id || comprehensive.text)
+
+        raise ArgumentError,
+              "#{self.class.name}#comprehensive must be a non-empty " \
+              "ConceptRef (source, id, or text required)"
+      end
+
+      def validate_members!
+        if members.empty?
+          raise ArgumentError, "#{self.class.name} requires at least one member"
+        end
+        unless coordinate?
+          raise ArgumentError,
+                "#{self.class.name} requires >=2 members (ISO 704); a single " \
+                "binary edge should be used instead"
+        end
+
+        members.each(&:validate!)
+      end
+
+      def validate_self_loop!
+        return unless comprehensive.is_a?(ConceptRef)
+
+        comp_key = [comprehensive.source, comprehensive.id]
+        members.each do |member|
+          next unless member.ref.is_a?(ConceptRef)
+          next unless comp_key == [member.ref.source, member.ref.id]
+
+          raise ArgumentError,
+                "#{self.class.name}#members cannot include the comprehensive"
+        end
+      end
+
+      def validate_completeness!
+        return if completeness.nil?
+
+        unless Glossarist::GlossaryDefinition::COMPLETENESS_VALUES
+            .include?(completeness)
+          raise ArgumentError,
+                "#{self.class.name}#completeness has invalid value " \
+                "#{completeness.inspect}; must be one of " \
+                "#{GlossaryDefinition::COMPLETENESS_VALUES.join(', ')}"
+        end
+      end
+    end
+  end
+end

data/lib/glossarist/v3/definition_type.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # DefinitionType — ISO 704:2022 §5.3 definition strategy constants.
+    #
+    # SSOT for the set of definition-type values. `DetailedDefinition#type`
+    # reads `VALUES` from here, not from `GlossaryDefinition`. The config
+    # (config.yml) feeds `GlossaryDefinition::DEFINITION_TYPE_VALUES`, which
+    # is consumed here so the source-of-truth chain is:
+    #
+    #     config.yml → GlossaryDefinition::DEFINITION_TYPE_VALUES
+    #                → DefinitionType::VALUES  (consumer-facing)
+    #                → DetailedDefinition#type (model attribute)
+    module DefinitionType
+      INTENSIONAL = "intensional"
+      EXTENSIONAL = "extensional"
+      PARTITIVE = "partitive"
+      TRANSLATED = "translated"
+
+      DEFAULT = INTENSIONAL
+
+      VALUES = Glossarist::GlossaryDefinition::DEFINITION_TYPE_VALUES.freeze
+
+      def self.valid?(value)
+        VALUES.include?(value)
+      end
+    end
+  end
+end

data/lib/glossarist/v3/detailed_definition.rb

@@ -6,9 +6,13 @@ module Glossarist
       attribute :sources, V3::ConceptSource, collection: true
       attribute :examples, V3::DetailedDefinition, collection: true,
                                                    initialize_empty: true
+      attribute :type, :string,
+                values: DefinitionType::VALUES,
+                default: -> { DefinitionType::DEFAULT }
 
       key_value do
         map :content, to: :content
+        map :type, to: :type
         map :sources, to: :sources
         map :examples, to: :examples
       end

data/lib/glossarist/v3/generic_hyperedge.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # GenericHyperedge — an ISO 704 / ISO 1087-1 / ISO 12620 generic
+    # hyperedge connecting a comprehensive concept (the genus) to two
+    # or more specific concepts (the species) which together
+    # constitute a decomposition by some criterion of subdivision.
+    #
+    # Mirror of PartitiveHyperedge. The `comprehensive` field denotes
+    # the genus concept. Multiple GenericHyperedges on the same
+    # comprehensive distinguished by `criterion` is the OIML pattern
+    # (5.1 measurement standard has 6 criterion groups).
+    #
+    # See docs/design/generic-relation.md (concept-model repo).
+    #
+    # The `key_value` mapping is inherited from AbstractHyperedge
+    # (single SSOT). Only the typed member collection is narrowed here.
+    #
+    # Per-class metadata block — see PartitiveHyperedge for field docs.
+    class GenericHyperedge < AbstractHyperedge
+      WIRE_KEY     = "generic_relations"
+      TYPE_TAG     = "generic_relation"
+      RDF_TYPE     = "gloss:GenericRelation"
+      MEMBER_CLASS = GenericMember
+      V1_WIRE_KEYS = [].freeze
+      KIND_LABEL   = "GEN"
+
+      attribute :members, GenericMember, collection: true
+    end
+
+    HyperedgeRegistry.register(GenericHyperedge)
+  end
+end

data/lib/glossarist/v3/generic_member.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # GenericMember — one member of a GenericHyperedge. Carries the same
+    # MECE dimensions as PartitiveMember; the comprehensive of its
+    # parent GenericHyperedge denotes the genus concept.
+    #
+    # See docs/design/generic-relation.md and docs/design/abstract-nary-relation.md
+    # (concept-model repo).
+    class GenericMember < HyperedgeMember
+      # Inherits all attributes and validations from HyperedgeMember.
+      # Declared as a distinct class for type safety and to leave room
+      # for future generic-specific extensions.
+    end
+  end
+end

data/lib/glossarist/v3/hyperedge_index.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # HyperedgeIndex — derived reverse-lookup index over a flat list
+    # of hyperedges.
+    #
+    # A hyperedge is directional: 1 comprehensive → N members. To
+    # answer the reverse query ("which hyperedges is X a member of?"),
+    # build a HyperedgeIndex on demand from the flat list and consult
+    # #for_member. The index is NOT stored on the concept — it's a
+    # derived view.
+    #
+    # Use cases:
+    #   index.for_comprehensive("OIML:5.1")
+    #     # => 6 hyperedges (different criteria — the OIML pattern)
+    #   index.for_member("OIML:5.13")
+    #     # => hyperedges where 5.13 appears as a member
+    class HyperedgeIndex
+      attr_reader :by_comprehensive, :by_member
+
+      def initialize(hyperedges)
+        @by_comprehensive = {}
+        @by_member = {}
+
+        Array(hyperedges).each do |h|
+          register_comprehensive(h)
+          register_members(h)
+        end
+
+        @by_comprehensive.freeze
+        @by_member.freeze
+      end
+
+      # All hyperedges where the given concept is the comprehensive.
+      # Accepts either a qualified-id string ("VIM:1.2") or a ConceptRef.
+      def for_comprehensive(qualified_id_or_ref)
+        key = resolve_key(qualified_id_or_ref)
+        @by_comprehensive[key] || []
+      end
+
+      # All hyperedges where the given concept is one of the members.
+      # Accepts either a qualified-id string or a ConceptRef.
+      def for_member(qualified_id_or_ref)
+        key = resolve_key(qualified_id_or_ref)
+        @by_member[key] || []
+      end
+
+      # Every concept that appears anywhere in this hyperedge set
+      # (as comprehensive OR as a member), with its roles.
+      def all_concept_ids
+        (@by_comprehensive.keys | @by_member.keys).freeze
+      end
+
+      private
+
+      def register_comprehensive(hyperedge)
+        return unless hyperedge.is_a?(AbstractHyperedge)
+
+        key = Glossarist::ConceptRef.qualified_id(hyperedge.comprehensive)
+        return unless key
+
+        (@by_comprehensive[key] ||= []) << hyperedge
+      end
+
+      def register_members(hyperedge)
+        return unless hyperedge.is_a?(AbstractHyperedge)
+
+        Array(hyperedge.members).each do |m|
+          next unless m.is_a?(HyperedgeMember)
+          next unless m.ref.is_a?(Glossarist::ConceptRef)
+
+          key = Glossarist::ConceptRef.qualified_id(m.ref)
+          next unless key
+
+          (@by_member[key] ||= []) << hyperedge
+        end
+      end
+
+      def resolve_key(qualified_id_or_ref)
+        if qualified_id_or_ref.is_a?(Glossarist::ConceptRef)
+          Glossarist::ConceptRef.qualified_id(qualified_id_or_ref)
+        else
+          qualified_id_or_ref.to_s
+        end
+      end
+    end
+  end
+end