opencdd 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74a134259cf9d336b0e401139d10fcda58d1df883ec52312e04eadd2c6016bb9
-  data.tar.gz: b2c6cd320d420f7258c4116c218e0de50850d9ebb1745f81e4b06c33113196ef
+  metadata.gz: 9fc81f8bcb07863fa5c69e681de61f2d198f39bc81a0fc59da37ec987c9b2a1f
+  data.tar.gz: 90e951f6174389ecab19ae8170b3e23ed8ff3e7d79602505f9ae2bd517369384
 SHA512:
-  metadata.gz: 5147138e2581efbaf28bf224de9c56ed541040cdedec3569436c786419df35fc190a144982d78d53ca7d1ce4d4b7f73b7cd21847d5c3597e1987b0ade886db85
-  data.tar.gz: 9bd7ee2d030cfb9792177763875b02114aca94534754986fe17ba6c7b24dcf5cd47ad9361fd9f9533c8d3fcbdc4bcc296d4610b335809358d5a6d3ae9844f0f0
+  metadata.gz: c20ebb47fc6253b09cc1dc083066aadb552af65606c77400c932a3f78ac1ee08e78b431eb69a7409a1c9ec9dd2059b7d6d3a6ce78c0143393b6fd80f8c6a89dc
+  data.tar.gz: 50c2e7547728041faa53a8acc143e545628e5d3750d61dd55b36e2cd7ec980ee0a7af4755e2fafd8024f0d67a9e4c9cdb9f2140274ae893d8aba29906d26f185

data/CLAUDE.md

@@ -448,6 +448,18 @@ ParcelMaker's interactive flows in a browser. Plans are in `TODO.cdd-editor/`.
   + iec61360 (574) + iec62683 (1855) + iec61987 (11831) =
   **14,529 entities** across 7 dictionaries. Run `cd browser && npm run dev`
   to serve at `http://localhost:5173`.
+- **2026-07-17 data pipeline additions** (see `TODO.final/`):
+  - `rake browser:build_parcel[<dict>]` — emit a Parcel .xlsx via
+    `Opencdd::Parcel::Writer`. Output at `data/<dict>/parcel/<parcel_id>.xlsx`.
+  - `rake browser:build_versions[<dict>]` — emit per-version JSON
+    via `Opencdd::Parcel::VersionedReader` + `Opencdd::Exporters::Json#payload_for`.
+    Output at `data/<dict>/versions/<code>/<unid>.json`.
+  - `rake browser:build_all_parcel` — batch Parcel emit across all dicts.
+- **2026-07-17 public API additions**:
+  - `Opencdd::Cddal::Serializer#emit_entity(entity)` — single-entity CDDAL.
+  - `Opencdd::Exporters::Json#payload_for(entity, database: nil)` — registry-dispatched per-entity payload (no case/when).
+  - `Opencdd::Parcel::VersionedReader#versions_for(code)`, `#load_version(code, unid)`.
+  - `Opencdd::EntityDiff.between(a, b)` + `#added` / `#removed` / `#changed`.
 - **Phase 2 (lutaml-model migration) NOT started**: tracked in
   `TODO.full-cdd/16-lutaml-model-migration.md`. This is the major
   remaining architectural work — migrate entities to `Lutaml::Model`

data/lib/opencdd/cddal/serializer.rb

@@ -40,6 +40,18 @@ module Opencdd
         lines.join("\n") + "\n"
       end
 
+      # Emit a single entity as a standalone CDDAL document.
+      # Returns the canonical text (with header) for one entity,
+      # suitable for download from the browser or extraction from
+      # a database by IRDI.
+      #
+      # Round-trips: <tt>Opencdd::Cddal.parse(emit_entity(e))</tt>
+      # yields a Database whose single entity is equivalent to +e+.
+      def emit_entity(entity)
+        body = emit_instance(entity).join("\n")
+        "#{HEADER.chomp}\n#{body}\n"
+      end
+
       private
 
       def emit_default_aliases(lines)

data/lib/opencdd/entity.rb

@@ -69,6 +69,17 @@ module Opencdd
     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]
+      # Fall back to other known code property IDs when the entity-
+      # specific one is absent (happens with name-only header sheets
+      # where "Code" synthesizes to MDC_P001_5 regardless of type).
+      if raw_code.nil? || raw_code.to_s.strip.empty?
+        Opencdd::MetaClasses::CODE_PROPERTY_IDS.each_value do |alt_id|
+          val = row[alt_id]
+          next if val.nil? || val.to_s.strip.empty?
+          raw_code = val
+          break
+        end
+      end
       irdi = raw_code && Opencdd::IRDI.parse(raw_code)
 
       props = row.each_with_object({}) do |(k, v), h|

