opencdd 0.1.1

data/lib/opencdd/klass.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module Opencdd
+  class Klass < Opencdd::Entity
+    PARENT_PROPERTY_IDS = [Opencdd::PropertyIds::MDC_P010_1, Opencdd::PropertyIds::MDC_P010].freeze
+
+    # Read-only accessors for state that the Database mutates via
+    # the explicit mutator methods below. Exposing only readers
+    # (instead of attr_accessor) keeps the entity's invariants
+    # under the class's control: parent linkage, child registration,
+    # and declared-property tracking each have a single mutator
+    # that can guard against duplicates, cycles, and stale state.
+    attr_reader :parent_irdi, :children, :declared_property_irdis, :database
+
+    def initialize(irdi: nil, properties:, schema: nil, meta_class_irdi: nil)
+      super
+      @children = []
+      @declared_property_irdis = []
+    end
+
+    # ── Mutators (called by Opencdd::Database and Opencdd::Cddal::Builder
+    #     during finalize/link phases). Single entry points keep
+    #     invariant checks (dedup, validity) in one place. ──────
+
+    def attach_parent_irdi(irdi)
+      @parent_irdi = irdi
+      self
+    end
+
+    def add_child(klass)
+      return self if @children.include?(klass)
+      @children << klass
+      self
+    end
+
+    def declare_property(irdi)
+      return self if @declared_property_irdis.include?(irdi)
+      @declared_property_irdis << irdi
+      self
+    end
+
+    def attach_database(database)
+      @database = database
+      self
+    end
+
+    # ── Pure field reads ─────────────────────────────────────────
+    field :is_case_of_irdis,           "MDC_P013", as: "is_case_of"
+    field :applicable_property_irdis,  "MDC_P014", as: "applicable_properties"
+    field :imported_property_irdis,    "MDC_P090", as: "imported_properties"
+    field :sub_class_selection_irdis,  "MDC_P016", as: "sub_class_selection"
+    field :applicable_documents,       "MDC_P094"
+    field :imported_documents,         "MDC_P093"
+
+    # ── Computed fields with block-form readers ──────────────────
+    field(:class_type, synthetic: true) do
+      @class_type ||= Opencdd::ClassType.parse(properties[Opencdd::PropertyIds::MDC_P011])
+    end
+    field(:superclass_irdi, synthetic: true, as: "superclass") do
+      raw = properties[Opencdd::PropertyIds::MDC_P010_1] || properties[Opencdd::PropertyIds::MDC_P010]
+      next nil if raw.nil? || raw.to_s.strip.empty?
+      Opencdd::IRDI.parse(raw)
+    end
+    field(:superclass_type_property, synthetic: true) do
+      properties[Opencdd::PropertyIds::MDC_P010_1] || properties[Opencdd::PropertyIds::MDC_P010]
+    end
+
+    alias_method :parent_property_value, :superclass_irdi
+
+    def parent_property_id
+      return @parent_property_id if defined?(@parent_property_id)
+      @parent_property_id = detect_parent_property_id
+    end
+
+    def parent
+      return nil unless @parent_irdi && @database
+      @database.find(@parent_irdi)
+    end
+
+    def ancestors
+      out = []
+      cur = self
+      while cur
+        out << cur
+        ref = cur.parent_irdi || cur.superclass_irdi
+        break unless ref
+        break if out.any? { |a| a.irdi == ref }
+        parent_obj = cur.database&.find(ref)
+        break unless parent_obj
+        cur = parent_obj
+      end
+      out
+    end
+
+    def descendants
+      out = []
+      queue = children.dup
+      seen = { irdi => true }
+      until queue.empty?
+        c = queue.shift
+        next if seen[c.irdi]
+        seen[c.irdi] = true
+        out << c
+        queue.concat(c.children)
+      end
+      out
+    end
+
+    def subclasses
+      children
+    end
+
+    def properties_on_class(database = @database)
+      return [] unless database
+      declared_property_irdis.map { |i| database.find(i) }.compact
+    end
+
+    def all_properties(database = @database)
+      return effective_properties if database
+      properties_on_class(database)
+    end
+
+    def effective_properties(database = @database)
+      return [] unless database
+      database.effective_properties.for(self)
+    end
+
+    def is_case_of(database = @database)
+      return [] unless database
+      is_case_of_irdis.map { |i| database.find(i) }.compact
+    end
+
+    def sub_class_selection(database = @database)
+      return [] unless database
+      sub_class_selection_irdis.map { |i| database.find(i) }.compact
+    end
+
+    # ── Powertype semantics (CDD four-layer ontology) ───────────
+    #
+    # A CATEGORICAL_CLASS at M1 occupies the powertype position: its
+    # subclasses ARE themselves classes, but they are also treated
+    # as *instances* of the categorical class for the purpose of
+    # CLASS_REFERENCE data types and sub_class_selection. This is
+    # the distinguishing capability of CDD vs UML/RDF/OWL.
+    #
+    # Example (OceanRunner):
+    #   EngineType (CATEGORICAL_CLASS)
+    #     ├── SingleDieselEngine  (ITEM_CLASS)
+    #     ├── TwinDieselEngine    (ITEM_CLASS)
+    #     └── ElectricHybridEngine (ITEM_CLASS)
+    #
+    # EngineType#powertype? returns true.
+    # EngineType#categorical_instances returns [SingleDiesel, TwinDiesel,
+    # ElectricHybrid] — the valid values for any CLASS_REFERENCE(EngineType)
+    # property.
+
+    def powertype?
+      categorical?
+    end
+
+    # Returns the powertype instances of this categorical class —
+    # direct children that are themselves classes (ITEM_CLASS or
+    # VALUE_CLASS terminal types). Returns empty for non-powertype
+    # classes or when +database+ is unavailable.
+    def categorical_instances(database = @database)
+      return [] unless powertype? && database
+      children.select { |c| c.item? || c.value_class? || c.powertype? }
+    end
+
+    # Sub-powertypes: categorical classes that specialize this one.
+    # E.g. PrimaryColor (CATEGORICAL) under Color (CATEGORICAL) is a
+    # sub-powertype. Useful for hierarchical option trees.
+    def sub_powertypes(database = @database)
+      return [] unless powertype? && database
+      children.select(&:powertype?)
+    end
+
+    # Walks the ancestor chain and returns the categorical classes
+    # this class is an instance of (in the powertype sense). For
+    # SingleDiesel: [EngineType]. For a configured product subclass
+    # under EngineType + InteriorPackage: [EngineType, InteriorPackage].
+    def powertype_owners(database = @database)
+      return [] unless database
+      ancestors.filter_map do |a|
+        next if a == self
+        a if a.powertype?
+      end
+    end
+
+    def attach_database(database)
+      @database = database
+      self
+    end
+
+    def item?
+      class_type&.item?
+    end
+
+    def categorical?
+      class_type&.categorical?
+    end
+
+    def value_class?
+      class_type&.value_class?
+    end
+
+    def message?
+      class_type&.message?
+    end
+
+    private
+
+    def detect_parent_property_id
+      return Opencdd::PropertyIds::MDC_P010 unless @schema
+
+      PARENT_PROPERTY_IDS.each do |id|
+        return id if @schema.find_by_property_id(id)
+      end
+
+      @schema.each do |col|
+        next unless col.name.to_s =~ /superclass|subclass of|parent/i
+        next if col.name.to_s =~ /sub alternate/i
+        return col.property_id
+      end
+
+      col = @schema.find_by_name("Subclass of") || @schema.find_by_name("Superclass")
+      col&.property_id
+    end
+  end
+end

