dcc 0.2.0

data/lib/dcc/cli/formatters.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "tty-table"
+
+module Dcc
+  module Cli
+    # `Dcc::Cli::Formatters` picks the right text/JSON/YAML representation
+    # of a result model and prints it.
+    module Formatters
+      module_function
+
+      def print(object, format: "text")
+        case format
+        when "json" then puts object.to_json
+        when "yaml" then puts object.to_yaml
+        else
+          puts object.to_s
+        end
+      end
+
+      def print_files(files)
+        if files.empty?
+          puts "(no embedded files)"
+          return
+        end
+
+        # TTY::Table calls ioctl which fails on StringIO / pipes. Fall back
+        # to a plain-text rendering when stdout isn't a real terminal.
+        if $stdout.is_a?(::IO) && !$stdout.tty?
+          print_files_plain(files)
+          return
+        end
+
+        table = ::TTY::Table.new(
+          ["Index", "Name", "File Name", "MIME", "Ring", "Size"],
+          files.each_with_index.map do |f, i|
+            [i, f.name.to_s, f.file_name.to_s, f.mime_type.to_s, f.ring, f.data.bytesize]
+          end,
+        )
+        puts table.render
+      rescue StandardError
+        # Fallback if TTY::Table rendering fails for any reason.
+        print_files_plain(files)
+      end
+
+      def print_files_plain(files)
+        # Widths
+        widths = ["Index".size, "Name".size, "File Name".size, "MIME".size, "Ring".size, "Size".size]
+        rows = files.each_with_index.map do |f, i|
+          [
+            i.to_s,
+            f.name.to_s,
+            f.file_name.to_s,
+            f.mime_type.to_s,
+            f.ring.to_s,
+            f.data.bytesize.to_s,
+          ].each_with_index { |v, idx| widths[idx] = [widths[idx], v.size].max }
+        end
+        header = ["Index", "Name", "File Name", "MIME", "Ring", "Size"]
+        sep = widths.map { |w| "-" * (w + 2) }.join("+")
+        puts header.zip(widths).map { |c, w| " #{c.ljust(w)} " }.join("|")
+        puts sep
+        files.each_with_index do |f, i|
+          row = [
+            i.to_s,
+            f.name.to_s,
+            f.file_name.to_s,
+            f.mime_type.to_s,
+            f.ring.to_s,
+            f.data.bytesize.to_s,
+          ]
+          puts row.zip(widths).map { |c, w| " #{c.ljust(w)} " }.join("|")
+        end
+      end
+    end
+  end
+end

data/lib/dcc/cli.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# `Dcc::Cli` namespace root — autoloads the Thor command class.
+module Dcc
+  module Cli
+  end
+end

data/lib/dcc/common_elements.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Dcc
+  # `Dcc::CommonElements` is the base class for all DCC element wrappers in a
+  # version namespace. It provides the shared `lutaml_default_register`
+  # override that version wrappers inherit, so they don't each have to declare
+  # it themselves.
+  #
+  # Version modules (`Dcc::V2`, `Dcc::V3`) subclass this to define their
+  # own `CommonElements` with a `lutaml_default_register` matching their
+  # `CONTEXT_ID`.
+  class CommonElements < Lutaml::Model::Serializable
+    # Default context; version wrappers override this via subclassing.
+    def self.lutaml_default_register
+      :dcc_v3
+    end
+  end
+end

