iev 0.4.4 → 0.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54693df7923bcf4dc686eac69daf1f4e3f981db12a0c3f7f672e2c7c656a53b2
-  data.tar.gz: 5404339eaad56057bccd9880b324194c73a9d82f8e86224429df4d651b361b67
+  metadata.gz: a539da108086dd1fb862d1d99d6763a3d32015a921ef580018ac9671660b0b68
+  data.tar.gz: af0e1813cae179dd69da3a9e8fde6e8d275e34d59949bd43a0642a171988f311
 SHA512:
-  metadata.gz: 474e483fbab5ad2b3450a617d51a67ea1a6217bdfcfa46d99a469234e5fbffc2da4e89e20d7f5049303212086d0edebcb1712b2334829be2daed5d55816ad2b9
-  data.tar.gz: 34595c499fb3855449f92059629fad4da01a5d24b77409e8eab7cd7abf3b6a1eb4b6770e83baca6d0d2df46f22f69d9635eb282d7200e2ac364dd0eef8dea983
+  metadata.gz: c93e2479cccfbe56b37b1d1cd604a3b327258abd8c50f9b99e2091abe7e4e714aa8e44c49f9e886d11483ec80e8e2325ce78f0598e8b34fdeb4fe7442b0e0d32
+  data.tar.gz: 28c5084f7a75106feee144201b75b642217674438f14a48c216a1069ed1b5d0abe822d137afb6671303bc1a407689ec236c4b2ff5abe2c0626e3a34f1ec35b34

data/.github/workflows/rake.yml

@@ -1,15 +1,18 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
 name: rake
 
-permissions:
-  contents: write
-
 on:
   push:
     branches: [ master, main ]
     tags: [ v* ]
   pull_request:
-  workflow_dispatch:
+
+permissions:
+  contents: write
 
 jobs:
   rake:
     uses: metanorma/ci/.github/workflows/generic-rake.yml@main
+    secrets:
+      pat_token: ${{ secrets.GLOSSARIST_CI_PAT_TOKEN }}

data/.github/workflows/release.yml

@@ -1,3 +1,5 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
 name: release
 
 permissions:

data/.gitignore

@@ -15,5 +15,7 @@
 .vscode/
 
 /concepts/
+/output/
 Gemfile.lock
 TODO*
