Validate and migrate configurations
===================================

An installed mpylab provides several maintenance tools. All migration tools
perform a dry run unless ``--write`` is supplied.

Complete configuration packages
-------------------------------

``mpylab-config-check`` validates a TOML-inventoried package of DOT, INI, and
DAT files without initializing instruments or opening hardware:

.. code-block:: console

   mpylab-config-check config-checks.toml \
       --json-report config-check-report.json

A finding uses the CI-friendly format
``file:line:column: severity[code]: message``. Checks cover DOT, INI, and DAT
syntax, driver and file references, NPORT data quality, names, and explicitly
declared context and frequency paths. At every explicit frequency, the tool
also checks that each instrument and correction element used by the active
path permits that frequency within its INI ``FSTART`` to ``FSTOP`` range. A
violation is reported as a ``path-frequency-range`` error at the affected
bound line. After domain review, ``--warnings-as-errors`` can promote
data-quality warnings to a failing exit status.

A minimal inventory looks like this:

.. code-block:: toml

   format_version = 1

   [policy]
   lowercase_graph_names = true

   [[graphs]]
   dot = "immunity.dot"
   condition_map = "tem"

   [[graphs.scenarios]]
   name = "gtem"
   context = { mode = "GTEM" }

   [[graphs.scenarios.paths]]
   start = "sg"
   end = "gtem"
   mode = "exactly_one_path"
   values = [80e6, 1e9, 1.000000001e9, 4.2e9]

Values should include boundaries and at least one representative point on
either side of a switch. Local validation and CI invoke the same command.

DOT files
---------

.. code-block:: console

   mpylab-dot-migrate local-config.dot
   mpylab-dot-migrate --check --recursive path/to/configurations

The tool migrates historical condition names, validates syntax, and can check
selected signal paths across a frequency range:

.. code-block:: console

   mpylab-dot-migrate \
       --path Sg:TxAnt \
       --frequency-range 80e6 6e9 \
       --path-mode exactly_one_path \
       local-config.dot

The :doc:`DOT reference <dot>` documents the complete input and condition
semantics.

NPORT configurations
--------------------

.. code-block:: console

   mpylab-nport-migrate local-cable.ini
   mpylab-nport-migrate --check --recursive path/to/configurations

Migration replaces historical ambiguous interpolation settings with separate
frequency, value, and complex options.

Check data quality separately:

.. code-block:: console

   mpylab-nport-check --recursive path/to/configurations \
       --json-report nport-quality.json

The check covers frequency range, support-point spacing, interpolation, and
referenced DAT files. Their syntax, units, and uncertainty declarations are
described in :doc:`instrument-data`.

CI strategy
-----------

A configuration repository should inventory production graphs in a
version-controlled TOML file. Named tables record expected instrument count,
permitted fallbacks, and domain path checks. A generic test can then ensure
that:

* every production DOT file is listed exactly once;
* all INI and DAT references resolve;
* conditions produce unambiguous paths at range boundaries;
* active path devices cover every explicit check frequency;
* new configurations cannot silently bypass validation.

The JSON report can be retained as a pipeline artifact. Neither a passing
package check nor virtual tests demonstrate that addresses, switches,
protection limits, and physical RF paths work correctly at the bench.

Before hardware access
----------------------

A passing syntax check does not replace preflight. Also verify instrument
limits, RF-off, amplifier protection, frequency coverage, output paths, and
autosave resume behavior with the concrete measurement class.