data/lib/dcc/context_configuration.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+# `Dcc::ContextConfiguration` mirrors the registry-aware per-major-version
+# pattern from plurimath/mml. Each version module (`Dcc::V2`, `Dcc::V3`,
+# `Dcc::Si::V1`, `Dcc::Si::V2`) extends this module and defines a unique
+# `CONTEXT_ID` symbol (e.g. `:dcc_v3`). The version's Configuration then
+# provides:
+#
+# * `register_model(klass, id:)` — register a model class for an XML element
+#   name within this version's type registry.
+# * `create_context(id:, substitutions:, ...)` — derive a custom context for
+#   minor-version variants (e.g. `:dcc_v3_4`).
+# * `populate_context!` — rebuild the version's built-in context (useful in
+#   tests after clearing the global cache).
+# * `default_context_id` — the context id that `parse` uses when no override
+#   is supplied.
+module Dcc
+  module ContextConfiguration
+    # @return [Symbol] the version's canonical context id (e.g. `:dcc_v3`).
+    def context_id
+      self::CONTEXT_ID
+    end
+
+    # @return [Lutaml::Model::Context, nil] the live context for this version,
+    #   or `nil` if not yet populated.
+    def context
+      Lutaml::Model::GlobalContext.context(context_id)
+    end
+
+    # Create or replace a context. If `id` matches the version's canonical
+    # context id, the built-in context is rebuilt via `populate_context!`.
+    #
+    # @param id [Symbol, String] context name.
+    # @param registry [Lutaml::Model::TypeRegistry, nil] custom registry.
+    # @param fallback_to [Array<Symbol>] fallback chain for type lookup.
+    # @param substitutions [Array<Hash{from_type:, to_type:}>] type substitutions.
+    def create_context(id:, registry: nil, fallback_to: [context_id], substitutions: [])
+      normalized_id = ::Dcc::ContextOptions.normalize_context_reference(id)
+      return populate_context! if normalized_id == context_id
+
+      unregister_existing(normalized_id)
+      create_type_context(
+        id: normalized_id,
+        registry: registry || Lutaml::Model::TypeRegistry.new,
+        fallback_to: normalize_fallbacks(fallback_to),
+        substitutions: substitutions,
+      )
+    end
+
+    # Rebuild the version's built-in context from `registered_models`.
+    def populate_context!
+      unregister_existing(context_id)
+      register_models_in(base_type_context)
+    end
+
+    # Contexts that this one falls back to when type lookup fails.
+    # Override in version modules to pull in cross-namespace types
+    # (e.g. DCC contexts fall back to D-SI contexts for `:real`, `:hybrid`).
+    # @return [Array<Symbol>]
+    def fallback_contexts
+      [:default]
+    end
+
+    # Register a model for an XML element name and remember it for rebuilds.
+    #
+    # @param klass [Class] the model class.
+    # @param id [Symbol, String] XML element local name (e.g. `:digitalCalibrationCertificate`).
+    # @return [Class] the registered class.
+    def register_model(klass, id:)
+      normalized_id = id.to_sym
+      registered_models[normalized_id] = klass
+      (context || populate_base_context).registry.register(normalized_id, klass)
+      clear_cache(klass)
+      klass
+    end
+
+    # @return [Symbol] the context id used when none is supplied explicitly.
+    def default_context_id
+      @default_context_id || context_id
+    end
+
+    # Override the default context (used by `custom_models=`).
+    attr_writer :default_context_id
+
+    # Convenience: bulk-register model substitutions.
+    #
+    # @param models [Hash{Class => Class}] from_type => to_type.
+    def custom_models=(models)
+      substitutions = models.map do |from_type, to_type|
+        { from_type: from_type, to_type: to_type }
+      end
+      create_context(id: :custom_models, substitutions: substitutions)
+      @default_context_id = :custom_models
+    end
+
+    # Reset any custom default context.
+    def clear_custom_models
+      @default_context_id = nil
+    end
+
+    # Public read-only accessors for cross-context re-export.
+    # @return [Array<Symbol>] ids registered in this context.
+    def registered_model_ids
+      registered_models.keys
+    end
+
+    # @param id [Symbol] the model id.
+    # @return [Class, nil] the registered class.
+    def registered_model_class(id)
+      registered_models[id.to_sym]
+    end
+
+    private
+
+    def unregister_existing(id)
+      return unless Lutaml::Model::GlobalContext.context(id)
+
+      Lutaml::Model::GlobalContext.unregister_context(id)
+    end
+
+    def populate_base_context
+      base_type_context
+    end
+
+    def create_type_context(id:, registry:, fallback_to:, substitutions: [])
+      Lutaml::Model::GlobalContext.create_context(
+        id: id,
+        registry: registry,
+        fallback_to: fallback_to,
+        substitutions: substitutions,
+      ).tap { Lutaml::Model::GlobalContext.clear_caches }
+    end
+
+    def base_type_context
+      create_type_context(
+        id: context_id,
+        registry: Lutaml::Model::TypeRegistry.new,
+        fallback_to: fallback_contexts,
+      )
+    end
+
+    def register_models_in(type_context)
+      registered_models.each do |model_id, klass|
+        type_context.registry.register(model_id, klass)
+        clear_cache(klass)
+      end
+      Lutaml::Model::GlobalContext.clear_caches
+      type_context
+    end
+
+    def normalize_fallbacks(fallback_to)
+      Array(fallback_to).map { |f| ::Dcc::ContextOptions.normalize_context_reference(f) }
+    end
+
+    def registered_models
+      @registered_models ||= {}
+    end
+
+    def clear_cache(klass)
+      return unless klass.is_a?(Class)
+      return unless klass < ::Lutaml::Model::Serializable
+      return unless klass.method_defined?(:clear_cache)
+
+      klass.clear_cache(context_id)
+    end
+  end
+end

