dcc 0.2.0 → 0.2.1

data/lib/dcc/migrate/route.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Dcc
+  module Migrate
+    # Registry of migrations whose full incompatibility set has been verified
+    # against the bundled XSDs.
+    #
+    # Unregistered pairs raise rather than run. DCC 2.1.0 and 2.1.1 sit in the
+    # `https://ptb.de/si/smartcom/d-si/v1_0_1` D-SI namespace, which no
+    # transform here addresses, so accepting them by major version alone would
+    # silently emit an unmigrated document.
+    module Route
+      TRANSFORMS = { %w[2.3.0 3.3.0] => :V2ToV3 }.freeze
+
+      # v3.3.0 is a strict superset of v3.2.1 at instance level; only the
+      # `schemaVersion` pattern differs.
+      SCHEMA_VERSION_ONLY = [%w[3.2.1 3.3.0]].freeze
+
+      class << self
+        # @param from [String] normalized source version, e.g. "2.3.0".
+        # @param to [String] normalized target version, e.g. "3.3.0".
+        # @return [Boolean] whether this migration is registered.
+        def supported?(from, to)
+          TRANSFORMS.key?([from, to]) ||
+            SCHEMA_VERSION_ONLY.include?([from, to])
+        end
+
+        # @return [Module, nil] a module responding to
+        #   `.call(xml, to:, on_loss:)`, or nil when only `schemaVersion`
+        #   needs rewriting.
+        def for(from, to)
+          name = TRANSFORMS[[from, to]]
+          name && ::Dcc::Migrate.const_get(name)
+        end
+
+        # @return [Array<String>] every registered pair, for error messages.
+        def supported_pairs
+          (TRANSFORMS.keys + SCHEMA_VERSION_ONLY)
+            .map { |from, to| "#{from} to #{to}" }
+        end
+      end
+    end
+  end
+end

data/lib/dcc/migrate/v2_to_v3.rb

