glossarist 2.8.7 → 2.8.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6de74f1a2e3c9d3379f35ccf94a46a0d407149329e27fa95521e40e8a22c883
-  data.tar.gz: 2159f19a3d6c355b7bafba1f76d3f673fe3a0813af919479c1835dbcd609dbd7
+  metadata.gz: 3d52bb386f776f12beb9671c25c5f1ce8330ff8349df68d734c80fa3937cec6f
+  data.tar.gz: 43cab5da334046a266967ba590d9791ee56f1fe283110075c880ddb8f5ec8344
 SHA512:
-  metadata.gz: 9c46b4f37c08ce6d40158098c5b39006b319a3dab247660a43aa4ebb82ba7527ee9898ccf1513e960abf56a6987dea8b083d9b11b4cff2306d66e5e0b054af03
-  data.tar.gz: 4bb9c91a99347f353bcabb17702d13e295f50323173c8fd25fde164af7ac0ea117d38542b9e03449fd386e253f31cd003832310ce5cc5b3f85e4c34978a33fdd
+  metadata.gz: 6364fe8da9e37fdf669b2064fa244ad7f97f745cc4059243e4d1a337e710aff0ad1f1a6034573504b6106708cc9ed153e8fd9a6f1396d504c5d8b45e917c6e15
+  data.tar.gz: 71ac705f2149e4995b1476a2802a3f5361e8d8733435d3fda15b7f2033d4ac62c72183b11770032bda22c6e6de8fadc8798f80c6f9af636b2e06828571d16d30

data/.gitignore

@@ -25,3 +25,5 @@ spec/fixtures/relaton_cache/
 TODO*
 
 *.gem
+*.orig
+PROPOSAL.*

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-06-09 09:29:01 UTC using RuboCop version 1.86.1.
+# on 2026-06-13 04:17:12 UTC using RuboCop version 1.86.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,13 +11,101 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'glossarist.gemspec'
 
-# Offense count: 419
+# Offense count: 7
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Exclude:
+    - 'lib/glossarist/errors.rb'
+    - 'lib/glossarist/reference_resolver.rb'
+    - 'lib/glossarist/schema_migration/v0_to_v1.rb'
+    - 'lib/glossarist/schema_migration/v2_to_v3.rb'
+    - 'spec/unit/reference_resolver_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: IndentationWidth.
+Layout/AssignmentIndentation:
+  Exclude:
+    - 'lib/glossarist/schema_migration/v0_to_v1.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
+  Exclude:
+    - 'lib/glossarist/sts/importer.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'lib/glossarist/sts/importer.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/ClosingParenthesisIndentation:
+  Exclude:
+    - 'spec/unit/concept_source_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: consistent, consistent_relative_to_receiver, special_for_inner_method_call, special_for_inner_method_call_in_parentheses
+Layout/FirstArgumentIndentation:
+  Exclude:
+    - 'spec/unit/concept_source_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Exclude:
+    - 'lib/glossarist/managed_concept.rb'
+    - 'lib/glossarist/schema_migration/v0_to_v1.rb'
+    - 'spec/unit/validation/rules/cite_ref_integrity_rule_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
+# SupportedStylesAlignWith: start_of_line, relative_to_receiver
+Layout/IndentationWidth:
+  Exclude:
+    - 'lib/glossarist/sts/importer.rb'
+
+# Offense count: 449
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: symmetrical, new_line, same_line
+Layout/MultilineMethodCallBraceLayout:
+  Exclude:
+    - 'spec/unit/concept_source_spec.rb'
+
+# Offense count: 11
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/glossarist/errors.rb'
+    - 'lib/glossarist/managed_concept.rb'
+    - 'lib/glossarist/reference_resolver.rb'
+    - 'lib/glossarist/schema_migration/v0_to_v1.rb'
+    - 'lib/glossarist/schema_migration/v2_to_v3.rb'
+    - 'spec/unit/reference_resolver_spec.rb'
+    - 'spec/unit/validation/rules/cite_ref_integrity_rule_spec.rb'
+
 # Offense count: 1
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
@@ -39,7 +127,12 @@ Lint/UnusedMethodArgument:
   Exclude:
     - 'lib/glossarist/dataset_validator.rb'
 
-# Offense count: 84
+# Offense count: 1
+Lint/UselessConstantScoping:
+  Exclude:
+    - 'lib/glossarist/sts/term_extractor.rb'
+
+# Offense count: 89
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -50,12 +143,12 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Max: 41
 
-# Offense count: 52
+# Offense count: 58
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 107
+# Offense count: 109
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 47
@@ -65,17 +158,21 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Max: 6
 
-# Offense count: 39
+# Offense count: 43
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
 
-# Offense count: 6
-# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
-# AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
-Naming/MethodParameterName:
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
   Exclude:
