dynamic-systems-testing-framework 1.0.1__py3-none-any.whl

dstf/discovery/test_registry.py

@@ -0,0 +1,488 @@
+"""Orchestrate test discovery: find test models and merge parameters."""
+
+import copy
+import logging
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Optional
+
+from ..config import (
+    DEFAULT_METHOD,
+    DEFAULT_STOP_TIME,
+    DEFAULT_TOLERANCE,
+    Config,
+)
+from .recognizer import RecognizerResult, get_recognizers
+
+if TYPE_CHECKING:
+    from ..comparison.tree_spec import SpecNode
+    from .mo_parser import LocatedClass
+    from .plots import PlotExtra
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TestModel:
+    """A fully resolved test model with all metadata needed for simulation."""
+
+    model_id: str
+    source_file: Path
+    source_package: str
+    short_name: str
+    n_vars: int
+    # The UnitTests component's instance name: its variables are
+    # ``<instance>.x[i]`` in the result file. A test with no such component
+    # (``source == "spec"``) keeps the conventional default, and
+    # ``unit_test_variables`` returns nothing for it, so that default never
+    # ends up naming anything.
+    unit_tests_instance: str = "unitTests"
+    x_expressions: list[str] = field(default_factory=list)
+    x_raw: str = ""
+    x_reference: list[float] | None = None
+    error_expected: float = 1e-6
+    # Simulation fields default to None = "not set by any source" so the
+    # spec-over-annotation merge can use `is not None` as the explicitly-set
+    # sentinel, exactly like number_of_intervals / output_interval — review
+    # 2026-07-06 finding 13: equality-with-default sentinels silently dropped
+    # a spec value that happened to equal the framework default. During
+    # discovery they may be None; ``finalize_defaults()`` (called at the end
+    # of discover_tests) resolves them to the framework defaults so
+    # downstream consumers (backends, reporters, storage) only ever see
+    # concrete values.
+    stop_time: float | None = None
+    tolerance: float | None = None
+    method: str | None = None
+    number_of_intervals: int | None = None
+    output_interval: float | None = None
+    result_file: str = ""
+    timeout: int | None = None  # Per-test timeout override (seconds)
+
+    # External spec: variable patterns (may include globs like "medium.T*" or "*")
+    # These are resolved against actual .mat variable names after simulation.
+    variable_patterns: list[str] = field(default_factory=list)
+
+    # Comparison settings (per-test and per-variable overrides)
+    #: Overrides config.tolerance. As the spec wrote it: a value that is no
+    #: number is carried to ``compare_test``, which refuses the test.
+    comparison_tolerance: Any = None
+    variable_overrides: dict[str, dict] = field(default_factory=dict)
+    # variable_overrides format: {"var_name": {"tolerance": 0.1}, ...}
+
+    # Phase 3.2: optional user-authored MetricTree spec from test_spec.json
+    # under the "metrics" key. When set, Phase 3.3+ will use this in place
+    # of the implicit flat-AND. Parse-only today — no behavior gated on it.
+    metric_tree_spec: Optional["SpecNode"] = None
+
+    # The entry's optional ``plots`` extras (`discovery.plots`): context
+    # series and watch plots beside the plots derived from the tree. None
+    # when the key is absent, ``()`` for ``[]`` — both mean no extras.
+    plots: tuple["PlotExtra", ...] | None = None
+
+    # The entry's own ``baseline_points`` (D153): ``"all"`` or a whole number
+    # of 2 or more — the points this test's stored baseline keeps of its
+    # run. None when the entry has no such key: the project's applies
+    # (``Config.baseline_points``).
+    baseline_points: int | str | None = None
+
+    # PTA.4 — richer-contract fields settable via recognizers. Additive;
+    # defaults preserve pre-PTA behavior.
+    #
+    # simulate_only: a recognizer's MARK — the test passes iff the simulation
+    # completes without error, whatever it declares, and no criterion staged
+    # on it is ever scored. What a reader asks is `is_simulate_only`, which
+    # is also true of a test that declares nothing to score.
+    simulate_only: bool = False
+    # requested_baselines: names of additional baselines to produce for this
+    # test (e.g., ["dymola-via-fmpy"]). Placeholder for 4.B.
+    requested_baselines: list[str] = field(default_factory=list)
+
+    # Per-field provenance: where the value came from.
+    # Keys: "stop_time", "tolerance", "method", "number_of_intervals",
+    # "output_interval". Values: "annotation", "test_spec", "default".
+    # Populated during recognizer + spec merge so the dashboard's
+    # resolution-explainer column can show "stop_time: 10 (annotation)".
+    field_sources: dict[str, str] = field(default_factory=dict)
+
+    # Where this test was defined: "unit_tests", "spec", "both"
+    source: str = "unit_tests"
+
+    @property
+    def is_simulate_only(self) -> bool:
+        """Whether the test passes iff its simulation completes — THE one
+        rule: a recognizer marked it (``simulate_only``), or it DECLARES
+        nothing to score: no UnitTests variable, no ``variables`` pattern,
+        no ``metrics`` tree and no ``comparison.variable_overrides`` entry.
+        That is the entry ``dstf add <model>`` writes (``"variables": []``),
+        which has no key of its own for it.
+
+        An override is a declaration: whoever wrote ``{"x": {"mode":
+        "range", ...}}`` asked for ``x`` to be checked. On an entry that
+        tracks nothing it scores nothing — an override changes how a TRACKED
+        variable is scored — and such a test passed, simulate-only, with no
+        word of the bound it never read.
+
+        Not the test that declares variables and whose result holds none of
+        them, nor the one whose overrides are all it declares: each scored
+        nothing it asked about, and fails
+        (``comparison.comparator.nothing_scored``)."""
+        from .unit_tests import unit_test_variables
+
+        if self.simulate_only:
+            return True
+        return (
+            not unit_test_variables(self)
+            and not self.variable_patterns
+            and self.metric_tree_spec is None
+            and not self.variable_overrides
+        )
+
+    def finalize_defaults(self) -> "TestModel":
+        """Resolve unset (None) simulation fields to framework defaults.
+
+        Called once, at the END of discover_tests — review 2026-07-06
+        finding 13: only the merge logic distinguishes "unset" (None) from
+        "explicitly the default value"; everything downstream sees concrete
+        values. Also stamps provenance "default" for the five sim fields no
+        source set (finding 57: spec-only tests used to claim "test_spec"
+        provenance for pure framework defaults).
+        """
+        if self.stop_time is None:
+            self.stop_time = DEFAULT_STOP_TIME
+        if self.tolerance is None:
+            self.tolerance = DEFAULT_TOLERANCE
+        if self.method is None:
+            self.method = DEFAULT_METHOD
+        for fname in (
+            "stop_time",
+            "tolerance",
+            "method",
+            "number_of_intervals",
+            "output_interval",
+        ):
+            self.field_sources.setdefault(fname, "default")
+        return self
+
+
+def _build_test_model_from_recognizer_results(
+    model_id: str,
+    results: list[RecognizerResult],
+) -> TestModel:
+    """Merge per-recognizer results for one model into a TestModel.
+
+    Later results override earlier ones per-field. The bundled recognizer
+    registers first; user-provided recognizers (PTA.3) append, so user values
+    win on conflicts. Fields no recognizer set fall back to TestModel's
+    dataclass defaults.
+
+    The UnitTests variables are the ones a recognizer DECLARED: ``n_vars``
+    when one gave it, else as many as the expressions one gave, else none.
+    A test recognized by something other than the component (``extends
+    *Icons.Example``) has no ``<instance>.x[i]``, and a default of one made
+    every run look for ``unitTests.x[1]`` in its result and warn.
+    """
+    parts = model_id.rsplit(".", 1)
+    source_package = parts[0] if len(parts) > 1 else ""
+    short_name = parts[-1]
+
+    model = TestModel(
+        model_id=model_id,
+        source_file=Path(""),
+        source_package=source_package,
+        short_name=short_name,
+        n_vars=0,
+        result_file=short_name,
+    )
+
+    counted = False
+    for r in results:
+        if r.source_file is not None:
+            model.source_file = r.source_file
+        if r.n_vars is not None:
+            model.n_vars = r.n_vars
+            counted = True
+        if r.unit_tests_instance:
+            model.unit_tests_instance = r.unit_tests_instance
+        if r.x_expressions:
+            model.x_expressions = list(r.x_expressions)
+        if r.x_raw:
+            model.x_raw = r.x_raw
+        if r.x_reference is not None:
+            model.x_reference = list(r.x_reference)
+        if r.error_expected is not None:
+            model.error_expected = r.error_expected
+        if r.stop_time is not None:
+            model.stop_time = r.stop_time
+            model.field_sources["stop_time"] = "annotation"
+        if r.tolerance is not None:
+            model.tolerance = r.tolerance
+            model.field_sources["tolerance"] = "annotation"
+        if r.method is not None:
+            model.method = r.method
+            model.field_sources["method"] = "annotation"
+        if r.number_of_intervals is not None:
+            model.number_of_intervals = r.number_of_intervals
+            model.field_sources["number_of_intervals"] = "annotation"
+        if r.output_interval is not None:
+            model.output_interval = r.output_interval
+            model.field_sources["output_interval"] = "annotation"
+        if r.simulate_only is not None:
+            model.simulate_only = r.simulate_only
+        if r.requested_baselines is not None:
+            model.requested_baselines = list(r.requested_baselines)
+
+    if not counted:
+        model.n_vars = len(model.x_expressions)
+    return model
+
+
+def scan_source_tests(
+    config: Config, progress: Callable[[int, int], None] | None = None
+) -> dict[str, TestModel]:
+    """Step 1 of discovery: recognizer results over the source tree, keyed
+    by model_id. Empty unless ``source_type == "modelica"``. ``progress(done,
+    total)`` is called after each ``.mo`` file is scanned."""
+    if config.source_type != "modelica":
+        return {}
+    return scan_files(config, sorted(config.library_dir.rglob("*.mo")), progress)
+
+
+def scan_files(
+    config: Config,
+    files: Iterable[Path],
+    progress: Callable[[int, int], None] | None = None,
+) -> dict[str, TestModel]:
+    """The tests the recognizers find in ``files`` of a Modelica library,
+    keyed by model_id: :func:`scan_source_tests` over every ``.mo`` file of
+    it. ``progress(done, total)`` is called after each file."""
+    # Trigger bundled-recognizer registration on first call.
+    from . import mo_parser  # noqa: F401
+
+    # Bundled recognizers come from the module-level registry (filtered by
+    # config.disabled_bundled); user-provided recognizers from config.recognizers
+    # append, so user values win on per-field merge in
+    # _build_test_model_from_recognizer_results.
+    library_dir = config.library_dir
+    bundled = [
+        r for r in get_recognizers("modelica") if r.name not in config.disabled_bundled
+    ]
+    user = [r for r in config.recognizers if "modelica" in r.applies_to]
+    recognizers = bundled + user
+
+    files = list(files)
+    per_model: dict[str, list[RecognizerResult]] = {}
+    for done, mo_file in enumerate(files, start=1):
+        for recognizer in recognizers:
+            if not recognizer.applies_to_path(mo_file, library_dir):
+                continue
+            result = recognizer.recognize(mo_file)
+            if result is not None:
+                per_model.setdefault(result.model_id, []).append(result)
+        if progress is not None:
+            progress(done, len(files))
+
+    return {
+        model_id: _build_test_model_from_recognizer_results(model_id, results)
+        for model_id, results in per_model.items()
+    }
+
+
+def spec_tests_by_model(models: list[TestModel]) -> dict[str, TestModel]:
+    """Step 2: the spec's models keyed by model_id, first entry wins on a
+    duplicate (matching patch_apply / the spec edit helpers), with a warning."""
+    spec_tests: dict[str, TestModel] = {}
+    for test in models:
+        # review 2026-07-06 finding 51: duplicate model entries — FIRST
+        # wins (matching patch_apply / the spec edit helpers), with a
+        # warning. Last-wins here made applied patches silently
+        # ineffective (they edit the first entry).
+        if test.model_id in spec_tests:
+            logger.warning(
+                "test_spec has duplicate entries for model '%s'; "
+                "using the first — remove the duplicates",
+                test.model_id,
+            )
+            continue
+        spec_tests[test.model_id] = test
+    return spec_tests
+
+
+#: The simulation fields an ``experiment(...)`` annotation can give.
+_SIMULATION_FIELDS = (
+    "stop_time",
+    "tolerance",
+    "method",
+    "number_of_intervals",
+    "output_interval",
+)
+
+
+class SpecModelLocator:
+    """Finds the model of a test that only ``test_spec.json`` declares: its
+    file and its ``experiment(...)`` annotation
+    (:func:`~.mo_parser.find_class`), which :func:`merge_tests` fills the
+    entry's unset simulation fields from.
+
+    Modelica sources only — any other source type has no annotation to
+    read, and every ask answers None.
+
+    Each model is looked for ONCE per locator, a miss included: the
+    authoring Session re-merges on every edit of the spec, and on a slow
+    mount the probes for a few spec-only models are not something to repeat
+    at every keystroke. A locator therefore shows a model file as it was
+    when first asked; whoever holds one replaces it when the library is
+    scanned again, or takes one that knows better (:meth:`having`) when it
+    read a model's file again itself.
+    """
+
+    def __init__(self, config: Config):
+        self._config = config
+        self._found: dict[str, LocatedClass | None] = {}
+
+    def having(self, found: Mapping[str, "LocatedClass"]) -> "SpecModelLocator":
+        """A locator that answers *found* for those models and, for every
+        other, what this one has found so far (and looks for the rest)."""
+        other = SpecModelLocator(self._config)
+        other._found = {**self._found, **found}
+        return other
+
+    def __call__(self, model_id: str) -> "LocatedClass | None":
+        if self._config.source_type != "modelica":
+            return None
+        if model_id not in self._found:
+            from .mo_parser import find_class
+
+            config = self._config
+            assert config.library_name is not None  # resolved in __post_init__
+            self._found[model_id] = find_class(
+                config.library_dir, config.library_name, model_id
+            )
+        return self._found[model_id]
+
+
+def _fill_from_model(test: TestModel, located: "LocatedClass") -> None:
+    """Give a spec-only ``test`` what its model says: the file, and every
+    simulation field the entry left unset that the model's ``experiment``
+    annotation sets — the two-layer contract a scanned test already gets
+    (docs/usage.md). The entry's own ``simulation.*`` and ``source`` stay."""
+    if test.source_file == Path(""):
+        test.source_file = located.mo_file
+    experiment = located.experiment
+    if experiment is None:
+        return
+    for name in _SIMULATION_FIELDS:
+        value = getattr(experiment, name)
+        if getattr(test, name) is None and value is not None:
+            setattr(test, name, value)
+            test.field_sources[name] = "annotation"
+
+
+def merge_tests(
+    scanned: dict[str, TestModel],
+    spec_tests: dict[str, TestModel],
+    *,
+    locate: Callable[[str], "LocatedClass | None"] | None = None,
+) -> list[TestModel]:
+    """Step 3: union by model_id; the spec wins per field. Copies both
+    inputs, so a caller (the authoring Session) can keep one scan and
+    re-merge it against every edit of the spec.
+
+    ``locate`` finds the model of an entry the scan did not recognize
+    (:class:`SpecModelLocator`); such a test takes its model's file and
+    annotation. Without it a spec-only entry is taken as written."""
+    merged: dict[str, TestModel] = {
+        model_id: copy.deepcopy(test) for model_id, test in scanned.items()
+    }
+
+    # Merge spec tests. Two-layer contract (docs/usage.md): the model's
+    # experiment(...) annotation provides defaults; any field set in
+    # simulation.* overrides it. DECISION (review 2026-07-06 finding 13):
+    # "explicitly set in the spec" is `is not None` for ALL five sim fields —
+    # never equality with a framework default, which silently dropped a spec
+    # value like stop_time=1.0 against experiment(StopTime=100). Framework
+    # defaults are applied only afterwards, by finalize_defaults() below.
+    for model_id, spec_test in spec_tests.items():
+        spec_test = copy.deepcopy(spec_test)
+        if model_id in merged:
+            existing = merged[model_id]
+            existing.variable_patterns = spec_test.variable_patterns
+            existing.source = "both"
+            if spec_test.stop_time is not None:
+                existing.stop_time = spec_test.stop_time
+                existing.field_sources["stop_time"] = "test_spec"
+            if spec_test.tolerance is not None:
+                existing.tolerance = spec_test.tolerance
+                existing.field_sources["tolerance"] = "test_spec"
+            if spec_test.method is not None:
+                existing.method = spec_test.method
+                existing.field_sources["method"] = "test_spec"
+            if spec_test.number_of_intervals is not None:
+                existing.number_of_intervals = spec_test.number_of_intervals
+                existing.field_sources["number_of_intervals"] = "test_spec"
+            if spec_test.output_interval is not None:
+                existing.output_interval = spec_test.output_interval
+                existing.field_sources["output_interval"] = "test_spec"
+            if spec_test.comparison_tolerance is not None:
+                existing.comparison_tolerance = spec_test.comparison_tolerance
+            if spec_test.variable_overrides:
+                existing.variable_overrides.update(spec_test.variable_overrides)
+            if spec_test.timeout is not None:
+                existing.timeout = spec_test.timeout
+            if spec_test.metric_tree_spec is not None:
+                existing.metric_tree_spec = spec_test.metric_tree_spec
+            if spec_test.plots is not None:
+                existing.plots = spec_test.plots
+            if spec_test.baseline_points is not None:
+                existing.baseline_points = spec_test.baseline_points
+        else:
+            # Provenance for spec-set fields was stamped by parse_test_spec;
+            # unset fields get "default" in finalize_defaults — review
+            # 2026-07-06 finding 57 (the old blanket "test_spec" stamp lied).
+            located = locate(model_id) if locate is not None else None
+            if located is not None:
+                _fill_from_model(spec_test, located)
+            merged[model_id] = spec_test
+
+    # Sort by model_id for consistent ordering; resolve remaining None sim
+    # fields to framework defaults so downstream code never sees None
+    # (finding 13 decision: apply-defaults-at-end-of-merge).
+    tests = sorted(merged.values(), key=lambda t: t.model_id)
+    for test in tests:
+        test.finalize_defaults()
+    return tests
+
+
+def discover_tests(config: Config) -> list[TestModel]:
+    """Discover all test models from registered recognizers and/or external spec.
+
+    Sources (merged by model_id):
+    1. Source-file recognizers (PTA.1+) — for ``source_type == "modelica"``,
+       walks ``*.mo`` and runs every registered Modelica recognizer. Bundled
+       default is the ``UnitTests`` + ``experiment(...)`` recognizer; user-
+       provided recognizers (PTA.3) layer on top.
+    2. External test_spec.json (the configured file, else
+       ``<reference_root>/test_spec.json`` when it exists; overrides
+       recognizer values). A model only the spec names is looked up in the
+       library (:class:`SpecModelLocator`) for its file and its
+       ``experiment`` annotation.
+
+    When a model appears in both recognizers and spec, variable patterns
+    from the spec are added alongside the recognizer-derived variables, and
+    the source is marked as "both". Spec simulation parameters override
+    recognizer values when explicitly set.
+
+    The three steps are separable: the authoring Session keeps one
+    :func:`scan_source_tests` result and re-runs :func:`merge_tests` against
+    its in-memory spec document on every edit.
+    """
+    scanned = scan_source_tests(config)
+    if config.spec_path.exists():
+        from .spec_parser import parse_test_spec
+
+        models = parse_test_spec(config.spec_path)
+    else:
+        models = []
+    return merge_tests(
+        scanned, spec_tests_by_model(models), locate=SpecModelLocator(config)
+    )

