PageIndex/tests/test_legacy_shims.py

"""The top-level pageindex.page_index / .page_index_md / .utils modules are
now deprecation shims over the canonical pageindex.index.* modules. These
tests pin the compatibility contract."""
import asyncio
import importlib
import subprocess
import sys
import warnings
from pathlib import Path

import pytest

_REPO_ROOT = Path(__file__).resolve().parent.parent


def test_plain_import_pageindex_does_not_warn():
    # `import pageindex` must not route through the deprecation shims.
    with warnings.catch_warnings():
        warnings.simplefilter("error", PendingDeprecationWarning)
        importlib.import_module("pageindex")


@pytest.mark.parametrize("mod", [
    "pageindex.utils",
    "pageindex.page_index",
    "pageindex.page_index_md",
])
def test_legacy_submodule_import_warns(mod):
    with warnings.catch_warnings(record=True) as caught:
        warnings.simplefilter("always")
        importlib.reload(importlib.import_module(mod))
    assert any(issubclass(w.category, PendingDeprecationWarning) for w in caught)


def test_legacy_symbols_resolve_through_shims():
    with warnings.catch_warnings():
        warnings.simplefilter("ignore")
        from pageindex.utils import (  # noqa: F401
            get_page_tokens, ConfigLoader, convert_page_to_int,
            get_leaf_nodes, remove_fields,
        )
        from pageindex.page_index import page_index, page_index_main  # noqa: F401
        from pageindex.page_index_md import md_to_tree  # noqa: F401


def test_canonical_and_shim_share_one_implementation():
    with warnings.catch_warnings():
        warnings.simplefilter("ignore")
        import pageindex.utils as shim
    import pageindex.index.utils as canonical
    # Same function object -> a single source of truth (no divergence possible).
    assert shim.get_leaf_nodes is canonical.get_leaf_nodes
    assert shim.get_page_tokens is canonical.get_page_tokens


def test_get_leaf_nodes_has_331_fix():
    """Canonical get_leaf_nodes must use .get('nodes'); clean_node deletes the
    key on leaf nodes so [...]['nodes'] would KeyError (issue #330)."""
    from pageindex.index.utils import get_leaf_nodes
    # A leaf node with the 'nodes' key deleted (as clean_node leaves it).
    leaves = get_leaf_nodes({"title": "Leaf", "start_index": 1, "end_index": 2})
    assert leaves == [{"title": "Leaf", "start_index": 1, "end_index": 2}]


def test_configloader_defaults_come_from_packaged_yaml():
    """ConfigLoader must read the packaged config.yaml as its defaults, like
    0.2.x — notably if_add_doc_description ships as "no" there, while the
    IndexConfig field default is True (the new-SDK default)."""
    from pageindex.index.utils import ConfigLoader
    cfg = ConfigLoader().load({"model": "gpt-5.4"})
    assert cfg.model == "gpt-5.4"
    assert cfg.if_add_node_summary is True  # config.yaml: "yes"
    assert cfg.if_add_doc_description is False  # config.yaml: "no"
    with pytest.raises(ValueError, match="Unknown config keys"):
        ConfigLoader().load({"nope": 1})


def test_configloader_reads_custom_yaml_path(tmp_path):
    """A custom default_path must be honored; keys the YAML omits fall back to
    IndexConfig field defaults."""
    from pageindex.index.utils import ConfigLoader
    custom = tmp_path / "my.yaml"
    custom.write_text('model: "my-model"\nif_add_node_summary: "no"\n')
    cfg = ConfigLoader(str(custom)).load()
    assert cfg.model == "my-model"
    assert cfg.if_add_node_summary is False
    assert cfg.if_add_node_id is True  # omitted -> IndexConfig default


def test_configloader_missing_custom_yaml_raises(tmp_path):
    from pageindex.index.utils import ConfigLoader
    with pytest.raises(FileNotFoundError):
        ConfigLoader(str(tmp_path / "nope.yaml"))


def test_legacy_submodule_attrs_lazy_bound():
    """Shim warnings fire on first attribute use, never at package import.
    Subprocess: in-process the attrs may already be bound by other tests."""
    import subprocess
    import sys
    code = (
        "import warnings\n"
        "with warnings.catch_warnings(record=True) as w:\n"
        "    warnings.simplefilter('always')\n"
        "    import pageindex\n"
        "assert not any('has moved' in str(x.message) for x in w), 'import warned'\n"
        "with warnings.catch_warnings(record=True) as w:\n"
        "    warnings.simplefilter('always')\n"
        "    assert callable(pageindex.utils.print_tree)\n"
        "assert any('pageindex.utils has moved' in str(x.message) for x in w)\n"
        "assert callable(pageindex.page_index_md.md_to_tree)\n"
    )
    result = subprocess.run([sys.executable, "-c", code],
                            capture_output=True, text=True, timeout=120)
    assert result.returncode == 0, result.stderr