-    - 'lib/glossarist/schema_migration.rb'
+    - 'lib/glossarist/sts/importer.rb'
 
 # Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
@@ -90,6 +187,18 @@ Style/IdenticalConditionalBranches:
   Exclude:
     - 'scripts/migrate_dataset.rb'
 
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/MultilineIfModifier:
+  Exclude:
+    - 'lib/glossarist/schema_migration/v0_to_v1.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantRegexpCharacterClass:
+  Exclude:
+    - 'lib/glossarist/sts/term_extractor.rb'
+
 # Offense count: 3
 # Configuration parameters: Max.
 Style/SafeNavigationChainLength:
@@ -97,3 +206,11 @@ Style/SafeNavigationChainLength:
     - 'lib/glossarist/managed_concept.rb'
     - 'lib/glossarist/transforms/concept_to_tbx_transform.rb'
     - 'lib/glossarist/validation/rules/source_urn_format_rule.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInArguments:
+  Exclude:
+    - 'spec/unit/concept_source_spec.rb'

data/CLAUDE.md

@@ -59,11 +59,15 @@ Designation inheritance hierarchy (MECE):
 
 `ConceptData#domain` stores URI references (relative like `section-103-01`, URN like `urn:iec:std:iec:60050-103-01`, or URL like `https://...`) to subject area concepts.
 
+### Dataset Loading
+
+- **`GlossaryStore`** (`glossary_store.rb`) — the dataset abstraction. Backed by `Lutaml::Store::PackageStore`, handles loading/saving from directories and ZIPs, concept CRUD, metadata, bibliography, images, and stats. Format detection is model-driven via `ConceptDocument.for_version`. **All callers that need to load concepts from a dataset should use GlossaryStore.**
+- **`ConceptCollector`** (`concept_collector.rb`) — legacy scanner with hand-rolled format detection (file-system heuristics, not model-driven). Being replaced by GlossaryStore. Do not add new callers.
+- **`ConceptManager`** (`concept_manager.rb`) — legacy file I/O used by `ManagedConceptCollection`. Being replaced by GlossaryStore. Do not add new callers.
+- **`ManagedConceptCollection`** (`managed_concept_collection.rb`) — legacy collection that loads via ConceptManager. Being replaced by GlossaryStore.
+
 ### YAML Serialization
 
-- **`ConceptManager`** (`concept_manager.rb`) — handles file I/O. Supports two storage formats:
-  1. Separate `concept/` and `localized_concept/` directories (or `localized-concept/` with dashes)
-  2. Grouped: concept + localized concepts in a single YAML stream file
 - Supports both camelCase and snake_case keys in YAML (e.g., `localizedConcepts` / `localized_concepts`) using `%i[key1 key2]` mapping syntax.
 - Also supports V1 format (`concept-*.yaml` files at root level).
 
@@ -121,3 +125,30 @@ The Gemfile overrides relaton gems from git branches for lutaml-model 0.8 compat
 - Released 2.0.0 gems have untyped lutaml-model attributes that fail with 0.8+
 - relaton-bib 2.1.0 is released but sub-gems pin `~> 2.0.0`, blocking 2.1.0 adoption until upstream updates constraints
 - Remove git overrides once relaton gems release versions with lutaml-model 0.8 support
+
+## Schema Version Subclasses Are NOT Duplication
+
+V2 and V3 namespace classes (e.g. `V2::ManagedConceptData`, `V3::ManagedConceptData`) exist because each schema version has its own `key_value` mapping and its own type references (`V2::LocalizedConcept` vs `V3::LocalizedConcept`). These are version-specific serialization adapters at a **real seam** — two adapters justifies the seam.
+
+Do not attempt to "parameterize" or "collapse" these into the base class:
+
+- **OCP**: Adding a new schema version = adding a new subclass, not modifying the base. This is the pattern working as intended.
+- **lutaml-model DSL is class-level**: `attribute` and `key_value` mappings are declarative DSL invoked at class definition time. They cannot be meaningfully "parameterized" at the instance level without metaprogramming (`Class.new`), which is worse than the current clear, declarative pattern.
+- **Structural similarity ≠ accidental duplication**: The fact that V2 and V3 `ManagedConceptData` look similar is because V3 evolved from V2. Their `localizations_from_yaml` callbacks differ in which class they instantiate, their `key_value` mappings differ in which fields are mapped, and V2 has custom `related` handling that V3 doesn't. These differences will diverge further as the schemas evolve.
+- **Three similar lines is better than a wrong abstraction**: The global instruction applies directly here.
+
+## Architectural Review Findings (2026-06-10)
+
+### Valid deepening opportunities
+
+See `TODO.improve/` for detailed plans.
+
+1. **Migrate callers to GlossaryStore** — ConceptCollector (8 call sites) and ConceptManager (1 call site) duplicate format detection with file-system heuristics. GlossaryStore is model-driven, framework-aligned, and handles both directory and ZIP. All callers should go through GlossaryStore.
+
+2. **Split SchemaMigration into focused modules** — Currently handles V0→V1 hash migration, V2→V3 model migration, and a CLI pipeline at three different abstraction levels. Each should be its own module.
+
+### Rejected candidates (do not re-suggest)
+
+- **Collapse V2/V3 ManagedConceptData** — Version subclasses are a real seam, not duplication. See "Schema Version Subclasses Are NOT Duplication" above.
+- **Extract validation reporter from CLI::ValidateCommand** — 159 lines of terminal formatting in a CLI command is normal. Creating 4 reporter classes to replace a 3-way case statement (where 2 branches are 1 line each) is premature abstraction. CLI commands are leaf nodes, not extension points.
+- **Refactor ConceptToGlossTransform** — The transform is already deep (3 public methods, 343 lines of implementation). Moving mapping to domain models would violate model-driven by leaking RDF knowledge into the domain layer. Using lutaml-model views can't handle the type dispatching and URI construction the transform does. The module has locality (all mapping in one place) and leverage (one interface, N callers).

