opencdd 0.1.1

data/lib/opencdd/reader.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Opencdd
+  class Reader
+    XLSX_EXTENSIONS = %w[.xlsx .xlsm .xltx].freeze
+
+    # Layout detection is owned by Opencdd::Parcel::LayoutDetector
+    # (single source of truth). These regexes are exposed here as
+    # backward-compat constants for external callers; new code
+    # should call LayoutDetector directly.
+    SHARDED_CLASS_CODE = Opencdd::Parcel::LayoutDetector::CLASS_CODE_PATTERN
+    UNID_PATTERN       = Opencdd::Parcel::LayoutDetector::UNID_PATTERN
+    LEGACY_XLS_RE      = Opencdd::Parcel::LayoutDetector::FILE_PATTERN
+
+    class << self
+      def load_database(path)
+        new(path).load
+      end
+
+      def detect(path)
+        case File.basename(path)
+        when LEGACY_XLS_RE then :legacy_single
+        else
+          if File.directory?(path)
+            children = Dir.children(path)
+            if children.any? { |f| f =~ LEGACY_XLS_RE }
+              :legacy_dir
+            elsif children.any? { |f| sharded_class_subdir?(File.join(path, f)) }
+              :sharded_dir
+            else
+              :unknown_dir
+            end
+          elsif XLSX_EXTENSIONS.include?(File.extname(path).downcase)
+            :xlsx
+          elsif File.extname(path).downcase == ".xls"
+            :legacy_single
+          else
+            :unknown
+          end
+        end
+      end
+    end
+
+    # A class-code subdir is "sharded" if it contains export_*.xls
+    # directly (legacy flat layout) OR exposes the per-version layout
+    # (+_entity.json+ pointing at a UNID subfolder, or a single UNID
+    # subfolder holding export_*.xls).
+    def self.sharded_class_subdir?(path)
+      return false unless File.directory?(path)
+      return false unless File.basename(path) =~ SHARDED_CLASS_CODE
+
+      children = Dir.children(path)
+      return true if children.any? { |f| f =~ LEGACY_XLS_RE }
+
+      # Per-version layout: _entity.json names a UNID subfolder.
+      entity_idx = File.join(path, "_entity.json")
+      if File.file?(entity_idx)
+        require "json"
+        begin
+          data = JSON.parse(File.read(entity_idx))
+          current = data["current_version_dir"]
+          return true if current && current =~ UNID_PATTERN &&
+                         File.directory?(File.join(path, current))
+        rescue JSON::ParserError
+          # fall through
+        end
+      end
+
+      # Per-version layout without _entity.json: a UNID subfolder holds XLS.
+      unid_subdirs = children.select { |n| n =~ UNID_PATTERN }
+                              .map { |n| File.join(path, n) }
+      unid_subdirs.any? do |p|
+        File.directory?(p) && Dir.children(p).any? { |f| f =~ LEGACY_XLS_RE }
+      end
+    end
+
+    attr_reader :path
+
+    def initialize(path)
+      @path = path
+    end
+
+    def load
+      db = Opencdd::Database.new
+      load_into(db)
+      db.finalize!
+      db
+    end
+
+    def load_into(db)
+      case Opencdd::Reader.detect(@path)
+      when :xlsx, :legacy_single
+        Opencdd::Parcel::WorkbookReader.new(@path).load_into(db)
+      when :legacy_dir
+        Opencdd::Parcel::FlatDirReader.new(@path).load_into(db)
+      when :sharded_dir
+        Opencdd::Parcel::ShardedDirReader.new(@path).load_into(db)
+      else
+        raise ArgumentError, "Cannot detect Parcel/Excel format at #{@path.inspect}"
+      end
+    end
+  end
+end

