"""Stub coverage/usage tests for NumpyChain (.pyi).

These assertions ensure key doc examples stay present; if an AI or tooling
accidentally strips them, the breakage is detectable.
"""

from __future__ import annotations

from pathlib import Path


STUB_PATH = Path("src/crystflux/v1/adapters/numpy_chain.pyi")


def test_scope_mentions_approximate_count() -> None:
    """Scope section should note ~50 methods to guide IDE expectation."""
    text = STUB_PATH.read_text()
    assert "~50 stable, frequent ndarray methods" in text


def test_examples_present_for_shape_and_stat_ops() -> None:
    """Key shape/stat ops should include example snippets for IDE help."""
    text = STUB_PATH.read_text()
    # Shape-related
    assert "reshape(2,2).shape" in text
    assert "transpose().tolist()" in text
    assert "flatten().tolist()" in text
    assert "ravel().tolist()" in text
    assert "squeeze().shape" in text
    # Statistical
    assert "sum()\n            6" in text
    assert "mean()\n            2.5" in text
    assert "std()" in text
    assert "var()" in text
    assert "min()" in text
    assert "max()" in text
    assert "cumsum().tolist()" in text


def test_examples_present_for_new_additions() -> None:
    """Recently added helper methods should carry examples for IDE popups."""
    text = STUB_PATH.read_text()
    assert "compress([False,True,False,True]).tolist()" in text
    assert "nonzero()" in text
    assert "np.where(as_numpy_chain" in text
