unitsdb 2.2.2 → 2.2.4

data/lib/unitsdb/config.rb

@@ -5,10 +5,18 @@ module Unitsdb
     CONTEXT_ID = :unitsdb_v2
 
     class << self
+      # The currently-active default context id. Config-populated
+      # contexts are created on demand under this id.
       def context_id
         @context_id ||= CONTEXT_ID
       end
 
+      # ---------------------------------------------------------------
+      # Model registry
+      # ---------------------------------------------------------------
+
+      # Register a model class under `id`. Single registration API;
+      # `models=` is a thin enumerator over this.
       def register_model(klass, id:)
         registered_models[id.to_sym] = klass
         klass
@@ -18,28 +26,34 @@ module Unitsdb
         @registered_models ||= {}
       end
 
-      def models
-        @models ||= {}
-      end
-
+      # Bulk-register models from a hash. Reads back through
+      # `register_model` so there is a single source of truth.
       def models=(user_models)
-        normalized_models = user_models.each_with_object({}) do |(id, klass), result|
-          model_id = id.to_sym
-          result[model_id] = register_model(klass, id: model_id)
+        user_models.each do |id, klass|
+          register_model(klass, id: id.to_sym)
         end
-
-        models.merge!(normalized_models)
       end
 
+      # Look up a registered model by id. Kept as a stable public
+      # API for downstream gems (e.g. unitsml) that previously used
+      # the Configuration module.
       def model_for(model_name)
-        model_id = model_name.to_sym
-        models[model_id] || registered_models[model_id]
+        registered_models[model_name.to_sym]
       end
 
-      def register(id = context_id)
-        explicit_registers[id.to_sym]
+      # ---------------------------------------------------------------
+      # Lutaml register bridge (opt-in)
+      # ---------------------------------------------------------------
+
+      # Look up the Lutaml::Model::Register id (or nil) that was
+      # explicitly created for `context_id` via `populate_register`.
+      def register_id_for(context_id = context_id())
+        explicit_registers[context_id.to_sym]
       end
 
+      # Create a Lutaml::Model::Register for `id`, enabling
+      # `from_hash(register: id)` deserialization. Power-user API —
+      # most callers want `populate_context` only.
       def populate_register(id: context_id, fallback_to: [:default], substitutions: [])
         register_id = id.to_sym
         context(register_id)
@@ -57,6 +71,14 @@ module Unitsdb
         explicit_registers[register_id] = Lutaml::Model::GlobalRegister.register(model_register)
       end
 
+      def explicit_registers
+        @explicit_registers ||= {}
+      end
+
+      # ---------------------------------------------------------------
+      # Context lifecycle
+      # ---------------------------------------------------------------
+
       def find_context(id)
         Lutaml::Model::GlobalContext.context(id.to_sym)
       end
@@ -65,25 +87,40 @@ module Unitsdb
         Lutaml::Model::GlobalContext.resolve_type(type_name, context.to_sym)
       end
 
-      def context(id = context_id, force_populate: false)
-        existing = find_context(id)
-        return existing if existing && !force_populate && populated?(id)
-
-        populate_context(id: id)
+      # Return the context for `id`, creating it via `populate_context`
+      # when missing. Non-destructive: existing contexts (whether
+      # Config-created or externally-managed) are returned as-is.
+      # Use `populate_context` directly to force-rebuild.
+      def context(id = context_id())
+        find_context(id) || populate_context(id: id)
       end
 
-      def populate_context(id: context_id, fallback_to: [:default], substitutions: [])
+      # Force-create a context under `id`, replacing any prior
+      # context (owned or external).
+      def populate_context(id: context_id, fallback_to: [:default],
+                           substitutions: [])
         Lutaml::Model::GlobalContext.unregister_context(id) if find_context(id)
 
         opts = { registry: build_registry, fallback_to: fallback_to, id: id }
