glossarist 2.13.8 → 2.13.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 439b6f94f23e6018ec771d6032a05f83aac496fb4a03c8d33cebc793886cc8fa
-  data.tar.gz: 8462a0e92e3e0ff0a9b3447fe94ae1ce9d8f3b59ce10955daeb746a4c0b514d7
+  metadata.gz: 5e42372897ecf000813b37db02afdc6461039b9ee4618182515793d548bd9951
+  data.tar.gz: 33f5ba8dfb1b35782fc3711aa9ec7a0f1f675c55a0876c830975d4ca14770761
 SHA512:
-  metadata.gz: e6be9e8613779b1e7a791cc40df512e0592e9d3aa8d27d2339f80f04dc832e001024d412a71f20571e366b7be952581834e12e09dede444a8bf604a3b556e865
-  data.tar.gz: 37170de8e503b351d2e609fd91e294e10bd48f4ae53d20c81b3224737a6413cb53e593bab170e2ea9683f5583cc7969447492bd136ba1dcb2c559d707a9fe3eb
+  metadata.gz: 02d246dd723fd2f2834c54ac2e3d8f4a38251e543d7b677ed0ada8cd11af05cddfd41999f6772bbf8235ba486af8d76a603585185f4fd8475bcfaac22ce72a59
+  data.tar.gz: d1f34a759e7505afee75884ca7d5cbaa0b02f547ce8f1464317e00fc31fb011b4cd9820faa4a13d9eaa3e87c5daae74d93236cf940759d8b0cd7367996c00f78

data/lib/glossarist/v3/abstract_hyperedge.rb

@@ -77,6 +77,54 @@ module Glossarist
         members.length >= 2
       end
 
+      # ── External-concept awareness ─────────────────────────────────
+      #
+      # ISO 704:2022 diagrams use parenthetical notation for external
+      # concepts — concepts referenced from this dataset but defined
+      # elsewhere (status: external). Detection requires concept
+      # resolution (looking up the referenced concept's status), so
+      # these methods take a resolver block: `->(ref) { store.concept(ref) }`.
+      #
+      # The model stays pure — it does NOT carry a store reference.
+      # Consumers inject the resolver at query time.
+
+      # True if the comprehensive resolves (via the supplied resolver)
+      # to a concept with status: external.
+      def external_comprehensive?(resolver = nil)
+        return false unless comprehensive.is_a?(ConceptRef)
+        return false unless resolver
+
+        concept = resolver.call(comprehensive)
+        concept_is_external?(concept)
+      end
+
+      # Array of members whose refs resolve to status: external.
+      # Empty when no resolver is supplied (detection is opt-in).
+      def external_members(resolver = nil)
+        return [] unless resolver
+
+        members.select do |m|
+          next false unless m.is_a?(HyperedgeMember)
+          next false unless m.ref.is_a?(ConceptRef)
+
+          concept = resolver.call(m.ref)
+          concept_is_external?(concept)
+        end
+      end
+
+      # True if any external comprehensive or member lacks a
+      # `provided_by` edge — i.e., the decomposition dangles. The
+      # resolver is used twice: once to detect externals, once to
+      # check each external's related edges.
+      def dangling_externals?(resolver = nil)
+        return false unless resolver
+
+        candidates = []
+        candidates << comprehensive if external_comprehensive?(resolver)
+        candidates.concat(external_members(resolver).map(&:ref))
+        candidates.any? { |ref| !has_provided_by?(ref, resolver) }
+      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
@@ -130,6 +178,20 @@ module Glossarist
 
       private
 
+      def concept_is_external?(concept)
+        concept.respond_to?(:status) && concept.status == "external"
+      end
+
+      # True if the concept referenced by `ref` has at least one
+      # `provided_by` edge in its related list. The resolver must
+      # return a concept with a `related` collection.
+      def has_provided_by?(ref, resolver)
+        concept = resolver.call(ref)
+        return false unless concept.respond_to?(:related)
+
+        Array(concept.related).any? { |r| r.respond_to?(:type) && r.type == "provided_by" }
+      end
+
       def criterion_hash
         return "0" unless criterion.is_a?(Hash) && !criterion.empty?
 