@@ -0,0 +1,445 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Dcc
+  module Migrate
+    # Rewrites a DCC v2.x document into the v3.x wire format.
+    #
+    # v3 renamed several elements, renamed the `hashType` children on all three
+    # v2 elements carrying that type, made `coreData/performanceLocation` and
+    # `measurementResult/name` mandatory, moved the statement `refId` from a
+    # child element to an attribute, narrowed four `description` elements to
+    # single occurrence, tightened many string types to reject surrounding
+    # whitespace, and switched from D-SI v1 to D-SI v2.
+    #
+    # Two v2 constructs have no v3 home — `formula/@lang` and the second and
+    # later `calibrationLaboratory/contact`. Those, the element ids lost to a
+    # description merge, and every trimmed value are reported rather than
+    # dropped in silence.
+    #
+    # Every rule is conditional, so applying the transform twice is a no-op.
+    module V2ToV3
+      NS = {
+        "dcc" => "https://ptb.de/dcc",
+        "si" => "https://ptb.de/si",
+      }.freeze
+
+      ROOT_ELEMENT = "digitalCalibrationCertificate"
+
+      # Only the canonical URI. `Dcc::Namespace::Dcc` also accepts the
+      # `https://ptb.de/dcc.xsd` alias, but every rule below binds `dcc:` to
+      # the canonical URI, so an alias document would match no xpath: it would
+      # come back unmigrated, reporting nothing, and fail the v3 schema.
+      # Refusing it says so instead of returning a quietly broken document.
+      ROOT_NAMESPACE = NS["dcc"]
+
+      # `performanceLocationType` is an enum and v2 records no location, so
+      # the catch-all is the only truthful value.
+      DEFAULT_PERFORMANCE_LOCATION = "other"
+      DEFAULT_MEASUREMENT_RESULT_NAME = "Measurement result"
+
+      # `byteData`, `descriptionData` and `document` are all typed
+      # `byteDataType`, so all three carry the `data` child v3 renamed.
+      BYTE_DATA_DATA_XPATH = [
+        "//dcc:byteData/dcc:data",
+        "//dcc:descriptionData/dcc:data",
+        "//dcc:document/dcc:data",
+      ].join(" | ").freeze
+
+      # The three elements v2.3.0 types `dcc:hashType`. v3 renamed that type's
+      # `reference`/`referenceID` children, so all three need the rename, not
+      # `previousReport` alone. `linkedReport` is itself a `hashType` child, so
+      # the `//` anchor covers nesting at any depth.
+      #
+      # A fourth `identifier` appears in the file but sits inside the
+      # commented-out `metrologicallyTraceableType` block (v2.3.0
+      # dcc.xsd:325-341), so no valid v2 document can carry it.
+      #
+      # The anchor is what keeps this safe: v2 also declares `reference` under
+      # `equipmentClass` and `statement`, and v3 keeps BOTH of those named
+      # `reference`. An unanchored `//dcc:reference` would corrupt them.
+      HASH_TYPE_PARENTS = %w[previousReport certificate linkedReport].freeze
+
+      HASH_TYPE_REFERENCE_XPATH = HASH_TYPE_PARENTS
+        .map { |parent| "//dcc:#{parent}/dcc:reference" }.join(" | ").freeze
+      HASH_TYPE_REFERENCE_ID_XPATH = HASH_TYPE_PARENTS
+        .map { |parent| "//dcc:#{parent}/dcc:referenceID" }.join(" | ").freeze
+
+      RENAMES = {
+        "//dcc:identification/dcc:description" => "name",
+        "//dcc:influenceCondition/dcc:state" => "status",
+        HASH_TYPE_REFERENCE_XPATH => "referral",
+        HASH_TYPE_REFERENCE_ID_XPATH => "referralID",
+        BYTE_DATA_DATA_XPATH => "dataBase64",
+        "//dcc:formula/dcc:siunitx" => "latex",
+      }.freeze
+
+      # v2 let these `description` elements repeat; v3 allows one.
+      MERGED_DESCRIPTION_PARENTS = %w[
+        software item measuringEquipment usedMethod
+      ].freeze
+
+      # Elements retyped to `notEmptyStringType`, which rejects leading and
+      # trailing whitespace as well as empty values.
+      TRIMMED_ELEMENTS = %w[
+        release model uniqueIdentifier value classID reference norm
+        convention calibrationLaboratoryCode city postCode postOfficeBox
+        state street streetNo eMail phone fax referralID procedure
+        fileName mimeType
+      ].freeze
+
+      # Children a v2.2.1 `si:list` accepts directly; anything else in a v1
+      # list body has to move into a wrapper.
+      LIST_CONTAINER_CHILDREN = %w[
+        label dateTime realList realListXMLList complexList
+        complexListXMLList list
+      ].freeze
+
+      class << self
+        # Every route in `Dcc::Migrate` funnels raw input through here, not
+        # just this transform: this file is the only one sanctioned to parse
+        # XML directly, so the DCC-root check has to live with it.
+        #
+        # @param xml [String] candidate DCC XML.
+        # @return [String] the same XML, when the root is a DCC root.
+        # @raise [Dcc::ParseError] otherwise.
+        def assert_dcc_root(xml)
+          reject_rootless(parse(xml))
+          xml
+        end
+
+        # @param xml [String] DCC v2 XML.
+        # @param to [String] target v3 version for `schemaVersion`.
+        # @param on_loss [#call, nil] receives each loss message (a String)
+        #   instead of the stderr report; nil keeps the `Kernel.warn` report.
+        # @return [String] DCC v3 XML.
+        # @raise [Dcc::ParseError] on malformed XML or a non-DCC root.
+        def call(xml, to:, on_loss: nil)
+          doc = parse(xml)
+          reject_rootless(doc)
+
+          losses = []
+          doc.root["schemaVersion"] = to
+          apply_rules(doc, losses)
+          report(losses, to, on_loss)
+
+          doc.to_xml
+        end
+
+        private
+
+        # Strict, so a truncated or malformed document is refused rather than
+        # silently recovered into a partial one. Nokogiri's default recovery
+        # mode would drop everything after the first syntax error, and the
+        # migration would report no loss for the sections it never saw.
+        def parse(xml)
+          ::Nokogiri::XML(xml, &:strict)
+        rescue ::Nokogiri::XML::SyntaxError => e
+          raise ::Dcc::ParseError,
+                "Dcc::Migrate::V2ToV3 expects well-formed DCC XML: #{e.message}"
+        end
+
+        # Checking the name and namespace, not merely that a root exists: the
+        # target parser builds an empty certificate out of a foreign root
+        # rather than refusing it, so a stray document would otherwise migrate
+        # to a valid-looking but empty v3 result.
+        def reject_rootless(doc)
+          root = doc.root
+          return if root && root.name == ROOT_ELEMENT &&
+            root.namespace&.href == ROOT_NAMESPACE
+
+          raise ::Dcc::ParseError,
+                "Dcc.migrate expects a <dcc:#{ROOT_ELEMENT}> root " \
+                "in the #{ROOT_NAMESPACE} namespace, got " \
+                "#{describe_root(root)}."
+        end
+
+        def describe_root(root)
+          return "input with no root element" unless root
+
+          "<#{root.name}> in #{root.namespace&.href.inspect}"
+        end
+
+        def apply_rules(doc, losses)
+          rename_elements(doc)
+          move_ref_id_to_attribute(doc)
+          add_performance_location(doc)
+          add_measurement_result_names(doc)
+          merge_descriptions(doc, losses)
+          rehome_description_data(doc)
+          trim_not_empty_strings(doc, losses)
+          upgrade_dsi(doc)
+          collect_losses(doc, losses)
+        end
+
+        def rename_elements(doc)
+          RENAMES.each do |xpath, name|
+            doc.xpath(xpath, NS).each { |node| node.name = name }
+          end
+        end
+
+        def move_ref_id_to_attribute(doc)
+          doc.xpath("//dcc:statement/dcc:refId | //dcc:metaData/dcc:refId", NS)
+            .each do |node|
+            node.parent["refId"] = node.text.strip
+            node.remove
+          end
+        end
+
+        def add_performance_location(doc)
+          doc.xpath("//dcc:coreData", NS).each do |core_data|
+            next if core_data.at_xpath("dcc:performanceLocation", NS)
+
+            node = element(doc, "dcc:performanceLocation")
+            node.content = DEFAULT_PERFORMANCE_LOCATION
+            performance_anchor(core_data).add_next_sibling(node)
+          end
+        end
+
+        # `endPerformanceDate` is mandatory in v2, so its absence means the
+        # input is not the v2 document this transform was handed.
+        def performance_anchor(core_data)
+          core_data.at_xpath("dcc:endPerformanceDate", NS) ||
+            raise(::Dcc::ParseError,
+                  "coreData has no endPerformanceDate, so the mandatory v3 " \
+                  "performanceLocation cannot be placed.")
+        end
+
+        def add_measurement_result_names(doc)
+          doc.xpath("//dcc:measurementResult", NS).each do |result|
+            next if result.at_xpath("dcc:name", NS)
+
+            name = result_name(doc)
+            anchor = result.children.first
+            anchor ? anchor.add_previous_sibling(name) : result.add_child(name)
+          end
+        end
+
+        def result_name(doc)
+          name = element(doc, "dcc:name")
+          content = element(doc, "dcc:content")
+          content.content = DEFAULT_MEASUREMENT_RESULT_NAME
+          name.add_child(content)
+          name
+        end
+
+        # v2 `textType` carries an optional `@id` and real documents use it.
+        # Merging removes the ids of descriptions 2..N, so every reference to
+        # one is repointed at the survivor before the element goes away.
+        def merge_descriptions(doc, losses)
+          remap = {}
+          MERGED_DESCRIPTION_PARENTS.each do |parent|
+            doc.xpath("//dcc:#{parent}", NS)
+              .each { |node| merge_parent_descriptions(node, remap, losses) }
+          end
+          repoint_references(doc, remap, losses)
+        end
+
+        def merge_parent_descriptions(node, remap, losses)
+          first, *rest = node.xpath("dcc:description", NS).to_a
+          rest.each do |extra|
+            extra.element_children.each { |child| first.add_child(child) }
+            absorb_id(first, extra, remap, losses)
+            extra.remove
+          end
+        end
+
+        # The survivor ends up holding the removed description's content, so a
+        # reference to the removed id still means the same thing. Adopt the id
+        # outright when the survivor has none.
+        def absorb_id(first, extra, remap, losses)
+          id = extra["id"]
+          return unless id
+
+          first["id"] ||= id
+          return if first["id"] == id
+
+          remap[id] = first["id"]
+          losses << "description/@id=#{id} merged into #{first['id']}"
+        end
+
+        # Without this a `refId` would be left pointing at an id that no
+        # longer exists anywhere in the document.
+        def repoint_references(doc, remap, losses)
+          return if remap.empty?
+
+          doc.xpath("//*[@refId]").each do |node|
+            before = node["refId"].split
+            after = before.map { |token| remap.fetch(token, token) }
+            next if after == before
+
+            node["refId"] = after.join(" ")
+            losses << "#{node.name}/@refId repointed to #{after.join(' ')} " \
+                      "(merged descriptions)"
+          end
+        end
+
+        # v3 dropped `descriptionData`; `richContentType/file` carries the
+        # same `byteDataType` payload.
+        def rehome_description_data(doc)
+          doc.xpath(
+            "//dcc:item/dcc:descriptionData | " \
+            "//dcc:measuringEquipment/dcc:descriptionData", NS
+          ).each do |node|
+            parent = node.parent
+            node.name = "file"
+            description(doc, parent).add_child(node)
+          end
+        end
+
+        def description(doc, parent)
+          parent.at_xpath("dcc:description", NS) ||
+            element(doc, "dcc:description").tap do |node|
+              parent.at_xpath("dcc:name", NS).add_next_sibling(node)
+            end
+        end
+
+        # `notEmptyStringType` rejects surrounding whitespace, so trimming is
+        # required for validity — but it changes a value the author wrote,
+        # which this transform reports rather than doing silently.
+        def trim_not_empty_strings(doc, losses)
+          TRIMMED_ELEMENTS.each do |name|
+            doc.xpath("//dcc:#{name}", NS)
+              .each { |node| trim_node(node, name, losses) }
+          end
+        end
+
+        def trim_node(node, name, losses)
+          return unless node.element_children.empty?
+
+          original = node.text
+          trimmed = original.strip
+          reject_empty(name, original) if trimmed.empty?
+          return if trimmed == original
+
+          node.content = trimmed
+          losses << "#{name} whitespace trimmed to #{trimmed.inspect} " \
+                    "(v3 notEmptyStringType rejects it)"
+        end
+
+        # v2 typed these `xs:string` and accepted an empty or whitespace-only
+        # value; v3's `notEmptyStringType` rejects it and there is nothing
+        # truthful to put in its place.
+        def reject_empty(name, original)
+          raise ::Dcc::UnsupportedMigrationError,
+                "Cannot migrate <dcc:#{name}>#{original}</dcc:#{name}>: v3 " \
+                "types it notEmptyStringType, which rejects an empty or " \
+                "whitespace-only value, and no substitute can be invented."
+        end
+
+        def upgrade_dsi(doc)
+          wrap_uncertainty(doc, "expandedUnc", "expandedMU",
+                           "uncertainty" => "valueExpandedMU")
+          wrap_uncertainty(doc, "coverageInterval", "coverageIntervalMU",
+                           "standardUnc" => "valueStandardMU")
+          wrap_list_bodies(doc)
+          normalize_probabilities(doc)
+        end
+
+        # Only reals OUTSIDE an `si:list`. `realInListType` misspells the
+        # modern wrapper as `measurementUncertaintyUnivaraite` and accepts the
+        # deprecated forms as siblings, so rewriting a list-local uncertainty
+        # to the correct spelling would turn a valid document invalid. Both
+        # deprecated forms stay legal in v2.2.1, so leaving them costs
+        # nothing. `dcc:list` is a different element and does not match.
+        def wrap_uncertainty(doc, legacy_name, modern_name, renames)
+          doc.xpath("//si:real[not(ancestor::si:list)]/si:#{legacy_name}", NS)
+            .each do |legacy|
+            univariate = element(doc, "si:measurementUncertaintyUnivariate")
+            univariate.add_child(
+              modern_uncertainty(doc, legacy, modern_name, renames),
+            )
+            legacy.replace(univariate)
+          end
+        end
+
+        def modern_uncertainty(doc, legacy, modern_name, renames)
+          element(doc, "si:#{modern_name}").tap do |modern|
+            legacy.element_children.each do |child|
+              child.name = renames.fetch(child.name, child.name)
+              modern.add_child(child)
+            end
+          end
+        end
+
+        # v2.2.1 `si:list` is a pure container; a v1 body moves into one
+        # `si:realList` or `si:complexList`.
+        def wrap_list_bodies(doc)
+          doc.xpath("//si:list", NS).each do |list|
+            body = list.element_children.reject do |child|
+              LIST_CONTAINER_CHILDREN.include?(child.name)
+            end
+            next if body.empty?
+
+            wrapper = element(doc, "si:#{list_wrapper_name(body)}")
+            body.each { |child| wrapper.add_child(child) }
+            list.add_child(wrapper)
+          end
+        end
+
+        def list_wrapper_name(body)
+          if body.any? { |child| child.name == "complex" }
+            "complexList"
+          else
+            "realList"
+          end
+        end
+
+        # D-SI v1 accepted `.95`; v2.2.1 requires a leading zero.
+        def normalize_probabilities(doc)
+          doc.xpath("//si:coverageProbability", NS).each do |node|
+            text = node.text.strip
+            node.content = "0#{text}" if text.start_with?(".")
+          end
+        end
+
+        def collect_losses(doc, losses)
+          collect_formula_lang(doc, losses)
+          collect_extra_lab_contacts(doc, losses)
+        end
+
+        def collect_formula_lang(doc, losses)
+          doc.xpath("//dcc:formula[@lang]", NS).each do |node|
+            losses << "formula/@lang=#{node['lang']} " \
+                      "(v3 formulae carry no language)"
+            node.remove_attribute("lang")
+          end
+        end
+
+        def collect_extra_lab_contacts(doc, losses)
+          doc.xpath("//dcc:calibrationLaboratory", NS).each do |lab|
+            extra = lab.xpath("dcc:contact", NS).to_a.drop(1)
+            next if extra.empty?
+
+            extra.each(&:remove)
+            losses << "#{extra.size} extra calibrationLaboratory/contact " \
+                      "(v3 allows one)"
+          end
+        end
+
+        # With an `on_loss` callable the caller owns the loss list: every
+        # message goes to the callable, one call per loss, and nothing is
+        # warned. Without one, the report goes to stderr as before.
+        def report(losses, to, on_loss)
+          return if losses.empty?
+
+          if on_loss
+            losses.each { |loss| on_loss.call(loss) }
+            return
+          end
+
+          Kernel.warn(
+            "Dcc.migrate 2.3.0 to #{to} changed or discarded " \
+            "#{losses.size} construct(s) v3 cannot represent as written: " \
+            "#{losses.join('; ')}",
+          )
+        end
+
+        def element(doc, name)
+          ::Nokogiri::XML::Node.new(name, doc)
+        end
+      end
+    end
+  end
+end