data/lib/opencdd/languages.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Opencdd
+  # Value object representing the language configuration of a CDD
+  # dictionary. The source language is the one the data was originally
+  # authored in; translation languages are additional languages that
+  # appear in the .xls property keys (e.g. +MDC_P004.de+).
+  #
+  # The exporter scans each entity's +@properties+ hash for
+  # +<property_id>.<lang>+ keys to build per-field language maps
+  # (TODO.work/08). This class is the model object that aggregates
+  # "what languages does this dictionary have?" — used by the browser
+  # to render a language switcher and by the data pipeline to report
+  # language coverage.
+  class Languages
+    attr_reader :source, :translations
+
+    def initialize(source: "en", translations: [])
+      @source = source.to_s
+      @translations = Array(translations).map(&:to_s).uniq - [@source]
+      freeze
+    end
+
+    def all
+      [@source] + @translations
+    end
+
+    def include?(lang)
+      all.include?(lang.to_s)
+    end
+
+    def empty?
+      @source.nil? || @source.empty?
+    end
+
+    def size
+      all.size
+    end
+
+    def to_a
+      all
+    end
+
+    def ==(other)
+      other.is_a?(Opencdd::Languages) && source == other.source &&
+        translations == other.translations
+    end
+    alias_method :eql?, :==
+
+    def hash
+      [source, translations].hash
+    end
+
+    # Scan a properties hash for +<property_id>.<lang>+ keys and
+    # return a Languages object covering every language seen. The
+    # source language defaults to +default_source+ when no explicit
+    # source-language key is present.
+    def self.from_properties(properties, default_source: "en")
+      langs = properties.keys.each_with_object(Set.new) do |key, acc|
+        next unless key.include?(".")
+        prefix, lang = key.split(".", 2)
+        next unless lang =~ /\A[a-z]{2}(-[a-z0-9]+)?\z/i
+        acc << lang
+      end
+      source = langs.include?(default_source) ? default_source : (langs.first || default_source)
+      translations = langs.to_a - [source]
+      new(source: source, translations: translations)
+    end
+  end
+end