data/lib/dcc/context_options.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# `Dcc::ContextOptions` normalizes the `context:` / `register:` options that
+# callers can pass to `Dcc.parse`, `Dcc::V3.parse`, etc.
+module Dcc
+  module ContextOptions
+    module_function
+
+    # Collapse the public `context:` and `register:` options into a single
+    # context id symbol (or `nil` to fall back to the caller's default).
+    #
+    # @param context [Symbol, String, nil, Dcc::UNSPECIFIED_CONTEXT]
+    # @param register [Symbol, String, nil] deprecated alias for `context:`.
+    # @param default_context [Symbol, nil] returned when neither is given.
+    # @param warning_source [String] caller name for deprecation warnings.
+    def normalize_context_option(context:, register:, default_context:, warning_source:)
+      raise_if_conflicting!(context, register)
+      return normalize_context_reference(register) || default_context if register
+      return default_context unless context_specified?(context)
+
+      normalize_context_reference(context) || default_context
+    end
+
+    # Coerce any acceptable context reference (Symbol, String, or
+    # `Lutaml::Xml::Namespace`) into a Symbol.
+    def normalize_context_reference(reference)
+      return nil if reference.nil?
+      return reference if reference.is_a?(Symbol)
+      return reference.to_sym if reference.is_a?(String)
+      return reference.id.to_sym if reference.is_a?(::Lutaml::Xml::Namespace)
+
+      raise ArgumentError, "Unsupported context/register reference: #{reference.inspect}"
+    end
+
+    def context_specified?(context)
+      !context.equal?(::Dcc::UNSPECIFIED_CONTEXT)
+    end
+
+    def raise_if_conflicting!(context, register)
+      return unless context_specified?(context) && register
+
+      raise ArgumentError, "Use either `context` or `register`, not both"
+    end
+
+    private_class_method :raise_if_conflicting!
+  end
+end

data/lib/dcc/convert/csv.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module Dcc
+  module Convert
+    # `Dcc::Convert::Csv` flattens a parsed DCC into a tabular CSV with
+    # one row per measurement quantity.
+    module Csv
+      HEADERS = %w[result_name quantity_name quantity_type value unit uncertainty coverage_factor].freeze
+
+      class << self
+        # @param dcc [Lutaml::Model::Serializable]
+        # @return [Dcc::Convert::Result]
+        def call(dcc)
+          rows = collect_quantities(dcc)
+          payload = ::CSV.generate do |csv|
+            csv << HEADERS
+            rows.each { |row| csv << row }
+          end
+
+          ::Dcc::Convert::Result.new(
+            format: :csv,
+            payload: payload,
+            source_class: dcc.class.name,
+            schema_version: dcc.schema_version.to_s,
+          )
+        end
+
+        private
+
+        def collect_quantities(dcc)
+          rows = []
+          return rows unless Dcc::TypeGuards.has_attribute?(dcc, :measurement_results)
+
+          Array(dcc.measurement_results.measurement_result).each do |mr|
+            mr_name = name_of(mr)
+            next unless Dcc::TypeGuards.has_attribute?(mr, :results)
+
+            Array(mr.results.result).each do |r|
+              result_name = name_of(r)
+              next unless Dcc::TypeGuards.has_attribute?(r, :data)
+
+              Array(r.data).each do |d|
+                walk_data(d, mr_name, result_name, rows)
+              end
+            end
+          end
+          rows
+        end
+
+        def walk_data(data, mr_name, result_name, rows)
+          walk_quantities(Array(data.quantity), mr_name, result_name, rows)
+          Array(data.list).each do |list|
+            walk_quantities(Array(list.quantity), mr_name, result_name, rows)
+            Array(list.list).each { |sub| walk_data(sub, mr_name, result_name, rows) }
+          end
+        end
+
+        def walk_quantities(quantities, mr_name, result_name, rows)
+          quantities.each do |q|
+            push_quantity(q, mr_name, result_name, "real", rows)
+          end
+        end
+
+        def push_quantity(q, mr_name, result_name, kind, rows)
+          rows << [
+            mr_name, name_of(q), kind,
+            value_of(q), unit_of(q), uncertainty_of(q), k_factor_of(q),
+          ]
+        end
+
+        def name_of(node)
+          return "" unless node && Dcc::TypeGuards.has_attribute?(node, :name)
+          return "" unless node.name
+
+          content = Dcc::TypeGuards.has_attribute?(node.name, :content) ? node.name.content : []
+          first = Array(content).first
+          return "" unless first
+
+          vals = Dcc::TypeGuards.has_attribute?(first, :value) ? first.value : []
+          Array(vals).first.to_s
+        end
+
+        def value_of(q)
+          reals = Array(q.real)
+          return reals.first.value.to_s if reals.any?
+
+          lists = Array(q.real_list_xml_list)
+          return lists.first.value_xml_list.map(&:to_s).join("; ") if lists.any?
+
+          ""
+        end
+
+        def unit_of(q)
+          reals = Array(q.real)
+          return reals.first.unit.to_s if reals.any? && reals.first.unit
+
+          lists = Array(q.real_list_xml_list)
+          return lists.first.unit_xml_list.to_s if lists.any? && lists.first.unit_xml_list
+
+          ""
+        end
+
+        def uncertainty_of(q)
+          reals = Array(q.real)
+          return "" if reals.empty? || !reals.first.measurement_uncertainty_univariate
+
+          mu = reals.first.measurement_uncertainty_univariate
+          return mu.expanded_mu.value_expanded_mu.to_s if mu.expanded_mu
+          return mu.standard_mu.value_standard_mu.to_s if mu.standard_mu
+          return mu.coverage_interval_mu.value_standard_mu.to_s if mu.coverage_interval_mu
+
+          ""
+        end
+
+        def k_factor_of(q)
+          reals = Array(q.real)
+          return "" if reals.empty?
+
+          mu = reals.first.measurement_uncertainty_univariate
+          return "" unless mu&.expanded_mu
+
+          mu.expanded_mu.coverage_factor.to_s
+        end
+      end
+    end
+  end
+end