def test_unknown_package_attr_still_raises():
    import pageindex
    with pytest.raises(AttributeError, match="no attribute 'definitely_not_real'"):
        pageindex.definitely_not_real


def test_page_index_defaults_follow_config_yaml(monkeypatch):
    """page_index() resolution order: explicit args > config.yaml > IndexConfig
    field defaults (the 0.2.x contract)."""
    import pageindex.index.page_index as pi
    captured = {}
    monkeypatch.setattr(pi, "page_index_main",
                        lambda doc, opt: captured.setdefault("opt", opt))
    pi.page_index("dummy.pdf", model="my-model")
    opt = captured["opt"]
    assert opt.model == "my-model"  # explicit arg wins
    assert opt.if_add_doc_description is False  # config.yaml "no", not True


def test_configloader_coerces_legacy_yes_no_strings():
    """A legacy caller passing 'no' must get a real False, not a truthy
    string — page_index_main's `if opt.if_add_node_summary:` checks (bare
    truthy, not `== 'yes'`) would otherwise silently invert caller intent and
    fire unwanted billed LLM calls."""
    from pageindex.index.utils import ConfigLoader
    cfg = ConfigLoader().load({"if_add_node_summary": "no", "if_add_doc_description": "no"})
    assert cfg.if_add_node_summary is False
    assert cfg.if_add_doc_description is False
    assert bool(cfg.if_add_node_summary) is False

    cfg2 = ConfigLoader().load({"if_add_node_id": "yes"})
    assert cfg2.if_add_node_id is True


def test_md_to_tree_shim_is_the_canonical_function():
    """The shim no longer wraps md_to_tree with its own coercion — the
    canonical implementation coerces internally, so the shim is a pure
    re-export (single source of truth, can't diverge from the canonical
    behavior)."""
    with warnings.catch_warnings():
        warnings.simplefilter("ignore")
        import pageindex.page_index_md as shim
    import pageindex.index.page_index_md as canonical
    assert shim.md_to_tree is canonical.md_to_tree


def test_md_to_tree_coerces_legacy_yes_no_strings(tmp_path):
    """A bare 'no' must not read as truthy True — exercised end-to-end (no
    LLM calls needed with summary/description disabled)."""
    from pageindex.index.page_index_md import md_to_tree

    md_path = tmp_path / "doc.md"
    md_path.write_text("# Title\nbody\n\n## Sub\nmore body\n")

    result = asyncio.run(md_to_tree(
        md_path=str(md_path),
        if_add_node_summary="no",
        if_add_node_id="yes",
        if_add_doc_description="no",
    ))
    assert "doc_description" not in result

    def _has_summary(nodes):
        return any("summary" in n or (n.get("nodes") and _has_summary(n["nodes"]))
                   for n in nodes)

    assert not _has_summary(result["structure"])
    assert all("node_id" in n for n in result["structure"])


def test_page_index_stays_callable_after_the_submodule_is_imported():
    """pageindex/__init__.py binds the FUNCTION `page_index` as the package
    attribute, but pageindex/page_index.py is ALSO a real submodule of the
    same name — importing that submodule anywhere clobbers the package
    attribute with the module object (Python's import machinery does this
    unconditionally). Must run in a fresh subprocess: the effect depends on
    import order, so it can't be reliably observed against an
    already-imported pageindex in this test process."""
    script = (
        "import warnings; warnings.simplefilter('ignore')\n"
        "import pageindex.page_index\n"  # the clobbering import
        "from pageindex import page_index\n"
        "assert callable(page_index), f'page_index is not callable: {type(page_index)}'\n"
        "from pageindex.page_index import page_index_main\n"  # old multi-symbol import still works
        "assert callable(page_index_main)\n"
        "print('OK')\n"
    )
    result = subprocess.run(
        [sys.executable, "-c", script], capture_output=True, text=True, cwd=str(_REPO_ROOT),
    )
    assert result.returncode == 0, result.stderr
    assert "OK" in result.stdout