data/lib/opencdd/meta_class.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module Opencdd
+  # CDD is a four-layer ontology (IEC 61360 §5):
+  #
+  #   M2 (meta-model)  — the meta-classes themselves: MDC_C002 Class,
+  #                      MDC_C003 Property, MDC_C009 Unit, etc.
+  #                      Fixed set per the standard. Each is modeled
+  #                      by an +Opencdd::MetaClass+ instance.
+  #   M1 (model)       — dictionary content: AAA001 Vehicle, AAAP001
+  #                      vehicle_length, etc. Instances of M2
+  #                      meta-classes, modeled by Opencdd::Entity
+  #                      subclasses (Klass, Property, Unit, ...).
+  #   M0 (data)        — real-world individuals: ORCA30-TH-0001 etc.
+  #                      Instances of M1 classes.
+  #
+  # CDD's defining feature vs UML/RDF/OWL: at M1, a class declared
+  # +class_type=CATEGORICAL_CLASS+ has subclasses that ARE themselves
+  # classes but are also "instances" of the categorical class in the
+  # powertype sense (used in CLASS_REFERENCE data types and
+  # +sub_class_selection+). This two-level capability is the central
+  # abstraction the model must preserve.
+  class MetaClass
+    # Parcel sheet-type label (string written to the sheetmap "type"
+    # column). Single source of truth — Database, Writer, and
+    # WorkbookReader all read from MetaClass#sheet_type instead of
+    # maintaining parallel lookup tables.
+    PARCEL_SHEET_TYPES = {
+      class:        "CLASS",
+      property:     "PROPERTY",
+      value_list:   "ENUM",
+      value_term:   "TERMINOLOGY",
+      unit:         "UoM",
+      relation:     "RELATION",
+      view_control: "VIEWCONTROL",
+    }.freeze
+
+    attr_reader :irdi, :name, :allowed_property_ids, :entity_class,
+                :type, :sheet_type
+
+    def initialize(irdi:, name:, entity_class: nil, allowed_property_ids: [],
+                   type: nil, sheet_type: nil)
+      @irdi = irdi.to_s
+      @name = name.to_s
+      @entity_class = entity_class
+      @allowed_property_ids = allowed_property_ids.map(&:to_s).freeze
+      @type = type
+      @sheet_type = sheet_type || (type ? PARCEL_SHEET_TYPES[type] : nil)
+    end
+
+    def code = @irdi
+
+    def allows_property?(id)
+      @allowed_property_ids.include?(id.to_s)
+    end
+
+    def merge(other)
+      raise ArgumentError, "meta-class IRDI mismatch: #{other.irdi} != #{@irdi}" unless other.irdi == @irdi
+      MetaClass.new(
+        irdi: @irdi,
+        name: @name,
+        entity_class: @entity_class || other.entity_class,
+        allowed_property_ids: (@allowed_property_ids + other.allowed_property_ids).uniq,
+        type: @type || other.type,
+        sheet_type: @sheet_type || other.sheet_type,
+      )
+    end
+
+    def to_s
+      "#<#{self.class.name} #{@irdi} (#{@name}) type=#{@type} properties=#{@allowed_property_ids.size}>"
+    end
+    alias_method :inspect, :to_s
+
+    module MetaClasses
+      CODE_PROPERTY_IDS = {
+        "MDC_C002" => "MDC_P001_5",
+        "MDC_C003" => "MDC_P001_6",
+        "MDC_C005" => "MDC_P001_12",
+        "MDC_C011" => "MDC_P001_13",
+        "MDC_C009" => "MDC_P001_10",
+        "MDC_C010" => "MDC_P001_11",
+        "EXT_C001" => "EXT_P001",
+      }.freeze
+
+      TYPE_BY_META_CLASS = {
+        "MDC_C002" => :class,
+        "MDC_C003" => :property,
+        "MDC_C005" => :value_list,
+        "MDC_C011" => :relation,
+        "MDC_C009" => :unit,
+        "MDC_C010" => :value_term,
+        "EXT_C001" => :view_control,
+      }.freeze
+
+      @registry = nil
+
+      class << self
+        def common_property_ids
+          Opencdd::PropertyIds::REGISTRY.select { |_, e| e.applies_to == :all }.keys.freeze
+        end
+        def register(meta_class)
+          ensure_loaded
+          existing = @registry[meta_class.irdi]
+          merged = existing ? existing.merge(meta_class) : meta_class
+          @registry[meta_class.irdi] = merged
+          merged
+        end
+
+        def for(irdi)
+          ensure_loaded
+          @registry[irdi.to_s]
+        end
+
+        def all
+          ensure_loaded
+          @registry.values
+        end
+
+        def codes
+          ensure_loaded
+          @registry.keys
+        end
+
+        def reset!
+          @registry = built_in_registry
+          define_code_constants!
+          self
+        end
+
+        def type_for(irdi)
+          TYPE_BY_META_CLASS[irdi.to_s]
+        end
+
+        def code_property_id_for(irdi)
+          CODE_PROPERTY_IDS[irdi.to_s]
+        end
+
+        # Reverse of +meta_class_for_type+: returns the Ruby entity
+        # class (Opencdd::Klass, Opencdd::Property, etc.) registered
+        # for a given +type+ Symbol. Single source of truth — used
+        # by Database#add_workbook to dispatch entity construction
+        # without maintaining its own type→class map.
+        def entity_class_for_type(type)
+          code = meta_class_for_type(type)
+          return nil unless code
+          ensure_loaded
+          @registry[code]&.entity_class
+        end
+
+        # Parcel sheet-type label ("CLASS", "PROPERTY", "ENUM",
+        # "TERMINOLOGY", "UoM", "RELATION", "VIEWCONTROL") for a
+        # given +type+ Symbol. Used by Database#build_sheetmap_for
+        # and Parcel::Writer instead of local lookup tables.
+        def sheet_type_for_type(type)
+          MetaClass::PARCEL_SHEET_TYPES[type.to_sym]
+        end
+
+        def sheet_type_for(irdi)
+          ensure_loaded
+          @registry[irdi.to_s]&.sheet_type
+        end
+
+        def meta_class_for_type(type)
+          TYPE_BY_META_CLASS.key(type.to_sym) || TYPE_BY_META_CLASS.key(type.to_s.to_sym)
+        end
+
+        private
+
+        def ensure_loaded
+          return if @registry
+          @registry = built_in_registry
+          define_code_constants!
+        end
+
+        def define_code_constants!
+          @registry.each_key do |code|
+            unless const_defined?(code, false)
+              const_set(code, code.freeze)
+            end
+          end
+        end
+
+        def built_in_registry
+          common = common_property_ids
+          klass_class = MetaClass.new(
+            irdi: "MDC_C002",
+            name: "Class",
+            entity_class: Opencdd::Klass,
+            type: :class,
+            allowed_property_ids: common + %w[
+              MDC_P010 MDC_P010_1 MDC_P011 MDC_P012 MDC_P013 MDC_P014 MDC_P014_1 MDC_P014_2
+              MDC_P015 MDC_P015_1 MDC_P015_2 MDC_P016
+              MDC_P090 MDC_P091 MDC_P093 MDC_P094 MDC_P094_1 MDC_P094_2
+            ],
+          )
+          property_class = MetaClass.new(
+            irdi: "MDC_C003",
+            name: "Property",
+            entity_class: Opencdd::Property,
+            type: :property,
+            allowed_property_ids: common + %w[
+              MDC_P017 MDC_P018 MDC_P020 MDC_P021 MDC_P022 MDC_P023 MDC_P023_1 MDC_P023_2
+              MDC_P024 MDC_P025_1 MDC_P025_2 MDC_P025_3
+              MDC_P027_1 MDC_P027_2 MDC_P028
+              MDC_P030 MDC_P031 MDC_P032 MDC_P033 MDC_P040
+              MDC_P041 MDC_P042 MDC_P068 MDC_P096 MDC_P097
+              MDC_P101 MDC_P102 MDC_P110 MDC_P111 MDC_P114
+            ],
+          )
+          value_list = MetaClass.new(
+            irdi: "MDC_C005",
+            name: "ValueList",
+            entity_class: Opencdd::ValueList,
+            type: :value_list,
+            allowed_property_ids: common + %w[
+              MDC_P043 MDC_P044 MDC_P045 MDC_P046
+            ],
+          )
+          relation = MetaClass.new(
+            irdi: "MDC_C011",
+            name: "Relation",
+            entity_class: Opencdd::Relation,
+            type: :relation,
+            allowed_property_ids: common + %w[
+              MDC_P200 MDC_P201 MDC_P202 MDC_P203 MDC_P204 MDC_P205
+              MDC_P206 MDC_P207 MDC_P208 MDC_P209 MDC_P210 MDC_P211 MDC_P212
+              MDC_P230 MDC_P231
+            ],
+          )
+          unit = MetaClass.new(
+            irdi: "MDC_C009",
+            name: "Unit",
+            entity_class: Opencdd::Unit,
+            type: :unit,
+            allowed_property_ids: common + %w[
+              MDC_P021 MDC_P023 MDC_P023_1 MDC_P023_2
+            ],
+          )
+          value_term = MetaClass.new(
+            irdi: "MDC_C010",
+            name: "ValueTerm",
+            entity_class: Opencdd::ValueTerm,
+            type: :value_term,
+            allowed_property_ids: common + %w[
+              MDC_P018_1 MDC_P021 MDC_P022 MDC_P044 MDC_P045
+            ],
+          )
+          view_control = MetaClass.new(
+            irdi: "EXT_C001",
+            name: "ViewControl",
+            entity_class: Opencdd::ViewControl,
+            type: :view_control,
+            allowed_property_ids: common + %w[EXT_P002 EXT_P003],
+          )
+          {
+            klass_class.irdi    => klass_class,
+            property_class.irdi => property_class,
+            value_list.irdi     => value_list,
+            relation.irdi       => relation,
+            unit.irdi           => unit,
+            value_term.irdi     => value_term,
+            view_control.irdi   => view_control,
+          }
+        end
+      end
+    end
+  end
+
+  MetaClasses = MetaClass::MetaClasses
+
+  MetaClass::MetaClasses::TYPE_BY_META_CLASS.each_key do |code|
+    MetaClasses.const_set(code, code.freeze) unless MetaClasses.const_defined?(code, false)
+  end
+end