data/lib/glossarist/v3/concept_system.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # ConceptSystem — first-class concept system entity per ISO 12620 A.7.
+    #
+    # Promotes the previously-implicit concept system (domains + tags +
+    # relation graph) to an explicit first-class entity. Per-file at
+    # `concept-systems/<id>.yaml`.
+    #
+    # A ConceptSystem carries:
+    #   - id: stable identifier
+    #   - name: localized human-readable name
+    #   - type: ConceptSystemType (generic / partitive / sequential /
+    #     associative / mixed)
+    #   - members: ConceptRefs of concepts in the system
+    #   - hyperedges: references to per-file hyperedge $ids
+    #   - root_concepts: top-level concepts (no superordinate)
+    #   - sources, status: provenance and lifecycle
+    #
+    # See docs/design/concept-systems.md in concept-model repo.
+    class ConceptSystem < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :name, :hash
+      attribute :type, :string,
+                values: Glossarist::V3::ConceptSystemType::VALUES
+      attribute :domain, ConceptRef
+      attribute :purpose, :hash
+      attribute :members, ConceptRef, collection: true
+      attribute :hyperedges, :string, collection: true
+      attribute :root_concepts, ConceptRef, collection: true
+      attribute :sources, ConceptSource, collection: true
+      attribute :status, :string
+
+      key_value do
+        map :id, to: :id
+        map :name, to: :name
+        map :type, to: :type
+        map :domain, to: :domain
+        map :purpose, to: :purpose
+        map :members, to: :members
+        map :hyperedges, to: :hyperedges
+        map :root_concepts, to: :root_concepts, with: { from: :root_concepts_from, to: :root_concepts_to }
+        map :sources, to: :sources
+        map :status, to: :status
+      end
+
+      def validate!
+        validate_id!
+        validate_name!
+        validate_type!
+        validate_members!
+        self
+      end
+
+      def generic? = type == ConceptSystemType::GENERIC
+      def partitive? = type == ConceptSystemType::PARTITIVE
+      def sequential? = type == ConceptSystemType::SEQUENTIAL
+      def associative? = type == ConceptSystemType::ASSOCIATIVE
+      def mixed? = type == ConceptSystemType::MIXED
+
+      private
+
+      def validate_id!
+        return if id && !id.to_s.empty?
+
+        raise ArgumentError, "ConceptSystem#id must be non-empty"
+      end
+
+      def validate_name!
+        return if name.is_a?(Hash) && !name.empty?
+
+        raise ArgumentError, "ConceptSystem#name must be a non-empty hash (localized)"
+      end
+
+      def validate_type!
+        return if ConceptSystemType::VALUES.include?(type)
+
+        raise ArgumentError,
+              "ConceptSystem#type #{type.inspect} invalid; " \
+              "must be one of #{ConceptSystemType::VALUES.join(', ')}"
+      end
+
+      def validate_members!
+        return if members.is_a?(Array) && members.length.positive?
+
+        raise ArgumentError, "ConceptSystem#members must have at least one entry"
+      end
+
+      def root_concepts_from(model, value)
+        model.root_concepts = Array(value).map do |entry|
+          entry.is_a?(ConceptRef) ? entry : ConceptRef.new(entry || {})
+        end
+      end
+
+      def root_concepts_to(model, _doc)
+        model.root_concepts&.map(&:to_hash)
+      end
+    end
+  end
+end

data/lib/glossarist/v3/concept_system_type.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # ConceptSystemType — ISO 12620 A.7.1 concept system type enum.
+    module ConceptSystemType
+      GENERIC = "generic"
+      PARTITIVE = "partitive"
+      SEQUENTIAL = "sequential"
+      ASSOCIATIVE = "associative"
+      MIXED = "mixed"
+
+      VALUES = [GENERIC, PARTITIVE, SEQUENTIAL, ASSOCIATIVE, MIXED].freeze
+    end
+  end
+end

data/lib/glossarist/v3/concept_type.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # ConceptType — ISO 704:2022 §5.2-5.3 general vs individual concept.
+    module ConceptType
+      GENERAL = "general"
+      INDIVIDUAL = "individual"
+
+      DEFAULT = GENERAL
+
+      VALUES = [GENERAL, INDIVIDUAL].freeze
+    end
+  end
+end

data/lib/glossarist/v3/equivalence_degree.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # EquivalenceDegree — ISO 704:2022 §7.7.3 cross-language equivalence.
+    module EquivalenceDegree
+      FULL = "full"
+      PARTIAL = "partial"
+      NONE = "none"
+      DIRECTIONAL = "directional"
+
+      DEFAULT = FULL
+
+      VALUES = [FULL, PARTIAL, NONE, DIRECTIONAL].freeze
+    end
+  end
+end

