"""Fixtures for public-surface tests.

Every fixture here uses ONLY the public ``mgf.common.*`` API —
no underscore-prefixed imports. This is the same discipline the
test files themselves follow; the
``test_no_private_imports.py`` pin enforces it on the test
files, but it would be a lie to provide fixtures that reach into
internals.

Available fixtures:

  - :func:`app_ctx` — a ``bootstrap_for_test()`` AppContext
    with default test settings (WARNING-level logging, OTel
    off). Auto-shutdown on test exit.

  - :func:`captured_app_ctx` — same but with
    ``capture_logs=True`` and ``capture_spans=True``. Use when
    a test needs to assert on emitted logs / spans.

  - :func:`isolated_pyproject` — sets ``MGF_DISABLE_PYPROJECT=1``
    so the source's `[tool.mgf]` walk-up doesn't pick up the
    project's own pyproject.toml during these tests.
"""

from __future__ import annotations

from typing import TYPE_CHECKING

import pytest

import mgf.common

if TYPE_CHECKING:
    from collections.abc import Iterator


@pytest.fixture(autouse=True)
def isolated_pyproject(monkeypatch: pytest.MonkeyPatch) -> None:
    """Disable the pyproject.toml settings source for every
    public-surface test so the project's own pyproject doesn't
    leak ``[tool.mgf]`` config (it doesn't have one today, but
    the discipline is cheap)."""
    monkeypatch.setenv("MGF_DISABLE_PYPROJECT", "1")


@pytest.fixture
def app_ctx() -> Iterator[mgf.common.AppContext]:
    """A ``bootstrap_for_test()`` AppContext, auto-shutdown.

    Use as the default fixture for any test that needs a live
    bootstrapped context. Settings are ``MgfSettings.testing()``
    defaults; identity is ``("test-app", "0.0.1")``.
    """
    with mgf.common.bootstrap_for_test() as ctx:
        yield ctx


@pytest.fixture
def captured_app_ctx() -> Iterator[mgf.common.AppContext]:
    """A ``bootstrap_for_test(capture_logs=True)`` AppContext.

    Captured logs accessible via ``ctx.captured_logs``. Auto-
    shutdown removes the in-memory log handler.

    Note: this fixture intentionally does NOT pass
    ``capture_spans=True``. ``_wire_span_capture`` requires an
    SDK ``TracerProvider`` already active (the helper does NOT
    auto-install one — OTel's ``set_tracer_provider`` is
    one-shot and would pollute other tests' session-scoped
    fixtures). Public-surface tests don't have a TracerProvider
    set up, so spans aren't captured here. If a future
    public-surface test needs span capture, install a
    module-scoped TracerProvider fixture (see
    ``tests/unit/test_v04_03_capture.py::_otel_provider`` for
    the canonical pattern).
    """
    with mgf.common.bootstrap_for_test(capture_logs=True) as ctx:
        yield ctx
