glossarist 2.6.6 → 2.6.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0e6019628f010211b1f05fbc2297a9c20b53b85ac23e57ac71d8d09ac933dcc
-  data.tar.gz: 65bc93a2714354d47261e21d6ee34c0b46f6d967688188c2af04dcf04ed3aaca
+  metadata.gz: 5e27bfae8df00d59f8ef6ed55ec4ad8562171cee6740a4bc7baf1f5a9f9561eb
+  data.tar.gz: 78fc3b6f141bba0a3e3d7881321b25e1365f04fbbd5f7fb67c10ba364d7dfb65
 SHA512:
-  metadata.gz: 86d9478fdc0bdecdfdce06dd607bd6254c04a9be4e261f41131571c60c043af5b84a2dbef7904c721e0c2646c9436fc734038c4ccd5da3a7a8c31b3fb6fc5429
-  data.tar.gz: 0d9c205d5733dcc767f2f1922eb43fcfdc8e2b445f7c144667bdb508cc285a24e2b50fef9326d085642f1269177f0044401d92fb2128d22466afb91ef25faa34
+  metadata.gz: 1beb0e161bbc7d4a44ab7239ec6d3880633dcfdab0e6021dedccf4e4a9cc29bcea764c74cf13390c99232a324abfe3578de9df2613b0a51036ed77b0a3bdb682
+  data.tar.gz: ec719ad1adce3ac72aa67d766c9c7c437ad55c40d17ac5d8c514c7d26c9a934517fb544062e14a23e95c715e8f5e46d51709548b34b05f562c2fd9bd5e64cd9c

data/README.adoc

@@ -392,7 +392,7 @@ A concept related to the current concept with a typed relationship.
 
 type:: Enum — the relationship type (see <<relationship-types,Relationship Types>> below).
 content:: String — free-text content describing the related concept.
-ref:: A <<citation,Citation>> reference to the related concept.
+ref:: A <<concept-ref,ConceptRef>> reference to the related concept (`source + id`, no version or locality).
 
 There are two ways to initialize and populate a related concept
 
@@ -403,7 +403,7 @@ There are two ways to initialize and populate a related concept
 related_concept = Glossarist::RelatedConcept.new({
   content: "Test content",
   type: :supersedes,
-  ref: <concept citation>
+  ref: Glossarist::ConceptRef.new(source: "IEC", id: "102-03-02"),
 })
 ----
 
