56 lines
2.1 KiB
Python
56 lines
2.1 KiB
Python
"""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
|