opencdd 0.1.1

data/lib/opencdd/effective_properties.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Opencdd
+  class EffectiveProperties
+    Result = Struct.new(:properties, :sources, keyword_init: true) do
+      include Enumerable
+
+      def each
+        return enum_for(:each) unless block_given?
+        properties.each { |p| yield p }
+      end
+
+      def each_property
+        return enum_for(:each_property) unless block_given?
+        properties.each { |p| yield p }
+      end
+
+      def size
+        properties.size
+      end
+
+      def include?(property)
+        irdi = property.is_a?(Opencdd::IRDI) ? property : property&.irdi
+        properties.any? { |p| p.irdi == irdi }
+      end
+
+      def codes
+        properties.map(&:code)
+      end
+
+      def to_a
+        properties.dup
+      end
+    end
+
+    attr_reader :database
+
+    def initialize(database)
+      @database = database
+    end
+
+    def for(klass)
+      k = resolve_klass(klass)
+      return Result.new(properties: [], sources: {}) unless k
+      acc = []
+      sources = Hash.new { |h, kk| h[kk] = [] }
+      accumulate(k, Set.new, acc, sources)
+      Result.new(properties: acc.uniq { |p| p.irdi }, sources: sources)
+    end
+
+    def codes_for(klass)
+      result = self.for(klass)
+      result.properties.map(&:code)
+    end
+
+    private
+
+    def resolve_klass(value)
+      return value if value.is_a?(Opencdd::Klass)
+      @database.resolve_reference(value)
+    end
+
+    def accumulate(klass, seen, acc, sources)
+      return if seen.include?(klass.irdi)
+      seen << klass.irdi
+
+      add_declared_properties(klass, acc, sources)
+      add_applicable_properties(klass, acc, sources)
+      add_imported_properties(klass, acc, sources)
+      walk_superclass(klass, seen, acc, sources)
+      walk_is_case_of(klass, seen, acc, sources)
+    end
+
+    def add_declared_properties(klass, acc, sources)
+      klass.declared_property_irdis.each do |irdi|
+        prop = @database.find(irdi)
+        next unless prop
+        acc << prop
+        sources[prop.irdi.to_s] << klass unless sources[prop.irdi.to_s].include?(klass)
+      end
+    end
+
+    def add_applicable_properties(klass, acc, sources)
+      klass.applicable_property_irdis.each do |irdi|
+        prop = @database.find(irdi)
+        next unless prop
+        acc << prop
+        sources[prop.irdi.to_s] << klass unless sources[prop.irdi.to_s].include?(klass)
+      end
+    end
+
+    def add_imported_properties(klass, acc, sources)
+      klass.imported_property_irdis.each do |irdi|
+        prop = @database.find(irdi)
+        next unless prop
+        acc << prop
+        sources[prop.irdi.to_s] << klass unless sources[prop.irdi.to_s].include?(klass)
+      end
+    end
+
+    def walk_superclass(klass, seen, acc, sources)
+      ref = klass.parent_irdi || klass.superclass_irdi
+      return unless ref
+      parent = @database.find(ref)
+      return unless parent
+      accumulate(parent, seen, acc, sources)
+    end
+
+    def walk_is_case_of(klass, seen, acc, sources)
+      klass.is_case_of_irdis.each do |ref|
+        target = @database.find(ref)
+        next unless target
+        accumulate(target, seen, acc, sources)
+      end
+    end
+  end
+end

