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

dstf/discovery/recognizer.py

@@ -0,0 +1,103 @@
+"""Pluggable test-recognition system.
+
+A ``Recognizer`` inspects a source file (a Modelica ``.mo``, an FMU, a Julia
+script, ...) and emits a ``RecognizerResult`` describing a test it found.
+Discovery runs every registered recognizer that applies to the configured
+``source_type`` and merges results by ``model_id``. This lets users layer
+their own test-tagging conventions on top of (or in place of) the bundled
+defaults — a library that can't adopt the bundled ``UnitTests`` component
+provides its own recognizer (PTA.2 onward: via a JSON map) instead.
+
+PTA.1 wires the registry; only the bundled recognizer registers today, so
+behavior is identical to the pre-PTA hardcoded path.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class RecognizerResult:
+    """One recognizer's contribution toward a ``TestModel`` for one source file.
+
+    Fields left ``None`` / empty are not contributed by this recognizer; the
+    framework defaults fill them in (or another recognizer overrides, when
+    multiple recognizers emit for the same ``model_id``).
+
+    The shape today mirrors what the bundled Modelica recognizer extracts.
+    PTA.4 broadens this with runtime-behavior fields (``simulate_only``,
+    ``requested_baselines``, ...).
+    """
+
+    model_id: str
+    source_file: Path | None = None
+    # Variables-to-track contribution (was UnitTestInfo)
+    n_vars: int | None = None
+    # Instance name of the component whose ``x[i]`` the variables are: the
+    # result file names them ``<instance>.x[i]``. Contributed by a recognizer
+    # that takes those variables out of a matched component — their count
+    # (``n_vars``) or their expressions, either one; a recognizer that
+    # contributes neither leaves it None and the conventional default stands.
+    unit_tests_instance: str | None = None
+    x_expressions: list[str] = field(default_factory=list)
+    x_raw: str = ""
+    x_reference: list[float] | None = None
+    error_expected: float | None = None
+    # Simulation-parameters contribution (was ExperimentInfo)
+    stop_time: float | None = None
+    tolerance: float | None = None
+    method: str | None = None
+    number_of_intervals: int | None = None
+    output_interval: float | None = None
+    # PTA.4 — richer-contract runtime-behavior fields. Recognizers can set
+    # these; TestModel carries them through. Consumed by PTA.5 (simulate_only)
+    # and 4.B's cross-backend chain (requested_baselines).
+    simulate_only: bool | None = None
+    requested_baselines: list[str] | None = None
+
+
+class Recognizer(ABC):
+    """Base class for source-file recognizers."""
+
+    #: Unique recognizer name; used in diagnostics and as a registry key.
+    name: str = "<unnamed>"
+    #: ``Config.source_type`` values this recognizer applies to.
+    applies_to: frozenset[str] = frozenset()
+
+    @abstractmethod
+    def recognize(self, source_file: Path) -> RecognizerResult | None:
+        """Inspect a source file. Return a result if a test is recognized, else None."""
+        ...
+
+    def applies_to_path(self, source_file: Path, base: Path) -> bool:
+        """Optional pre-filter: return False to skip the file before recognize().
+
+        Default: True (no filtering). Subclasses can override to honor a
+        per-recognizer paths_include / paths_exclude config (PTA-follow.1).
+        """
+        return True
+
+
+# Registration-ordered list. The bundled recognizer registers first on import;
+# user-provided recognizers (PTA.3) append, and discovery's per-model merge
+# applies later writers as overrides — bundled defaults, user values win.
+_REGISTRY: list[Recognizer] = []
+
+
+def register(recognizer: Recognizer) -> None:
+    """Add a recognizer to the registry (idempotent on identity)."""
+    if recognizer not in _REGISTRY:
+        _REGISTRY.append(recognizer)
+
+
+def get_recognizers(source_type: str) -> list[Recognizer]:
+    """Return registered recognizers that apply to ``source_type``."""
+    return [r for r in _REGISTRY if source_type in r.applies_to]
+
+
+def _reset_for_tests() -> None:
+    """Clear the registry — only for unit tests that need a clean slate."""
+    _REGISTRY.clear()

dstf/discovery/scan_cache.py

@@ -0,0 +1,154 @@
+"""The source scan, cached across tool restarts (brief §3.8).
+
+Under ``$XDG_CACHE_HOME/dstf/scan/`` (default ``~/.cache/dstf/scan/``),
+one JSON file per (library path, recognizer set) — a file another DSTF
+version, or other discovery code, wrote is ignored and replaced — never in
+the work dir, which is a run's artifact directory that other tools read,
+and never validated per file: on a 9P mount (``/mnt/d``) a ``stat`` sweep
+over TRANSFORM's 3 269 ``.mo`` files measured 27 s, longer than parsing
+them. The Session opens from the cache and rescans in the background.
+Only ``source_type == "modelica"`` scans anything, so only those cache.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import functools
+import hashlib
+import json
+import logging
+import os
+import threading
+from pathlib import Path
+
+from .. import __version__
+from ..config import Config
+from . import (
+    mo_parser,  # noqa: F401  — registers the bundled recognizer; the key names it
+)
+from .recognizer import get_recognizers
+from .test_registry import TestModel
+
+logger = logging.getLogger(__name__)
+
+# The FORMAT of a cache file. What a scan MEANS — what the parser extracts
+# and how it spells it — is not versioned by hand: see _discovery_digest.
+CACHE_VERSION = 2
+
+#: The modules that decide what a scan produces. A cache holds parsed
+#: ``TestModel``s, so a change to any of them can make a cached entry mean
+#: something the current code would never have written, and no source file
+#: changed for a staleness check to see. Bumping a constant by hand is a
+#: step people forget — twice already, once for the instance name and once
+#: for expression whitespace — so the code itself is the version.
+_DISCOVERY_SOURCES = (
+    "json_recognizer.py",
+    "mo_parser.py",
+    "recognizer.py",
+    "test_registry.py",
+    "unit_tests.py",
+)
+
+
+@functools.lru_cache(maxsize=1)
+def _discovery_digest() -> str:
+    """A digest of the discovery code's source bytes.
+
+    Read once per process: these files do not change under a running tool,
+    and a warm ``dstf author`` open asks for this before anything else.
+    """
+    here = Path(__file__).parent
+    h = hashlib.sha256()
+    for name in _DISCOVERY_SOURCES:
+        h.update(name.encode("utf-8"))
+        try:
+            h.update((here / name).read_bytes())
+        except OSError as e:  # a zipped / stripped install: fall back
+            logger.warning("cannot digest the discovery source %s: %s", name, e)
+            h.update(b"<unreadable>")
+    return h.hexdigest()[:16]
+
+
+def cache_dir() -> Path:
+    root = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(root) / "dstf" / "scan"
+
+
+def _key(config: Config) -> str:
+    recognizers = sorted(
+        r.name
+        for r in get_recognizers("modelica")
+        if r.name not in config.disabled_bundled
+    ) + sorted(r.name for r in config.recognizers if "modelica" in r.applies_to)
+    payload = json.dumps(
+        [str(config.library_dir.resolve()), recognizers, CACHE_VERSION], sort_keys=True
+    )
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:24]
+
+
+def _path(config: Config) -> Path:
+    return cache_dir() / f"{_key(config)}.json"
+
+
+def _to_json(test: TestModel) -> dict:
+    if test.metric_tree_spec is not None:
+        raise ValueError(f"{test.model_id}: a scanned test carries no metric tree")
+    data = dataclasses.asdict(test)
+    data["source_file"] = str(test.source_file)
+    return data
+
+
+def _from_json(data: dict) -> TestModel:
+    data = dict(data)
+    data["source_file"] = Path(data["source_file"])
+    return TestModel(**data)
+
+
+def load_scan(config: Config) -> dict[str, TestModel] | None:
+    """The cached scan for ``config``, or None (no cache, another DSTF
+    version, other discovery code, unreadable, or not a Modelica source)."""
+    if config.source_type != "modelica":
+        return None
+    path = _path(config)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if data.get("dstf_version") != __version__:
+            return None
+        if data.get("discovery_digest") != _discovery_digest():
+            return None
+        return {m: _from_json(d) for m, d in data["tests"].items()}
+    except FileNotFoundError:
+        return None
+    except (OSError, ValueError, TypeError, KeyError) as e:
+        logger.warning("ignoring the scan cache %s: %s", path, e)
+        return None
+
+
+def store_scan(config: Config, scanned: dict[str, TestModel]) -> Path | None:
+    """Write the scan; returns the path, or None for a non-Modelica source
+    or when the cache cannot be written (a read-only home, a full disk).
+    The cache is an accelerator: a failed write is a warning, never an
+    error — an open that cannot cache still opens, and a rescan that cannot
+    cache still re-merges and finishes."""
+    if config.source_type != "modelica":
+        return None
+    path = _path(config)
+    payload = {
+        "dstf_version": __version__,
+        "discovery_digest": _discovery_digest(),
+        "library_dir": str(config.library_dir.resolve()),
+        "tests": {m: _to_json(t) for m, t in scanned.items()},
+    }
+    # Unique per thread as well as per process: a cached open's rescan
+    # thread and a second Session's in the same process write the same
+    # key, and with one name the second write replaced the first's file
+    # from under it and its own rename failed.
+    tmp = path.with_name(f"{path.stem}.{os.getpid()}.{threading.get_ident()}.tmp")
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp.write_text(json.dumps(payload), encoding="utf-8", newline="\n")
+        os.replace(tmp, path)
+    except OSError as e:
+        logger.warning("not caching the scan at %s: %s", path, e)
+        return None
+    return path