data/lib/opencdd/relation.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Opencdd
+  class Relation < Opencdd::Entity
+    RELATION_TYPES = {
+      "FUNCTION"    => :function,
+      "PREDICATION" => :predication,
+    }.freeze
+
+    # ── Pure field reads ─────────────────────────────────────────
+    field :domain_of_function_irdis, "MDC_P202"
+    field :codomain_irdi,            "MDC_P203"
+    field :formula,                  "MDC_P204", :string
+    field :formula_language,         "MDC_P205", :string
+    field :external_solver,          "MDC_P206", :string
+    field :trigger_event,            "MDC_P207", :string
+    field :domain_element_type,      "MDC_P208", :string
+    field :codomain_element_type,    "MDC_P209", :string
+    field :role,                     "MDC_P210", :string
+    field :segment,                  "MDC_P211", :string
+    field :super_relation_irdi,      "MDC_P212"
+
+    # ── Computed fields with block-form readers ──────────────────
+    field(:relation_type, synthetic: true) do
+      @relation_type_value ||= Opencdd::RelationType.parse(properties[Opencdd::PropertyIds::MDC_P200]) ||
+        parse_legacy_relation_type
+    end
+    field(:domain_irdis, synthetic: true) do
+      list = []
+      [Opencdd::PropertyIds::MDC_P201, Opencdd::PropertyIds::MDC_P202].each do |key|
+        list.concat(parse_irdi_list(properties[key]))
+      end
+      list
+    end
+
+    def relation_type_symbol
+      value = relation_type
+      value ? value.to_sym : nil
+    end
+
+    def predication?
+      rt = relation_type
+      rt ? rt.predication? : false
+    end
+
+    def function?
+      rt = relation_type
+      rt ? rt.function? : false
+    end
+
+    def association?
+      rt = relation_type
+      rt ? rt.association? : false
+    end
+
+    def aggregation?
+      rt = relation_type
+      rt ? rt.aggregation? : false
+    end
+
+    def composition?
+      rt = relation_type
+      rt ? rt.composition? : false
+    end
+
+    def generalization?
+      rt = relation_type
+      rt ? rt.generalization? : false
+    end
+
+    def specialization?
+      rt = relation_type
+      rt ? rt.specialization? : false
+    end
+
+    private
+
+    def parse_legacy_relation_type
+      raw = properties[Opencdd::PropertyIds::MDC_P200]
+      sym = RELATION_TYPES[raw]
+      return nil unless sym
+      case sym
+      when :function    then Opencdd::RelationType.new("FUNCTION")
+      when :predication then Opencdd::RelationType.new("PREDICATION")
+      end
+    end
+  end
+end

data/lib/opencdd/relation_tree.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Opencdd
+  class RelationTree
+    class Node < Struct.new(:relation, :children, keyword_init: true)
+      include Enumerable
+
+      def each(&block)
+        block.call(self)
+        (children || []).each { |c| c.each(&block) }
+      end
+
+      def depth
+        return 1 if children.nil? || children.empty?
+        1 + children.map(&:depth).max
+      end
+
+      def size
+        1 + (children || []).sum(&:size)
+      end
+    end
+
+    attr_reader :database
+
+    def initialize(database)
+      @database = database
+    end
+
+    def for(root = nil, max_depth: 10)
+      roots = root.nil? ? root_relations : [lookup_relation(root)].compact
+      roots.map { |r| build_node(r, Set.new, max_depth) }
+    end
+
+    private
+
+    def build_node(relation, path, max_depth)
+      return nil if relation.nil?
+      return nil if path.include?(relation.irdi)
+      return nil if max_depth <= 0
+
+      child_path = path + [relation.irdi]
+      children = children_of(relation).map { |c| build_node(c, child_path, max_depth - 1) }.compact
+      Node.new(relation: relation, children: children)
+    end
+
+    def children_of(relation)
+      index.fetch(relation.irdi, [])
+    end
+
+    def root_relations
+      database.relations.reject { |r| r.super_relation_irdi }
+    end
+
+    def lookup_relation(ref)
+      database.resolve_reference(ref)
+    end
+
+    def index
+      @index ||= build_index
+    end
+
+    def build_index
+      hash = Hash.new { |h, k| h[k] = [] }
+      database.relations.each do |r|
+        parent_raw = r.properties[Opencdd::PropertyIds::MDC_P212]
+        next unless parent_raw && !parent_raw.to_s.strip.empty?
+        parent = database.resolve_reference(parent_raw)
+        next unless parent
+        hash[parent.irdi] << r unless hash[parent.irdi].include?(r)
+      end
+      hash
+    end
+  end
+end