data/lib/opencdd/entity/field_reader.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Opencdd
+  class Entity
+    # Typed reader for field declarations. Knows how to extract a
+    # value of a given kind from an entity's properties hash. The
+    # single source of truth for "what does MDC_P004.en look like"
+    # so the Json exporter, validators, and TS codegen all agree.
+    module FieldReader
+      class << self
+        # Read the +name+ field from +entity+. Multilingual fields
+        # accept a +lang:+ keyword and fall back to source-language
+        # (stored under the bare `MDC_P###` key) when the requested
+        # language is missing.
+        def read(entity, name, lang: nil)
+          entry = FieldRegistry.field_for(entity.class, name)
+          return nil unless entry
+
+          # Synthetic fields defined with a block: evaluate the block
+          # in the entity's context via instance_exec. This preserves
+          # access to private helper methods without using send to
+          # bypass privacy (encapsulation rule from CLAUDE.md).
+          return entity.instance_exec(&entry.block) if entry.block?
+
+          # Legacy form: synthetic fields name a public reader method.
+          # public_send is safe here because readers are public API.
+          return entity.public_send(entry.reader) if entry.synthetic? && entry.reader
+
+          raw =
+            if entry.multilingual?
+              raw_multilingual(entity, entry, lang)
+            else
+              entity.properties[entry.property_id]
+            end
+
+          coerce(raw, entry.value_kind)
+        end
+
+        private
+
+        def raw_multilingual(entity, entry, lang)
+          props = entity.properties
+          # The scrape stores multilingual values under "<id>.<lang>"
+          # (e.g. "MDC_P004.en", "MDC_P004.de"). Some legacy data
+          # omits the suffix entirely ("MDC_P004" with no .en). When
+          # no lang is requested, default to "en" — the historical
+          # source language for all IEC CDD dictionaries.
+          effective_lang = lang || "en"
+          props["#{entry.property_id}.#{effective_lang}"] ||
+            props[entry.property_id] ||
+            props["#{entry.property_id}.en"]
+        end
+
+        # Convert +raw+ (a String from the .xls) into the typed
+        # Ruby value the model expects. Collection kinds (:set_of_refs,
+        # :synonym_pairs) return empty arrays for nil/blank input so
+        # callers can safely iterate without nil checks — mirrors the
+        # legacy hand-written accessors.
+        def coerce(raw, value_kind)
+          case value_kind
+          when :string, :date, :date_time, :condition
+            raw.nil? ? nil : raw.to_s
+          when :irdi, :identifier_ref, :class_ref
+            parse_irdi(raw)
+          when :set_of_refs
+            parse_irdi_list_via_helpers(raw)
+          when :string_list
+            parse_string_list_via_helpers(raw)
+          when :synonym_pairs
+            parse_pair_list_via_helpers(raw)
+          when :integer
+            raw.nil? ? nil : (Integer(raw) rescue raw)
+          when :boolean
+            raw.nil? ? nil : parse_boolean(raw)
+          else
+            raw
+          end
+        end
+
+        def parse_irdi(raw)
+          return nil if raw.to_s.strip.empty?
+          Opencdd::IRDI.parse(raw)
+        rescue Opencdd::IRDI::ParseError
+          nil
+        end
+
+        # Parcel's set_of_refs and synonym_pairs wire shapes are
+        # delimited with braces/parens and commas. Parsed inline
+        # rather than via Opencdd::ParseHelpers because ParseHelpers
+        # methods are private (intended for mixin within Entity).
+        def parse_irdi_list_via_helpers(raw)
+          return [] if raw.to_s.strip.empty?
+          stripped = raw.to_s.strip.sub(/\A[\{\(\[]+/, "").sub(/[\}\)\]]+\z/, "")
+          stripped
+            .split(/[,;\s]+/)
+            .reject(&:empty?)
+            .filter_map { |s| parse_irdi(s) }
+        end
+
+        def parse_pair_list_via_helpers(raw)
+          return [] if raw.to_s.strip.empty?
+          stripped = raw.to_s.strip.sub(/\A[\{\(\[]+/, "").sub(/[\}\)\]]+\z/, "")
+          tokens = stripped.split(/[,;]+/).map(&:strip).reject(&:empty?)
+          # Parcel synonym wire shape alternates lang, name, lang, name:
+          # "(en, Foo, fr, Bidon)" → [["en", "Foo"], ["fr", "Bidon"]].
+          # If a token contains ":", treat as explicit "lang:name" pair.
+          # Otherwise group consecutive tokens into pairs.
+          if tokens.any? { |t| t.include?(":") }
+            tokens.map { |pair| parse_synonym_pair(pair) }.compact
+          else
+            tokens.each_slice(2).map { |a, b| b ? [a, b] : [nil, a] }
+          end
+        end
+
+        def parse_string_list_via_helpers(raw)
+          return [] if raw.to_s.strip.empty?
+          stripped = raw.to_s.strip.sub(/\A[\{\(\[]+/, "").sub(/[\}\)\]]+\z/, "")
+          stripped.split(/[,;]+/).map(&:strip).reject(&:empty?)
+        end
+
+        def parse_synonym_pair(pair)
+          if pair.include?(":")
+            lang, name = pair.split(":", 2).map(&:strip)
+            [lang.empty? ? nil : lang, name]
+          else
+            [nil, pair]
+          end
+        end
+
+        def parse_boolean(raw)
+          return raw unless raw.is_a?(String)
+          case raw.strip.downcase
+          when "true", "1", "yes", "y" then true
+          when "false", "0", "no", "n", "" then false
+          else raw
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opencdd/entity/field_registry.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Opencdd
+  class Entity
+    # Registry of declared fields on Entity subclasses. Open/closed:
+    # adding a field is a single `field` declaration in the entity
+    # class body — no edits to switch statements elsewhere.
+    module FieldRegistry
+      Entry = Struct.new(
+        :entity_class, :name, :property_id, :value_kind,
+        :multilingual, :synthetic, :reader, :block, :json_key,
+        keyword_init: true,
+      ) do
+        def synthetic?    = !!synthetic
+        def multilingual? = !!multilingual
+
+        # True when this field's value is computed by a block rather
+        # than read directly from +properties+. FieldReader dispatches
+        # block-defined fields via +instance_exec+, which preserves
+        # access to private helpers — no +send+ bypass required.
+        def block?
+          !block.nil?
+        end
+
+        # The key to use when serializing this field to JSON. Defaults
+        # to the field's ruby name. Override via the `as:` DSL option
+        # when the wire-format name should differ from the method
+        # name (e.g. is_case_of_irdis → is_case_of).
+        def wire_name
+          (json_key || name).to_s
+        end
+      end
+
+      @by_class = Hash.new { |h, k| h[k] = {} }
+
+      class << self
+        # Register a field on +entity_class+. The DSL in Entity.field
+        # is the only intended caller. Re-registering the same name on
+        # the same class overwrites the prior declaration (useful for
+        # subclasses overriding the value_kind).
+        #
+        # Synthetic fields prefer the +block:+ form: the block is
+        # evaluated via +instance_exec+ on the entity when the field
+        # is read, so it has access to private helpers without
+        # requiring +send+ dispatch. The legacy +reader:+ form
+        # (a Symbol naming a public method on the entity) is accepted
+        # for back-compat but should not be used for new fields.
+        def register(entity_class:, name:, property_id:, value_kind:,
+                     multilingual: false, synthetic: false, reader: nil,
+                     block: nil, json_key: nil)
+          entry = Entry.new(
+            entity_class: entity_class,
+            name: name.to_sym,
+            property_id: property_id,
+            value_kind: value_kind,
+            multilingual: multilingual,
+            synthetic: synthetic,
+            reader: reader,
+            block: block,
+            json_key: json_key,
+          )
+          @by_class[entity_class][entry.name] = entry
+          entry
+        end
+
+        # Lookup a single field by name on +entity_class+. Walks up
+        # the ancestor chain so subclasses see inherited fields.
+        def field_for(entity_class, name)
+          each_entry(entity_class) { |e| return e if e.name == name.to_sym }
+          nil
+        end
+
+        # Every field visible on +entity_class+, including inherited
+        # fields. Order: base-class declarations first, then subclass
+        # overrides (last wins on duplicate names).
+        def fields_for(entity_class)
+          seen = {}
+          each_entry(entity_class) { |e| seen[e.name] = e }
+          seen.values
+        end
+
+        private
+
+        # Walk ancestors from most-generic (Entity) to most-specific,
+        # yielding each declared entry along the way. Subclass
+        # declarations come last so they overwrite base-class entries
+        # with the same name (visible to #fields_for via the `seen`
+        # hash in callers).
+        def each_entry(entity_class)
+          entity_class.ancestors.reverse_each do |klass|
+            next unless klass.is_a?(Class)
+            entries = @by_class[klass]
+            entries.each_value { |e| yield e } if entries
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opencdd/entity/version_history.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Opencdd
+  class Entity
+    # Model object for the per-version provenance captured in
+    # +downloads/<dict>/<CODE>/_entity.json#versions+. Each entry
+    # represents one historical version of the entity: which version
+    # and revision it was, its status at that point, who committed it,
+    # and the change-request ID.
+    #
+    # The ShardedDirReader parses +_entity.json+ for each class subdir
+    # and attaches a VersionHistory to every entity it creates. The
+    # Json exporter then emits it as an array of version entries,
+    # matching the IEC CDD "Version history" section on detail pages.
+    class VersionHistory
+      Entry = Struct.new(
+        :version, :revision, :status, :timestamp, :user,
+        :change_request_id, :unid, :is_current,
+        keyword_init: true,
+      ) do
+        def current? = !!is_current
+      end
+
+      include Enumerable
+
+      def initialize(entries = [])
+        @entries = Array(entries)
+      end
+
+      attr_reader :entries
+
+      def each(&block)
+        @entries.each(&block)
+      end
+
+      def size
+        @entries.size
+      end
+
+      def empty?
+        @entries.empty?
+      end
+
+      def current
+        @entries.find(&:current?) || @entries.first
+      end
+
+      def previous
+        @entries.reject { |e| e == current }
+      end
+
+      def to_a
+        @entries.dup
+      end
+
+      def attach(entry)
+        @entries << entry
+        self
+      end
+    end
+  end
+end