@@ -414,7 +414,7 @@ related_concept = Glossarist::RelatedConcept.new({
 related_concept = Glossarist::RelatedConcept.new
 related_concept.type = "supersedes"
 related_concept.content = "designation of the related concept"
-related_concept.ref = <Citation object>
+related_concept.ref = Glossarist::ConceptRef.new(source: "IEC", id: "102-03-02")
 ----
 
 [[relationship-types]]
@@ -658,7 +658,7 @@ A definition of the managed term.
 It has the following attributes:
 
 content:: The text of the definition of the managed term.
-sources:: List of Bibliographic references(<<citation,Citation>>) for this particular definition of the managed term.
+sources:: List of <<concept-source,bibliographic sources>> for this particular definition of the managed term.
 
 There are two ways to initialize and populate a detailed definition
 
@@ -684,42 +684,94 @@ detailed_definition.sources = [<list of citations>]
 [[id,citation]]
 === Citation
 
-Citation can be either structured or unstructured. A citation is structured if its reference contains one or all of the following keys `{ id: "id", source: "source", version: "version"}` and is unstructured if its reference is plain text. This also has 2 methods `structured?` and `plain?` to check if citation is structured or not.
+A bibliographic citation used in <<concept-source,ConceptSource>> entries. The
+`ref` field is always a structured hash (`Citation::Ref`), never a plain string.
 
 Citation has the following attributes.
 
-ref:: A hash or string based on type of citation. Hash if citation is structured or string if citation is plain.
-clause:: Referred clause of the document.
-link:: Link to document.
+ref:: A `Citation::Ref` object (always a hash). See below.
+locality:: A `Locality` with `type`, `reference_from`, and `reference_to`.
+link:: URL link to the source document.
+original:: Pre-parsed original citation text.
+custom_locality:: Array of `{ name:, value: }` pairs for non-standard locality types.
 
-There are two ways to initialize and populate a Citation
+`Citation::Ref` inner class:
+
+source:: String — the document series or termbase (e.g. `"ISO"`, `"IEC"`).
+id:: String — the document identifier within the series (e.g. `"1087-1:2000"`).
+version:: String — optional version of the document.
+
+`Citation#label` returns a display string combining source and id.
 
-1. Setting the fields by using a hash while initializing
-+
 [,ruby]
 ----
-# Unstructured Citation
-citation = Glossarist::Citation.new({
-  ref: "plain text reference",
-  clause: "clause",
-  link: "link",
-})
+# Create a Citation
+citation = Glossarist::Citation.new(
+  ref: Glossarist::Citation::Ref.new(source: "ISO", id: "9000"),
+  locality: Glossarist::Locality.new(type: "clause", reference_from: "3.3.3"),
+  link: "https://www.iso.org/standard/45481.html",
+)
 
-# Structured Citation
-citation = Glossarist::Citation.new({
-  ref: { id: "123", source: "source", version: "1.1" },
-  clause: "clause",
-  link: "link",
-})
+citation.label  # => "ISO 9000"
 ----
 
-2. Setting the fields after creating an object
-+
+YAML serialization (always this shape):
+
+[,yaml]
+----
+origin:
+  ref:
+    source: ISO
+    id: "1087-1:2000"
+  locality:
+    type: clause
+    reference_from: "3.2.9"
+  link: https://www.iso.org/standard/20057.html
+----
+
+=== ConceptRef
+
+A concept reference used in <<related-concept,RelatedConcept>> entries. Has
+`source` and `id` only — no version, locality, or link.
+
+[,ruby]
+----
+ref = Glossarist::ConceptRef.new(source: "IEC", id: "102-01-01")
+----
+
+=== V2 and V3 Namespaces
+
+Glossarist provides versioned model namespaces for forward and backward
+compatibility:
+
+* `Glossarist::V2::*` — loads V2 datasets where `ref` may be a plain string.
+  Maps string refs to a `text` attribute internally.
+* `Glossarist::V3::*` — canonical V3 models with structured `Citation::Ref`
+  hashes, `BibliographyEntry`, `BibliographyFile`, `ImageEntry`, `ImageFile`.
+
+The `ConceptDocument.for_version("2"|"3")` method dispatches to the correct
+namespace. `ConceptCollector.detect_schema_version(dir)` auto-detects from the
+data by checking `schema_version` in the first concept file.
+
+=== Concept Comparison
+
+Compare two concept datasets to identify additions, removals, and changes:
+
+[,bash]
+----
+glossarist compare path/to/v1 path/to/v2
+----
+
+Ruby API:
+
 [,ruby]
 ----
-citation = Glossarist::Citation.new
-citation.ref = <plain or structured ref>
-citation.clause = "some clause"
+comparator = Glossarist::ConceptComparator.new
+result = comparator.compare(old_concepts, new_concepts)
+result.matched_count    # concepts present in both
+result.new_only_count   # concepts only in new set
+result.old_only_count   # concepts only in old set
+result.diffs            # Array of ConceptDiff with similarity scores
 ----
 
 === NonVerbRep
@@ -753,7 +805,7 @@ Concept Source has the following fields
 
 status:: The status of the managed term in the present context, relative to the term as found in the bibliographic source.
 type:: The type of the managed term in the present context.
-origin:: The bibliographic <<citation,citation>> for the managed term. This is also aliased as `ref`.
+origin:: The bibliographic <<citation,citation>> for the managed term.
 modification:: A description of the modification to the cited definition of the term, if any, as it is to be applied in the present context.
 
 
@@ -1278,6 +1330,15 @@ Glossarist::Validation::Rules::Registry.register(MyCustomRule)
 Custom rules are automatically picked up by `DatasetValidator`, `GcrValidator`,
 and `ConceptValidator` on the next validation run.
 
+=== compare
+
+Compare two concept datasets and report differences.
+
+[,bash]
+----
+glossarist compare PATH_OLD PATH_NEW [--format text|json|yaml]
+----
+
 === upgrade
 
 Upgrade a dataset to the current schema version.

data/glossarist.gemspec

@@ -32,9 +32,11 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "lutaml-model", "~> 0.8.5"
+  spec.add_dependency "paint", "~> 2.3"
   spec.add_dependency "relaton", ">= 2.0.0", "< 3"
   spec.add_dependency "rubyzip", ">= 2.3", "< 3"
   spec.add_dependency "sts", "~> 0.5.6"
+  spec.add_dependency "table_tennis", "~> 0.0"
   spec.add_dependency "tbx", "~> 0.1"
   spec.add_dependency "thor"
 end

data/lib/glossarist/citation.rb

@@ -1,122 +1,41 @@
+# frozen_string_literal: true
+
 module Glossarist
   class Citation < Lutaml::Model::Serializable
-    # Unstructured (plain text) reference.
-    # @return [String]
-    attribute :text, :string
-
-    # Source in structured reference.
-    # @return [String]
-    attribute :source, :string
-
-    # Document ID in structured reference.
-    # @return [String]
-    attribute :id, :string
-
-    # Document version in structured reference.
-    # @return [String]
-    attribute :version, :string
+    class Ref < Lutaml::Model::Serializable
+      attribute :source, :string
+      attribute :id, :string
+      attribute :version, :string
+
+      key_value do
+        map :source, to: :source
+        map :id, to: :id
+        map :version, to: :version
+      end
+    end
 
-    # @return [String]
-    # Referred locality of the document.
+    attribute :ref, Ref
     attribute :locality, Locality
-
-    # Link to document.
-    # @return [String]
     attribute :link, :string
-
-    # Original ref text before parsing.
-    # @return [String]
-    # @note This attribute is likely to be removed or reworked in future.
-    #   It is arguably not relevant to Glossarist itself.
     attribute :original, :string
-
-    attribute :ref, :string
-
     attribute :custom_locality, CustomLocality, collection: true
 
     key_value do
-      map :id, to: :id, with: { from: :id_from_yaml, to: :id_to_yaml }
-      map :text, to: :text, with: { from: :text_from_yaml, to: :text_to_yaml }
-      map :source, to: :source,
-                   with: { from: :source_from_yaml, to: :source_to_yaml }
-      map :version, to: :version,
-                    with: { from: :version_from_yaml, to: :version_to_yaml }
-      map :ref, to: :ref, with: { from: :ref_from_yaml, to: :ref_to_yaml }
+      map :ref, to: :ref
       map %i[clause locality],
           to: :locality,
-          with: { from: :clause_from_yaml, to: :clause_to_yaml }
+          with: { from: :locality_from_yaml, to: :locality_to_yaml }
       map :link, to: :link
       map :original, to: :original
       map %i[custom_locality customLocality], to: :custom_locality
     end
 
-    def ref_from_yaml(model, value)
-      model.ref = value
-    end
-
-    def ref_to_yaml(model, doc)
-      doc["ref"] = if model.structured?
-                     ref_hash(model)
-                   else
-                     model.text
-                   end
-    end
-
-    def id_from_yaml(model, value)
-      model.id = value
-    end
-
-    def id_to_yaml(_model, _doc)
-      # skip, will be handled in ref
-    end
-
-    def text_from_yaml(model, value)
-      model.text = value
-    end
-
-    def text_to_yaml(_model, _doc)
-      # skip, will be handled in ref
+    def label
+      parts = [ref&.source, ref&.id].compact
+      parts.empty? ? nil : parts.join(" ")
     end
 
-    def source_from_yaml(model, value)
-      model.source = value
-    end
-
-    def source_to_yaml(_model, _doc)
-      # skip, will be handled in ref
-    end
-
-    def version_from_yaml(model, value)
-      model.version = value
-    end
-
-    def version_to_yaml(_model, _doc)
-      # skip, will be handled in ref
-    end
-
-    def ref_hash(model = self)
-      {
-        "source" => model.source,
-        "id" => model.id,
-        "version" => model.version,
-      }.compact
-    end
-
-    def ref=(ref)
-      if ref.is_a?(Hash)
-        @source = ref["source"]
-        @id = ref["id"]
-        @version = ref["version"]
-      else
-        @text = ref
-      end
-    end
-
-    def clause_from_yaml(model, value) # rubocop:disable Metrics/AbcSize
-      # accepts old format like
-      # clause: "11"
-      # or new format like
-      # locality: { type: "clause", reference_from: "11", reference_to: "12" }
+    def locality_from_yaml(model, value)
       locality = Locality.new
 
       if value.is_a?(Hash)
@@ -132,29 +51,13 @@ module Glossarist
       model.locality = locality
     end
 
-    def clause_to_yaml(model, doc) # rubocop:disable Metrics/AbcSize
-      if model.locality
-        doc["locality"] = {}
-        doc["locality"]["type"] = model.locality.type
-
-        if model.locality.reference_from
-          doc["locality"]["reference_from"] = model.locality.reference_from
-        end
-
-        if model.locality.reference_to
-          doc["locality"]["reference_to"] = model.locality.reference_to
-        end
-      end
-    end
-
-    def plain?
-      (source && id && version).nil?
-    end
+    def locality_to_yaml(model, doc)
+      return unless model.locality
 
-    # Whether it is a structured ref.
-    # @return [Boolean]
-    def structured?
-      !plain?
+      doc["locality"] = {}
+      doc["locality"]["type"] = model.locality.type
+      doc["locality"]["reference_from"] = model.locality.reference_from if model.locality.reference_from
+      doc["locality"]["reference_to"] = model.locality.reference_to if model.locality.reference_to
     end
   end
 end

data/lib/glossarist/cli/compare_command.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "paint"
+
+module Glossarist
+  class CLI
+    class CompareCommand
+      def initialize(new_path, old_path, options)
+        @new_path = new_path
+        @old_path = old_path
+        @options = options
+      end
+
+      def run
+        new_concepts = ConceptCollector.collect(@new_path)
+        old_concepts = ConceptCollector.collect(@old_path)
+
+        result = ConceptComparator.new(
+          new_concepts: new_concepts,
+          old_concepts: old_concepts,
+        ).compare(show_diffs: !@options[:no_diffs])
+
+        report(result)
+      end
+
+      private
+
+      def report(result)
+        case @options[:format]
+        when "json"
+          output result.to_json
+        when "yaml"
+          output result.to_yaml
+        else
+          print_text_report(result)
+        end
+      end
+
+      def print_text_report(result)
+        puts
+        puts Paint["Concept Comparison", :bold]
+        puts
+
+        print_counts(result)
+        print_new_only(result)
+        print_old_only(result)
+        print_similarity(result)
+
+        puts
+      end
+
+      def print_counts(result)
+        puts "  #{Paint['New:', :bold]} #{result.new_count} concepts"
+        puts "  #{Paint['Old:', :bold]} #{result.old_count} concepts"
+        puts "  #{Paint['Matched:', :bold]} #{result.matched.length}"
+        puts "  #{Paint['New only:', :bold]} #{result.new_only.length}"
+        puts "  #{Paint['Old only:', :bold]} #{result.old_only.length}"
+      end
+
+      def print_new_only(result)
+        return unless result.new_only.any?
+
+        puts
+        puts "  #{Paint['New concepts (not in old):', :green, :bold]}"
+        result.new_only.each { |id| puts "    + #{id}" }
+      end
+
+      def print_old_only(result)
+        return unless result.old_only.any?
+
+        puts
+        puts "  #{Paint['Removed concepts (not in new):', :red, :bold]}"
+        result.old_only.each { |id| puts "    - #{id}" }
+      end
+
+      def print_similarity(result)
+        return unless result.diffs.any?
+
+        puts
+        puts "  #{Paint['Per-concept similarity:', :bold]}"
+        result.diffs.each do |diff|
+          color = similarity_color(diff.similarity)
+          puts "    #{diff.concept_id}: #{Paint["#{diff.similarity}%", color]}"
+        end
+      end
+
+      def similarity_color(value)
+        if value >= 100
+          :green
+        elsif value >= 90
+          :yellow
+        else
+          :red
+        end
+      end
+
+      def output(content)
+        if @options[:report]
+          File.write(@options[:report], content)
+        else
+          puts content
+        end
+      end
+    end
+  end
+end

data/lib/glossarist/cli/export_command.rb

@@ -48,8 +48,8 @@ module Glossarist
       end
 
       def resolve_metadata_from_package(package)
-        @options[:shortname] ||= package.metadata["shortname"]
-        @options[:uri_prefix] ||= package.metadata["uri_prefix"]
+        @options[:shortname] ||= package.metadata.shortname
+        @options[:uri_prefix] ||= package.metadata.uri_prefix
       end
 
       def resolve_shortname
@@ -73,17 +73,15 @@ module Glossarist
       end
 
       def export_jsonld(concepts, name, output_dir)
-        require "glossarist/transforms/concept_to_skos_transform"
-        vocab = Transforms::ConceptToSkosTransform.transform_document(concepts,
-                                                                      transform_options)
-        File.write(File.join(output_dir, "#{name}.jsonld"), vocab.to_jsonld)
+        require "glossarist/transforms/concept_to_gloss_transform"
+        transform = Transforms::ConceptToGlossTransform.new(nil, transform_options)
+        File.write(File.join(output_dir, "#{name}.jsonld"), transform.to_jsonld(concepts))
       end
 
       def export_turtle(concepts, name, output_dir)
-        require "glossarist/transforms/concept_to_skos_transform"
-        vocab = Transforms::ConceptToSkosTransform.transform_document(concepts,
-                                                                      transform_options)
-        File.write(File.join(output_dir, "#{name}.ttl"), vocab.to_turtle)
+        require "glossarist/transforms/concept_to_gloss_transform"
+        transform = Transforms::ConceptToGlossTransform.new(nil, transform_options)
+        File.write(File.join(output_dir, "#{name}.ttl"), transform.to_turtle(concepts))
       end
 
       def export_tbx(concepts, name, output_dir)
@@ -94,12 +92,11 @@ module Glossarist
       end
 
       def export_jsonl(concepts, name, output_dir)
-        require "glossarist/transforms/concept_to_skos_transform"
+        require "glossarist/transforms/concept_to_gloss_transform"
         File.open(File.join(output_dir, "#{name}.jsonl"), "w") do |f|
           concepts.each do |concept|
-            skos = Transforms::ConceptToSkosTransform.transform(concept,
-                                                                transform_options)
-            f.write(skos.to_jsonld)
+            transform = Transforms::ConceptToGlossTransform.new(concept, transform_options)
+            f.write(transform.to_jsonl_line)
             f.write("\n")
           end
         end