data/lib/opencdd/relation_type.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Opencdd
+  class RelationType
+    VALUES = %w[
+      PREDICATION FUNCTION ASSOCIATION AGGREGATION COMPOSITION
+      GENERALIZATION SPECIALIZATION
+    ].freeze
+
+    attr_reader :value
+
+    def initialize(value)
+      v = value.to_s.strip.upcase
+      raise ArgumentError, "unknown relation type: #{value.inspect}" unless VALUES.include?(v)
+      @value = v
+    end
+
+    def predication?    = @value == "PREDICATION"
+    def function?       = @value == "FUNCTION"
+    def association?    = @value == "ASSOCIATION"
+    def aggregation?    = @value == "AGGREGATION"
+    def composition?    = @value == "COMPOSITION"
+    def generalization? = @value == "GENERALIZATION"
+    def specialization? = @value == "SPECIALIZATION"
+
+    def hierarchical?
+      generalization? || specialization? || aggregation? || composition?
+    end
+
+    def to_s   = @value
+    def to_sym = @value.downcase.to_sym
+
+    def ==(other)
+      other.is_a?(Opencdd::RelationType) && @value == other.value
+    end
+    alias_method :eql?, :==
+
+    def hash
+      @value.hash
+    end
+
+    alias_method :inspect, :to_s
+
+    def self.parse(raw)
+      return nil if raw.nil? || raw.to_s.strip.empty?
+      s = raw.to_s.strip.upcase
+      return nil unless VALUES.include?(s)
+      new(s)
+    end
+
+    def self.parse_or_symbol(raw)
+      parsed = parse(raw)
+      return parsed if parsed
+      return nil if raw.nil? || raw.to_s.strip.empty?
+      raw.to_s.strip.upcase.to_sym
+    end
+  end
+end