-        context = Lutaml::Model::GlobalContext.create_context(
+        Lutaml::Model::GlobalContext.create_context(
           substitutions: resolve_substitutions(substitutions, **opts),
           **opts,
         )
-        mark_populated!(id)
-        context
       end
 
+      # Convenience: ensure the default context exists. Idempotent.
+      # Used as the single bootstrap site for `Unitsdb.database` and
+      # `Database.from_db`.
+      def ensure_default_context!
+        return if find_context(context_id)
+
+        populate_context(id: context_id)
+      end
+
+      # ---------------------------------------------------------------
+      # Substitution resolution
+      # ---------------------------------------------------------------
+
       def resolve_substitutions(substitutions, registry:, fallback_to:, id:)
         resolution_context = Lutaml::Model::TypeContext.derived(
           id: "#{id}_substitution_resolution",
@@ -109,22 +146,39 @@ module Unitsdb
       end
 
       def build_registry
+        Unitsdb.eager_load_models!
         registry = Lutaml::Model::TypeRegistry.new
         registered_models.each { |model_id, klass| registry.register(model_id, klass) }
         registry
       end
 
-      def populated?(context_id)
-        @populated_for&.[](context_id.to_sym)
+      # ---------------------------------------------------------------
+      # Test support — snapshot/restore/isolate
+      # ---------------------------------------------------------------
+
+      def capture_state
+        {
+          registered_models: registered_models.dup,
+          explicit_registers: explicit_registers.dup,
+          context_id: @context_id,
+        }
       end
 
-      def mark_populated!(context_id)
-        @populated_for ||= {}
-        @populated_for[context_id.to_sym] = true
+      def restore_state(snapshot)
+        @registered_models = snapshot[:registered_models]
+        @explicit_registers = snapshot[:explicit_registers]
+        @context_id = snapshot[:context_id]
       end
 
-      def explicit_registers
-        @explicit_registers ||= {}
+      # Run a block against a fresh Lutaml global context, then
+      # restore Config state so subsequent specs see bundled defaults.
+      def with_isolated_config
+        snapshot = capture_state
+        Lutaml::Model::GlobalContext.reset!
+        yield
+      ensure
+        restore_state(snapshot) if snapshot
+        Lutaml::Model::GlobalContext.reset!
       end
     end
   end

data/lib/unitsdb/database/loader.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Unitsdb
+  class Database
+    # Filesystem and YAML-schema layer of Database. Reads the
+    # collection YAML files from a directory, validates their schema
+    # versions agree, and returns a combined hash ready for
+    # Lutaml::Model deserialization. Knows nothing about contexts or
+    # registers — that's `Database.from_db`'s job.
+    class Loader
+      DATABASE_FILES = {
+        "prefixes" => "prefixes.yaml",
+        "dimensions" => "dimensions.yaml",
+        "units" => "units.yaml",
+        "quantities" => "quantities.yaml",
+        "unit_systems" => "unit_systems.yaml",
+      }.freeze
+
+      SUPPORTED_SCHEMA_VERSION = "2.0.0"
+
+      def self.load(dir_path)
+        new(dir_path).load
+      end
+
+      def initialize(dir_path)
+        @dir_path = File.expand_path(dir_path.to_s)
+      end
+
+      # Read every YAML file under @dir_path, validate schema versions,
+      # and return a combined hash keyed by collection name.
+      def load
+        verify_directory!
+        documents = read_documents
+        schema_version = validate_schema_versions!(documents)
+        build_database_hash(documents, schema_version)
+      end
+
+      private
+
+      def verify_directory!
+        unless Dir.exist?(@dir_path)
+          raise Errors::DatabaseNotFoundError,
+                "Database directory not found: #{@dir_path}"
+        end
+
+        missing = DATABASE_FILES.values.reject do |filename|
+          File.exist?(File.join(@dir_path, filename))
+        end
+        return if missing.empty?
+
+        raise Errors::DatabaseFileNotFoundError,
+              "Missing required database files: #{missing.join(', ')}"
+      end
+
+      def read_documents
+        if ENV["UNITSDB_DEBUG"]
+          puts "[UnitsDB] Loading YAML files from directory: #{@dir_path}"
+        end
+        DATABASE_FILES.transform_values do |filename|
+          path = File.join(@dir_path, filename)
+          puts "  - #{path}" if ENV["UNITSDB_DEBUG"]
+          read_yaml(path, filename)
+        end
+      end
+
+      def read_yaml(path, filename)
+        document = YAML.safe_load_file(path)
+        unless document.is_a?(Hash)
+          raise Errors::DatabaseFileInvalidError,
+                "Invalid YAML structure in #{filename}: expected a mapping"
+        end
+
+        document
+      rescue Errno::ENOENT => e
+        raise Errors::DatabaseFileNotFoundError,
+              "Failed to read database file: #{e.message}"
+      rescue Psych::SyntaxError => e
+        raise Errors::DatabaseFileInvalidError,
+              "Invalid YAML in database file: #{e.message}"
+      rescue Errors::DatabaseError
+        raise
+      rescue StandardError => e
+        raise Errors::DatabaseLoadError,
+              "Error loading database file #{filename}: #{e.message}"
+      end
+
+      def validate_schema_versions!(documents)
+        versions = DATABASE_FILES.each_with_object({}) do |(collection_key, filename), result|
+          document = documents.fetch(collection_key)
+          result[filename] = document.fetch("schema_version")
+        rescue KeyError
+          raise Errors::DatabaseFileInvalidError,
+                "Missing schema_version in #{filename}"
+        end
+
+        unless versions.values.uniq.size == 1
+          raise Errors::VersionMismatchError,
+                "Version mismatch in database files: #{versions.inspect}"
+        end
+
+        version = versions.values.first
+        return version if version == SUPPORTED_SCHEMA_VERSION
+
+        raise Errors::UnsupportedVersionError,
+              "Unsupported database version: #{version}. " \
+              "Only version #{SUPPORTED_SCHEMA_VERSION} is supported."
+      end
+
+      def build_database_hash(documents, schema_version)
+        {
+          "schema_version" => schema_version,
+        }.merge(
+          DATABASE_FILES.keys.to_h do |collection_key|
+            document = documents.fetch(collection_key)
+            [collection_key, fetch_collection!(document, collection_key)]
+          end,
+        )
+      end
+
+      def fetch_collection!(document, collection_key)
+        document.fetch(collection_key)
+      rescue KeyError
+        raise Errors::DatabaseFileInvalidError,
+              "Missing #{collection_key} collection in #{DATABASE_FILES.fetch(collection_key)}"
+      end
+    end
+
+    # Backwards-compat aliases — external callers (and the spec) read
+    # these constants off Database directly.
+    DATABASE_FILES = Loader::DATABASE_FILES
+    SUPPORTED_SCHEMA_VERSION = Loader::SUPPORTED_SCHEMA_VERSION
+  end
+end

data/lib/unitsdb/database/reference_validator.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Unitsdb
+  class Database
+    # Validates that every cross-entity reference in a Database points
+    # at an entity that actually exists. Single source of truth for
+    # both `Database#validate_references` and the
+    # `unitsdb validate references` CLI command.
+    #
+    # Composition:
+    #   ReferenceValidator    — public façade; returns a Result
+    #   IdRegistry            — builds {type => {key => path}} from db
+    #   ReferenceChecker      — walks each reference kind
+    #   LookupStrategies      — pluggable "is this ref valid?" predicates
+    class ReferenceValidator
+      # @return [Hash] empty if all refs valid; otherwise
+      #   { file_type => { ref_path => { id:, type:, ref_type: } } }
+      Result = Struct.new(:invalid, keyword_init: true) do
+        def empty?
+          invalid.empty?
+        end
+      end
+
+      def initialize(database)
+        @database = database
+      end
+
+      def validate
+        registry = IdRegistry.build(@database)
+        checker = ReferenceChecker.new(registry, LookupStrategies::ALL)
+        Result.new(invalid: checker.check_all(@database))
+      end
+
+      # Convenience entry-point used by Database#validate_references.
+      def self.validate(database)
+        new(database).validate.invalid
+      end
+    end
+
+    # Builds a {collection_type => {ref_key => path}} registry
+    # covering identifiers (composite-keyed and bare-id keyed) plus
+    # short-name lookups for dimensions and unit_systems.
+    class IdRegistry
+      def self.build(database)
+        new(database).build
+      end
+
+      def initialize(database)
+        @database = database
+      end
+
+      def build
+        registry = {}
+        Database::COLLECTIONS.each do |name|
+          registry[name.to_s] = {}
+          add_identifiers(registry, name)
+        end
+        add_short_names(registry, :dimensions, "dimensions_short")
+        add_short_names(registry, :unit_systems, "unit_systems_short")
+        registry
+      end
+
+      private
+
+      def add_identifiers(registry, collection_name)
+        collection = @database.collection(collection_name)
+        collection.each_with_index do |entity, index|
+          entity.identifiers.each do |identifier|
+            next unless identifier.id && identifier.type
+
+            composite = "#{identifier.type}:#{identifier.id}"
+            registry[collection_name.to_s][composite] = "index:#{index}"
+            registry[collection_name.to_s][identifier.id] = "index:#{index}"
+          end
+        end
+      end
+
+      def add_short_names(registry, collection_name, key)
+        registry[key.to_s] = {}
+        @database.collection(collection_name).each_with_index do |entity, idx|
+          next unless entity.short
+
+          registry[key.to_s][entity.short] = "index:#{idx}"
+        end
+      end
+    end
+
+    # Walks each reference kind in the Database and records invalid
+    # references via the supplied lookup strategies.
+    class ReferenceChecker
+      def initialize(registry, strategies)
+        @registry = registry
+        @strategies = strategies
+      end
+
+      def check_all(database)
+        invalid = {}
+        check_unit_system_references(database, invalid)
+        check_quantity_references(database, invalid)
+        check_root_unit_references(database, invalid)
+        invalid
+      end
+
+      private
+
+      def check_unit_system_references(database, invalid)
+        database.units.each_with_index do |unit, index|
+          refs = unit.unit_system_reference
+          next unless refs
+
+          refs.each_with_index do |ref, idx|
+            validate(ref, "unit_systems", "units",
+                     "units:index:#{index}:unit_system_reference[#{idx}]", invalid)
+          end
+        end
+      end
+
+      def check_quantity_references(database, invalid)
+        database.units.each_with_index do |unit, index|
+          refs = unit.quantity_references
+          next unless refs
+
+          refs.each_with_index do |ref, idx|
+            validate(ref, "quantities", "units",
+                     "units:index:#{index}:quantity_references[#{idx}]", invalid)
+          end
+        end
+      end
+
+      def check_root_unit_references(database, invalid)
+        database.units.each_with_index do |unit, index|
+          refs = unit.root_units
+          next unless refs
+
+          refs.each_with_index do |root_unit, idx|
+            if root_unit.unit_reference
+              validate(root_unit.unit_reference, "units", "units",
+                       "units:index:#{index}:root_units.#{idx}.unit_reference",
+                       invalid)
+            end
+
+            next unless root_unit.prefix_reference
+
+            validate(root_unit.prefix_reference, "prefixes", "units",
+                     "units:index:#{index}:root_units.#{idx}.prefix_reference",
+                     invalid)
+          end
+        end
+      end
+
+      def validate(ref, ref_type, file_type, ref_path, invalid)
+        pair = Reference.destructure(ref)
+        valid = if pair
+                  any_strategy_matches?(pair, ref_type)
+                else
+                  @registry.key?(ref_type) && @registry[ref_type].key?(ref)
+                end
+
+        return if valid
+
+        invalid[file_type] ||= {}
+        invalid[file_type][ref_path] = if pair
+                                         { id: pair.id, type: pair.type, ref_type: ref_type }
+                                       else
+                                         { id: ref, type: ref_type }
+                                       end
+      end
+
+      def any_strategy_matches?(pair, ref_type)
+        @strategies.any? { |s| s.call(pair, ref_type, @registry) }
+      end
+    end
+
+    # A normalized reference pair. `id` and `type` are strings.
+    ReferencePair = Struct.new(:id, :type, keyword_init: true)
+
+    # Coerces various reference shapes (Identifier instance, Hash with
+    # string keys, plain String) into a ReferencePair (or nil if the
+    # ref is a bare string with no type metadata).
+    module Reference
+      module_function
+
+      def destructure(ref)
+        case ref
+        when Unitsdb::Identifier
+          ReferencePair.new(id: ref.id, type: ref.type) if ref.id && ref.type
+        when Hash
+          ReferencePair.new(id: ref["id"], type: ref["type"]) if ref["id"] && ref["type"]
+        end
+      end
+    end
+
+    # Lookup strategies. Each is a proc that takes (pair, ref_type,
+    # registry) and returns true if the reference is valid under that
+    # strategy. Composed in ALL and tried in order by ReferenceChecker.
+    module LookupStrategies
+      # Exact "#{type}:#{id}" match.
+      COMPOSITE_KEY = ->(pair, ref_type, registry) do
+        registry.key?(ref_type) && registry[ref_type].key?("#{pair.type}:#{pair.id}")
+      end
+
+      # Bare-id match (any type). For backward compatibility with
+      # databases that only stored the id without the type.
+      BARE_ID = ->(pair, ref_type, registry) do
+        registry.key?(ref_type) && registry[ref_type].key?(pair.id)
+      end
+
+      # Unit-system alternate IDs. The UnitsML `unitsml` authority uses
+      # kebab-case (`si-base`) while NIST uses snake-case (`SI_base`).
+      # Accept either form when resolving unit_system references.
+      UNIT_SYSTEM_ALTERNATE = ->(pair, ref_type, registry) do
+        next false unless ref_type == "unit_systems" && pair.type == "unitsml"
+        next false unless registry.key?(ref_type)
+
+        alternates = []
+        alternates << pair.id
+        alternates << "SI_#{pair.id.sub('si-', '')}" if pair.id.start_with?("si-")
+        alternates << "non-SI_#{pair.id.sub('nonsi-', '')}" if pair.id.start_with?("nonsi-")
+
+        keys = registry[ref_type].keys
+        alternates.any? { |alt| keys.any? { |k| k.end_with?(":#{alt}") } }
+      end
+
+      ALL = [COMPOSITE_KEY, BARE_ID, UNIT_SYSTEM_ALTERNATE].freeze
+    end
+  end
+end

data/lib/unitsdb/database/uniqueness_validator.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Unitsdb
+  class Database
+    # Validates that `short` names and identifier ids are unique
+    # within each collection. Encodes the policy of which
+    # collections participate in each check via two constants so
+    # the intent is explicit.
+    #
+    #   UniquenessValidator.new(db).validate
+    #   # => #<struct short={...}, id={...}>
+    class UniquenessValidator
+      # Collections that carry a `short` attribute and must be
+      # unique-by-short within each collection.
+      SHORT_COLLECTIONS = %i[units dimensions unit_systems].freeze
+
+      # Collections whose identifier `id` values must be unique.
+      IDENTIFIER_COLLECTIONS = Database::COLLECTIONS
+
+      Result = Struct.new(:short, :id, keyword_init: true) do
+        def empty?
+          short.empty? && id.empty?
+        end
+      end
+
+      def initialize(database)
+        @database = database
+      end
+
+      def validate
+        Result.new(
+          short: scan_shorts,
+          id: scan_identifiers,
+        )
+      end
+
+      # Convenience entry-point used by Database#validate_uniqueness.
+      def self.validate(database)
+        result = new(database).validate
+        {
+          short: result.short,
+          id: result.id,
+        }
+      end
+
+      private
+
+      def scan_shorts
+        SHORT_COLLECTIONS.each_with_object({}) do |name, results|
+          by_value = {}
+          @database.collection(name).each_with_index do |entity, index|
+            next unless entity.short
+
+            (by_value[entity.short] ||= []) << "index:#{index}"
+          end
+
+          dups = by_value.reject { |_, paths| paths.size == 1 }
+          results[name.to_s] = dups unless dups.empty?
+        end
+      end
+
+      def scan_identifiers
+        IDENTIFIER_COLLECTIONS.each_with_object({}) do |name, results|
+          by_id = {}
+          @database.collection(name).each_with_index do |entity, index|
+            entity.identifiers.each_with_index do |identifier, id_index|
+              next unless identifier.id
+
+              loc = "index:#{index}:identifiers[#{id_index}]"
+              (by_id[identifier.id] ||= []) << loc
+            end
+          end
+
+          dups = by_id.transform_values(&:uniq).reject { |_, paths| paths.size == 1 }
+          results[name.to_s] = dups unless dups.empty?
+        end
+      end
+    end
+  end
+end