glossarist 2.13.5 → 2.13.7

data/lib/glossarist/v3/relation_loader.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+module Glossarist
+  module V3
+    # RelationLoader — scans a directory for per-file hyperedge files
+    # and returns typed instances.
+    #
+    # Files live at `relations/<comprehensive-id>/<criterion-slug>.yaml`.
+    # The `type` field on each file discriminates which concrete
+    # hyperedge class to instantiate. Dispatch is via HyperedgeRegistry
+    # — adding a new hyperedge type requires no edit here.
+    #
+    # Usage:
+    #   relations = RelationLoader.load_all("path/to/dataset/relations")
+    #   partitive = RelationLoader.load_for_concept("path/to/dataset", "5-1")
+    class RelationLoader
+      class LoadError < ::StandardError
+      end
+
+      class << self
+        # Load every relation file under `dir`. Returns a hash keyed
+        # by comprehensive id, value = array of typed hyperedges.
+        def load_all(dir)
+          new(dir).load_all
+        end
+
+        # Load all relation files for a single comprehensive id.
+        # `dataset_root` is the path containing the `relations/` directory.
+        def load_for_concept(dataset_root, comprehensive_id)
+          new(File.join(dataset_root, "relations")).load_for_comprehensive(comprehensive_id)
+        end
+
+        # Load a single relation file. Returns a typed hyperedge
+        # instance (PartitiveHyperedge, GenericHyperedge, etc.).
+        def load_file(path)
+          new(File.dirname(path, 2)).load_path(path)
+        end
+      end
+
+      def initialize(relations_dir)
+        @relations_dir = Pathname.new(relations_dir)
+      end
+
+      def load_all
+        each_relation_path.with_object({}) do |path, h|
+          rel = load_path(path)
+          comp_id = Glossarist::ConceptRef.qualified_id(rel.comprehensive)
+          (h[comp_id] ||= []) << rel
+        end
+      end
+
+      def load_for_comprehensive(comprehensive_id)
+        dir = @relations_dir.join(comprehensive_id.to_s)
+        return [] unless dir.exist?
+
+        Dir.glob("#{dir}/*.yaml").map { |p| load_path(Pathname.new(p)) }
+      end
+
+      def load_path(path)
+        path = Pathname.new(path)
+        doc = YAML.load_file(path)
+        unless doc.is_a?(Hash) && doc["type"]
+          raise LoadError, "#{path} missing required `type` field"
+        end
+
+        klass = HyperedgeRegistry.for_type_tag(doc["type"])
+        unless klass
+          known = HyperedgeRegistry.all_classes.map { |c| c::TYPE_TAG }.join(", ")
+          raise LoadError, "#{path} has unknown type #{doc['type'].inspect}; " \
+                           "expected one of #{known}"
+        end
+
+        # Preserve the source $id so round-trip writes go to the same
+        # file path. Without this, write-back would derive a new path
+        # from comprehensive + criterion and could fragment files.
+        file_id = doc["$id"]
+        instance = klass.from_hash(doc)
+        instance.file_id = file_id if file_id && instance.respond_to?(:file_id=)
+        instance
+      end
+
+      private
+
+      def each_relation_path
+        return enum_for(:each_relation_path) unless block_given?
+
+        return unless @relations_dir.exist?
+
+        Dir.glob("#{@relations_dir}/**/*.yaml").each do |p|
+          yield Pathname.new(p)
+        end
+      end
+    end
+  end
+end

data/lib/glossarist/v3.rb

@@ -9,14 +9,17 @@ module Glossarist
     autoload :DetailedDefinition, "glossarist/v3/detailed_definition"
     autoload :ConceptRef, "glossarist/v3/concept_ref"
     autoload :RelatedConcept, "glossarist/v3/related_concept"
-    autoload :PartitiveRelation, "glossarist/v3/partitive_relation"
+    autoload :HyperedgeMember, "glossarist/v3/hyperedge_member"
+    autoload :AbstractHyperedge, "glossarist/v3/abstract_hyperedge"
+    autoload :HyperedgeRegistry, "glossarist/v3/hyperedge_registry"
+    autoload :HyperedgeIndex, "glossarist/v3/hyperedge_index"
+    autoload :PartitiveHyperedge, "glossarist/v3/partitive_hyperedge"
     autoload :PartitiveMember, "glossarist/v3/partitive_member"