data/lib/opencdd/entity_diff.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Opencdd
+  # Compute a structured diff between two entities of the same IRDI.
+  #
+  # Pure value object: doesn't mutate its inputs, doesn't reach
+  # beyond +entity.properties+. Iterates the union of keys and
+  # categorizes each into +added+, +removed+, or +changed+.
+  #
+  # Multilingual fields (<tt>MDC_P001.en</tt>, <tt>MDC_P001.fr</tt>)
+  # are diffed as a group keyed by their base property ID. A change
+  # in any language counts as one change to the base field.
+  #
+  # Example:
+  #   diff = Opencdd::EntityDiff.between(v001, v002)
+  #   diff.added      # => ["MDC_P999"]
+  #   diff.removed    # => []
+  #   diff.changed    # => [{ field: "preferred_name", from: "X", to: "Y" }]
+  #   diff.empty?     # => false
+  class EntityDiff
+    Change = Struct.new(:field, :from, :to, keyword_init: true)
+
+    attr_reader :from_entity, :to_entity, :added, :removed, :changed
+
+    def self.between(from_entity, to_entity)
+      new(from_entity, to_entity)
+    end
+
+    def initialize(from_entity, to_entity)
+      raise ArgumentError, "EntityDiff requires same IRDI (#{from_entity.irdi} vs #{to_entity.irdi})" unless from_entity.irdi == to_entity.irdi
+      @from_entity = from_entity
+      @to_entity   = to_entity
+      compute_diff
+    end
+
+    def empty?
+      added.empty? && removed.empty? && changed.empty?
+    end
+
+    # Total change count (added + removed + changed).
+    def size
+      added.size + removed.size + changed.size
+    end
+
+    # Wire-format summary suitable for JSON emit or browser diff view.
+    def to_h
+      {
+        irdi: from_entity.irdi.to_s,
+        added: added,
+        removed: removed,
+        changed: changed.map(&:to_h),
+      }
+    end
+
+    private
+
+    def compute_diff
+      @added = []
+      @removed = []
+      @changed = []
+      from_groups = grouped_properties(from_entity)
+      to_groups   = grouped_properties(to_entity)
+      (from_groups.keys | to_groups.keys).sort.each do |field|
+        from_val = from_groups[field]
+        to_val   = to_groups[field]
+        if from_val.nil? && !to_val.nil?
+          @added << field
+        elsif !from_val.nil? && to_val.nil?
+          @removed << field
+        elsif values_differ?(from_val, to_val)
+          @changed << Change.new(field: field, from: from_val, to: to_val)
+        end
+      end
+    end
+
+    # Group multilingual keys (<base>.<lang>) under their <base>.
+    # Returns +{ base_property_id => grouped_value }+ where
+    # +grouped_value+ is a string for monolingual fields or a
+    # sorted +{ lang => value }+ hash for multilingual fields.
+    def grouped_properties(entity)
+      groups = Hash.new { |h, k| h[k] = {} }
+      entity.properties.each do |key, value|
+        next if value.nil?
+        k = key.to_s
+        base, lang = split_language_suffix(k)
+        if lang
+          groups[base][lang] = value.to_s
+        else
+          groups[base] = value.to_s
+        end
+      end
+      # Collapse empty hashes (a group that had only nil values).
+      groups.transform_values { |v| v.is_a?(Hash) && v.empty? ? nil : v }
+    end
+
+    def split_language_suffix(key)
+      m = key.match(/\A(?<base>.+?)\.(?<lang>[a-z]{2,3}(?:-[a-z0-9]+)?)\z/i)
+      return [key, nil] unless m
+      [m[:base], m[:lang].downcase]
+    end
+
+    def values_differ?(from_val, to_val)
+      return from_val != to_val unless from_val.is_a?(Hash) && to_val.is_a?(Hash)
+      # For multilingual groups: compare as normalized hashes.
+      from_val == to_val ? false : true
+    end
+  end
+end

data/lib/opencdd/exporters/json.rb

@@ -53,7 +53,34 @@ module Opencdd
         @nodes << view_control_node(vc)
       end
 
