portfolio-optimiser/tests/test_shared_packaged_data_loadbearing.py

"""Load-bearing tests for shared/ as packaged data with the working tree as override (Fase 4a).

README's install story is a clone because the shared spec, persona skill and example bundles under
``shared/`` were read from the WORKING TREE at run time — an installed wheel had no shared data at
all (measured 2026-08-13: the 1.0.0 wheel carried 58 files, zero of them under ``shared/``). Fase
4a packages the whole ``shared/`` tree into the wheel as data (``portfolio_optimiser/_shared/``,
hatchling force-include) and teaches ``shared_root()`` a call-time resolution order: env override →
working tree (when present) → packaged copy. The working tree stays authoritative in a checkout —
that is what keeps the pull-only subtree contract and the byte-level goldens untouched.

Three seams, each one measured by mutation:

- the wheel really CARRIES the tree, byte-identical to ``shared/`` (RED when the force-include is
  dropped from pyproject — the packaged mirror silently disappears from every future wheel);
- an installed distribution RESOLVES to the packaged copy and a real consumer (the persona loader)
  reads it (RED when the fallback in ``shared_root()`` is detached — the subprocess imports from
  the unpacked wheel, never from the repo, so the working tree cannot mask the regression);
- the working tree still WINS when both copies exist (RED when the resolution order is flipped;
  green both before and after the 4a change, so its discriminating power is proven by the flip
  mutation, not by the fix itself — its control assert on the packaged copy is what made it red
  pre-4a).

The wheel is built by the REAL build backend (``uv build``) once per session: the packaging config
is itself a seam under test, and nothing short of a genuine build can measure it.
"""

from __future__ import annotations

import os
import subprocess
import sys
import zipfile
from pathlib import Path

import pytest

REPO_ROOT = Path(__file__).resolve().parents[1]
SHARED = REPO_ROOT / "shared"
PACKAGED_PREFIX = "portfolio_optimiser/_shared/"


@pytest.fixture(scope="session")
def built_wheel(tmp_path_factory: pytest.TempPathFactory) -> Path:
    """One genuine wheel build per test session. ``uv`` is the repo's documented toolchain (README
    sends a fresh clone through ``uv sync``), so its absence is a broken environment — a hard
    failure, never a skip: a skipped gate is no gate."""
    out_dir = tmp_path_factory.mktemp("wheel-dist")
    proc = subprocess.run(
        ["uv", "build", "--wheel", "--out-dir", str(out_dir)],
        cwd=REPO_ROOT,
        capture_output=True,
        text=True,
        check=False,
    )
    assert proc.returncode == 0, f"uv build failed:\n{proc.stderr}"
    wheels = sorted(out_dir.glob("*.whl"))
    assert len(wheels) == 1, f"expected exactly one wheel, got {wheels}"
    return wheels[0]


@pytest.fixture
def installed_dist(built_wheel: Path, tmp_path: Path) -> Path:
    """A per-test unpacked copy of the wheel (an installed distribution is an unpacked wheel on
    ``sys.path``). Per test, NOT per session: the override test plants a ``shared/`` directory at
    the working-tree position beside the copy, and a shared copy would leak that sibling into the
    resolution test."""
    site_dir = tmp_path / "installed"
    with zipfile.ZipFile(built_wheel) as zf:
        zf.extractall(site_dir)
    return site_dir


def _child_env(site_dir: Path) -> dict[str, str]:
    """Subprocess env: the unpacked wheel FIRST on ``sys.path`` (before the dev venv's editable
    install), and the production override unset so the resolver's own ordering is what gets
    measured."""
    env = dict(os.environ)
    env.pop("PORTFOLIO_SHARED_ROOT", None)
    env["PYTHONPATH"] = str(site_dir)
    return env


def _run_child(script: str, args: list[str], site_dir: Path, cwd: Path) -> str:
    cwd.mkdir(exist_ok=True)
    proc = subprocess.run(
        [sys.executable, "-c", script, *args],
        capture_output=True,
        text=True,
        check=False,
        env=_child_env(site_dir),
        cwd=cwd,
    )
    assert proc.returncode == 0, f"child failed:\n{proc.stderr}"
    return proc.stdout