-    # Multiplicity is a derived-view utility module (SSOT for the
-    # ISO 704:2022 (presence, count) → name mapping), not a Lutaml
-    # model — so it is autoloaded but NOT registered via
-    # Configuration.register_model. Used by renderers/viewers to
-    # display the ISO name; the PartitiveMember model itself only
-    # carries the orthogonal presence + count dimensions.
+    autoload :GenericHyperedge, "glossarist/v3/generic_hyperedge"
+    autoload :GenericMember, "glossarist/v3/generic_member"
+    autoload :DefinitionType, "glossarist/v3/definition_type"
+    autoload :RelationLoader, "glossarist/v3/relation_loader"
+    autoload :HyperedgeWriter, "glossarist/v3/hyperedge_writer"
     autoload :Multiplicity, "glossarist/v3/multiplicity"
     autoload :ConceptData, "glossarist/v3/concept_data"
     autoload :LocalizedConcept, "glossarist/v3/localized_concept"
@@ -32,10 +35,24 @@ module Glossarist
     Configuration.register_model(LocalizedConcept, id: :localized_concept)
     Configuration.register_model(ConceptRef, id: :concept_ref)
     Configuration.register_model(RelatedConcept, id: :related_concept)
-    Configuration.register_model(PartitiveRelation, id: :partitive_relation)
+    # HyperedgeMember and AbstractHyperedge are abstract base classes —
+    # they are NOT registered as Lutaml models because they must not be
+    # instantiable directly. Concrete leaves (PartitiveHyperedge,
+    # GenericHyperedge, PartitiveMember, GenericMember) are registered
+    # below and also auto-registered with HyperedgeRegistry.
+    Configuration.register_model(PartitiveHyperedge, id: :partitive_hyperedge)
     Configuration.register_model(PartitiveMember, id: :partitive_member)
+    Configuration.register_model(GenericHyperedge, id: :generic_hyperedge)
+    Configuration.register_model(GenericMember, id: :generic_member)
     Configuration.register_model(ManagedConceptData, id: :managed_concept_data)
     Configuration.register_model(ManagedConcept, id: :managed_concept)
     Configuration.register_model(ConceptDocument, id: :concept_document)
+
+    # Eager-load concrete hyperedge leaves so HyperedgeRegistry
+    # auto-populates via AbstractHyperedge.inherited. Without this,
+    # autoload defers leaf definition until first reference, leaving
+    # the registry empty at boot.
+    PartitiveHyperedge
+    GenericHyperedge
   end
 end

data/lib/glossarist/validation/rules/concept_context.rb

@@ -9,13 +9,21 @@ module Glossarist
       # rules examining the same concept share one extraction pass (DRY,
       # single source of truth). Rules ask the context for references rather
       # than instantiating their own ReferenceExtractor.
+      #
+      # In V3, n-ary relations (PartitiveHyperedge, GenericHyperedge) are
+      # per-file (see Glossarist::V3::RelationLoader). Each concept's
+      # relations are looked up via the relations lookup passed here.
+      # Pass an explicit `relations:` list when constructing the context
+      # — the loader does not run on demand so the validator behaviour
+      # is fully deterministic given the load.
       class ConceptContext
-        attr_reader :concept, :file_name, :collection_context
+        attr_reader :concept, :file_name, :collection_context, :relations
 
-        def initialize(concept, file_name:, collection_context:)
+        def initialize(concept, file_name:, collection_context:, relations: [])
           @concept = concept
           @file_name = file_name
           @collection_context = collection_context
+          @relations = Array(relations)
         end
 
         def concept_id

data/lib/glossarist/validation/rules/{partitive_relation_rule.rb → hyperedge_coherence_rule.rb}

@@ -3,14 +3,17 @@
 module Glossarist
   module Validation
     module Rules
-      # Validates semantic invariants of PartitiveRelation entries
-      # that the model constructor does NOT enforce. Specifically:
+      # Validates semantic invariants of n-ary relation entries
+      # (PartitiveHyperedge, GenericHyperedge) that the model constructor
+      # does NOT enforce. The relations are passed in via the
+      # ConceptContext (per-file storage — see Glossarist::V3::RelationLoader).
       #
-      #   - error when a relation has fewer than 2 partitives
-      #     (ISO 704: "two or more"; single binary should use
+      # Checks:
+      #   - error when a relation has fewer than 2 members
+      #     (ISO 704: "two or more"; single binary should use a
       #     has_part edge instead)
       #   - error when two relations share the same comprehensive