data/lib/opencdd/structured_values.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Opencdd
+  # Single source of truth for parsing/serialising CDD's structured
+  # property-value wire forms: reference sets, synonym tuples,
+  # class references, data types.
+  #
+  # Every format reader, writer, validator, and exporter that touches
+  # a `{a,b,c}` or `(a,b)` collection goes through this module.
+  # The brace/paren/comma convention lives here exactly once; a bug
+  # fixed here is fixed everywhere.
+  module StructuredValues
+    module_function
+
+    # ── Generic collection seam ─────────────────────────────────
+    #
+    # Used by Database#normalize_reference_collections!,
+    # Database#rewrite_back_references!, Cddal::Builder,
+    # Cddal::Serializer, Validator::ReferenceRule,
+    # Validator::ClassReferenceRule. Replaces six hand-rolled
+    # variants of "strip delimiters, split, reject empties".
+
+    # Split a `{a,b,c}` or `(a,b,c)` literal into `[a, b, c]`.
+    # Accepts unwrapped strings too (split directly). Empty/blank
+    # input returns []. Respects nested `{}`/`()` so
+    # `{(a,b),(c,d)}` yields two tuple strings, not four fragments.
+    def unwrap_and_split(value)
+      return [] if value.nil? || value.to_s.strip.empty?
+      s = value.to_s.strip
+      s = s[1..-2] if (s.start_with?("{") && s.end_with?("}")) ||
+                       (s.start_with?("(") && s.end_with?(")"))
+      split_at_top_level_commas(s)
+    end
+
+    # Inverse of +unwrap_and_split+: join with `,` and wrap in `{}`.
+    # Empty input returns "".
+    def rejoin(elements)
+      elements = Array(elements).map(&:to_s).reject { |e| e.nil? || e.strip.empty? }
+      return "" if elements.empty?
+      "{#{elements.join(",")}}"
+    end
+
+    def parse_synonyms(value)
+      return [] if value.nil? || value.to_s.strip.empty?
+      SynonymTupleScanner.new(value.to_s).scan
+    end
+
+    def serialize_synonyms(pairs)
+      return "" if pairs.nil? || pairs.empty?
+      tuples = Array(pairs).map do |pair|
+        lang, name = Array(pair)
+        "(#{name},#{lang})"
+      end
+      "{#{tuples.join(",")}}"
+    end
+
+    def parse_ref_set(value)
+      return [] if value.nil? || value.to_s.strip.empty?
+      unwrap_and_split(value).filter_map { |t| Opencdd::IRDI.parse(t) }
+    end
+
+    def serialize_ref_set(irdis)
+      return "" if irdis.nil? || irdis.empty?
+      elements = Array(irdis).map { |i| i.is_a?(Opencdd::IRDI) ? i.to_s : i.to_s }
+      "{#{elements.join(",")}}"
+    end
+
+    def parse_class_ref(value)
+      return nil if value.nil? || value.to_s.strip.empty?
+      Opencdd::IRDI.parse(value.to_s.strip)
+    end
+
+    def serialize_class_ref(irdi)
+      return "" if irdi.nil?
+      irdi.is_a?(Opencdd::IRDI) ? irdi.to_s : irdi.to_s
+    end
+
+    def parse_data_type(value)
+      return nil if value.nil? || value.to_s.strip.empty?
+      Opencdd::DataType.parse_or_string(value)
+    end
+
+    # ── Internal: split on commas at the top nesting level only ─
+    # Needed so `{(a,b),(c,d)}` → `["(a,b)", "(c,d)"]`, not four
+    # fragments.
+    def split_at_top_level_commas(s)
+      result = []
+      current = +""
+      depth = 0
+      s.each_char do |ch|
+        case ch
+        when "{", "(" then depth += 1; current << ch
+        when "}", ")" then depth -= 1; current << ch
+        when ","
+          if depth.zero?
+            result << current.strip unless current.strip.empty?
+            current = +""
+          else
+            current << ch
+          end
+        else
+          current << ch
+        end
+      end
+      result << current.strip unless current.strip.empty?
+      result
+    end
+    private_class_method :split_at_top_level_commas
+
+    def serialize_data_type(data_type)
+      return "" if data_type.nil?
+      data_type.to_s
+    end
+
+    def parse_condition(value)
+      return nil if value.nil? || value.to_s.strip.empty?
+      Opencdd::Condition.parse(value)
+    rescue ArgumentError
+      nil
+    end
+
+    def serialize_condition(condition)
+      return "" if condition.nil?
+      condition.to_s
+    end
+
+    def parse_value_format(value)
+      return nil if value.nil? || value.to_s.strip.empty?
+      Opencdd::ValueFormat.parse(value)
+    end
+
+    def serialize_value_format(format)
+      return "" if format.nil?
+      format.to_s
+    end
+  end
+end
+
+# Internal scanner for the `{(name,lang),(name,lang)}` synonym wire
+# form. Lives here so StructuredValues is the single home for all
+# collection parsing. Parsed via StringScanner because the format
+# can include quoted commas inside names.
+class Opencdd::StructuredValues::SynonymTupleScanner
+  def initialize(source)
+    require "strscan"
+    @ss = StringScanner.new(source)
+  end
+
+  def scan
+    @ss.skip(/\s*\{?\s*/)
+    collect_tuples
+  end
+
+  private
+
+  def collect_tuples
+    result = []
+    while @ss.check(/\(/)
+      result << scan_tuple
+      @ss.skip(/\s*,\s*/)
+    end
+    result
+  end
+
+  def scan_tuple
+    @ss.skip(/\(\s*/)
+    name = scan_element_until(",")
+    @ss.skip(/,\s*/)
+    lang = scan_element_until(")")
+    @ss.skip(/\)/)
+    [lang&.strip, name&.strip]
+  end
+
+  def scan_element_until(delimiter)
+    start = @ss.pos
+    until @ss.eos?
+      ch = @ss.peek(1)
+      return @ss.string[start...@ss.pos] if ch == delimiter || ch == ")"
+      @ss.getch
+    end
+    @ss.string[start...@ss.pos]
+  end
+end

data/lib/opencdd/unit.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Opencdd
+  class Unit < Opencdd::Entity
+    # ── Pure field reads ─────────────────────────────────────────
+    # MDC_P023/023_1/023_2 are :identifier_ref in REGISTRY but used
+    # as raw strings for unit symbols/representations. Explicit :string
+    # override preserves historical behavior.
+    field :structure,            "MDC_P023",   :string
+    field :text_representation,  "MDC_P023_1", :string
+    field :sgml_representation,  "MDC_P023_2", :string
+    field :definition_class_irdi, "MDC_P021"
+
+    alias_method :symbol, :text_representation
+  end
+end

data/lib/opencdd/validator/class_reference_rule.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Opencdd
+  module Validator
+    # R16 — CLASS_REFERENCE target validation.
+    #
+    # When a property's data_type is +CLASS_REFERENCE(CategoricalClass)+
+    # (or the column carries a CLASS_REFERENCE schema), the value IRDI
+    # must resolve to an entity that is a valid powertype instance of
+    # the named categorical class — i.e. one of its
+    # +categorical_instances+.
+    #
+    # This rule closes the loop on CDD's powertype semantics: a
+    # CLASS_REFERENCE data type doesn't just say "this is an IRDI";
+    # it says "this is an IRDI of an instance of this categorical
+    # class." Plain reference resolution (R08) doesn't catch the
+    # categorical constraint.
+    #
+    # Example: a Property `engine_type: CLASS_REFERENCE(EngineType)`
+    # whose value is "AAA001" (Vehicle) should fail — Vehicle is
+    # not a categorical instance of EngineType. Only SingleDiesel /
+    # TwinDiesel / ElectricHybrid (EngineType's subclasses) pass.
+    class ClassReferenceRule < Rule
+      def id
+        "R16"
+      end
+
+      def applies?(context)
+        return false unless context.database
+        parsed = parse_data_type(context)
+        parsed.is_a?(Opencdd::DataType::ClassReference)
+      end
+
+      def call(value, context)
+        return true if value.nil? || value.to_s.strip.empty?
+        target = categorical_target(context)
+        return true unless target # cannot validate without target resolution
+
+        refs(value).all? { |ref| context.database.valid_class_reference?(target, ref) }
+      end
+
+      def message(value, context)
+        target = categorical_target(context)
+        name = target ? target.code : "<unresolved>"
+        "R16: CLASS_REFERENCE(#{name}) value #{value.inspect} is not a valid powertype instance"
+      end
+
+      private
+
+      def parse_data_type(context)
+        raw = context.data_type
+        return nil if raw.nil? || raw.to_s.strip.empty?
+        Opencdd::DataType.parse(raw.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      def categorical_target(context)
+        @cache ||= {}
+        key = context.data_type
+        return @cache[key] if @cache.key?(key)
+        parsed = parse_data_type(context)
+        @cache[key] = parsed ? resolve_target(parsed, context) : nil
+      end
+
+      def resolve_target(parsed, context)
+        identifier = parsed.class_identifier
+        return nil unless identifier
+        context.database.resolve_reference(identifier)
+      end
+
+      def refs(value)
+        Opencdd::StructuredValues.unwrap_and_split(value)
+      end
+    end
+  end
+end

data/lib/opencdd/validator/condition_rule.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Opencdd
+  module Validator
+    class ConditionRule < Rule
+      def id
+        "R11"
+      end
+
+      def applies?(context)
+        context.column_iri == Opencdd::PropertyIds::MDC_P028 ||
+          context.value_kind == :condition
+      end
+
+      def call(value, _context)
+        return true if value.nil? || value.to_s.strip.empty?
+        !Opencdd::Condition.parse(value.to_s).nil?
+      rescue ArgumentError
+        false
+      end
+
+      def message(value, _context)
+        "R11: condition expression #{value.inspect} is not well-formed"
+      end
+    end
+  end
+end

data/lib/opencdd/validator/data_type_rule.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Opencdd
+  module Validator
+    class DataTypeRule < Rule
+      def id
+        "R12"
+      end
+
+      def applies?(context)
+        context.column_iri == Opencdd::PropertyIds::MDC_P022
+      end
+
+      def call(value, _context)
+        return true if value.nil? || value.to_s.strip.empty?
+        !Opencdd::DataType.parse(value.to_s).nil?
+      rescue ArgumentError
+        false
+      end
+
+      def message(value, _context)
+        "R12: data type expression #{value.inspect} is not well-formed"
+      end
+    end
+  end
+end

data/lib/opencdd/validator/enum_rule.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Opencdd
+  module Validator
+    class EnumRule < Rule
+      def id
+        "R04"
+      end
+
+      def applies?(context)
+        return false unless context.data_type
+        context.data_type.to_s.start_with?("ENUM_")
+      end
+
+      def call(value, context)
+        return true if value.nil? || value.to_s.strip.empty?
+        terms = context.enum_terms_for(context.data_type)
+        return true if terms.empty?
+        terms.any? { |t| t.to_s == value.to_s }
+      end
+
+      def message(value, _context)
+        "R04: #{value.inspect} is not a member of the value list"
+      end
+    end
+  end
+end