dcc 0.2.0

data/lib/dcc/convert/yaml.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Dcc
+  module Convert
+    module Yaml
+      class << self
+        def call(dcc)
+          hash = ::Dcc::Convert::Json.xml_to_hash(dcc.to_xml)
+          ::Dcc::Convert::Result.new(
+            format: :yaml,
+            payload: ::YAML.dump(hash),
+            source_class: dcc.class.name,
+            schema_version: dcc.schema_version.to_s,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/dcc/convert.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# `Dcc::Convert` is the entry-point module for format converters. Each
+# converter accepts a parsed DCC object tree and returns a `Dcc::Convert::Result`
+# model that can be rendered as text, JSON, or YAML.
+module Dcc
+  module Convert
+    autoload :Result, "dcc/convert/result"
+    autoload :Json, "dcc/convert/json"
+    autoload :Yaml, "dcc/convert/yaml"
+    autoload :Csv, "dcc/convert/csv"
+    autoload :Html, "dcc/convert/html"
+  end
+end

data/lib/dcc/diff/change.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Dcc
+  module Diff
+    # A single structural change between two DCC object trees.
+    Change = ::Struct.new(:path, :kind, :before, :after) do
+      def added? = kind == :add
+      def removed? = kind == :remove
+      def changed? = kind == :change
+
+      def to_s
+        case kind
+        when :add    then "+ #{path}: #{after}"
+        when :remove then "- #{path}: #{before}"
+        when :change then "~ #{path}: #{before} -> #{after}"
+        else path
+        end
+      end
+    end
+  end
+end

data/lib/dcc/diff/result.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Dcc
+  module Diff
+    # Result of comparing two DCC object trees.
+    class Result
+      attr_reader :changes
+
+      def initialize(changes:)
+        @changes = changes
+      end
+
+      def additions
+        changes.select(&:added?)
+      end
+
+      def removals
+        changes.select(&:removed?)
+      end
+
+      def modifications
+        changes.select(&:changed?)
+      end
+
+      def empty?
+        changes.empty?
+      end
+
+      def to_s
+        if empty?
+          "(no structural changes)"
+        else
+          header = "#{changes.size} change(s): " \
+                  "#{additions.size} added, #{removals.size} removed, #{modifications.size} changed"
+          ([header] + changes.map(&:to_s)).join("\n")
+        end
+      end
+
+      def to_json(*_args)
+        require "json"
+        ::JSON.pretty_generate(
+          additions: additions.map { |c| { path: c.path, value: c.after } },
+          removals: removals.map { |c| { path: c.path, value: c.before } },
+          modifications: modifications.map { |c| { path: c.path, before: c.before, after: c.after } },
+        )
+      end
+
+      def to_yaml(*_args)
+        require "yaml"
+        {
+          additions: additions.map { |c| { path: c.path, value: c.after } },
+          removals: removals.map { |c| { path: c.path, value: c.before } },
+          modifications: modifications.map { |c| { path: c.path, before: c.before, after: c.after } },
+        }.to_yaml
+      end
+    end
+  end
+end

data/lib/dcc/diff.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "lutaml/model"
+
+module Dcc
+  # `Dcc::Diff` compares two parsed DCC object trees and returns a
+  # `Dcc::Diff::Result` describing structural changes (counts, additions,
+  # removals, modifications). Identity is determined by `uniqueIdentifier`
+  # for the top-level DCC and by element `@id` / `@refId` for nested items.
+  module Diff
+    autoload :Result, "dcc/diff/result"
+    autoload :Change, "dcc/diff/change"
+
+    class << self
+      # @param a [Lutaml::Model::Serializable]
+      # @param b [Lutaml::Model::Serializable]
+      # @return [Dcc::Diff::Result]
+      def call(a, b)
+        changes = []
+        collect_differences(a, b, "", changes)
+        Result.new(changes: changes)
+      end
+
+      private
+
+      def collect_differences(a, b, path, changes)
+        # Both nil - no diff
+        return if a.nil? && b.nil?
+        # One is nil - add/remove
+        if a.nil?
+          changes << Change.new(path: path, kind: :add, before: nil, after: summarize(b))
+          return
+        end
+        if b.nil?
+          changes << Change.new(path: path, kind: :remove, before: summarize(a), after: nil)
+          return
+        end
+
+        # Both primitives - compare values
+        if primitive?(a) || primitive?(b)
+          if a != b
+            changes << Change.new(path: path, kind: :change, before: a, after: b)
+          end
+          return
+        end
+
+        # Both arrays
+        if a.is_a?(::Array) || b.is_a?(::Array)
+          max = [a.size, b.size].max
+          max.times do |i|
+            collect_differences(a[i], b[i], "#{path}[#{i}]", changes)
+          end
+          return
+        end
+
+        # Both objects
+        keys = (a.class.attributes.keys | b.class.attributes.keys)
+        keys.each do |key|
+          av = Dcc::TypeGuards.has_attribute?(a, key) ? a.public_send(key) : nil
+          bv = Dcc::TypeGuards.has_attribute?(b, key) ? b.public_send(key) : nil
+          collect_differences(av, bv, "#{path}/#{key}", changes)
+        end
+      end
+
+      def primitive?(value)
+        return true if value.nil?
+        return true if value.is_a?(::String) || value.is_a?(::Numeric) || value.is_a?(::Symbol)
+        return true if value == true || value == false
+        return true if value.is_a?(::Time) || value.is_a?(::Date) || value.is_a?(::DateTime)
+        return true if value.is_a?(::BigDecimal)
+
+        false
+      end
+
+      def summarize(node)
+        return node.to_s if primitive?(node)
+
+        "#{node.class.name.split('::').last}"
+      end
+    end
+  end
+end

data/lib/dcc/error.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Dcc
+  # Base error class for all dcc gem errors. Subclasses live directly under
+  # `Dcc::Error::*` (e.g. `Dcc::ParseError`).
+  class Error < StandardError; end
+
+  # Raised when an XML document cannot be parsed (malformed XML, encoding
+  # issues, IO errors).
+  class ParseError < Error; end
+
+  # Base class for all validation failures (XSD, Schematron, business rules).
+  class ValidationError < Error
+    attr_reader :issues
+
+    def initialize(message, issues: [])
+      @issues = issues
+      super(message)
+    end
+  end
+
+  # Raised when an XSD validation fails or the XSD itself cannot be loaded.
+  class SchemaError < ValidationError; end
+
+  # Raised when XMLDSig signing or verification fails.
+  class SignatureError < Error; end
+
+  # Raised when a converter cannot produce the requested output format.
+  class ConversionError < Error; end
+
+  # Raised when an extractor encounters malformed content.
+  class ExtractionError < Error; end
+
+  # Raised when an XSLT transform fails.
+  class TransformError < Error; end
+
+  # Raised when an unsupported schema version is requested.
+  class UnknownVersionError < Error; end
+
+  # Raised when the builder DSL is used incorrectly.
+  class BuilderError < Error; end
+
+  # Raised when a soft dependency (`xmldsig`, `sinatra`, etc.) is required
+  # but not installed.
+  class MissingDependencyError < Error
+    attr_reader :gem_name, :feature
+
+    def initialize(gem_name:, feature:)
+      @gem_name = gem_name
+      @feature = feature
+      super("The '#{gem_name}' gem is required for #{feature}. Add it to your Gemfile or run: gem install #{gem_name}")
+    end
+  end
+end

data/lib/dcc/extract/file.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "base64"
+require "set"
+
+module Dcc
+  module Extract
+    # `Dcc::Extract::File` enumerates embedded files (`dcc:byteDataType`
+    # elements) inside a parsed DCC. Each entry carries the decoded binary
+    # payload, MIME type, file name, and the surrounding ring.
+    class File
+      attr_reader :name, :file_name, :mime_type, :data, :ring
+
+      # @param name [String, nil] human-readable name (typically from `dcc:name`).
+      # @param file_name [String, nil] original file name.
+      # @param mime_type [String, nil] MIME type (e.g. `text/plain`).
+      # @param data [String] binary payload (decoded from base64).
+      # @param ring [Symbol] one of `Dcc::Extract::Ring::ALL`.
+      def initialize(name:, file_name:, mime_type:, data:, ring:)
+        @name = name
+        @file_name = file_name
+        @mime_type = mime_type
+        @data = data
+        @ring = ring
+      end
+
+      # @return [Boolean] true if the embedded payload is textual (text/*).
+      def text?
+        mime_type.to_s.start_with?("text/")
+      end
+
+      def to_s
+        "File #{file_name || '(unnamed)'} [#{ring}] (#{mime_type}, #{data.bytesize} bytes)"
+      end
+
+      class << self
+        # Walk a parsed DCC and yield each embedded file in document order.
+        # Detects cycles (recursive list) via object_id tracking so the walk
+        # terminates for self-referential subtrees.
+        # @param dcc [Lutaml::Model::Serializable]
+        # @yieldparam [Dcc::Extract::File]
+        # @return [Array<Dcc::Extract::File>] the list when no block given.
+        def each(dcc, &block)
+          list = []
+          visited = ::Set.new
+
+          collect = lambda do |node, ring|
+            return unless node.is_a?(::Lutaml::Model::Serializable)
+            return if visited.include?(node.object_id)
+
+            visited << node.object_id
+
+            new_ring =
+              if admin_data?(node)
+                Ring::ADMINISTRATIVE_DATA
+              elsif measurement_list?(node)
+                Ring::MEASUREMENT_RESULTS
+              else
+                ring
+              end
+            list << build_file(node, new_ring) if byte_data?(node)
+            walk_children(node, new_ring, collect)
+          end
+
+          collect.call(dcc, nil)
+          return list unless block_given?
+
+          list.each(&block)
+        end
+
+        # @param dcc [Lutaml::Model::Serializable]
+        # @param index [Integer] zero-based index.
+        # @return [Dcc::Extract::File, nil]
+        def at(dcc, index)
+          each(dcc)[index]
+        end
+
+        # @param dcc [Lutaml::Model::Serializable]
+        # @param ring [Symbol] one of Ring::ALL.
+        # @return [Array<Dcc::Extract::File>]
+        def in_ring(dcc, ring:)
+          each(dcc).select { |f| f.ring == ring }
+        end
+
+        private
+
+        def admin_data?(node)
+          node.class.name.end_with?("::AdministrativeData")
+        end
+
+        def measurement_list?(node)
+          node.class.name.end_with?("::MeasurementResultList")
+        end
+
+        def byte_data?(node)
+          node.class.name.end_with?("::ByteData")
+        end
+
+        # Recursive walk: for each attribute, get its value and descend.
+        # Handles both single objects and collection arrays.
+        def walk_children(node, ring, walker)
+          node.class.attributes.each_key do |attr_name|
+            values = node.public_send(attr_name)
+            next if values.nil?
+
+            if values.is_a?(::Array)
+              walk_values(values, ring, walker)
+            elsif values.is_a?(::Lutaml::Model::Serializable)
+              walker.call(values, ring)
+            end
+          end
+        end
+
+        def walk_values(values, ring, walker)
+          Array(values).each do |v|
+            walker.call(v, ring) if v.is_a?(::Lutaml::Model::Serializable)
+          end
+        end
+
+        def build_file(byte_data, ring)
+          name = extract_name(byte_data.name)
+          new(
+            name: name,
+            file_name: byte_data.file_name,
+            mime_type: byte_data.mime_type,
+            data: ::Dcc::Type::Base64Binary.decode(byte_data.data_base64),
+            ring: ring || Ring::ADMINISTRATIVE_DATA,
+          )
+        end
+
+        def extract_name(name_obj)
+          return nil unless name_obj
+
+          first = name_obj.content.first
+          return nil unless first
+
+          values = first.value
+          values.is_a?(::Array) ? values.first : values
+        end
+      end
+    end
+  end
+end

data/lib/dcc/extract/ring.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Dcc
+  module Extract
+    # The "Ring" of a `dcc:byteDataType` element: which section of the DCC
+    # document contained it. PTB defines these as `administrativeData`,
+    # `measurementResults`, `comment`, and `document`.
+    module Ring
+      ADMINISTRATIVE_DATA = :administrativeData
+      MEASUREMENT_RESULTS = :measurementResults
+      COMMENT = :comment
+      DOCUMENT = :document
+
+      ALL = [ADMINISTRATIVE_DATA, MEASUREMENT_RESULTS, COMMENT, DOCUMENT].freeze
+
+      class << self
+        # @param symbol_or_string [Symbol, String, nil]
+        # @return [Symbol, nil] the canonical ring symbol.
+        def normalize(symbol_or_string)
+          return nil if symbol_or_string.nil?
+
+          sym = symbol_or_string.to_sym
+          ALL.include?(sym) ? sym : nil
+        end
+      end
+    end
+  end
+end

data/lib/dcc/extract.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Dcc
+  module Extract
+    autoload :File, "dcc/extract/file"
+    autoload :Ring, "dcc/extract/ring"
+    autoload :Formula, "dcc/extract/formula"
+  end
+end

data/lib/dcc/i18n/text_lookup.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Dcc
+  module I18n
+    # `Dcc::I18n::TextLookup` extracts the best-matching localized string
+    # from a `dcc:textType` block.
+    #
+    # Selection order:
+    #   1. Exact match for the requested language
+    #   2. First mandatory language declared in the DCC coreData
+    #   3. First used language declared in the DCC coreData
+    #   4. First content element regardless of language
+    #   5. nil if no content at all
+    module TextLookup
+      class << self
+        # @param text_obj [Object, nil] a parsed `dcc:textType` block.
+        # @param dcc [Object, nil] the parent DCC (used to read declared langs).
+        # @param lang [String, nil] requested ISO 639-1 code.
+        # @return [String, nil]
+        def call(text_obj, dcc: nil, lang: nil)
+          return nil unless text_obj && Dcc::TypeGuards.has_attribute?(text_obj, :content)
+
+          contents = Array(text_obj.content)
+          return nil if contents.empty?
+
+          return content_value(contents, lang) if lang
+
+          dcc_langs = declared_languages(dcc)
+          dcc_langs.each do |fallback|
+            val = content_value(contents, fallback)
+            return val if val
+          end
+
+          content_value(contents, nil)
+        end
+
+        private
+
+        def content_value(contents, lang)
+          match = if lang
+                    contents.find { |c| c.lang.to_s == lang.to_s }
+                  else
+                    contents.first
+                  end
+          return nil unless match
+
+          values = Array(match.value)
+          values.first&.to_s
+        end
+
+        def declared_languages(dcc)
+          return [] unless dcc && Dcc::TypeGuards.has_attribute?(dcc, :administrative_data)
+
+          admin = dcc.administrative_data
+          return [] unless admin && Dcc::TypeGuards.has_attribute?(admin, :core_data)
+
+          core = admin.core_data
+          return [] unless core
+
+          mandatory = Array(core.mandatory_lang_code_iso_639_1).map(&:to_s)
+          used = Array(core.used_lang_code_iso_639_1).map(&:to_s)
+          (mandatory + used).uniq
+        end
+      end
+    end
+  end
+end

data/lib/dcc/i18n.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# `Dcc::I18n` provides helpers for navigating multilingual DCC content.
+# PTB DCC documents carry `usedLangCodeISO639_1` and
+# `mandatoryLangCodeISO639_1` attributes; text blocks (`dcc:textType`)
+# contain one `dcc:content` element per language. These helpers pick the
+# best-matching language with a configurable fallback chain.
+module Dcc
+  module I18n
+    autoload :TextLookup, "dcc/i18n/text_lookup"
+  end
+end

data/lib/dcc/inspect/report.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Dcc
+  module Inspect
+    # `Dcc::Inspect::Report` summarizes a parsed DCC: counts, key
+    # identifiers, signature presence, and a human-readable `to_s` /
+    # `to_json` / `to_yaml`.
+    class Report < Lutaml::Model::Serializable
+      attribute :schema_version, :string
+      attribute :unique_identifier, :string
+      attribute :country_code, :string
+      attribute :item_count, :integer
+      attribute :measurement_result_count, :integer
+      attribute :quantity_count, :integer
+      attribute :list_count, :integer
+      attribute :embedded_file_count, :integer
+      attribute :languages, :string, collection: true
+      attribute :signer_count, :integer
+      attribute :has_signature, :boolean
+
+      def to_s
+        lines = []
+        lines << "DCC Inspection Report"
+        lines << "=" * 50
+        lines << "Schema version:     #{schema_version}"
+        lines << "Unique identifier:  #{unique_identifier}"
+        lines << "Country:            #{country_code}"
+        lines << "Languages:          #{languages.join(', ')}" if languages.any?
+        lines << "Items:              #{item_count}"
+        lines << "Measurement results: #{measurement_result_count}"
+        lines << "Quantities:         #{quantity_count}"
+        lines << "Lists:              #{list_count}"
+        lines << "Embedded files:     #{embedded_file_count}"
+        lines << "Signers:            #{signer_count}"
+        lines << "Has signature:      #{has_signature ? 'yes' : 'no'}"
+        lines.join("\n")
+      end
+
+      def to_json(*_args)
+        require "json"
+        payload = {}
+        self.class.attributes.each_key { |k| payload[k] = public_send(k) }
+        ::JSON.pretty_generate(payload)
+      end
+
+      def to_yaml(*_args)
+        require "yaml"
+        payload = {}
+        self.class.attributes.each_key { |k| payload[k] = public_send(k) }
+        payload.to_yaml
+      end
+
+      class << self
+        # @param dcc [Lutaml::Model::Serializable]
+        # @return [Dcc::Inspect::Report]
+        def call(dcc)
+          admin = admin_data(dcc)
+          mr_list = measurement_results(dcc)
+          new(
+            schema_version: dcc.schema_version.to_s,
+            unique_identifier: core_data(dcc)&.unique_identifier,
+            country_code: core_data(dcc)&.country_code_iso_3166_1.to_s,
+            item_count: items(dcc).size,
+            measurement_result_count: mr_list.size,
+            quantity_count: count_quantities(mr_list),
+            list_count: count_lists(mr_list),
+            embedded_file_count: ::Dcc::Extract::File.each(dcc).size,
+            languages: lang_codes(dcc),
+            signer_count: resp_persons(dcc).size,
+            has_signature: signature_present?(dcc),
+          )
+        end
+
+        private
+
+        def admin_data(dcc)
+          Dcc::TypeGuards.has_attribute?(dcc, :administrative_data) ? dcc.administrative_data : nil
+        end
+
+        def core_data(dcc)
+          ad = admin_data(dcc)
+          ad && Dcc::TypeGuards.has_attribute?(ad, :core_data) ? ad.core_data : nil
+        end
+
+        def items(dcc)
+          ad = admin_data(dcc)
+          return [] unless ad && Dcc::TypeGuards.has_attribute?(ad, :items) && ad.items && Dcc::TypeGuards.has_attribute?(ad.items, :item)
+
+          Array(ad.items.item)
+        end
+
+        def measurement_results(dcc)
+          Dcc::TypeGuards.has_attribute?(dcc, :measurement_results) && dcc.measurement_results && Dcc::TypeGuards.has_attribute?(dcc.measurement_results, :measurement_result) ?
+            Array(dcc.measurement_results.measurement_result) : []
+        end
+
+        def count_quantities(mr_list)
+          mr_list.sum do |mr|
+            next 0 unless Dcc::TypeGuards.has_attribute?(mr, :results) && mr.results && Dcc::TypeGuards.has_attribute?(mr.results, :result)
+
+            Array(mr.results.result).sum do |r|
+              Dcc::TypeGuards.has_attribute?(r, :data) && r.data && Dcc::TypeGuards.has_attribute?(r.data, :quantity) ? Array(r.data.quantity).size : 0
+            end
+          end
+        end
+
+        def count_lists(mr_list)
+          mr_list.sum do |mr|
+            next 0 unless Dcc::TypeGuards.has_attribute?(mr, :results) && mr.results && Dcc::TypeGuards.has_attribute?(mr.results, :result)
+
+            Array(mr.results.result).sum do |r|
+              Dcc::TypeGuards.has_attribute?(r, :data) && r.data && Dcc::TypeGuards.has_attribute?(r.data, :list) ? Array(r.data.list).size : 0
+            end
+          end
+        end
+
+        def lang_codes(dcc)
+          cd = core_data(dcc)
+          return [] unless cd
+
+          [cd.used_lang_code_iso_639_1, cd.mandatory_lang_code_iso_639_1].flatten.compact.map(&:to_s)
+        end
+
+        def resp_persons(dcc)
+          ad = admin_data(dcc)
+          return [] unless ad && Dcc::TypeGuards.has_attribute?(ad, :resp_persons) && ad.resp_persons && Dcc::TypeGuards.has_attribute?(ad.resp_persons, :resp_person)
+
+          Array(ad.resp_persons.resp_person)
+        end
+
+        def signature_present?(dcc)
+          Dcc::TypeGuards.has_attribute?(dcc, :document) && dcc.document
+        end
+      end
+    end
+  end
+end

data/lib/dcc/inspect.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Dcc
+  module Inspect
+    autoload :Report, "dcc/inspect/report"
+  end
+end