-      #     AND the same non-nil criterion (duplicate decomposition;
+      #     AND the same non-empty criterion (duplicate decomposition;
       #     ISO 12620 coordinate-concept coherence)
       #   - warning when a relation has no criterion (cannot
       #     distinguish from siblings sharing the comprehensive)
@@ -21,12 +24,16 @@ module Glossarist
       #     at least one designation
       #
       # The model constructor already rejects empty comprehensive,
-      # empty partitives list, self-loops, invalid enum values, and
+      # empty members list, self-loops, invalid enum values, and
       # the optional + at_least_one combination.
-      class PartitiveRelationRule < Base
+      class HyperedgeCoherenceRule < Base
         DEFAULT_PRESENCE = "required"
         DEFAULT_COUNT = "exactly_one"
 
+        # Stable identifier for downstream issue trackers / config.
+        # Originally assigned when the rule was partitive-only; kept
+        # after the rename to GenericHyperedge + n-ary generalization
+        # so existing suppression configs continue to work.
         def code = "GLS-221"
         def category = :schema
         def severity = "error"
@@ -36,18 +43,17 @@ module Glossarist
           concept = context.concept
           return false unless concept.is_a?(V3::ManagedConcept)
 
-          concept.partitive_relations&.any? || external?(concept)
+          context.relations&.any? || external?(concept)
         end
 
         def check(context)
           concept = context.concept
           fname = context.file_name
+          relations = context.relations
           issues = []
 
           return issues unless concept.is_a?(V3::ManagedConcept)
 
-          relations = Array(concept.partitive_relations)
-
           relations.each_with_index do |rel, idx|
             check_cardinality(rel, idx, fname, issues)
             check_criterion_present(rel, idx, fname, issues)
@@ -67,10 +73,10 @@ module Glossarist
         end
 
         def check_cardinality(rel, idx, fname, issues)
