opencdd 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74a134259cf9d336b0e401139d10fcda58d1df883ec52312e04eadd2c6016bb9
-  data.tar.gz: b2c6cd320d420f7258c4116c218e0de50850d9ebb1745f81e4b06c33113196ef
+  metadata.gz: 2fef2d0d21f84980a8ecd470525ad52e687f511de1ca0c0567b08d55ca63d138
+  data.tar.gz: b5497fc0a22a1ccedabc62ed3424a99164e2c6b964cd049f5b139a2060316fbc
 SHA512:
-  metadata.gz: 5147138e2581efbaf28bf224de9c56ed541040cdedec3569436c786419df35fc190a144982d78d53ca7d1ce4d4b7f73b7cd21847d5c3597e1987b0ade886db85
-  data.tar.gz: 9bd7ee2d030cfb9792177763875b02114aca94534754986fe17ba6c7b24dcf5cd47ad9361fd9f9533c8d3fcbdc4bcc296d4610b335809358d5a6d3ae9844f0f0
+  metadata.gz: f4d40389beaf651c46c1acebf77d557ea6ee0b722e6048914bf5e9107937e82aadb65ed7cdce2ae421984cfabf722303145f9dd69c9715fdcabec6d94811da43
+  data.tar.gz: '083684e0064e581c101c3a906dca0e25e33d06c96c75d1170eef5b46c7a77a5380fb7ebd1d9782b7fac5602086ca0e44d74d7824cc39726c9a12f3f353686f00'

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_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/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.1"
 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.1
 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