-      private
+      # ─────────────────────────────────────────────────────────────
+      # Public per-entity payload API
+      #
+      # `payload_for(entity, database:)` returns the wire-format Hash
+      # for a single entity. Dispatch is via the PAYLOAD_BUILDERS
+      # registry — adding a new entity type means adding one entry to
+      # the registry and one builder method, not editing a switch.
+      #
+      # The optional `database:` enables cross-entity resolution
+      # (e.g. property → value_list). Without it, cross-links are
+      # omitted (payload still has all the entity's own fields).
+      # ─────────────────────────────────────────────────────────────
+      PAYLOAD_BUILDERS = {
+        Opencdd::Klass        => :class_node,
+        Opencdd::Property     => :property_node,
+        Opencdd::Unit         => :unit_node,
+        Opencdd::ValueList    => :value_list_node,
+        Opencdd::ValueTerm    => :value_term_node,
+        Opencdd::Relation     => :relation_node,
+        Opencdd::ViewControl  => :view_control_node,
+      }.freeze
+
+      def payload_for(entity, database: nil)
+        @database = database if database
+        builder = PAYLOAD_BUILDERS[entity.class]
+        raise ArgumentError, "No JSON payload builder for #{entity.class}" unless builder
+        public_send(builder, entity)
+      end
 
       # ─────────────────────────────────────────────────────────────
       # Open/closed payload builders
@@ -98,6 +125,8 @@ module Opencdd
         entity_payload(vc).merge(type: "view_control").compact
       end
 
+      private
+
       # Iterates every declared field on the entity's class (walking
       # the ancestor chain via FieldRegistry.fields_for). Each field's
       # value is read by name (synthetic fields call their custom

data/lib/opencdd/meta_class.rb

@@ -79,6 +79,7 @@ module Opencdd
         "MDC_C011" => "MDC_P001_13",
         "MDC_C009" => "MDC_P001_10",
         "MDC_C010" => "MDC_P001_11",
+        "MDC_C0100" => "C0101",
         "EXT_C001" => "EXT_P001",
       }.freeze
 
@@ -89,6 +90,7 @@ module Opencdd
         "MDC_C011" => :relation,
         "MDC_C009" => :unit,
         "MDC_C010" => :value_term,
+        "MDC_C0100" => :list_of_unit,
         "EXT_C001" => :view_control,
       }.freeze
 
@@ -252,6 +254,13 @@ module Opencdd
             type: :view_control,
             allowed_property_ids: common + %w[EXT_P002 EXT_P003],
           )
+          list_of_unit = MetaClass.new(
+            irdi: "MDC_C0100",
+            name: "ListOfUnit",
+            entity_class: Opencdd::Entity,
+            type: :list_of_unit,
+            allowed_property_ids: common,
+          )
           {
             klass_class.irdi    => klass_class,
             property_class.irdi => property_class,
@@ -260,6 +269,7 @@ module Opencdd
             unit.irdi           => unit,
             value_term.irdi     => value_term,
             view_control.irdi   => view_control,
+            list_of_unit.irdi   => list_of_unit,
           }
         end
       end

data/lib/opencdd/parcel/flat_dir_reader.rb

@@ -23,6 +23,7 @@ module Opencdd
         "UNIT"       => :unit,
         "VALUELIST"  => :value_list,
         "VALUETERMS" => :value_term,
+        "LISTOFUNITS" => :list_of_unit,
       }.freeze
 
       attr_reader :path

data/lib/opencdd/parcel/layout_detector.rb

@@ -32,7 +32,7 @@ module Opencdd
 
       # Per-type export filename produced by cdd.iec.ch's download
       # endpoint.
-      FILE_PATTERN = /\Aexport_(CLASS|PROPERTY|RELATION|UNIT|VALUELIST|VALUETERMS)_[^\.]+\.(xls|xlsx)\z/i.freeze
+      FILE_PATTERN = /\Aexport_(CLASS|PROPERTY|RELATION|UNIT|VALUELIST|VALUETERMS|LISTOFUNITS)_[^\.]+\.(xls|xlsx)\z/i.freeze
 
       module_function
 

data/lib/opencdd/parcel/sheet_schema.rb

@@ -159,6 +159,9 @@ module Opencdd
 
       def finalize!
         ids = @column_directives["PROPERTY_ID"] || []
+        if ids.empty? || ids.all? { |id| id.nil? || id.to_s.strip.empty? }
+          ids = synthesize_ids_from_names
+        end
         ids.each_with_index do |id, idx|
           next if id.nil? || id.to_s.strip.empty?
 
@@ -194,6 +197,81 @@ module Opencdd
         freeze
       end
 