data/lib/opencdd/entity.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Opencdd
+  class Entity
+    include Opencdd::ParseHelpers
+
+    # Open/closed field declaration. Each `field :foo, "MDC_P###",
+    # :kind` call registers a typed accessor on the entity class and
+    # adds an entry to FieldRegistry. Adding a field is one line
+    # here — no edits to switch statements in the exporter,
+    # validators, or TS codegen (all read from FieldRegistry).
+    autoload :FieldRegistry,   "opencdd/entity/field_registry"
+    autoload :FieldReader,     "opencdd/entity/field_reader"
+    autoload :VersionHistory,  "opencdd/entity/version_history"
+
+    class << self
+      # Declare a typed field on this entity class. Defaults for
+      # +value_kind+ and +multilingual+ are resolved from
+      # +Opencdd::PropertyIds::REGISTRY+ when the +property_id+ is known
+      # there — the REGISTRY is the SSOT for wire-format metadata,
+      # and re-declaring it here would violate DRY.
+      #
+      # Pass an explicit +value_kind+ to override (used when REGISTRY's
+      # kind doesn't match how the field is consumed — e.g. MDC_P023
+      # is :identifier_ref in REGISTRY but Unit#structure uses it as
+      # a raw string).
+      #
+      # +synthetic: true+ for computed fields with no MDC_P### —
+      # requires a block (preferred) that returns the value. The
+      # block is evaluated via +instance_exec+ on the entity, so it
+      # has access to private helpers without +send+ dispatch.
+      def field(name, property_id = nil, value_kind = nil,
+                multilingual: nil, synthetic: false, reader: nil,
+                as: nil, &block)
+        resolved_kind, resolved_ml = resolve_from_registry(property_id)
+        Opencdd::Entity::FieldRegistry.register(
+          entity_class: self,
+          name: name,
+          property_id: property_id,
+          value_kind: value_kind || resolved_kind || :string,
+          multilingual: multilingual.nil? ? resolved_ml : multilingual,
+          synthetic: synthetic,
+          reader: reader,
+          block: block,
+          json_key: as,
+        )
+        define_method(name) do |lang = nil|
+          Opencdd::Entity::FieldReader.read(self, name, lang: lang)
+        end
+      end
+
+      private
+
+      def resolve_from_registry(property_id)
+        return [nil, false] unless property_id
+        entry = Opencdd::PropertyIds::REGISTRY[property_id.to_s]
+        return [nil, false] unless entry
+        [entry.value_kind, entry.multilingual]
+      end
+    end
+
+    META_CLASS_CODE = nil
+
+    attr_reader :irdi, :properties, :schema, :meta_class_irdi, :source_location
+
+    def self.from_row(row, schema:, meta_class_irdi:, code_property_id: nil)
+      code_property_id ||= default_code_property_id(meta_class_irdi)
+      raw_code = code_property_id && row[code_property_id]
+      irdi = raw_code && Opencdd::IRDI.parse(raw_code)
+
+      props = row.each_with_object({}) do |(k, v), h|
+        next if k == "__row_index__"
+        h[k] = v if v
+      end
+
+      new(irdi: irdi, properties: props, schema: schema, meta_class_irdi: meta_class_irdi)
+    end
+
+    def self.default_code_property_id(meta_class_irdi)
+      Opencdd::MetaClasses.code_property_id_for(meta_class_irdi&.code)
+    end
+
+    def initialize(irdi:, properties:, schema: nil, meta_class_irdi: nil)
+      @irdi = irdi
+      @properties = properties
+      @schema = schema
+      @meta_class_irdi = meta_class_irdi
+      @version_history = Opencdd::Entity::VersionHistory.new
+    end
+
+    def type
+      Opencdd::Parcel::META_CLASS_TYPES[meta_class_irdi&.code]
+    end
+
+    def code
+      @irdi&.code
+    end
+
+    alias_method :short, :code
+
+    # ── Pure field reads (value_kind and multilingual auto-resolved
+    #     from PropertyIds::REGISTRY). `as:` aliases preserve the
+    #     existing JSON wire shape — ruby method names differ from
+    #     historical JSON keys for backward compatibility. ─────────
+    # Note: irdi and code are NOT declared as DSL fields — they're
+    # emitted explicitly by Exporters::Json#entity_payload because
+    # the model's `irdi` accessor must return the Opencdd::IRDI object
+    # (not a String); DSL emission would override it.
+    field :version,           "MDC_P002_1"
+    field :revision,          "MDC_P002_2"
+    field :preferred_name,    "MDC_P004"   # multilingual via REGISTRY
+    field :short_name,        "MDC_P005"   # multilingual via REGISTRY
+    field :definition,        "MDC_P006"   # multilingual via REGISTRY
+    # source_document wins the MDC_P006_1 dedup (declared before the
+    # _of_definition alias); JSON key is "source_document".
+    field :source_document,              "MDC_P006_1"
+    field :source_document_of_definition, "MDC_P006_1"
+    field :synonyms,           "MDC_P007", :synonym_pairs, multilingual: true, as: "synonyms"
+    field :synonymous_names,   "MDC_P007", :synonym_pairs, multilingual: true
+    field :note,              "MDC_P008"   # multilingual via REGISTRY
+    field :simplified_drawing, "MDC_P008_1", :string
+    field :remark,            "MDC_P009"   # multilingual via REGISTRY
+    field :description,       "MDC_P112"   # multilingual via REGISTRY
+    field :example,           "MDC_P113"
+    field :guid,              "MDC_P066", as: "guid"
+    field :data_object_identifier, "MDC_P066"
+    field :time_stamp,        "MDC_P067"
+
+    # ── C### workbook-specific codes. These are IEC CDD export column
+    #     identifiers that don't have MDC_P### codes in PropertyIds::REGISTRY.
+    #     They carry publisher, status, committee, and change-request data.
+    #     Declared as synthetic (no MDC_P###) with block-form readers
+    #     evaluated via instance_exec (no send-to-private bypass).
+    field(:status_level,         synthetic: true) { @properties["C016"] }
+    field(:publisher,            synthetic: true) { @properties["C011"] }
+    field(:published_in,         synthetic: true) { @properties["C012"] }
+    field(:responsible_committee, synthetic: true) { @properties["MDC_P012"] || @properties["C019.en"] }
+    field(:change_request_id,    synthetic: true) { @properties["C002"] }
+
+    # ── Full raw properties dump. Every key in @properties appears
+    #     in the JSON output. This guarantees "full import" — every
+    #     column from the .xls is preserved, including multilingual
+    #     variants (MDC_P004.en/de/fr/zh), C### workbook-specific
+    #     codes (status, publisher, etc.), and sub-IDs the DSL
+    #     hasn't named yet. The browser can render typed fields
+    #     nicely and fall back to raw_properties for completeness.
+    field(:raw_properties, synthetic: true) { @properties }
+
+    # ── Per-version provenance from _entity.json#versions. Set by
+    #     Opencdd::Parcel::ShardedDirReader after entity creation. The
+    #     DSL serializer converts VersionHistory → array of entry
+    #     hashes for JSON emission.
+    field(:version_history, synthetic: true) { @version_history }
+
+    # ── Computed field with custom block ────────────────────────
+    Dates = Struct.new(:original_definition, :current_version, :current_revision, keyword_init: true)
+
+    field(:dates, synthetic: true) do
+      Dates.new(
+        original_definition: @properties[Opencdd::PropertyIds::MDC_P003_1],
+        current_version:     @properties[Opencdd::PropertyIds::MDC_P003_2],
+        current_revision:    @properties[Opencdd::PropertyIds::MDC_P003_3],
+      )
+    end
+
+    def [](key)
+      @properties[key.to_s]
+    end
+
+    def key?(key)
+      @properties.key?(key.to_s)
+    end
+
+    def keys
+      @properties.keys
+    end
+
+    def each_property
+      return enum_for(:each_property) unless block_given?
+      @properties.each { |k, v| yield k, v }
+    end
+
+    def eql?(other)
+      other.is_a?(Opencdd::Entity) &&
+        irdi == other.irdi &&
+        type == other.type
+    end
+
+    def hash
+      [irdi, type].hash
+    end
+
+    alias_method :==, :eql?
+
+    def inspect
+      "#<#{self.class.name} #{irdi}>"
+    end
+
+    def replace_irdi!(new_irdi)
+      @irdi = Opencdd::IRDI === new_irdi ? new_irdi : Opencdd::IRDI.parse(new_irdi.to_s)
+      self
+    end
+
+    def replace_code_value!(code_property_id, new_code)
+      return self unless code_property_id
+      @properties[code_property_id.to_s] = new_code.to_s
+      self
+    end
+
+    # ── Field DSL access seam ───────────────────────────────────
+    #
+    # The canonical way to read or write a typed field on an entity.
+    # Goes through FieldRegistry so multilingual, value-kind, and
+    # synthetic-field semantics are consistent across all callers
+    # (SheetEmitter, Json exporter, validator, GUID setter, etc.).
+    # Callers that index +properties+ directly bypass these and
+    # risk round-trip drift — see TODO.impl/26.
+
+    # Read a declared field by name. Accepts an optional +lang:+ for
+    # multilingual fields. Returns the typed value (parsed IRDI,
+    # Array, etc.) per the field's declared value_kind.
+    def read_field(name, lang: nil)
+      Opencdd::Entity::FieldReader.read(self, name, lang: lang)
+    end
+
+    # Write a value to a property ID, routing through canonical-id
+    # alias resolution so writes are consistent with reads. Use
+    # this in preference to +entity.properties[id] = value+ from
+    # non-infrastructure callers.
+    def write_property!(id, value)
+      canonical = Opencdd::PropertyIds.canonical_id(id.to_s) || id.to_s
+      base = canonical.to_s.split(".").first
+      @properties[base] = value.to_s
+      self
+    end
+
+    # Attach per-version provenance captured in _entity.json. Called
+    # by Opencdd::Parcel::ShardedDirReader after entity creation — the
+    # constructor doesn't take it because FlatDirReader creates
+    # entities from .xls rows without version context.
+    def attach_version_history(version_history)
+      @version_history = version_history
+      self
+    end
+
+    # Attach source location (file:line) where this entity was
+    # declared. Set by Opencdd::Cddal::Builder from import/instantiation
+    # context. Nil for entities constructed from Parcel readers
+    # (which don't have a single source file).
+    def attach_source_location(loc)
+      @source_location = loc
+      self
+    end
+  end
+end