scripts.check_source_provenance

Reference › scripts › check_source_provenance

The source-provenance gate: it proves that the test suite imports the checkout it is meant to test. No module or test imports it; it runs before a test run.

Invocation: main takes --python, the interpreter to probe (default the current one). Two checks run in order. The first compares the install origin, which _install_origin reads from the package's installation metadata, with this checkout; the package must have been built from exactly this tree. A mismatch prints that another checkout re-synced the environment and names the remedy, a non-editable dev sync from this checkout. The second runs the interpreter as a subprocess (_probe) to import the main package and report its file path, then verifies the file lives where expected. _shadowing_entries lists entries on the module search path that would shadow the expected source. Any failure returns 1.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

No internal imports and no importers.

API

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/scripts/check_source_provenance.py

#!/usr/bin/env python3
"""Source-provenance gate — prove the suite imports the checkout it is testing.

A test run is only evidence about the tree it actually imported. On
2026-07-27 the "final gate" run in a worktree reported 30 failures that were
pure artifacts: an exported

    PYTHONPATH=/home/mohamed/workspace/orchestrata-ultimate-architecture/src

leaked into the run and landed at ``sys.path[1]``, outranking the worktree's
own editable ``.pth`` entry at ``sys.path[6]``. The run executed the
worktree's TESTS against a DIFFERENT BRANCH's SOURCE. Both directions of that
verdict were worthless -- the failures were not real, and real defects in the
tree under test were never exercised.

This gate makes that state impossible to reach silently: import the package
the way the suite does, resolve where it came from, and fail the run when it
did not come from this repository's ``src/``.

Exit codes:
    0 -- the package resolves inside this checkout
    1 -- it resolves somewhere else, or cannot be imported at all
"""

from __future__ import annotations

import argparse
import os
import subprocess
import sys
from pathlib import Path
from typing import Any

REPO_ROOT = Path(__file__).resolve().parent.parent
PACKAGE = "orchestrata_ultimate"

# Resolving the package in THIS process is not enough: the gate may itself be
# invoked by a runner whose environment differs from the one pytest will get.
# Ask a child interpreter -- the same one the suite uses -- and read back the
# resolved path, so the answer reflects the real import environment.
_PROBE = (
    "import importlib, json, sys\n"
    "try:\n"
    "    mod = importlib.import_module({pkg!r})\n"
    "except Exception as exc:\n"
    "    print(json.dumps({{'error': f'{{type(exc).__name__}}: {{exc}}'}}))\n"
    "    raise SystemExit(0)\n"
    "print(json.dumps({{'file': getattr(mod, '__file__', None),\n"
    "                  'path': sys.path}}))\n"
)


def _probe(python: str, env: dict[str, str]) -> dict[str, Any]:
    """Import *PACKAGE* in a child interpreter and report where it came from."""
    import json

    proc = subprocess.run(
        [python, "-c", _PROBE.format(pkg=PACKAGE)],
        capture_output=True,
        text=True,
        env=env,
        cwd=str(REPO_ROOT),
    )
    line = proc.stdout.strip().splitlines()
    if not line:
        return {"error": proc.stderr.strip() or "probe produced no output"}
    try:
        return json.loads(line[-1])
    except ValueError:
        return {"error": f"probe output not JSON: {line[-1][:200]}"}


def _shadowing_entries(sys_path: list[str], expected_src: Path) -> list[str]:
    """Path entries that precede *expected_src* and carry their own copy of the
    package -- i.e. the entries that actually win the import."""
    shadows: list[str] = []
    for entry in sys_path:
        if not entry:
            continue
        resolved = Path(entry).resolve()
        if resolved == expected_src:
            break
        if (resolved / PACKAGE / "__init__.py").exists():
            shadows.append(str(resolved))
    return shadows


def _install_origin() -> str:
    """The PEP 610 direct-URL origin the installer recorded for this package —
    the exact checkout the installed wheel was BUILT FROM. This repo now
    installs PROPERLY (non-editable, into site-packages; see tests/conftest.py),
    so the old "resolves to src/" check is permanently false; the recorded
    origin is its replacement — a strictly stronger claim that a stale
    PYTHONPATH shadow (which changes where an import resolves, never what the
    installer recorded) cannot satisfy."""
    import json
    from importlib.metadata import PackageNotFoundError, distribution

    try:
        raw = distribution("orchestrata-ultimate").read_text("direct_url.json")
    except PackageNotFoundError:
        return ""
    if raw is None:
        return ""
    return json.loads(raw).get("url", "")


def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "--python",
        default=sys.executable,
        help="interpreter to probe (default: the current one)",
    )
    args = parser.parse_args()

    expected_src = (REPO_ROOT / "src").resolve()
    expected_origin = REPO_ROOT.resolve().as_uri()

    # Check 1 — the install origin (the checkout the wheel was BUILT FROM).
    # Proper install (2026-10-20) means the package lives in site-packages and
    # carries a PEP 610 direct_url.json naming the exact checkout; that origin
    # is the provenance proof, mirroring tests/conftest.py.
    origin = _install_origin()
    if origin != expected_origin:
        print("[source-provenance] ❌ THE SUITE WOULD TEST THE WRONG SOURCE TREE")
        print(f"[source-provenance]    repo under test : {REPO_ROOT}")
        print(
            f"[source-provenance]    installed from  : "
            f"{origin or '<no origin recorded>'}"
        )
        print(
            "[source-provenance]    Another checkout re-synced this venv. Fix: "
            "run `uv sync --dev --no-editable` from THIS checkout."
        )
        return 1

    env = dict(os.environ)
    result = _probe(args.python, env)

    if "error" in result:
        print(f"[source-provenance] ❌ cannot import {PACKAGE}: {result['error']}")
        print(f"[source-provenance]    expected it under: {expected_src}")
        return 1

    raw_file = result.get("file")
    if not raw_file:
        print(
            f"[source-provenance] ❌ {PACKAGE} has no __file__ — cannot verify origin"
        )
        return 1

    actual_pkg = Path(str(raw_file)).resolve().parent
    actual_src = actual_pkg.parent

    # Check 2 — a proper install resolves to site-packages. A src/ tree that
    # wins the import instead (a PYTHONPATH shadow or an editable .pth) is the
    # exact defect this gate exists to catch.
    if "site-packages" in actual_pkg.parts:
        print(f"[source-provenance] ✅ {PACKAGE} resolves to {actual_pkg}")
        return 0

    sys_path = [str(p) for p in result.get("path", []) if isinstance(p, str)]
    shadows = _shadowing_entries(sys_path, expected_src)

    print("[source-provenance] ❌ THE SUITE WOULD TEST THE WRONG SOURCE TREE")
    print(f"[source-provenance]    repo under test : {REPO_ROOT}")
    print(f"[source-provenance]    expected source : {expected_src}")
    print(f"[source-provenance]    actual source   : {actual_src}")
    if shadows:
        print("[source-provenance]    shadowed by these earlier sys.path entries:")
        for entry in shadows:
            print(f"[source-provenance]      - {entry}")
    pythonpath = env.get("PYTHONPATH")
    if pythonpath:
        print(f"[source-provenance]    PYTHONPATH={pythonpath}")
        print(
            "[source-provenance]    PYTHONPATH precedes the installed copy. "
            "Unset it — the proper install needs no PYTHONPATH."
        )
    print(
        "[source-provenance]    A run in this state proves nothing about this "
        "checkout. Fix the import path and re-run."
    )
    return 1


if __name__ == "__main__":
    raise SystemExit(main())