+      # When a sheet has no #PROPERTY_ID directive row (only
+      # #PROPERTY_NAME), synthesize property IDs from the names.
+      # This happens with some export formats (notably RELATION
+      # exports from cdd.iec.ch) that omit the PROPERTY_ID row.
+      NAME_TO_PROPERTY_ID = {
+        "Code"                   => "MDC_P001_5",
+        "Version"                => "MDC_P002_1",
+        "Revision"               => "MDC_P002_2",
+        "VersionInitiationDate"  => "MDC_P003_1",
+        "VersionReleaseDate"     => "MDC_P003_2",
+        "RevisionReleaseDate"    => "MDC_P003_3",
+        "PreferredName"          => "MDC_P004",
+        "SynonymousName"         => "MDC_P007",
+        "ShortName"              => "MDC_P005",
+        "Definition"             => "MDC_P006",
+        "DefinitionSource"       => "MDC_P006_1",
+        "Note"                   => "MDC_P008",
+        "Remark"                 => "MDC_P009",
+        "Drawing"                => "MDC_P008_1",
+        "GUID"                   => "MDC_P066",
+        "TimeStamp"              => "MDC_P067",
+        "ClassType"              => "MDC_P011",
+        "Superclass"             => "MDC_P010",
+        "IsCaseOf"               => "MDC_P013",
+        "ApplicableProperties"   => "MDC_P014",
+        "ImportedProperties"     => "MDC_P090",
+        "SubClassSelection"      => "MDC_P016",
+        "DataType"               => "MDC_P022",
+        "ValueFormat"            => "MDC_P024",
+        "DefinitionClass"        => "MDC_P021",
+        "Unit"                   => "MDC_P041",
+        "Condition"              => "MDC_P028",
+        "ListType"               => "MDC_P046",
+        "CodeList"               => "MDC_P044",
+        "TermList"               => "MDC_P043",
+        "EnumerationCode"        => "MDC_P044",
+        "RelationType"           => "MDC_P200",
+        "RelationDomain"         => "MDC_P201",
+        "FunctionDomain"         => "MDC_P202",
+        "FunctionCodomain"       => "MDC_P203",
+        "Formula"                => "MDC_P204",
+        "FormulaLanguage"        => "MDC_P205",
+        "FormulaExternalSolver"  => "MDC_P206",
+        "TriggerEvent"           => "MDC_P207",
+        "DomainElementType"      => "MDC_P208",
+        "CodomainElementType"    => "MDC_P209",
+        "Role"                   => "MDC_P210",
+        "Segment"                => "MDC_P211",
+        "SuperRelation"          => "MDC_P212",
+      }.freeze
+
+      def synthesize_ids_from_names
+        names = nil
+        @column_directives.each do |key, vals|
+          base, = key.split(".", 2)
+          next unless base == "PROPERTY_NAME"
+          names = vals
+          break
+        end
+        return [] unless names
+        Array.new(names.size) do |idx|
+          val = names[idx]
+          next nil if val.nil? || val.to_s.strip.empty?
+          raw = val.to_s.strip
+          if raw =~ /\A(.+)\.([A-Za-z]{2})\z/
+            base = $1
+            lang = $2
+            pid = NAME_TO_PROPERTY_ID[base]
+            pid ? "#{pid}.#{lang.downcase}" : nil
+          else
+            NAME_TO_PROPERTY_ID[raw]
+          end
+        end
+      end
+
       def [](property_id_or_name)
         find_by_property_id(property_id_or_name) || find_by_name(property_id_or_name)
       end