+spec/fixtures/*.sqlite3

data/.rubocop.yml

@@ -1,8 +1,10 @@
 # Auto-generated by Cimas: Do not edit it manually!
 # See https://github.com/metanorma/cimas
 inherit_from:
-  - .rubocop_todo.yml
-  - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.yml
 
 # local repo-specific modifications
 # ...
+
+AllCops:
+  TargetRubyVersion: 3.4

data/Gemfile

@@ -14,7 +14,3 @@ gem "rubocop-rspec"
 gem "simplecov"
 
 gemspec
-
-# TODO: remove once glossarist 2.7.0 is released with domains migration
-gem "glossarist", git: "https://github.com/glossarist/glossarist-ruby.git",
-                 branch: "feat/metanorma-parity-designation-model"

data/README.adoc

@@ -360,6 +360,371 @@ authoritative_source:
 ----
 
 
+== Excel-to-Glossarist Column Mapping
+
+This section provides a complete mapping from every IEV Excel export column
+to the corresponding Glossarist concept model field. The IEV Excel export has
+19 columns (see <<_structure_of_the_iev_excel_export>>). Each row represents
+one *localized term entry* (one language variant of one concept).
+
+=== Glossarist Model Layers
+
+The Glossarist model organizes concept data into two layers:
+
+* *ManagedConcept* — the concept entry itself (identity, domain classification,
+  cross-concept relationships, lifecycle)
+* *LocalizedConcept* — a language-specific variant of a concept (designations,
+  definition, notes, examples, sources)
+
+One IEV Excel row produces one `LocalizedConcept`, which is attached to its
+`ManagedConcept` (identified by `IEVREF`).
+
+=== Column-by-Column Mapping
+
+The table below maps each of the 19 Excel columns to the Glossarist model.
+
+[cols="15h,25h,15h,45h",options="header"]
+|===
+| Excel Column | Glossarist Path | Data Type | Notes
+
+| `IEVREF`
+| `ManagedConceptData#id`
+| `String`
+| The concept identifier (e.g. `103-01-02`). Also set as `LocalizedConcept#id` and `ConceptData#id`. Used to group multiple language rows into one `ManagedConcept`. The IEVREF pattern `AAA-BB-CC` is also used to derive domain references (see <<_derived-fields>>).
+
+| `LANGUAGE`
+| `ConceptData#language_code`
+| `String` (ISO 639-2/3)
+| Two-character code (e.g. `en`, `fr`) converted to three-character ISO 639 code (e.g. `eng`, `fra`) via `Iev::Iso639Code`. This determines which language slot the localized concept fills.
+
+| `TERM`
+| `Designation::Expression#designation`
+| `String`
+| Primary term designation. Creates a `Designation::Expression` with `normative_status: "preferred"`. If the value is `.....` (5 dots, meaning "not available"), it is replaced with `"NA"`. The term text undergoes MathML-to-AsciiMath conversion and cross-reference expansion.
+
+| `TERMATTRIBUTE`
+| (multiple designation fields)
+| Composite string
+| Parsed by `TermAttrsParser` into multiple designation attributes. See <<_termattribute-breakdown>> for the full sub-mapping.
+
+| `SYNONYM1`
+| `Designation::Expression#designation`
+| `String`
+| Additional designation. Creates a `Designation::Expression`. Some synonyms contain multiple entries separated by `<p>`, `<b>`, `<br>` tags — each is split into a separate designation. `normative_status` comes from `SYNONYM1STATUS`.
+
+| `SYNONYM1ATTRIBUTE`
+| (multiple designation fields)
+| Composite string
+| Same parsing as `TERMATTRIBUTE`, applied to the `SYNONYM1` designation. See <<_termattribute-breakdown>>.
+
+| `SYNONYM1STATUS`
+| `Designation::Expression#normative_status`
+| `String` or nil
+| Maps to the synonym's normative status. The value is lowercased. Known localized values are mapped: e.g. `"obsoleto"` to `"deprecated"`, Cyrillic variants similarly. When nil, the synonym has no explicit status. Also used to derive `LocalizedConcept#classification` (see <<_derived-fields>>).
+
+| `SYNONYM2`
+| `Designation::Expression#designation`
+| `String`
+| Same pattern as `SYNONYM1`.
+
+| `SYNONYM2ATTRIBUTE`
+| (multiple designation fields)
+| Composite string
+| Same as `SYNONYM1ATTRIBUTE`.
+
+| `SYNONYM2STATUS`
+| `Designation::Expression#normative_status`
+| `String` or nil
+| Same as `SYNONYM1STATUS`.
+
+| `SYNONYM3`
+| `Designation::Expression#designation`
+| `String`
+| Same pattern as `SYNONYM1`.
+
+| `SYNONYM3ATTRIBUTE`
+| (multiple designation fields)
+| Composite string
+| Same as `SYNONYM1ATTRIBUTE`.
+
+| `SYNONYM3STATUS`
+| `Designation::Expression#normative_status`
+| `String` or nil
+| Same as `SYNONYM1STATUS`.
+
+| `SYMBOLE`
+| `Designation::Symbol#designation`
+| `String`
+| International math symbol. Creates a `Designation::Symbol` with `international: true`. If this column is empty, no symbol designation is created.
+
+| `DEFINITION`
+| `ConceptData#definition`, `ConceptData#examples`, `ConceptData#notes`
+| HTML string
+| The unified definition text is split by `TermBuilder#split_definition` which uses regex to detect EXAMPLE, EXEMPLE, Note N to entry, Note N a l'article, NOTE markers. Each part becomes a `DetailedDefinition` object in the corresponding collection. The content undergoes MathML-to-AsciiMath conversion and cross-reference expansion.
+
+| `SOURCE`
+| `ConceptData#sources` (via `ConceptSource`)
+| HTML string
+| Parsed by `SourceParser` into one or more `ConceptSource` objects, each with `type: "authoritative"`. The source string is split after normalization. Each source has: `status` (identical/modified/similar/related/not_equal), `origin` (a `Citation` with `ref`, `locality`, `link`, `original`), and optionally `modification` text. See <<_source-parsing>>.
+
+| `PUBLICATIONDATE`
+| `ConceptData#dates` (via `ConceptDate`)
+| `String` (YYYY-MM or YYYY-MM-DD)
+| Converted to a full ISO 8601 datetime. Creates two `ConceptDate` entries: `{type: "accepted", date: ...}` and `{type: "amended", date: ...}`. Also sets `ConceptData#review_date` and `ConceptData#review_decision_date` to the same value.
+
+| `STATUS`
+| `LocalizedConcept#entry_status`
+| `String`
+| Only `Standard` is known; it maps to `"valid"`. Lowercased and matched.
+
+| `REPLACES`
+| `ConceptData#related` (via `RelatedConcept`)
+| `String`
+| Parsed by `SupersessionParser`. Expected format: `IEVREF:VERSION` (e.g. `881-01-23:1983-01`). Creates a `RelatedConcept` with `type: "supersedes"` and a `Citation` containing `{source: "IEV", id: "...", version: "..."}`.
+
+|===
+
+
+[[_termattribute-breakdown]]
+=== TERMATTRIBUTE Sub-Field Mapping
+
+The `TERMATTRIBUTE` column is a composite string parsed by `TermAttrsParser`.
+It may contain multiple attributes separated by semicolons. The parser extracts
+them in order: gender, plurality, geographical area, part of speech, usage
+info, prefix.
+
+[cols="15h,30h,55h",options="header"]
+|===
+| Parsed Value | Glossarist Path | Notes
+
+| `m`, `f`, `n`
+| `GrammarInfo#gender` (via `Designation::Expression#grammar_info`)
+| Grammatical gender. May appear inside brackets: `(m)`, `[f]`.
+
+| `pl`
+| `GrammarInfo#number` (via `Designation::Expression#grammar_info`)
+| Plurality. `pl` maps to `"plural"`. If gender was found but not `pl`, defaults to `"singular"`.
+
+| `adj`, `noun`, `verb`
+| `GrammarInfo#part_of_speech`
+| Part of speech. Localized variants are mapped: German `Adjektiv` to `adj`, Japanese and Korean variants similarly.
+
+| Angle bracket text (ASCII or full-width)
+| `Designation::Expression#usage_info`
+| Usage info / domain indicator extracted from angle brackets. Full-width brackets used in some CJK terms.
+
+| Prefix keywords in multiple languages
+| `Designation::Expression#prefix`
+| Marks the designation as a prefix. Keywords include German, French, Japanese, Korean, Chinese, Portuguese variants.
+
+| Two-letter uppercase (e.g. `CA`, `US`)
+| `Designation::Base#geographical_area`
+| ISO 3166-1 alpha-2 country code.
+
+|===
+
+
+[[_source-parsing]]
+=== SOURCE Column Parsing
+
+The `SOURCE` column is the most complex field. It is parsed by `SourceParser`
+into one or more `ConceptSource` objects.
+
+==== Relationship Status Detection
+
+The parser detects the source relationship type from textual markers:
+
+[cols="20h,20h,60h",options="header"]
+|===
+| Marker | Status | Notes
+
+| Not-equal sign
+| `not_equal`
+| Definition differs from source.
+
+| Approximately-equal sign
+| `similar`
+| Definition is similar to source.
+
+| `see`, `voir`
+| `related`
+| Cross-reference to another definition.
+
+| `MOD`, `modified`, `modifie` (with accent)
+| `modified`
+| Definition modified from source. Modification text is captured in `ConceptSource#modification`.
+
+| (default)
+| `identical`
+| No special marker found.
+
+|===
+
+==== Source Reference Extraction
+
+The parser normalizes and extracts the source reference (e.g. `IEC 60050-121`),
+the clause locality (e.g. `151-12-05`), and optionally resolves a URL via
+Relaton. Reference normalization handles many localized forms: `CEI` to `IEC`,
+`UIT` to `ITU`, `VEI` to `IEV`, etc.
+
+
+[[_derived-fields]]
+=== Derived Fields (Not Directly From Excel Columns)
+
+Some Glossarist model fields are *derived* from IEVREF or from combinations
+of columns during export:
+
+[cols="25h,25h,50h",options="header"]
+|===
+| Glossarist Path | Source | Notes
+
+| `ManagedConceptData#domains`
+| Derived from `IEVREF`
+| The IEVREF pattern `AAA-BB-CC` is split. Creates two `ConceptReference` objects with `ref_type: "domain"` and `source: "urn:iec:std:iec:60050"` (IEC URN per IEC URN specification): `area-AAA` and `section-AAA-BB`. For example, `103-01-02` produces `area-103` + `section-103-01`.
+
+| `LocalizedConcept#classification`
+| `SYNONYM1STATUS`
+| Maps localized classification values: Chinese/Russian/Spanish `"admitido"` to `"admitted"`, various forms of `"preferred"` similarly; other values lowercased as-is.
+
+| `ConceptData#domain`
+| Derived from `IEVREF`
+| The section-level domain URI (e.g. `section-103-01`), resolved from the `SubjectAreas` data. Falls back to area-level if section not found.
+
+| `ConceptData#review_decision_event`
+| Hard-coded
+| Always set to `"published"`.
+
+| `ConceptDate {type: "amended"}`
+| `PUBLICATIONDATE`
+| A second date entry with type `"amended"` is created alongside the `"accepted"` date, using the same publication date value.
+
+| `ManagedConcept#related`
+| Derived from `IEVREF`
+| Hierarchy relations using `broader`/`narrower`. Regular IEV concepts have `broader → section-AAA-BB`. Section concepts have `broader → area-AAA` (from SubjectAreaConcepts) and `narrower → child concepts` (from Exporter). Area concepts have `narrower → section-AAA-BB`. Each `RelatedConcept` has both `content` (string) and `ref` (Citation with source `"IEV"` and `id`) set, so the glossarist RDF transform emits `skos:broader`/`skos:narrower` triples.
+
+|===
+
+
+=== Glossarist Model Fields NOT Populated From IEV Excel
+
+The following Glossarist model fields exist in the data model but are *not*
+populated from any IEV Excel column. They remain at their defaults:
+
+[cols="25h,60h,15h",options="header"]
+|===
+| Glossarist Field | Description | Default
+
+| `ManagedConceptData#uri`
+| External URI for the concept
+| nil
+
+| `ManagedConceptData#sources`
+| Managed-concept-level sources (distinct from localized sources)
+| empty
+
+| `ManagedConcept#dates`
+| Managed-concept-level dates (distinct from localized dates)
+| empty
+
+| `ManagedConcept#status`
+| Concept lifecycle status (draft/valid/retired etc.)
+| nil
+
+| `ConceptData#release`
+| Release version tag
+| nil
+
+| `ConceptData#lineage_source_similarity`
+| Lineage source similarity percentage
+| nil
+
+| `ConceptData#script`
+| ISO 15924 script code
+| nil
+
+| `ConceptData#system`
+| ISO 24229 conversion system code
+| nil
+
+| `ConceptData#references`
+| ConceptReference collection on localized concept
+| empty
+
+| `ConceptData#entry_status`
+| Entry status on ConceptData (duplicate of LocalizedConcept#entry_status)
+| nil
+
+| `Concept#non_verb_rep`
+| Non-verbal representations (images, tables, formulas)
+| empty
+
+| `Designation::Base#language`
+| Per-designation language override
+| nil
+
+| `Designation::Base#script`
+| Per-designation ISO 15924 script
+| nil
+
+| `Designation::Base#system`
+| Per-designation ISO 24229 system
+| nil
+
+| `Designation::Base#international`
+| International validity flag (set `true` only for SYMBOLE)
+| false
+
+| `Designation::Base#absent`
+| Explicitly absent designation flag
+| false
+
+| `Designation::Base#pronunciation`
+| Pronunciation entries (IPA, romanization, etc.)
+| empty
+
+| `Designation::Base#sources`
+| Per-designation bibliographic sources
+| empty
+
+| `Designation::Base#term_type`
+| ISO 12620 term type classification (24 values)
+| nil
+
+| `Designation::Base#related`
+| Designation-level relationships (abbreviated_form_for, short_form_for)
+| empty
+
+| `Designation::Expression#field_of_application`
+| Subject field / specific use
+| nil
+
+| `Designation::Abbreviation#acronym`
+| Acronym type flag
+| false
+
+| `Designation::Abbreviation#initialism`
+| Initialism type flag
+| false
+
+| `Designation::Abbreviation#truncation`
+| Truncation type flag
+| false
+
+| `Designation::LetterSymbol`
+| Letter symbol designation type (subclass of Symbol with `text`)
+| (not used)
+
+| `Designation::GraphicalSymbol`
+| Graphical symbol designation type (subclass of Symbol with `text`, `image`)
+| (not used)
+
+| `LocalizedConcept#review_type`
+| Review type
+| nil
+
+|===
+
+
 == Copyright and license
 
 Data copyright IEC. All others copyright Ribose.
@@ -379,8 +744,10 @@ data:
   identifier: "103-01-01"
   domains:
     - concept_id: area-103
+      source: urn:iec:std:iec:60050
       ref_type: domain
     - concept_id: section-103-01
+      source: urn:iec:std:iec:60050
       ref_type: domain
 ----
 
@@ -390,10 +757,21 @@ The `ref_type: domain` distinguishes domain references from other
 === Subject Area Hierarchy
 
 The `SubjectAreaConcepts` module creates area and section concepts that
-form a two-level hierarchy:
-
-* **Area concepts** (e.g. `area-103`) — have domain reference to themselves,
-  and `narrower` relations to their sections
-* **Section concepts** (e.g. `section-103-01`) — have domain references to
-  both parent area and themselves, a `broader` relation to the parent area,
-  and `ConceptData#domain` pointing to the parent area
+form a two-level hierarchy with symmetric `broader`/`narrower` linkages
+at the `ManagedConcept#related` level:
+
+* **Area concepts** (e.g. `area-103`) — domain reference to themselves,
+  `narrower` relations to their sections
+* **Section concepts** (e.g. `section-103-01`) — domain references to
+  both parent area and themselves, `broader` relation to parent area,
+  `narrower` relations to child IEV concepts (added by `Exporter`)
+* **Regular IEV concepts** (e.g. `103-01-02`) — `broader` relation to
+  their section concept (added by `Exporter`)
+
+All hierarchy `RelatedConcept` entries set both `content` (string, for
+YAML serialization) and `ref` (`Citation` with `source: "IEV"` and `id`,
+for RDF transformation via glossarist's gloss ontology).
+
+Separately, `domains` (classification via `ConceptReference.domain(...)`)
+and `ConceptData#domain` (per-localization string) remain for
+classification/filtering — distinct from hierarchy.

data/exe/iev

@@ -9,7 +9,7 @@ require "creek"
 require "glossarist"
 require "nokogiri"
 require "relaton"
-require "relaton_bib"
+require "relaton/bib"
 require "sequel"
 require "thor"
 

data/iev.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = Gem::Requirement.new(">= 3.2.0")
 
   spec.add_dependency "creek", "~> 2.6"
-  spec.add_dependency "glossarist", ">= 2.3.0"
+  spec.add_dependency "glossarist", "~> 2.6", ">= 2.6.7"
   spec.add_dependency "ferrum", "~> 0.15"
   spec.add_dependency "nokogiri", "~> 1.19"
   spec.add_dependency "plurimath"

data/lib/iev/cli/command_helper.rb

@@ -111,8 +111,7 @@ module Iev
 
         definition = entry["definition"]
         if definition
-          content = definition.is_a?(String) ? definition : definition
-          cd.definition = [Glossarist::DetailedDefinition.new(content: content)]
+          cd.definition = [Glossarist::DetailedDefinition.new(content: definition)]
         end
 
         l10n = Glossarist::LocalizedConcept.new

data/lib/iev/exporter.rb

@@ -55,6 +55,7 @@ module Iev
       dataset = load_dataset
       collection = build_collection(dataset)
       add_subject_area_concepts(collection) if @include_areas
+      build_section_narrower_relations(collection) if @include_areas
       save_collection(collection)
       elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
@@ -85,7 +86,7 @@ module Iev
 
       exts = (XLSX_EXTENSIONS + SQLITE_EXTENSIONS).join(", ")
       raise ArgumentError,
-        "Unsupported format: #{input_path.extname}. Supported: #{exts}"
+            "Unsupported format: #{input_path.extname}. Supported: #{exts}"
     end
 
     def input_format
@@ -141,11 +142,16 @@ module Iev
 
         concept = concept_index[term.id] ||= begin
           c = Glossarist::ManagedConcept.new(data: { "id" => term.id })
+          c.uuid = term.id
           c.data.domains = domain_references_for(term.id)
+          add_section_broader(c, term.id)
           collection.store(c)
           c
         end
         concept.add_l10n(term)
+
+        promote_supersession(concept, term)
+        set_managed_status(concept, term)
       end
 
       collection
@@ -160,21 +166,102 @@ module Iev
     def save_collection(collection)
       concepts_dir = output_dir.expand_path.join("concepts")
       FileUtils.mkdir_p(concepts_dir)
-      collection.save_to_files(concepts_dir.to_s)
+      collection.save_grouped_concepts_to_files(concepts_dir.to_s)
     end
 
     def localized_count(collection)
       collection.sum { |c| c.localized_concepts.count }
     end
 
+    IEV_SOURCE = "urn:iec:std:iec:60050"
+
     def domain_references_for(ievref)
-      parts = ievref.to_s.split("-")
-      return [] unless parts.length >= 2
+      code = IevCode.new(ievref.to_s)
+      refs = []
+      if code.area_code
+        refs << Glossarist::ConceptReference.new(
+          concept_id: code.area_uri,
+          source: IEV_SOURCE,
+          ref_type: "domain",
+        )
+      end
+      if code.section_code
+        refs << Glossarist::ConceptReference.new(
+          concept_id: code.section_uri,
+          source: IEV_SOURCE,
+          ref_type: "domain",
+        )
+      end
+      refs
+    end
+
+    def add_section_broader(concept, ievref)
+      code = IevCode.new(ievref.to_s)
+      return unless code.section_uri
+
+      concept.related ||= []
+      return if concept.related.any? do |r|
+        r.type == "broader" && r.ref&.id == code.section_uri
+      end
+
+      concept.related << Glossarist::RelatedConcept.new(
+        type: "broader",
+        content: code.section_uri,
+        ref: Glossarist::ConceptRef.new(source: "IEV", id: code.section_uri),
+      )
+    end
+
+    def build_section_narrower_relations(collection)
+      mc_index = collection.each_with_object({}) do |c, h|
+        h[c.data&.id] = c if c.data&.id
+      end
+
+      section_children = {}
+      mc_index.each_key do |concept_id|
+        code = IevCode.new(concept_id)
+        next unless code.section_uri
+
+        (section_children[code.section_uri] ||= []) << concept_id
+      end
+
+      section_children.each do |section_uri, child_ids|
+        section_mc = mc_index[section_uri]
+        next unless section_mc
+
+        narrower = child_ids.sort.map do |child_id|
+          Glossarist::RelatedConcept.new(
+            type: "narrower",
+            content: child_id,
+            ref: Glossarist::ConceptRef.new(source: "IEV", id: child_id),
+          )
+        end
+
+        section_mc.related ||= []
+        section_mc.related.concat(narrower)
+      end
+    end
+
+    # Promote supersedes relations from localized ConceptData to managed level.
+    # Supersession is language-independent (REPLACES column is per-concept).
+    def promote_supersession(concept, term)
+      related = term.data&.related
+      return unless related&.any?
+
+      concept.related ||= []
+      related.each do |r|
+        next if concept.related.any? { |er| er.type == r.type && er.ref&.id == r.ref&.id }
+
+        concept.related << r
+      end
+      term.data.related = nil
+    end
+
+    # Derive managed concept status from the localization's entry_status.
+    def set_managed_status(concept, term)
+      return if concept.status
 
-      [
-        SubjectAreas.area_uri(parts[0]),
-        SubjectAreas.section_uri(parts[0..1].join("-")),
-      ].map { |id| Glossarist::ConceptReference.domain(id) }
+      status = term.entry_status
+      concept.status = status if status && !status.empty?
     end
   end
 end

data/lib/iev/iev_code.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Iev
+  # Immutable value object that decomposes an IEV concept code
+  # into its structural parts: area code, section code, and number.
+  #
+  # The IEV code format is AAA-BB-CC where:
+  #   AAA = area code (e.g. "103")
+  #   BB  = section sub-code (e.g. "01")
+  #   CC  = concept number (e.g. "02")
+  #
+  # @example Full concept code
+  #   code = Iev::IevCode.new("103-01-02")
+  #   code.area_code    #=> "103"
+  #   code.section_code #=> "103-01"
+  #   code.number       #=> "02"
+  #   code.area_uri     #=> "area-103"
+  #   code.section_uri  #=> "section-103-01"
+  #
+  # @example Section code (no concept number)
+  #   code = Iev::IevCode.new("103-01")
+  #   code.area_code    #=> "103"
+  #   code.section_code #=> "103-01"
+  #   code.number       #=> nil
+  #   code.section_uri  #=> "section-103-01"
+  #
+  class IevCode
+    include Comparable
+
+    attr_reader :raw, :area_code, :section_code, :number
+
+    # @param code [#to_s] IEV reference, e.g. "103-01-02"
+    def initialize(code)
+      @raw = code.to_s
+      parts = @raw.split("-")
+      @area_code = parts[0]
+      @section_code = parts.length >= 2 ? "#{parts[0]}-#{parts[1]}" : nil
+      @number = parts.length >= 3 ? parts[2] : nil
+      freeze
+    end
+
+    def area_uri
+      "area-#{area_code}"
+    end
+
+    def section_uri
+      "section-#{section_code}" if section_code
+    end
+
+    def to_s
+      @raw
+    end
+
+    def to_str
+      @raw
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && raw == other.raw
+    end
+    alias_method :eql?, :==
+
+    def hash
+      raw.hash
+    end
+
+    def <=>(other)
+      to_s <=> other.to_s
+    end
+
+    # Safe constructor that returns nil for codes that don't parse.
+    # @param code [#to_s]
+    # @return [IevCode, nil]
+    def self.parse(code)
+      new(code)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/iev/iso_639_code.rb

@@ -6,7 +6,7 @@
 module Iev
   # @todo This needs to be rewritten.
   class Iso639Code
-    COUNTRY_CODES = YAML.load(IO.read(File.join(__dir__, "iso_639_2.yaml")))
+    COUNTRY_CODES = YAML.safe_load(IO.read(File.join(__dir__, "iso_639_2.yaml")), permitted_classes: [Symbol]).freeze
     # rubocop:disable Style/MutableConstant
     THREE_CHAR_MEMO = {} # Memoization cache, must be mutable
     # rubocop:enable Style/MutableConstant

data/lib/iev/section.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Iev
+  # Immutable value object representing an IEV section (e.g. "103-01").
+  #
+  # A section belongs to exactly one area, identified by +area_code+.
+  class Section
+    attr_reader :code, :title, :area_code
+
+    # @param code [#to_s] section code, e.g. "103-01"
+    # @param title [#to_s] section title, e.g. "General concepts on functions"
+    # @param area_code [#to_s] parent area code, e.g. "103"
+    def initialize(code:, title:, area_code:)
+      @code = code.to_s
+      @title = title.to_s
+      @area_code = area_code.to_s
+      freeze
+    end
+
+    def uri
+      "section-#{code}"
+    end
+
+    def to_h
+      { "code" => code, "title" => title }
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && code == other.code
+    end
+    alias_method :eql?, :==
+
+    def hash
+      code.hash
+    end
+  end
+end

data/lib/iev/source_parser.rb

@@ -79,10 +79,11 @@ module Iev
       relationship = extract_source_relationship(raw_ref)
       clean_ref = normalize_ref_string(raw_ref)
       source_ref = extract_source_ref(clean_ref)
+      ref_source, ref_id = split_ref(source_ref)
       clause = extract_source_clause(clean_ref)
 
       origin = Glossarist::Citation.new(
-        ref: source_ref,
+        ref: Glossarist::Citation::Ref.new(source: ref_source, id: ref_id),
         locality: build_locality(clause),
         link: obtain_source_link(source_ref),
         original: Iev::Converter.mathml_to_asciimath(
@@ -351,6 +352,52 @@ module Iev
       )
     end
 
+    # Splits a normalized bibliographic reference into [source, id] for
+    # structured Citation::Ref construction.  The full string is still
+    # passed to Relaton for link resolution — only the Citation::Ref
+    # model receives the split form.
+    #
+    #   "IEC 62302:2007"           → ["IEC",          "62302:2007"]
+    #   "ISO/IEC 2382:2015"        → ["ISO/IEC",      "2382:2015"]
+    #   "ISO/TS 14812:2022"        → ["ISO/TS",       "14812:2022"]
+    #   "IEC CISPR 16-1:2003"      → ["IEC CISPR",    "16-1:2003"]
+    #   "ITU-T Recommendation F.791 (11/2015)" → ["ITU-T Recommendation", "F.791 (11/2015)"]
+    #   "IEV"                      → ["IEV",          nil]
+    def split_ref(full_ref)
+      case full_ref
+      when /\A(ISO\/IEC\/IEEE)\s+(.+)/
+        [$1, $2]
+      when /\A(ISO\/IEC\s+Guide)\s+(.+)/
+        [$1, $2]
+      when /\A(ISO\/IEC)\s+(.+)/
+        [$1, $2]
+      when /\A(IEC\/IEEE)\s+(.+)/
+        [$1, $2]
+      when %r{\A((?:ISO|IEC)/(?:PAS|TR|TS))\s+(.+)}
+        [$1, $2]
+      when /\A(IEC\s+CISPR)\s+(.+)/
+        [$1, $2]
+      when /\A(ITU-T\s+Recommendation)\s+(.+)/
+        [$1, $2]
+      when /\A(ITU-R\s+Recommendation)\s+(.+)/
+        [$1, $2]
+      when /\A(ITU-R)\s+(.+)/
+        [$1, $2]
+      when /\A((?:ISO|IEC)\s+Guide)\s+(.+)/
+        [$1, $2]
+      when /\A(ISO|IEC|IAEA)\s+(.+)/
+        [$1, $2]
+      when /\AIEV\z/
+        ["IEV", nil]
+      when /\A(JCGM)\s+(VIM)\z/
+        [$1, $2]
+      when /\ABBIPM/
+        ["BIPM", "SI Brochure"]
+      else
+        [full_ref, nil]
+      end
+    end
+
     # Uses Relaton to obtain link for given source ref.
     def obtain_source_link(ref)
       return nil unless self.class.relaton_enabled

data/lib/iev/subject_area.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Iev
+  # Immutable value object representing an IEV subject area (e.g. "102").
+  #
+  # A subject area is the aggregate root for its sections.
+  # Navigation: area → sections (direct), section → area (via registry).
+  class SubjectArea
+    attr_reader :code, :title, :sections
+
+    # @param code [#to_s] area code, e.g. "103"
+    # @param title [#to_s] area title, e.g. "Mathematics - Functions"
+    # @param sections [Array<Iev::Section>] child sections
+    def initialize(code:, title:, sections: [])
+      @code = code.to_s
+      @title = title.to_s
+      @sections = sections
+      freeze
+    end
+
+    def uri
+      "area-#{code}"
+    end
+
+    def section(section_code)
+      sections.find { |s| s.code == section_code.to_s }
+    end
+
+    def to_h
+      {
+        "code" => code,
+        "title" => title,
+        "sections" => sections.map(&:to_h),
+      }
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && code == other.code
+    end
+    alias_method :eql?, :==
+
+    def hash
+      code.hash
+    end
+  end
+end

data/lib/iev/subject_area_concepts.rb

@@ -4,15 +4,24 @@ module Iev
   # Creates ManagedConcept entries for the IEV subject area hierarchy.
   #
   # The hierarchy has two levels:
-  #   - Area (e.g., "102" = "Mathematics - General concepts and linear algebra")
+  #   - Area (e.g., "102" = "Mathematics - General concepts")
   #   - Section (e.g., "102-01" = "Sets and operations")
   #
-  # Linking:
-  #   - Each IEV concept's ConceptData#domain references its section URI
-  #   - Each IEV concept's ManagedConceptData#domains includes area and section codes
-  #   - Each section concept has a "broader" relation to its parent area
-  #   - Each area concept has "narrower" relations to its sections
+  # Linking (all at ManagedConcept#related level):
+  #   - Each area has "narrower" relations to its sections
+  #   - Each section has "broader" relation to parent area
+  #   - Each section gets "narrower" to child concepts (added by Exporter)
+  #   - Each regular IEV concept gets "broader" to its section
+  #     (added by Exporter)
+  #
+  # Classification (separate from hierarchy):
+  #   - Each concept's ManagedConceptData#domains includes area and
+  #     section ConceptReferences
+  #   - Each concept's ConceptData#domain references its section URI
+  #   - Each section concept's ConceptData#domain references parent area
   module SubjectAreaConcepts
+    IEV_SOURCE = "urn:iec:std:iec:60050"
+
     class << self
       # Build all area and section concepts and add them to the collection.
       #
@@ -23,7 +32,7 @@ module Iev
           area_mc = build_area_concept(area)
           collection.store(area_mc)
 
-          (area["sections"] || []).each do |section|
+          area.sections.each do |section|
             section_mc = build_section_concept(section, area)
             collection.store(section_mc)
           end
@@ -32,42 +41,53 @@ module Iev
 
       private
 
+      def domain_ref(concept_id)
+        Glossarist::ConceptReference.new(
+          concept_id: concept_id,
+          source: IEV_SOURCE,
+          ref_type: "domain",
+        )
+      end
+
       def build_area_concept(area)
-        id = SubjectAreas.area_uri(area["code"])
+        id = area.uri
 
         mc = Glossarist::ManagedConcept.new(
           data: Glossarist::ManagedConceptData.new(
             id: id,
-            domains: [Glossarist::ConceptReference.domain(id)],
+            domains: [domain_ref(id)],
           ),
         )
+        mc.uuid = id
 
-        mc.add_localization(build_localization(id, area["title"], "eng"))
-
-        narrower = (area["sections"] || []).map { |s| build_narrower_ref(s["code"]) }
-        mc.related = narrower unless narrower.empty?
+        mc.add_localization(build_localization(id, area.title, "eng"))
+        mc.related = area.sections.map { |s| build_narrower_relation(s.uri) }
+        mc.related = nil if mc.related.empty?
 
         mc
       end
 
       def build_section_concept(section, area)
-        id = SubjectAreas.section_uri(section["code"])
+        id = section.uri
 
         mc = Glossarist::ManagedConcept.new(
           data: Glossarist::ManagedConceptData.new(
             id: id,
             domains: [
-              Glossarist::ConceptReference.domain(SubjectAreas.area_uri(area["code"])),
-              Glossarist::ConceptReference.domain(id),
+              domain_ref(area.uri),
+              domain_ref(id),
             ],
           ),
         )
+        mc.uuid = id
 
-        cd = build_concept_data(id, section["title"], "eng")
-        cd.domain = SubjectAreas.area_uri(area["code"])
-        cd.related = [build_broader_ref(area["code"])]
+        cd = build_concept_data(id, section.title, "eng")
+        cd.domain = area.uri
 
         mc.add_localization(build_localization_from_data(id, cd))
+
+        mc.related = [build_broader_relation(area.uri)]
+
         mc
       end
 
@@ -105,17 +125,19 @@ module Iev
         l10n
       end
 
-      def build_broader_ref(area_code)
+      def build_broader_relation(target_uri)
         Glossarist::RelatedConcept.new(
           type: "broader",
-          content: SubjectAreas.area_uri(area_code),
+          content: target_uri,
+          ref: Glossarist::ConceptRef.new(source: "IEV", id: target_uri),
         )
       end
 
-      def build_narrower_ref(section_code)
+      def build_narrower_relation(target_uri)
         Glossarist::RelatedConcept.new(
           type: "narrower",
-          content: SubjectAreas.section_uri(section_code),
+          content: target_uri,
+          ref: Glossarist::ConceptRef.new(source: "IEV", id: target_uri),
         )
       end
     end

data/lib/iev/subject_areas.rb

@@ -39,49 +39,59 @@ module Iev
         "section-#{code}"
       end
 
-      # --- Query API (reads from bundled data) ---
+      # --- Query API (returns typed objects) ---
 
       # Return all subject areas with their sections.
-      # @return [Array<Hash>] each hash has "code", "title", "sections"
+      # @return [Array<SubjectArea>]
       def all
-        data["areas"]
+        @typed_areas ||= raw_data["areas"].map { |h| build_area(h) }
       end
 
-      # Find a single subject area by its numeric code.
+      # Find a single subject area by its numeric code. O(1) indexed.
       # @param code [String, Integer] e.g. "102" or 102
-      # @return [Hash, nil]
+      # @return [SubjectArea, nil]
       def find_area(code)
-        all.find { |a| a["code"] == code.to_s }
+        area_index[code.to_s]
       end
 
       # Return all sections for a given area code.
       # @param code [String, Integer] area code, e.g. "102"
-      # @return [Array<Hash>] each hash has "code", "title"
+      # @return [Array<Section>]
       def sections_for(code)
-        area = find_area(code)
-        area ? area["sections"] : []
+        find_area(code)&.sections || []
       end
 
-      # Find a single section by its section code.
+      # Find a single section by its section code. O(1) indexed.
       # @param section_code [String] e.g. "102-01"
-      # @return [Hash, nil]
+      # @return [Section, nil]
       def find_section(section_code)
-        sc = section_code.to_s
-        all.each do |area|
-          found = area["sections"]&.find { |s| s["code"] == sc }
-          return found if found
-        end
-        nil
+        section_index[section_code.to_s]
       end
 
       # Return the parent area for a given section code.
       # @param section_code [String] e.g. "102-01"
-      # @return [Hash, nil]
+      # @return [SubjectArea, nil]
       def area_for_section(section_code)
-        sc = section_code.to_s
-        all.find do |area|
-          area["sections"]&.any? { |s| s["code"] == sc }
-        end
+        sec = find_section(section_code)
+        sec ? find_area(sec.area_code) : nil
+      end
+
+      # --- Navigation from IEV reference ---
+
+      # Find the subject area for any IEV reference.
+      # @param ievref [String] e.g. "103-01-02"
+      # @return [SubjectArea, nil]
+      def area_for(ievref)
+        code = IevCode.new(ievref)
+        find_area(code.area_code)
+      end
+
+      # Find the section for any IEV reference.
+      # @param ievref [String] e.g. "103-01-02"
+      # @return [Section, nil]
+      def section_for(ievref)
+        code = IevCode.new(ievref)
+        code.section_code ? find_section(code.section_code) : nil
       end
 
       # --- Fetching (network, writes to bundled data file) ---
@@ -164,10 +174,31 @@ module Iev
         sections.uniq { |s| s["code"] }
       end
 
+      # Clear cached typed objects (useful after fetch updates raw data).
+      def reload!
+        @typed_areas = nil
+        @area_index = nil
+        @section_index = nil
+        @raw_data = nil
+      end
+
       private
 
-      def data
-        @data ||= begin
+      def build_area(hash)
+        area_code = hash["code"]
+        sections = (hash["sections"] || []).map do |s|
+          Section.new(code: s["code"], title: s["title"], area_code: area_code)
+        end
+
+        SubjectArea.new(
+          code: area_code,
+          title: hash["title"],
+          sections: sections,
+        )
+      end
+
+      def raw_data
+        @raw_data ||= begin
           path = File.exist?(DATA_FILE) ? DATA_FILE : nil
           if path
             YAML.safe_load(File.read(path, encoding: "utf-8")) || { "areas" => [] }
@@ -177,6 +208,16 @@ module Iev
         end
       end
 
+      def area_index
+        @area_index ||= all.each_with_object({}) { |a, h| h[a.code] = a }
+      end
+
+      def section_index
+        @section_index ||= all.each_with_object({}) do |area, h|
+          area.sections.each { |s| h[s.code] = s }
+        end
+      end
+
       def complete?(data)
         areas = data["areas"]
         return false unless areas&.length&.>= 99

data/lib/iev/supersession_parser.rb

@@ -54,10 +54,9 @@ module Iev
     def relation_from_match(match_data)
       Glossarist::RelatedConcept.new(
         type: "supersedes",
-        ref: Glossarist::Citation.new(
+        ref: Glossarist::ConceptRef.new(
           source: "IEV",
           id: match_data[:ref],
-          version: match_data[:version],
         ),
       )
     end

data/lib/iev/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Iev
-  VERSION = "0.4.4"
+  VERSION = "0.4.5"
 end

data/lib/iev.rb

@@ -29,11 +29,14 @@ module Iev
   autoload :DataSource, "iev/data_source"
   autoload :DbWriter, "iev/db_writer"
   autoload :Exporter, "iev/exporter"
+  autoload :IevCode, "iev/iev_code"
   autoload :Iso639Code, "iev/iso_639_code"
   autoload :Profiler, "iev/profiler"
   autoload :RelatonDb, "iev/relaton_db"
   autoload :Scraper, "iev/scraper"
+  autoload :Section, "iev/section"
   autoload :SourceParser, "iev/source_parser"
+  autoload :SubjectArea, "iev/subject_area"
   autoload :SubjectAreas, "iev/subject_areas"
   autoload :SubjectAreaConcepts, "iev/subject_area_concepts"
   autoload :SupersessionParser, "iev/supersession_parser"
@@ -84,36 +87,43 @@ module Iev
   end
 
   # Return all IEV subject areas with their sections (from bundled data).
-  # @return [Array<Hash>]
+  # @return [Array<SubjectArea>]
   def self.subject_areas
     SubjectAreas.all
   end
 
   # Find a subject area by code.
   # @param code [String, Integer] e.g. "102"
-  # @return [Hash, nil]
+  # @return [SubjectArea, nil]
   def self.find_subject_area(code)
     SubjectAreas.find_area(code)
   end
 
   # Find a section by its section code.
   # @param section_code [String] e.g. "102-01"
-  # @return [Hash, nil]
+  # @return [Section, nil]
   def self.find_section(section_code)
     SubjectAreas.find_section(section_code)
   end
 
   # Return sections for a given area code.
   # @param code [String, Integer] e.g. "102"
-  # @return [Array<Hash>]
+  # @return [Array<Section>]
   def self.sections_for(code)
     SubjectAreas.sections_for(code)
   end
 
   # Return the parent subject area for a given section code.
   # @param section_code [String] e.g. "102-01"
-  # @return [Hash, nil]
+  # @return [SubjectArea, nil]
   def self.area_for_section(section_code)
     SubjectAreas.area_for_section(section_code)
   end
+
+  # Parse an IEV code into its structural components.
+  # @param code [String] e.g. "103-01-02"
+  # @return [IevCode, nil] nil if the code is blank
+  def self.parse_code(code)
+    IevCode.parse(code)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: iev
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.4.5
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-13 00:00:00.000000000 Z
+date: 2026-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: creek
@@ -28,16 +28,22 @@ dependencies:
   name: glossarist
   requirement: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: 2.6.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: 2.6.7
 - !ruby/object:Gem::Dependency
   name: ferrum
   requirement: !ruby/object:Gem::Requirement
@@ -206,6 +212,7 @@ files:
 - lib/iev/data_source.rb
 - lib/iev/db_writer.rb
 - lib/iev/exporter.rb
+- lib/iev/iev_code.rb
 - lib/iev/iso_639_2.yaml
 - lib/iev/iso_639_code.rb
 - lib/iev/profiler.rb
@@ -213,7 +220,9 @@ files:
 - lib/iev/scraper.rb
 - lib/iev/scraper/browser.rb
 - lib/iev/scraper/page_parser.rb
+- lib/iev/section.rb
 - lib/iev/source_parser.rb
+- lib/iev/subject_area.rb
 - lib/iev/subject_area_concepts.rb
 - lib/iev/subject_areas.rb
 - lib/iev/supersession_parser.rb