data/lib/opencdd/model/entity_store.rb

@@ -0,0 +1,85 @@
+# frozen_string: true
+
+require "lutaml/store"
+require "fileutils"
+
+module Opencdd
+  module Model
+    # Per-entity YAML persistence using lutaml-store as the backend.
+    # Each entity is stored as a single YAML file in a directory layout,
+    # serialized via Lutaml::Model (YamlEntity). Diff-friendly at the
+    # entity level — one git diff shows exactly which entity changed.
+    #
+    # Directory layout (managed by lutaml-store's FileSystem adapter):
+    #
+    #   data/
+    #   └── entities/
+    #       ├── AA/
+    #       │   ├── AAA001.data
+    #       │   └── AAA010.data
+    #       └── ...
+    #
+    # The FileSystem adapter shards by first 2 chars for scalability.
+    class EntityStore
+      attr_reader :path, :store
+
+      def initialize(path)
+        @path = File.expand_path(path.to_s)
+        FileUtils.mkdir_p(@path)
+        @store = Lutaml::Store.new(
+          adapter: :filesystem,
+          adapter_options: { path: @path },
+          models: [
+            { model: Opencdd::Model::YamlEntity, key: :irdi, dir: "entities" },
+          ],
+        )
+      end
+
+      # Save all entities from +database+ to individual YAML files
+      # via lutaml-store's FileSystem backend. Returns self.
+      def save_database(database)
+        database.entities.each do |entity|
+          yaml_entity = Opencdd::Model::YamlEntity.from_entity(entity)
+          key = safe_key(yaml_entity.irdi || yaml_entity.code)
+          next unless key
+          yaml_str = yaml_entity.to_yaml
+          @store.store.adapter.set(key, yaml_str)
+        end
+        self
+      end
+
+      # Load all YAML files from the store into a Database.
+      # Returns a finalized Database.
+      def load_database(database = nil)
+        database ||= Opencdd::Database.new
+        @store.store.adapter.keys.each do |key|
+          raw = @store.store.adapter.get(key)
+          next unless raw
+          begin
+            yaml_entity = Opencdd::Model::YamlEntity.from_yaml(raw)
+            entity = yaml_entity.to_entity(database)
+            database.add_entity(entity)
+          rescue StandardError => e
+            warn "EntityStore: skipping #{key}: #{e.message}"
+          end
+        end
+        database.finalize!
+        database
+      end
+
+      # Fetch a single entity by key.
+      def fetch(key)
+        raw = @store.store.adapter.get(safe_key(key))
+        return nil unless raw
+        Opencdd::Model::YamlEntity.from_yaml(raw)
+      end
+
+      private
+
+      def safe_key(key)
+        return nil if key.nil? || key.to_s.strip.empty?
+        key.to_s.split("#").last || key.to_s
+      end
+    end
+  end
+end