-          return if rel.partitives.length >= 2
+          return if rel.members.length >= 2
 
           issues << issue(
-            "partitive_relation #{idx + 1} has fewer than 2 partitives " \
+            "relation #{idx + 1} has fewer than 2 members " \
             "(ISO 704 requires two or more); a single binary has_part edge " \
             "should be used instead",
             location: fname,
@@ -81,7 +87,7 @@ module Glossarist
           return if rel.criterion && !rel.criterion.empty?
 
           issues << issue(
-            "partitive_relation #{idx + 1} has no criterion; cannot verify " \
+            "relation #{idx + 1} has no criterion; cannot verify " \
             "distinctness from sibling relations sharing the comprehensive " \
             "(ISO 12620 coordinate-concept coherence)",
             severity: "warning",
@@ -97,14 +103,14 @@ module Glossarist
         # legal; the warning encourages an explicit, reviewed choice
         # rather than an accidental non-default.
         def check_member_dimensions(rel, idx, fname, issues)
-          rel.partitives.each_with_index do |member, mi|
+          rel.members.each_with_index do |member, mi|
             non_default = []
             non_default << "presence='#{member.presence}'" if member.presence != DEFAULT_PRESENCE
             non_default << "count='#{member.count}'" if member.count != DEFAULT_COUNT
             next if non_default.empty?
 
             issues << issue(
-              "partitive_relation #{idx + 1}.partitives[#{mi}] uses " \
+              "relation #{idx + 1}.members[#{mi}] uses " \
               "non-default #{non_default.join(' ')} " \
               "(defaults: presence=#{DEFAULT_PRESENCE}, count=#{DEFAULT_COUNT}) " \
               "— confirm the dimensions are intentional",
@@ -129,7 +135,7 @@ module Glossarist
             next if idxs.length == 1
 
             issues << issue(
-              "duplicate PartitiveRelation for comprehensive " \
+              "duplicate relation for comprehensive " \
               "#{key.first.inspect} with criterion #{key.last.inspect} " \
               "(relations ##{idxs.map { |i| i + 1 }.join(', ')}); " \
               "two relations sharing comprehensive AND criterion are the " \

data/lib/glossarist/version.rb

@@ -4,5 +4,5 @@
 #
 
 module Glossarist
-  VERSION = "2.13.5"
+  VERSION = "2.13.7"
 end

data/lib/glossarist.rb

@@ -85,6 +85,7 @@ module Glossarist
   autoload :VERSION,                  "glossarist/version"
   autoload :GlossaryDefinition,       "glossarist/glossary_definition"
   autoload :GlossaryStore,            "glossarist/glossary_store"
+  autoload :Tasks,                    "glossarist/tasks"
 
   LANG_CODES = %w[eng ara deu fra spa ita jpn kor pol por srp swe zho rus fin
                   dan nld msa nob nno].freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glossarist
 version: !ruby/object:Gem::Version
-  version: 2.13.5
+  version: 2.13.7
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-28 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -296,6 +296,7 @@ files:
 - lib/glossarist/non_verbal_reference.rb
 - lib/glossarist/pronunciation.rb
 - lib/glossarist/rdf.rb
+- lib/glossarist/rdf/deterministic_slug.rb
 - lib/glossarist/rdf/gloss_citation.rb
 - lib/glossarist/rdf/gloss_concept.rb
 - lib/glossarist/rdf/gloss_concept_date.rb
@@ -306,9 +307,13 @@ files:
 - lib/glossarist/rdf/gloss_figure.rb
 - lib/glossarist/rdf/gloss_figure_image.rb
 - lib/glossarist/rdf/gloss_formula.rb
+- lib/glossarist/rdf/gloss_generic_member.rb
+- lib/glossarist/rdf/gloss_generic_relation.rb
 - lib/glossarist/rdf/gloss_grammar_info.rb
 - lib/glossarist/rdf/gloss_locality.rb
 - lib/glossarist/rdf/gloss_localized_concept.rb
+- lib/glossarist/rdf/gloss_nary_member.rb
+- lib/glossarist/rdf/gloss_nary_relation.rb
 - lib/glossarist/rdf/gloss_non_verbal_rep.rb
 - lib/glossarist/rdf/gloss_partitive_member.rb
 - lib/glossarist/rdf/gloss_partitive_relation.rb
@@ -358,6 +363,7 @@ files:
 - lib/glossarist/sts/term_mapper.rb
 - lib/glossarist/table.rb
 - lib/glossarist/table_reference.rb
+- lib/glossarist/tasks.rb
 - lib/glossarist/tasks/shacl.rake
 - lib/glossarist/tasks/sync.rake
 - lib/glossarist/tasks/sync_model.rb
@@ -385,6 +391,7 @@ files:
 - lib/glossarist/v2/managed_concept_data.rb
 - lib/glossarist/v2/related_concept.rb
 - lib/glossarist/v3.rb
+- lib/glossarist/v3/abstract_hyperedge.rb
 - lib/glossarist/v3/citation.rb
 - lib/glossarist/v3/concept_data.rb
 - lib/glossarist/v3/concept_date.rb
@@ -392,14 +399,22 @@ files:
 - lib/glossarist/v3/concept_ref.rb
 - lib/glossarist/v3/concept_source.rb
 - lib/glossarist/v3/configuration.rb
+- lib/glossarist/v3/definition_type.rb
 - lib/glossarist/v3/detailed_definition.rb
+- lib/glossarist/v3/generic_hyperedge.rb
+- lib/glossarist/v3/generic_member.rb
+- lib/glossarist/v3/hyperedge_index.rb
+- lib/glossarist/v3/hyperedge_member.rb
+- lib/glossarist/v3/hyperedge_registry.rb
+- lib/glossarist/v3/hyperedge_writer.rb
 - lib/glossarist/v3/localized_concept.rb
 - lib/glossarist/v3/managed_concept.rb
 - lib/glossarist/v3/managed_concept_data.rb
 - lib/glossarist/v3/multiplicity.rb
+- lib/glossarist/v3/partitive_hyperedge.rb
 - lib/glossarist/v3/partitive_member.rb
-- lib/glossarist/v3/partitive_relation.rb
 - lib/glossarist/v3/related_concept.rb
+- lib/glossarist/v3/relation_loader.rb
 - lib/glossarist/validation.rb
 - lib/glossarist/validation/asset_index.rb
 - lib/glossarist/validation/bibliography_index.rb
@@ -429,6 +444,7 @@ files:
 - lib/glossarist/validation/rules/entry_status_rule.rb
 - lib/glossarist/validation/rules/filename_id_rule.rb
 - lib/glossarist/validation/rules/gcr_context.rb
+- lib/glossarist/validation/rules/hyperedge_coherence_rule.rb
 - lib/glossarist/validation/rules/image_reference_rule.rb
 - lib/glossarist/validation/rules/l10n_uuid_integrity_rule.rb
 - lib/glossarist/validation/rules/language_code_format_rule.rb
@@ -441,7 +457,6 @@ files:
 - lib/glossarist/validation/rules/orphaned_bibliography_rule.rb
 - lib/glossarist/validation/rules/orphaned_images_rule.rb
 - lib/glossarist/validation/rules/orphaned_l10n_files_rule.rb
-- lib/glossarist/validation/rules/partitive_relation_rule.rb
 - lib/glossarist/validation/rules/preferred_term_rule.rb
 - lib/glossarist/validation/rules/ref_shape_rule.rb
 - lib/glossarist/validation/rules/registry.rb

data/lib/glossarist/v3/partitive_relation.rb

@@ -1,114 +0,0 @@
-# frozen_string_literal: true
-
-module Glossarist
-  module V3
-    # PartitiveRelation — an ISO 704 / ISO 1087-1 / ISO 12620
-    # partitive relation connecting a comprehensive concept
-    # (superordinate concept partitive) to two or more partitive
-    # concepts (subordinate concepts partitive) which fitted together
-    # constitute the comprehensive.
-    #
-    # Shown as a rake or bracket in source diagrams. All partitives
-    # within one relation are coordinate concepts: they share the
-    # comprehensive AND share the criterion of subdivision.
-    #
-    # Per-partitive metadata (ISO 704:2022, MECE decomposition):
-    #   - presence (required, optional) — line style: solid vs dashed
-    #   - count (exactly_one, at_least_one, multiple) — line count
-    #   - is_delimiting — orthogonal flag; a delimiting part behaves
-    #     like a delimiting characteristic (distinguishes the
-    #     comprehensive from coordinate concepts)
-    #
-    # Replaces the prior PartitiveHyperedge class. The "hyperedge"
-    # framing was graph-theoretic; ISO calls this a *relation*.
-    class PartitiveRelation < Lutaml::Model::Serializable
-      DEFAULT_COMPLETENESS = "complete"
-
-      attribute :comprehensive, ConceptRef
-      attribute :partitives, PartitiveMember, collection: true
-      attribute :completeness, :string,
-                values: Glossarist::GlossaryDefinition::COMPLETENESS_VALUES,
-                default: -> { DEFAULT_COMPLETENESS }
-      attribute :criterion, :hash
-
-      key_value do
-        map :comprehensive, to: :comprehensive
-        map :partitives, to: :partitives
-        map :completeness, to: :completeness
-        map :criterion, to: :criterion
-      end
-
-      def validate!
-        validate_comprehensive!
-        validate_partitives!
-        validate_self_loop!
-        validate_completeness!
-        self
-      end
-
-      def complete?
-        completeness == "complete"
-      end
-
-      def partial?
-        completeness == "partial"
-      end
-
-      # ISO 704: a partitive relation connects to two or more
-      # partitives. A single binary has_part edge is not a
-      # PartitiveRelation.
-      def coordinate?
-        partitives.length >= 2
-      end
-
-      private
-
-      def validate_comprehensive!
-        return if comprehensive.is_a?(ConceptRef) &&
-                  (comprehensive.source || comprehensive.id || comprehensive.text)
-
-        raise ArgumentError,
-              "PartitiveRelation#comprehensive must be a non-empty " \
-              "ConceptRef (source, id, or text required)"
-      end
-
-      def validate_partitives!
-        if partitives.empty?
-          raise ArgumentError, "PartitiveRelation requires at least one partitive"
-        end
-        unless coordinate?
-          raise ArgumentError,
-                "PartitiveRelation requires ≥2 partitives (ISO 704); a single " \
-                "binary has_part edge should be used instead"
-        end
-
-        partitives.each(&:validate!)
-      end
-
-      def validate_self_loop!
-        return unless comprehensive.is_a?(ConceptRef)
-
-        comp_key = [comprehensive.source, comprehensive.id]
-        partitives.each do |member|
-          next unless member.ref.is_a?(ConceptRef)
-          next unless [member.ref.source, member.ref.id] == comp_key
-
-          raise ArgumentError,
-                "PartitiveRelation#partitives cannot include the comprehensive"
-        end
-      end
-
-      def validate_completeness!
-        return if completeness.nil?
-
-        unless Glossarist::GlossaryDefinition::COMPLETENESS_VALUES
-                 .include?(completeness)
-          raise ArgumentError,
-                "PartitiveRelation#completeness has invalid value " \
-                "#{completeness.inspect}; must be one of " \
-                "#{GlossaryDefinition::COMPLETENESS_VALUES.join(', ')}"
-        end
-      end
-    end
-  end
-end