data/Gemfile

@@ -7,6 +7,7 @@ gemspec
 gem "canon"
 gem "nokogiri"
 gem "rake", "~> 13.0"
+gem "rdf-turtle", "~> 3.3"
 gem "relaton", "~> 2.1.0"
 gem "rspec", "~> 3.0"
 gem "rubocop"

data/lib/glossarist/cli/compare_command.rb

@@ -12,8 +12,8 @@ module Glossarist
       end
 
       def run
-        new_concepts = ConceptCollector.collect(@new_path)
-        old_concepts = ConceptCollector.collect(@old_path)
+        new_concepts = GlossaryStore.new.tap { |s| s.load(@new_path) }.concepts
+        old_concepts = GlossaryStore.new.tap { |s| s.load(@old_path) }.concepts
 
         result = ConceptComparator.new(
           new_concepts: new_concepts,

data/lib/glossarist/cli/export_command.rb

@@ -41,9 +41,7 @@ module Glossarist
           resolve_metadata_from_package(package)
           package.concepts
         else
-          collection = ManagedConceptCollection.new
-          collection.load_from_files(@path)
-          collection.to_a
+          GlossaryStore.new.tap { |s| s.load(@path) }.concepts
         end
       end
 

data/lib/glossarist/collection.rb

@@ -68,7 +68,7 @@ module Glossarist
     def load_concept_from_file(filename)
       Concept.from_yaml(File.read(filename))
     rescue Psych::SyntaxError => e
-      raise Glossarist::ParseError.new(filename: filename, line: e.line)
+      raise Glossarist::Errors::ParseError.new(filename: filename, line: e.line)
     end
 
     def save_concept_to_file(concept)

data/lib/glossarist/collections/bibliography_collection.rb

@@ -30,7 +30,7 @@ module Glossarist
           expected = Relaton::Registry.instance.by_type(dir.split("/").last)&.grammar_hash
           next if expected.nil? || actual == expected
 
-          return CacheVersionMismatchError.new(dir, expected, actual)
+          return Errors::CacheVersionMismatchError.new(dir, expected, actual)
         end
 
         nil

data/lib/glossarist/concept_data.rb

@@ -88,6 +88,7 @@ module Glossarist
       self.class.detailed_definition_fields.each do |field|
         send(field).each { |d| list.concat(d.sources.to_a) }
       end
+      Array(terms).each { |t| list.concat(Array(t.sources)) }
       list
     end
 

data/lib/glossarist/concept_reference.rb

@@ -13,6 +13,7 @@ module Glossarist
     attribute :source, :string
     attribute :ref_type, :string
     attribute :urn, :string
+    attribute :version, :string
 
     key_value do
       map :term, to: :term
@@ -20,6 +21,7 @@ module Glossarist
       map :source, to: :source
       map :ref_type, to: :ref_type
       map :urn, to: :urn
+      map :version, to: :version
     end
 
     def self.domain(concept_id)
@@ -31,7 +33,7 @@ module Glossarist
     end
 
     def local?
-      %w[local designation].include?(ref_type) ||
+      %w[local designation cite].include?(ref_type) ||
         (ref_type.nil? && (source.nil? || source.empty?))
     end
 
@@ -39,6 +41,10 @@ module Glossarist
       !local?
     end
 
+    def cite?
+      ref_type == "cite"
+    end
+
     def dedup_key
       concept_id ? [source, concept_id] : [source, concept_id, term]
     end

data/lib/glossarist/concept_source.rb

@@ -1,5 +1,6 @@
 module Glossarist
   class ConceptSource < Lutaml::Model::Serializable
+    attribute :id, :string
     attribute :status, :string,
               values: Glossarist::GlossaryDefinition::CONCEPT_SOURCE_STATUSES
     attribute :type, :string,
@@ -8,8 +9,7 @@ module Glossarist
     attribute :modification, :string
 
     key_value do
-      # TODO: change to `map [:ref, :origin], to: :origin
-      #       when multiple key mapping is supported in lutaml-model
+      map :id, to: :id
       map :origin, to: :origin
       map :status, to: :status
       map :type, to: :type

data/lib/glossarist/concept_validator.rb

@@ -16,7 +16,9 @@ module Glossarist
       context = Validation::Rules::DatasetContext.new(@path)
       concept_rules = Validation::Rules::Registry.for_scope(:concept)
 
-      all_concepts = ConceptCollector.collect(@path)
+      store = GlossaryStore.new
+      store.load(@path)
+      all_concepts = store.concepts
       total = all_concepts.length
 
       if total.zero?

data/lib/glossarist/dataset_validator.rb

@@ -52,7 +52,7 @@ module Glossarist
     def validate_directory_cross_references(path, reference_path)
       extractor = ReferenceExtractor.new
       resolver = build_resolver(reference_path)
-      concepts = ConceptCollector.collect(path)
+      concepts = GlossaryStore.new.tap { |s| s.load(path) }.concepts
       resolver.register_self(concepts)
       resolver.validate_all(concepts, extractor: extractor)
     end

data/lib/glossarist/{error.rb → errors/base.rb}

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module Glossarist
-  class Error < StandardError
+  module Errors
+    class Base < StandardError
+    end
   end
 end

data/lib/glossarist/errors/cache_version_mismatch_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Errors
+    class CacheVersionMismatchError < Base
+      def initialize(cache_dir, expected, actual)
+        super("Relaton cache version mismatch in '#{cache_dir}': " \
+              "expected '#{expected}', got '#{actual}'")
+      end
+    end
+  end
+end

data/lib/glossarist/errors/invalid_language_code_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Errors
+    class InvalidLanguageCodeError < Base
+      attr_reader :code
+
+      def initialize(code:)
+        @code = code
+
+        super()
+      end
+
+      def to_s
+        "Invalid value for language_code: `#{code}`. It must be 3 characters long string."
+      end
+    end
+  end
+end

data/lib/glossarist/errors/invalid_type_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Errors
+    class InvalidTypeError < Base
+    end
+  end
+end

data/lib/glossarist/errors/load_error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Errors
+    class LoadError < Base
+      attr_accessor :path, :reason
+
+      def initialize(path:, reason: nil)
+        @path = path
+        @reason = reason
+
+        super(to_s)
+      end
+
+      def to_s
+        parts = ["Unable to load: #{path}"]
+        parts << reason if reason
+        parts.join(" — ")
+      end
+    end
+  end
+end

data/lib/glossarist/errors/parse_error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Errors
+    class ParseError < Base
+      attr_accessor :line, :filename, :message
+
+      def initialize(filename:, line: nil, message: nil)
+        @filename = filename
+        @line = line
+        @message = message
+
+        super(to_s)
+      end
+
+      def to_s
+        parts = ["Unable to parse file: #{filename}"]
+        parts << "error on line: #{line}" if line
+        parts << message if message
+        parts.join(", ")
+      end
+    end
+  end
+end

data/lib/glossarist/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Errors
+    autoload :Base, "glossarist/errors/base"
+    autoload :ParseError, "glossarist/errors/parse_error"
+    autoload :LoadError, "glossarist/errors/load_error"
+    autoload :InvalidTypeError, "glossarist/errors/invalid_type_error"
+    autoload :InvalidLanguageCodeError,
+             "glossarist/errors/invalid_language_code_error"
+    autoload :CacheVersionMismatchError,
+             "glossarist/errors/cache_version_mismatch_error"
+  end
+end

data/lib/glossarist/gcr_package.rb

@@ -259,7 +259,9 @@ module Glossarist
 
       def create_batch(dir, output:, shortname:, version:,
 compiled_formats: [], **opts)
-        concepts = ConceptCollector.collect(dir)
+        store = GlossaryStore.new
+        store.load(dir)
+        concepts = store.concepts
         if concepts.empty?
           raise ArgumentError,
                 "No concept files found in #{dir}"
@@ -304,7 +306,7 @@ compiled_formats: [], **opts)
             zos.write(register_data.to_yaml)
           end
 
-          ConceptCollector.each_concept(dir) do |mc|
+          GlossaryStore.new.tap { |s| s.load(dir) }.each_concept do |mc|
             enricher.inject_references([mc])
             if opts[:concept_uri_template]
               enricher.apply_uri_template([mc],