def test_wheel_carries_shared_tree_byte_identical(built_wheel: Path) -> None:
    """Every file under ``shared/`` lands in the wheel under ``portfolio_optimiser/_shared/`` —
    same file set, same bytes. Byte identity is the property that lets the commons-owned goldens
    keep gating the packaged copy: the mirror IS the subtree, never an edited derivative."""
    worktree_files = sorted(
        p.relative_to(SHARED).as_posix() for p in SHARED.rglob("*") if p.is_file()
    )
    assert worktree_files, "control: shared/ in the working tree must not be empty"

    with zipfile.ZipFile(built_wheel) as zf:
        packaged = {
            name[len(PACKAGED_PREFIX) :]: zf.read(name)
            for name in zf.namelist()
            if name.startswith(PACKAGED_PREFIX)
        }

    assert sorted(packaged) == worktree_files, (
        "the wheel's packaged copy does not mirror shared/ — is the force-include still in "
        "pyproject.toml?"
    )
    drifted = [rel for rel in worktree_files if packaged[rel] != (SHARED / rel).read_bytes()]
    assert not drifted, f"byte drift between shared/ and the packaged copy: {drifted}"


def test_installed_distribution_resolves_the_packaged_copy(
    installed_dist: Path, tmp_path: Path
) -> None:
    """From an installed distribution (no working tree anywhere above the package), the resolver
    yields the packaged copy and the persona loader — a real consumer, not just the resolver —
    reads it. The child first proves it imported the unpacked wheel (never the repo's editable
    install), so a green here cannot be the working tree answering in the wheel's name."""
    script = (
        "import sys\n"
        "from pathlib import Path\n"
        "import portfolio_optimiser\n"
        "from portfolio_optimiser.persona import load_persona_example\n"
        "from portfolio_optimiser.shared_root import shared_root\n"
        "site_dir = Path(sys.argv[1]).resolve()\n"
        "pkg_file = Path(portfolio_optimiser.__file__).resolve()\n"
        "assert pkg_file == site_dir / 'portfolio_optimiser' / '__init__.py', (\n"
        "    f'control: child imported {pkg_file}, not the unpacked wheel'\n"
        ")\n"
        "root = shared_root()\n"
        "expected = site_dir / 'portfolio_optimiser' / '_shared'\n"
        "assert root == expected, f'resolved {root}, expected the packaged copy {expected}'\n"
        "assert (root / 'method-spec.md').is_file(), f'packaged spec missing under {root}'\n"
        "example = load_persona_example()\n"
        "assert example.marker, 'persona example unreadable from the packaged copy'\n"
        "print('PACKAGED-OK')\n"
    )
    stdout = _run_child(script, [str(installed_dist)], installed_dist, tmp_path / "cwd")
    assert "PACKAGED-OK" in stdout, "child never reached its final assert"


def test_working_tree_overrides_the_packaged_copy(installed_dist: Path, tmp_path: Path) -> None:
    """When a ``shared/`` directory exists at the working-tree position (two levels above the
    package — the layout of a repo checkout, and of this test's planted sibling), it wins over the
    packaged copy. The control assert that the packaged copy EXISTS is load-bearing: without it,
    an ordering flipped to packaged-first would still return the working tree whenever the
    packaged copy is missing, and the assert below could not tell the two orderings apart."""
    worktree_shared = (
        tmp_path / "shared"
    )  # parents[2] of installed/portfolio_optimiser/shared_root.py
    worktree_shared.mkdir()
    (worktree_shared / "method-spec.md").write_text("worktree override marker\n", encoding="utf-8")

    script = (
        "import sys\n"
        "from pathlib import Path\n"
        "import portfolio_optimiser\n"
        "from portfolio_optimiser.shared_root import shared_root\n"
        "site_dir = Path(sys.argv[1]).resolve()\n"
        "worktree = Path(sys.argv[2]).resolve()\n"
        "pkg_file = Path(portfolio_optimiser.__file__).resolve()\n"
        "assert pkg_file == site_dir / 'portfolio_optimiser' / '__init__.py', (\n"
        "    f'control: child imported {pkg_file}, not the unpacked wheel'\n"
        ")\n"
        "packaged = site_dir / 'portfolio_optimiser' / '_shared'\n"
        "assert packaged.is_dir(), (\n"
        "    'control: the packaged copy must exist, or the ordering below is unmeasurable'\n"
        ")\n"
        "root = shared_root()\n"
        "assert root == worktree, (\n"
        "    f'resolved {root}, expected the working-tree override {worktree}'\n"
        ")\n"
        "print('WORKTREE-OK')\n"
    )
    stdout = _run_child(
        script, [str(installed_dist), str(worktree_shared)], installed_dist, tmp_path / "cwd"
    )
    assert "WORKTREE-OK" in stdout, "child never reached its final assert"