data/lib/opencdd/model/yaml_database.rb

@@ -0,0 +1,49 @@
+# frozen_string: true
+
+require "lutaml/model"
+
+module Opencdd
+  module Model
+    # CDD-native YAML database. Wraps a collection of YamlEntity
+    # objects with dictionary-level metadata (source language,
+    # translation languages). Serializes to YAML via lutaml-model
+    # — no hand-rolled serialization on the model class itself.
+    #
+    # YAML shape:
+    #
+    #   ---
+    #   source_language: en
+    #   translation_languages:
+    #     - fr
+    #     - ja
+    #   entities:
+    #     - irdi: 0112/2///61360_4#AAA001
+    #       type: class
+    #       code: AAA001
+    #       preferred_name:
+    #         en: Vehicle
+    #       ...
+    class YamlDatabase < Lutaml::Model::Serializable
+      attribute :source_language, :string, default: "en"
+      attribute :translation_languages, :string, collection: true
+      attribute :entities, YamlEntity, collection: true
+
+      # ── Conversion: Database → YamlDatabase ─────────────────
+      def self.from_database(database)
+        new(
+          source_language: "en",
+          translation_languages: [],
+          entities: database.entities.map { |e| YamlEntity.from_entity(e) },
+        )
+      end
+
+      # ── Conversion: YamlDatabase → Database ─────────────────
+      def to_database(database = nil)
+        database ||= Opencdd::Database.new
+        entities.each { |ye| database.add_entity(ye.to_entity(database)) }
+        database.finalize!
+        database
+      end
+    end
+  end
+end