data/lib/glossarist/v3/sequential_hyperedge.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # SequentialHyperedge — an ISO 12620 A.6.3 / ISO 704:2022 §5.5.5
+    # sequential relation connecting a comprehensive concept to two or
+    # more subordinate concepts in an ORDERED sequence (temporal,
+    # spatial, causal, developmental).
+    #
+    # Mirror of PartitiveHyperedge and GenericHyperedge. Members are
+    # ORDERED — array order is significant. Reversing the array
+    # reverses the sequence.
+    class SequentialHyperedge < AbstractHyperedge
+      WIRE_KEY = "sequential_relations"
+      TYPE_TAG = "sequential_relation"
+      RDF_TYPE = "gloss:SequentialRelation"
+      V1_WIRE_KEYS = [].freeze
+
+      attribute :members, SequentialMember, collection: true
+
+      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
+
+      HyperedgeRegistry.register(SequentialHyperedge)
+    end
+  end
+end

data/lib/glossarist/v3/sequential_member.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module V3
+    # SequentialMember — one member of a SequentialHyperedge. Inherits
+    # the MECE shape from HyperedgeMember.
+    #
+    # Distinct leaf class for type safety. The member's POSITION IN THE
+    # ARRAY is significant for sequential hyperedges (unlike partitive
+    # and generic where order is insignificant).
+    class SequentialMember < HyperedgeMember
+      # Inherits all attributes and validations from HyperedgeMember.
+    end
+  end
+end

data/lib/glossarist/v3.rb

@@ -17,7 +17,13 @@ module Glossarist
     autoload :PartitiveMember, "glossarist/v3/partitive_member"
     autoload :GenericHyperedge, "glossarist/v3/generic_hyperedge"
     autoload :GenericMember, "glossarist/v3/generic_member"
+    autoload :SequentialHyperedge, "glossarist/v3/sequential_hyperedge"
+    autoload :SequentialMember, "glossarist/v3/sequential_member"
     autoload :DefinitionType, "glossarist/v3/definition_type"
+    autoload :ConceptType, "glossarist/v3/concept_type"
+    autoload :ConceptSystemType, "glossarist/v3/concept_system_type"
+    autoload :EquivalenceDegree, "glossarist/v3/equivalence_degree"
+    autoload :ConceptSystem, "glossarist/v3/concept_system"
     autoload :RelationLoader, "glossarist/v3/relation_loader"
     autoload :HyperedgeWriter, "glossarist/v3/hyperedge_writer"
     autoload :Multiplicity, "glossarist/v3/multiplicity"
@@ -44,9 +50,12 @@ module Glossarist
     Configuration.register_model(PartitiveMember, id: :partitive_member)
     Configuration.register_model(GenericHyperedge, id: :generic_hyperedge)
     Configuration.register_model(GenericMember, id: :generic_member)
+    Configuration.register_model(SequentialHyperedge, id: :sequential_hyperedge)
+    Configuration.register_model(SequentialMember, id: :sequential_member)
     Configuration.register_model(ManagedConceptData, id: :managed_concept_data)
     Configuration.register_model(ManagedConcept, id: :managed_concept)
     Configuration.register_model(ConceptDocument, id: :concept_document)
+    Configuration.register_model(ConceptSystem, id: :concept_system)
 
     # Eager-load concrete hyperedge leaves so HyperedgeRegistry
     # auto-populates via AbstractHyperedge.inherited. Without this,
@@ -54,5 +63,6 @@ module Glossarist
     # the registry empty at boot.
     PartitiveHyperedge
     GenericHyperedge
+    SequentialHyperedge
   end
 end

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

@@ -17,13 +17,21 @@ module Glossarist
       # — 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, :relations
+        attr_reader :concept, :file_name, :collection_context, :relations,
+                    :concept_resolver
 
-        def initialize(concept, file_name:, collection_context:, relations: [])
+        # `concept_resolver` is an optional callable that takes a
+        # ConceptRef and returns the resolved ManagedConcept (or nil).
+        # Rules that need cross-concept lookups (e.g.,
+        # ExternalConceptRule's dangling-external detection) use this.
+        # When nil, those rules no-op.
+        def initialize(concept, file_name:, collection_context:, relations: [],
+                       concept_resolver: nil)
           @concept = concept
           @file_name = file_name
           @collection_context = collection_context
           @relations = Array(relations)