dstf/discovery/unit_tests.py

@@ -0,0 +1,95 @@
+"""The one place a UnitTests component's variables are named.
+
+A variable's NAME is the one it has in the result file —
+``<instance>.x[i]``. The text the model wrote in ``x={...}`` is its
+EXPRESSION: a label that rides beside the name, never a key. The
+backends that extract a result, and the variable filter OpenModelica
+simulates under, ask here rather than spelling ``unitTests.x[i]``
+themselves.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .test_registry import TestModel
+
+
+#: The array the component tracks, ``x={...}`` (see :func:`unit_test_variables`).
+_ARRAY = "x"
+
+
+def unit_test_name(instance: str, index: int) -> str:
+    """``<instance>.x[i]`` — the result-file name of element ``index``."""
+    return f"{instance}.{_ARRAY}[{index}]"
+
+
+def is_unit_test_variable(test: TestModel, name: str) -> bool:
+    """Whether ``name`` is an element of the test's UnitTests component,
+    ``<instance>.x[i]`` — declared through the component or tracked by that
+    name. Each is its own test quantity, whatever its expression reads as,
+    so no plot folds it into a family with another (the owner's ruling O3,
+    2026-09-28)."""
+    head = f"{test.unit_tests_instance}.{_ARRAY}["
+    # ASCII digits: `str.isdigit` takes `²` and `١` for one too
+    return (
+        name.startswith(head)
+        and name.endswith("]")
+        and re.fullmatch(r"[0-9]+", name[len(head) : -1]) is not None
+    )
+
+
+@dataclass(frozen=True)
+class UnitTestVariable:
+    """One tracked variable of the component: its result-file name and the
+    expression the model wrote for it (``""`` when nothing said which
+    expression belongs to which index)."""
+
+    name: str
+    expression: str
+
+
+def unit_test_variables(test: TestModel) -> list[UnitTestVariable]:
+    """The component's variables in index order, empty for a test with no
+    such component (``source == "spec"``, or no variables declared).
+
+    The component is assumed to name its tracked array ``x`` — the bundled
+    one does, and a custom component reached through a JSON recognizer is
+    taken to follow it.
+
+    The expression is ``x_expressions[i - 1]`` when the model wrote one per
+    variable, and ``f"{x_expressions[0]}[{i}]"`` when it wrote a SINGLE
+    expression covering all of them — an array (``x=y``) or a concatenation
+    (``x=cat(1, a, b)``), whose element ``i`` reads as ``y[i]`` /
+    ``cat(1, a, b)[i]``.
+
+    Any other shape leaves the expression ``""``: two expressions for three
+    variables says nothing about which piece is which, and a wrong label is
+    worse than none.
+    """
+    if test.source not in ("unit_tests", "both") or test.n_vars <= 0:
+        return []
+    exprs = test.x_expressions
+    out: list[UnitTestVariable] = []
+    for i in range(1, test.n_vars + 1):
+        if len(exprs) == test.n_vars:
+            expression = exprs[i - 1]
+        elif len(exprs) == 1:
+            expression = f"{exprs[0]}[{i}]"
+        else:
+            expression = ""
+        out.append(
+            UnitTestVariable(unit_test_name(test.unit_tests_instance, i), expression)
+        )
+    return out
+
+
+__all__ = [
+    "UnitTestVariable",
+    "is_unit_test_variable",
+    "unit_test_name",
+    "unit_test_variables",
+]

dstf/figures/__init__.py

@@ -0,0 +1,14 @@
+"""One figure layer, two consumers.
+
+A :class:`~.view.VariableView` is everything a plot of one variable needs —
+trajectories, overlays, the leaves that target it with their geometry and
+summaries, the error series — assembled the same way by the HTML report
+and by the authoring tool. :func:`~.plotly.variable_figure` renders it to a
+plain Plotly figure dict (``data`` / ``layout`` / ``config``), with no
+``plotly.py`` dependency; the report embeds the dict, the tool hands it to
+its plotly element. :func:`~.plotly.plot_figure` renders a plot of SEVERAL
+views the same way — array families in one hue ramp (:mod:`.families`) —
+and is ``variable_figure`` itself when a plot holds one. Nothing here knows
+a mode name: drawing is keyed on primitive type
+(:mod:`dstf.comparison.geometry`).
+"""

dstf/figures/assemble.py

@@ -0,0 +1,48 @@
+"""From a comparison and a trajectory to a VariableView — the assembly the
+report's figure build and the authoring Session's ``view`` share."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ..comparison.types import VariableComparison
+from .view import VariableView, build_view
+
+LeafPair = tuple[str, VariableComparison]
+
+
+def leaves_by_variable(metric_tree) -> dict[str, list[LeafPair]]:
+    """Every scored leaf, keyed by the variable it scores, as the
+    ``(leaf_path, comparison)`` pairs ``build_view`` takes. Empty for
+    ``None``."""
+    from ..comparison.tree_eval import leaf_comparisons_by_path
+
+    out: dict[str, list[LeafPair]] = {}
+    if metric_tree is None:
+        return out
+    for path, vc in leaf_comparisons_by_path(metric_tree).items():
+        out.setdefault(vc.name, []).append((path, vc))
+    return out
+
+
+def view_from_trajectory(
+    name: str, trajectory: dict, leaves: Sequence[LeafPair]
+) -> VariableView:
+    """The view for one variable from a report-shaped trajectory entry
+    (``act_time`` / ``act_values`` / ``ref_time`` / ``ref_values`` /
+    ``text`` / ``overlays``, any of them absent).
+
+    The view's label is the trajectory's ``text`` — what the test's page
+    reads for the variable — not its ``label``: the plain label belongs to
+    the surfaces that show the muted name beside it, and a figure's legend
+    and hover show no name."""
+    return build_view(
+        name,
+        label=trajectory.get("text") or trajectory.get("label") or name,
+        act_time=trajectory.get("act_time"),
+        act_values=trajectory.get("act_values"),
+        ref_time=trajectory.get("ref_time"),
+        ref_values=trajectory.get("ref_values"),
+        overlays=trajectory.get("overlays") or [],
+        leaves=leaves,
+    )