data/lib/dcc/convert/html.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Dcc
+  module Convert
+    # `Dcc::Convert::Html` renders a parsed DCC into a human-readable HTML
+    # report with collapsible sections per administrative section and
+    # measurement result.
+    module Html
+      class << self
+        # @param dcc [Lutaml::Model::Serializable]
+        # @return [Dcc::Convert::Result]
+        def call(dcc)
+          payload = <<~HTML
+            <!DOCTYPE html>
+            <html lang="en">
+            <head>
+              <meta charset="utf-8">
+              <title>DCC Report #{escape(unique_identifier_of(dcc))}</title>
+              <style>
+                body { font-family: -apple-system, system-ui, sans-serif; margin: 2rem; }
+                h1, h2, h3 { color: #333; }
+                section { margin-bottom: 1.5rem; padding: 1rem; border: 1px solid #eee; border-radius: 4px; }
+                table { border-collapse: collapse; }
+                th, td { border: 1px solid #ddd; padding: 0.5rem 1rem; text-align: left; }
+                th { background: #f5f5f5; }
+              </style>
+            </head>
+            <body>
+              <h1>Digital Calibration Certificate</h1>
+              #{summary_table(dcc)}
+              #{administrative_section(dcc)}
+              #{measurement_section(dcc)}
+            </body>
+            </html>
+          HTML
+
+          ::Dcc::Convert::Result.new(
+            format: :html,
+            payload: payload,
+            source_class: dcc.class.name,
+            schema_version: dcc.schema_version.to_s,
+          )
+        end
+
+        private
+
+        def summary_table(dcc)
+          <<~HTML
+            <section>
+              <h2>Identity</h2>
+              <table>
+                <tr><th>Schema version</th><td>#{escape(dcc.schema_version)}</td></tr>
+                <tr><th>Unique identifier</th><td>#{escape(unique_identifier_of(dcc))}</td></tr>
+                <tr><th>Country</th><td>#{escape(country_of(dcc))}</td></tr>
+              </table>
+            </section>
+          HTML
+        end
+
+        def administrative_section(dcc)
+          return "" unless Dcc::TypeGuards.has_attribute?(dcc, :administrative_data) && dcc.administrative_data
+
+          admin = dcc.administrative_data
+          items = Dcc::TypeGuards.has_attribute?(admin, :items) && admin.items ? Array(admin.items.item) : []
+          <<~HTML
+            <section>
+              <h2>Items (#{items.size})</h2>
+              <ul>
+                #{items.map { |i| "<li>#{escape(name_of(i))}</li>" }.join("\n")}
+              </ul>
+            </section>
+          HTML
+        end
+
+        def measurement_section(dcc)
+          return "" unless Dcc::TypeGuards.has_attribute?(dcc, :measurement_results) && dcc.measurement_results
+
+          mrs = Array(dcc.measurement_results.measurement_result)
+          <<~HTML
+            <section>
+              <h2>Measurement Results (#{mrs.size})</h2>
+              <ul>
+                #{mrs.map { |mr| "<li>#{escape(name_of(mr))}</li>" }.join("\n")}
+              </ul>
+            </section>
+          HTML
+        end
+
+        def unique_identifier_of(dcc)
+          Dcc::TypeGuards.has_attribute?(dcc, :administrative_data) &&
+            Dcc::TypeGuards.has_attribute?(dcc.administrative_data, :core_data) &&
+            dcc.administrative_data.core_data &&
+            dcc.administrative_data.core_data.unique_identifier.to_s
+        end
+
+        def country_of(dcc)
+          Dcc::TypeGuards.has_attribute?(dcc, :administrative_data) &&
+            Dcc::TypeGuards.has_attribute?(dcc.administrative_data, :core_data) &&
+            dcc.administrative_data.core_data &&
+            dcc.administrative_data.core_data.country_code_iso_3166_1.to_s
+        end
+
+        def name_of(node)
+          return "" unless node && Dcc::TypeGuards.has_attribute?(node, :name)
+          return "" unless node.name
+
+          content = Dcc::TypeGuards.has_attribute?(node.name, :content) ? node.name.content : []
+          first = Array(content).first
+          return "" unless first
+
+          vals = Dcc::TypeGuards.has_attribute?(first, :value) ? first.value : []
+          Array(vals).first.to_s
+        end
+
+        def escape(s)
+          return "" if s.nil?
+
+          s.to_s
+            .gsub("&", "&amp;")
+            .gsub("<", "&lt;")
+            .gsub(">", "&gt;")
+            .gsub('"', "&quot;")
+        end
+      end
+    end
+  end
+end

data/lib/dcc/convert/json.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Dcc
+  module Convert
+    # `Dcc::Convert::Json` serializes a parsed DCC to JSON by converting
+    # the `to_xml` output to a JSON-compatible hash.
+    module Json
+      class << self
+        def call(dcc, pretty: true)
+          hash = xml_to_hash(dcc.to_xml)
+          payload = pretty ? ::JSON.pretty_generate(hash) : ::JSON.generate(hash)
+          ::Dcc::Convert::Result.new(
+            format: :json,
+            payload: payload,
+            source_class: dcc.class.name,
+            schema_version: dcc.schema_version.to_s,
+          )
+        end
+
+        def xml_to_hash(xml_string)
+          doc = ::Lutaml::Model::Config.xml_adapter.parse(xml_string)
+          element_to_hash(doc.root)
+        end
+
+        private
+
+        def element_to_hash(element)
+          hash = {}
+
+          element.attributes&.each do |k, v|
+            hash[k.to_s] = v.value.to_s
+          end
+
+          children = element.children.to_a.reject(&:text?)
+          text_children = element.children.to_a.select(&:text?)
+          combined_text = text_children.map(&:text).join.strip
+
+          if children.empty?
+            return combined_text if hash.empty? && !combined_text.empty?
+            return hash if combined_text.empty?
+
+            hash["_text"] = combined_text
+            return hash
+          end
+
+          children.each do |child|
+            name = child.name.to_s.split(":").last
+            value = element_to_hash(child)
+            if hash.key?(name)
+              hash[name] = Array(hash[name]) << value
+            else
+              hash[name] = value
+            end
+          end
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/dcc/convert/result.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Dcc
+  module Convert
+    # Output of a `Dcc::Convert::*` converter. Carries the format and the
+    # string payload. Outputs are models per the user's directive:
+    # `to_s` returns the rendered payload, `to_json` / `to_yaml` return
+    # the formatted payload directly.
+    class Result
+      attr_reader :format, :payload, :source_class, :schema_version
+
+      # @param format [Symbol, String] the conversion target (`:json`, `:yaml`, etc.).
+      # @param payload [String] the rendered output.
+      # @param source_class [String, nil] the source model's class name.
+      # @param schema_version [String, nil] the DCC schema version.
+      def initialize(format:, payload:, source_class: nil, schema_version: nil)
+        @format = format.to_sym
+        @payload = payload.to_s
+        @source_class = source_class
+        @schema_version = schema_version
+      end
+
+      # `to_s` returns the rendered output.
+      def to_s
+        @payload
+      end
+
+      # Convenience: parse the payload back into Ruby data structures.
+      # @return [Object]
+      def parsed
+        case @format
+        when :json
+          ::JSON.parse(@payload)
+        when :yaml
+          ::YAML.safe_load(@payload)
+        else
+          @payload
+        end
+      end
+
+      # Already-rendered JSON payload (not a re-render).
+      def to_json(*_args)
+        @payload
+      end
+
+      def to_yaml(*_args)
+        @payload
+      end
+    end
+  end
+end