+          @concept_resolver = concept_resolver
         end
 
         def concept_id

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Validation
+    module Rules
+      # Validates that extensional definitions do not contain open-ended
+      # wording, per ISO 704:2022 §6.4.5.1. An extensional definition
+      # must be an EXHAUSTIVE enumeration — open-ended wordings like
+      # `...`, `etc.`, `and so on`, `and similar`, `and others`,
+      # `including` violate this principle because they imply the
+      # enumeration is incomplete.
+      #
+      # Mirrors concept-model's `check-definition-rules`
+      # §6.4.5.1 open-ended-wording check, exposed as a consumer-side
+      # Validation::Rule.
+      #
+      # Scope: concept (rule runs once per concept). Inspects every
+      # DetailedDefinition with `type: extensional` across all of the
+      # concept's localized definitions.
+      class ExtensionalDefinitionRule < Base
+        # ISO 704:2022 §6.4.5.1 — patterns that signal incomplete
+        # enumeration in an extensional definition. The list is
+        # intentionally conservative: only wordings that clearly
+        # indicate "more exist beyond what's listed."
+        OPEN_ENDED_PATTERNS = [
+          /\.\.\./,                         # ellipsis
+          /\betc\b\.?/i,                    # etc / etc.
+          /\band\s+similar\b/i,             # and similar
+          /\band\s+so\s+on\b/i,             # and so on
+          /\band\s+the\s+like\b/i,          # and the like
+          /\band\s+others?\b/i,             # and other / and others
+          /\bsuch\s+as\b/i,                 # such as (often partial)
+          /\bincluding\b/i,                 # including (often partial)
+          /\be\.?g\.?\b/i,                  # e.g. / eg
+        ].freeze
+
+        def code = "GLS-223"
+        def category = :schema
+        def severity = "warning"
+        def scope = :concept
+
+        def applicable?(context)
+          return false unless context.concept.is_a?(V3::ManagedConcept)
+
+          concept_has_extensional_definition?(context.concept)
+        end
+
+        def check(context)
+          issues = []
+
+          each_extensional_definition(context.concept) do |l10n_lang, defn, path|
+            check_definition(defn, l10n_lang, path, context.file_name, issues)
+          end
+
+          issues
+        end
+
+        private
+
+        def concept_has_extensional_definition?(concept)
+          each_extensional_definition(concept).any? { true }
+        rescue StopIteration
+          false
+        end
+
+        # Yields (lang, definition, path_string) for every extensional
+        # definition on every localization of the concept.
+        def each_extensional_definition(concept)
+          return enum_for(:each_extensional_definition, concept) unless block_given?
+
+          concept.localizations.each_value do |l10n|
+            next unless l10n.respond_to?(:data)
+
+            lang = l10n.language_code
+            %i[definition examples notes].each do |field|
+              value = l10n.data&.public_send(field)
+              next if value.nil?
+
+              Array(value).each_with_index do |item, idx|
+                next unless item.is_a?(Glossarist::DetailedDefinition) ||
+                  item.is_a?(V3::DetailedDefinition)
+                next unless item.type.to_s == "extensional"
+
+                yield lang, item, "#{field}[#{idx}]"
+              end
+            end
+          end
+        end
+
+        def check_definition(defn, lang, path, fname, issues)
+          content = extract_content(defn)
+          return if content.nil? || content.empty?
+
+          OPEN_ENDED_PATTERNS.each do |pattern|
+            match = content.match(pattern)
+            next unless match
+
+            issues << issue(
+              "#{path} (#{lang}) extensional definition contains " \
+              "open-ended wording #{match[0].inspect}; ISO 704:2022 " \
+              "§6.4.5.1 requires exhaustive enumeration in " \
+              "extensional definitions",
+              location: fname,
+              severity: "warning",
+              suggestion: "Either enumerate all instances exhaustively, " \
+                          "or change the definition type to intensional.",
+            )
+            break # one issue per definition is enough
+          end
+        end
+
+        def extract_content(definition)
+          return definition.content if definition.respond_to?(:content)
+
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Validation
+    module Rules
+      # Validates that external concepts referenced by hyperedges have
+      # a `provided_by` edge for resolution. Mirrors concept-model's
+      # `check-external-as-comprehensive` validator, exposed as a
+      # consumer-side Validation::Rule so it runs in the standard
+      # validation pipeline.
+      #
+      # Per concept-model docs/design/external-concepts.md: an external
+      # concept (status: external) is referenced from this dataset but
+      # defined elsewhere. Without a `provided_by` edge, the reference
+      # dangles — there is no resolvable target. ISO 704 models this
+      # case as a parenthetical term in the diagram; the data model
+      # requires the resolution edge to exist.
+      #
+      # Scope: concept (rule runs once per concept). The concept's
+      # relations are inspected via `context.relations`; each
+      # relation's comprehensive + members are checked.
+      #
+      # Requires a `concept_resolver` on the context. Without one,
+      # the rule is a no-op (cannot detect externals without
+      # resolution).
+      class ExternalConceptRule < Base
+        def code = "GLS-222"
+        def category = :schema
+        def severity = "warning"
+        def scope = :concept
+
+        def applicable?(context)
+          return false unless context.concept.is_a?(V3::ManagedConcept)
+          return false unless context.concept_resolver
+          return false if context.relations.empty?
+
+          true
+        end
+
+        def check(context)
+          resolver = context.concept_resolver
+          issues = []
+
+          context.relations.each_with_index do |rel, idx|
+            check_comprehensive(rel, idx, context.file_name, resolver, issues)
+            check_members(rel, idx, context.file_name, resolver, issues)
+          end
+
+          issues
+        end
+
+        private
+
+        def check_comprehensive(rel, idx, fname, resolver, issues)
+          return unless rel.external_comprehensive?(resolver)
+
+          comp_id = Glossarist::ConceptRef.qualified_id(rel.comprehensive)
+          issues << issue(
+            "relation #{idx + 1} comprehensive #{comp_id.inspect} is " \
+            "external (status: external) — confirm a `provided_by` edge " \
+            "exists on the external concept so the decomposition resolves",
+            location: fname,
+            severity: "info",
+            suggestion: "Add `provided_by` to #{comp_id}'s related list.",
+          )
+        end
+
+        def check_members(rel, idx, fname, resolver, issues)
+          rel.external_members(resolver).each_with_index do |member, mi|
+            member_id = Glossarist::ConceptRef.qualified_id(member.ref)
+            has_resolution = resolver.call(member.ref)&.related&.any? do |r|
+              r.respond_to?(:type) && r.type == "provided_by"
+            end
+
+            next if has_resolution
+
+            issues << issue(
+              "relation #{idx + 1}.members[#{mi}] #{member_id.inspect} is " \
+              "external (status: external) without a `provided_by` edge — " \
+              "the decomposition dangles; no resolvable target",
+              location: fname,
+              severity: "warning",
+              suggestion: "Add `provided_by` to #{member_id}'s related " \
+                          "list, or define the concept in this dataset.",
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/glossarist/version.rb

@@ -4,5 +4,5 @@
 #
 
 module Glossarist
-  VERSION = "2.13.8"
+  VERSION = "2.13.9"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glossarist
 version: !ruby/object:Gem::Version
-  version: 2.13.8
+  version: 2.13.9
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-30 00:00:00.000000000 Z
+date: 2026-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -398,9 +398,13 @@ files:
 - lib/glossarist/v3/concept_document.rb
 - lib/glossarist/v3/concept_ref.rb
 - lib/glossarist/v3/concept_source.rb
+- lib/glossarist/v3/concept_system.rb
+- lib/glossarist/v3/concept_system_type.rb
+- lib/glossarist/v3/concept_type.rb
 - lib/glossarist/v3/configuration.rb
 - lib/glossarist/v3/definition_type.rb
 - lib/glossarist/v3/detailed_definition.rb
+- lib/glossarist/v3/equivalence_degree.rb
 - lib/glossarist/v3/generic_hyperedge.rb
 - lib/glossarist/v3/generic_member.rb
 - lib/glossarist/v3/hyperedge_index.rb
@@ -415,6 +419,8 @@ files:
 - lib/glossarist/v3/partitive_member.rb
 - lib/glossarist/v3/related_concept.rb
 - lib/glossarist/v3/relation_loader.rb
+- lib/glossarist/v3/sequential_hyperedge.rb
+- lib/glossarist/v3/sequential_member.rb
 - lib/glossarist/validation.rb
 - lib/glossarist/validation/asset_index.rb
 - lib/glossarist/validation/bibliography_index.rb
@@ -442,6 +448,8 @@ files:
 - lib/glossarist/validation/rules/domain_target_rule.rb
 - lib/glossarist/validation/rules/duplicate_term_rule.rb
 - lib/glossarist/validation/rules/entry_status_rule.rb
+- lib/glossarist/validation/rules/extensional_definition_rule.rb
+- lib/glossarist/validation/rules/external_concept_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