release: freeze RC-05-RC-08 closeout candidate

test_support/__init__.py

@@ -0,0 +1 @@
+"""Shared helpers for deterministic test infrastructure."""

test_support/external_qa.py

@@ -0,0 +1,55 @@
+"""Explicit gate for historical QA evidence kept outside release source."""
+from __future__ import annotations
+
+import os
+from pathlib import Path, PurePosixPath
+
+import pytest
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+QA_ROOT = (REPO_ROOT / "docs/qa").resolve()
+REQUIRE_EXTERNAL_QA_ENV = "YUQEI_REQUIRE_EXTERNAL_QA_EVIDENCE"
+
+
+def _enabled(value: str | None) -> bool:
+    return (value or "").strip().casefold() in {"1", "true", "yes", "on"}
+
+
+def _safe_relative(value: str) -> Path:
+    pure = PurePosixPath(value)
+    if pure.is_absolute() or not pure.parts or any(part in {"", ".", ".."} for part in pure.parts):
+        raise ValueError("external QA evidence paths must be non-empty relative paths")
+    return Path(*pure.parts)
+
+
+def require_external_qa(
+    *relative_files: str,
+    allow_module_level: bool = False,
+    root: Path | None = None,
+) -> Path:
+    """Return the QA root or explicitly skip/fail when required files are absent.
+
+    A dedicated evidence job restores the archived ``docs/qa`` mirror into an
+    isolated checkout and sets ``YUQEI_REQUIRE_EXTERNAL_QA_EVIDENCE=true``.  The
+    ordinary source-only gate records a skip instead of treating intentionally
+    externalized historical evidence as release source.
+    """
+
+    if not relative_files:
+        raise ValueError("at least one external QA evidence file is required")
+    evidence_root = (root or QA_ROOT).resolve()
+    required_paths = [(evidence_root / _safe_relative(value)).resolve() for value in relative_files]
+    if any(
+        path == evidence_root or evidence_root not in path.parents
+        for path in required_paths
+    ):
+        raise ValueError("external QA evidence path escapes its configured root")
+    missing = [path for path in required_paths if not path.is_file()]
+    if missing:
+        shown = ", ".join(path.relative_to(evidence_root).as_posix() for path in missing)
+        message = f"external historical QA evidence is missing: {shown}"
+        if _enabled(os.environ.get(REQUIRE_EXTERNAL_QA_ENV)):
+            pytest.fail(message, pytrace=False)
+        pytest.skip(message, allow_module_level=allow_module_level)
+    return evidence_root