data/lib/dcc/migrate.rb

@@ -1,41 +1,145 @@
 # frozen_string_literal: true
 
-# `Dcc::Migrate` upgrades or downgrades a parsed DCC between schema versions,
-# applying the necessary field renames and D-SI version transitions.
+# `Dcc::Migrate` upgrades a DCC to a newer schema version.
 #
-# Currently a thin shim: serializes the source DCC and re-parses under
-# the target version's context. Future work will add per-field transformations.
+# Migration is a document transform: the route's field rules are applied to
+# the XML and the result is parsed under the target version. The input is
+# never modified.
+#
+# Pass the source XML when you have it. Passing a parsed model instead costs
+# whatever that model could not round-trip, because the model has to be
+# serialised back to XML before the transform can see it — the transform
+# cannot report a construct the parse already dropped.
+#
+# Migrations are one-way. A downgrade cannot preserve the source — v3 adds
+# elements and attributes that no older schema accepts — so downgrading warns
+# and then raises rather than returning a quietly invalid document.
 module Dcc
   module Migrate
+    autoload :Route, "dcc/migrate/route"
+    autoload :V2ToV3, "dcc/migrate/v2_to_v3"
+
     class << self
-      # @param dcc [Lutaml::Model::Serializable]
-      # @param from [String] source version (e.g. "2.3.0").
-      # @param to [String] target version (e.g. "3.3.0").
-      # @return [Dcc::V2::DigitalCalibrationCertificate, Dcc::V3::DigitalCalibrationCertificate]
-      def call(dcc, from:, to:)
-        from_major = ::Dcc::Schema::Version.major(from)
-        to_major = ::Dcc::Schema::Version.major(to)
-        if from_major == to_major
-          # Same major: just rewrite the schemaVersion attribute.
-          return rewrite_schema_version(dcc, to)
-        end
+      # @param input [String, IO, Lutaml::Model::Serializable] DCC source XML,
+      #   or a parsed DCC. Prefer the source XML: see the note on this module.
+      # @param from [String] source version, e.g. "2.3.0".
+      # @param to [String] target version, e.g. "3.3.0".
+      # @param on_loss [#call, nil] callable receiving each loss message (a
+      #   String) the transform would otherwise send to `Kernel.warn`; when
+      #   given, nothing is warned. Nil keeps the stderr report.
+      # @raise [Dcc::UnknownVersionError] if either version is not bundled.
+      # @raise [Dcc::UnsupportedMigrationError] on a downgrade, or on a pair
+      #   whose incompatibilities have not been verified.
+      # @return [Dcc::V2::DigitalCalibrationCertificate,
+      #   Dcc::V3::DigitalCalibrationCertificate] always a parsed DCC.
+      def call(input, from:, to:, on_loss: nil)
+        source = ::Dcc::Schema::Version.resolve_dcc(from)
+        target = ::Dcc::Schema::Version.resolve_dcc(to)
+        return same_version_result(input, target) if source == target
 