data/lib/opencdd/parcel/versioned_reader.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Opencdd
+  module Parcel
+    # Reads historical versions of entities from a sharded
+    # per-version Parcel layout.
+    #
+    # The sharded layout stores every version of an entity in a
+    # per-UNID subfolder: +<entity_dir>/<UNID>/export_*.xls+. The
+    # +_entity.json+ sidecar lists every version and which UNID is
+    # current. ShardedDirReader reads only the current version;
+    # VersionedReader exposes the full history.
+    #
+    # Delegates to:
+    #   - +Opencdd::Parcel::EntityManifest+ for version metadata.
+    #   - +Opencdd::Parcel::FlatDirReader+ for xls parsing of one
+    #     version's subfolder.
+    #
+    # Example:
+    #   reader = Opencdd::Parcel::VersionedReader.new("downloads/iec63213")
+    #   reader.versions_for("KEA012")    # => 3 VersionHistory::Entry
+    #   reader.load_version("KEA012", "ABC123...") # => Database with v002 content
+    class VersionedReader
+      attr_reader :path
+
+      def initialize(path)
+        @path = path
+      end
+
+      # All versions recorded for +code+, as
+      # +Opencdd::Entity::VersionHistory::Entry+ instances.
+      # Empty +VersionHistory+ if +code+ has no manifest.
+      def versions_for(code)
+        manifest = manifest_for(code)
+        return Opencdd::Entity::VersionHistory.new unless manifest
+        manifest.version_history
+      end
+
+      # Load a single historical version's content as a standalone
+      # Database. The +unid+ identifies which version's subfolder
+      # to read.
+      #
+      # Returns +nil+ if the version subfolder doesn't exist or has
+      # no +.xls+ files. The returned database is finalized but not
+      # cross-linked to other entities (historical context only).
+      def load_version(code, unid)
+        version_dir = version_dir_for(code, unid)
+        return nil unless version_dir && File.directory?(version_dir)
+        return nil unless Dir.children(version_dir).any? { |f| Opencdd::Parcel::LayoutDetector.legacy_export?(f) }
+
+        workbook = Opencdd::Parcel::FlatDirReader.new(version_dir).read_workbook
+        database = Opencdd::Database.new
+        database.add_workbook(workbook)
+        attach_version_history(database, code)
+        database.finalize!
+        database
+      end
+
+      # The entity subdirectory for +code+. Tries both the legacy
+      # +<path>/<code>+ layout and the manifest-driven
+      # +<path>/_entities/<code>+ layout.
+      def entity_dir_for(code)
+        flat = File.join(@path, code)
+        return flat if File.directory?(flat)
+        sharded = File.join(@path, "_entities", code)
+        return sharded if File.directory?(sharded)
+        nil
+      end
+
+      private
+
+      def manifest_for(code)
+        dir = entity_dir_for(code)
+        return nil unless dir
+        Opencdd::Parcel::EntityManifest.read(dir)
+      end
+
+      def version_dir_for(code, unid)
+        dir = entity_dir_for(code)
+        return nil unless dir
+        candidate = File.join(dir, unid)
+        return candidate if File.directory?(candidate)
+        nil
+      end
+
+      def attach_version_history(database, code)
+        manifest = manifest_for(code)
+        return unless manifest
+        return if manifest.versions_empty?
+        manifest.version_history.entries.each do |entry|
+          next unless entry.unid
+          target = database.find_by_code(code)
+          target&.attach_version_history(manifest.version_history)
+          break
+        end
+      end
+    end
+  end
+end

data/lib/opencdd/parcel.rb

@@ -12,6 +12,7 @@ module Opencdd
     autoload :WorkbookReader,  "opencdd/parcel/workbook_reader"
     autoload :FlatDirReader,   "opencdd/parcel/flat_dir_reader"
     autoload :ShardedDirReader, "opencdd/parcel/sharded_dir_reader"
+    autoload :VersionedReader,  "opencdd/parcel/versioned_reader"
     autoload :LayoutDetector,  "opencdd/parcel/layout_detector"
     autoload :EntityManifest,  "opencdd/parcel/entity_manifest"
     autoload :ReferencedIrdis,  "opencdd/parcel/referenced_irdis"

data/lib/opencdd/validator/runner.rb

@@ -77,7 +77,7 @@ module Opencdd
         base = column_iri.to_s.split(".").first
         entry = Opencdd::PropertyIds::REGISTRY[base]
         kind = entry&.value_kind
-        column_schema = schema&.column_for(base)
+        column_schema = schema&.find_by_property_id(base)
         RuleContext.new(
           database: database,
           entity: entity,

data/lib/opencdd/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Opencdd
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

data/lib/opencdd.rb

@@ -36,6 +36,7 @@ module Opencdd
   autoload :Reader,              "opencdd/reader"
   autoload :ClassTree,           "opencdd/class_tree"
   autoload :Visitor,             "opencdd/visitor"
+  autoload :EntityDiff,          "opencdd/entity_diff"
 
   autoload :Parcel, "opencdd/parcel"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opencdd
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - OpenCDD contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-16 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: roo
@@ -241,6 +241,7 @@ files:
 - lib/opencdd/entity/field_registry.rb
 - lib/opencdd/entity/version_history.rb
 - lib/opencdd/entity/yaml.rb
+- lib/opencdd/entity_diff.rb
 - lib/opencdd/exporters.rb
 - lib/opencdd/exporters/json.rb
 - lib/opencdd/exporters/mermaid.rb
@@ -268,6 +269,7 @@ files:
 - lib/opencdd/parcel/sheet.rb
 - lib/opencdd/parcel/sheet_emitter.rb
 - lib/opencdd/parcel/sheet_schema.rb
+- lib/opencdd/parcel/versioned_reader.rb
 - lib/opencdd/parcel/workbook.rb
 - lib/opencdd/parcel/workbook_reader.rb
 - lib/opencdd/parcel/writer.rb