-        # Cross-major migration: serialize then re-parse under target.
-        xml = dcc.to_xml
-        target_parser = ::Dcc.parser_for(to_major)
-        target_parser.load_all!
-        migrated = target_parser.parse(xml)
-        rewrite_schema_version(migrated, to)
+        reject_downgrade(source, target)
+        reject_unregistered(source, target)
+
+        transform = Route.for(source, target)
+        xml = source_xml(input)
+        migrated = if transform
+                     transform.call(xml, to: target,
+                                         on_loss: on_loss)
+                   else
+                     xml
+                   end
+        parse_as(migrated, target)
       end
 
       private
 
-      def rewrite_schema_version(dcc, version)
-        return dcc unless Dcc::TypeGuards.has_writer?(dcc, :schema_version)
+      # A same-version call must not round-trip a model through XML: that
+      # would apply the parse loss this transform exists to avoid. The model
+      # is still checked, so the no-op path cannot hand back a non-DCC object
+      # the other paths would have refused.
+      #
+      # The version is checked too. Every other route re-parses under the
+      # target, so its result carries the requested version whatever `from:`
+      # said. This route returns the input untouched, so a mis-declared
+      # `from:` would hand back a document of some other version and make both
+      # parameters meaningless.
+      def same_version_result(input, target)
+        if dcc_document?(input)
+          reject_version_mismatch(input, target)
+          return input
+        end
+
+        parse_as(source_xml(input), target)
+      end
+
+      def reject_version_mismatch(dcc, target)
+        actual = dcc.schema_version
+        return if actual.nil? || actual == target
+
+        raise ::Dcc::Error,
+              "Dcc.migrate was asked for #{target} but the document " \
+              "declares #{actual}."
+      end
+
+      # The one place an input becomes XML, and the one place the DCC root is
+      # checked.
+      #
+      # The root check belongs here rather than in the transform: the
+      # schemaVersion-only and same-version routes never reach a transform,
+      # and any `Serializable` serialises happily, so both would otherwise
+      # turn a foreign document into an empty certificate.
+      def source_xml(input)
+        V2ToV3.assert_dcc_root(raw_xml(input))
+      end
+
+      # `Dcc.read_input` falls through to `to_s` for anything that is not
+      # IO-like, so the parsed-model case has to be answered first.
+      def raw_xml(input)
+        return input.to_xml if input.is_a?(::Lutaml::Model::Serializable)
+
+        reject_untranslatable(input)
+        ::Dcc.read_input(input)
+      end
+
+      # The two DCC root models. Checked by class rather than by serialising
+      # and re-reading, so the same-version no-op stays a no-op.
+      def dcc_document?(input)
+        input.is_a?(::Dcc::V2::DigitalCalibrationCertificate) ||
+          input.is_a?(::Dcc::V3::DigitalCalibrationCertificate)
+      end
+
+      def reject_untranslatable(input)
+        return if input.is_a?(::String) || ::Dcc.io_like?(input)
+
+        raise ::Dcc::Error,
+              "Dcc.migrate expects DCC source XML or a parsed DCC document, " \
+              "got #{input.class}."
+      end
+
+      def reject_downgrade(source, target)
+        return if ::Gem::Version.new(target) > ::Gem::Version.new(source)
+
+        message = "Cannot migrate #{source} to #{target}: downgrading " \
+                  "discards information the older schema cannot represent."
+        Kernel.warn(message)
+        raise ::Dcc::UnsupportedMigrationError, message
+      end
+
+      def reject_unregistered(source, target)
+        return if Route.supported?(source, target)
+
+        raise ::Dcc::UnsupportedMigrationError,
+              "No verified migration from #{source} to #{target}. " \
+              "Supported: #{Route.supported_pairs.join(', ')}."
+      end
 
-        dcc.schema_version = version
-        dcc
+      def parse_as(xml, version)
+        parser = ::Dcc.parser_for(::Dcc::Schema::Version.major(version))
+        parser.load_all!
+        parsed = parser.parse(xml)
+        parsed.schema_version = version
+        parsed
       end
     end
   end
-end
+end