llm-ingestion-okf/tests/test_bundle_map.py

"""The map a reader writes sub-questions from (v1.1 order C, C5).

A question is best put in the collection's OWN words, and the one place those
words are listed is the collection itself. `bundlemap.build_map` lists them:
one line per source document -- its name, then the titles of its concepts in
document order -- and a SERIES of documents whose names differ only in their
numbers (a changelog per release, a note per week) as ONE line with the span,
because four hundred lines saying the same thing crowd out the rest.

`okf card` and `okf_describe` carry it as `map`.
"""

from __future__ import annotations

import json
import sys
from pathlib import Path

import pytest

from llm_ingestion_okf import bundlemap, consume, mcp_server

TOOLS = Path(__file__).resolve().parent.parent / "tools"
if str(TOOLS) not in sys.path:
    sys.path.insert(0, str(TOOLS))

import okf_retrieval_gate as retrieval  # noqa: E402


def _doc(name: str, *titles: str) -> retrieval.DocumentSpec:
    return retrieval.DocumentSpec(
        name,
        f"{name}.md",
        tuple(
            retrieval.ConceptSpec(slug=f"s{position}", title=title, body=f"About {title}.")
            for position, title in enumerate(titles, start=1)
        ),
    )


RELEASES = tuple(_doc(f"changes-1-{minor}", f"1.{minor}") for minor in range(2, 14))
WEEKLY = tuple(
    _doc(f"notes-2026-w{week}", "Highlights", f"Week {week} fixes") for week in (1, 2, 3, 4, 5)
)


@pytest.fixture(scope="module")
def bundle(tmp_path_factory: pytest.TempPathFactory) -> Path:
    spec = retrieval.BundleSpec(
        "map-synthetic",
        (
            _doc("guide-setup", "Setup", "Install the tool", "Configure a project"),
            _doc("guide-hooks", "Hooks", "Hook events", "Hook events"),
            *RELEASES,
            *WEEKLY,
        ),
    )
    return retrieval.build_bundle(tmp_path_factory.mktemp("map") / "bundle", spec)


def _map(bundle: Path) -> dict[str, object]:
    return bundlemap.bundle_map(bundle, profile=consume.DEFAULT_PROFILE)


def test_one_line_per_document_with_its_own_titles_in_order(bundle: Path) -> None:
    lines = _map(bundle)["lines"]
    assert isinstance(lines, list)
    assert "guide-setup: Setup · Install the tool · Configure a project" in lines
    # A title the document repeats is listed once.
    assert "guide-hooks: Hooks · Hook events" in lines


def test_a_series_is_one_line_with_its_span(bundle: Path) -> None:
    lines = _map(bundle)["lines"]
    assert isinstance(lines, list)
    series = [line for line in lines if line.startswith("changes-#-#")]
    assert series == ["changes-#-# (12 documents: changes-1-2 … changes-1-13)"]
    assert not any(line.startswith("changes-1-") for line in lines)


def test_a_series_keeps_the_titles_that_are_words(bundle: Path) -> None:
    lines = _map(bundle)["lines"]
    assert isinstance(lines, list)
    (line,) = [line for line in lines if line.startswith("notes-#-w#")]
    assert line.startswith("notes-#-w# (5 documents: notes-2026-w1 … notes-2026-w5): Highlights")
    assert "Week 1 fixes" in line


def test_the_map_states_its_denominators(bundle: Path) -> None:
    built = _map(bundle)
    assert built["documents"] == 2 + 12 + 5
    assert built["concepts"] == 3 + 3 + 12 + 10
    assert built["lines_count"] == 4


def test_a_long_document_is_cut_and_says_so(tmp_path: Path) -> None:
    titles = [f"Section {n}" for n in range(bundlemap.TITLES_PER_LINE + 5)]
    spec = retrieval.BundleSpec("long", (_doc("big", *titles),))
    bundle = retrieval.build_bundle(tmp_path / "bundle", spec)
    (line,) = _map(bundle)["lines"]  # type: ignore[misc]
    assert line.endswith("· (+5 more)")
    assert line.count(" · ") == bundlemap.TITLES_PER_LINE


def test_the_map_is_deterministic(bundle: Path) -> None:
    assert json.dumps(_map(bundle)) == json.dumps(_map(bundle))


def test_describe_and_the_card_carry_the_map(bundle: Path) -> None:
    surface = mcp_server.build_surface(bundle=bundle, roots=())
    described = mcp_server.call_describe(surface, {})
    assert described["map"] == _map(bundle)
    assert mcp_server.card(bundle, profile=consume.DEFAULT_PROFILE)["map"] == _map(bundle)


def test_the_card_names_documents_through_the_map_alone(bundle: Path) -> None:
    """`source_files` listed every document a second time, one name per line
    and no series collapsed; the map names every document or series already."""
    assert "source_files" not in mcp_server.card(bundle, profile=consume.DEFAULT_PROFILE)


def test_the_working_method_is_map_first_then_one_call() -> None:
    from llm_ingestion_okf import skill as okf_skill

    generic = okf_skill.render_generic()
    assert "`map`" in generic
    assert "ONE run" in generic
    # The example command itself carries more than one sub-question.
    command = next(
        line
        for line in generic.splitlines()
        if line.startswith("okf consume ") and "sub-question" in line
    )
    assert command.count("--question ") >= 2
    instructions = mcp_server.SERVER_INSTRUCTIONS
    assert "map" in instructions
    assert "`questions`" in instructions
    assert "ONE call" in instructions
    assert len(instructions.encode("utf-8")) <= 2048


def test_the_map_has_a_ceiling_and_says_what_it_left_out(
    bundle: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    whole = _map(bundle)
    assert whole["lines_truncated"] == 0
    lines = whole["lines"]
    assert isinstance(lines, list)
    monkeypatch.setattr(bundlemap, "MAP_MAX_BYTES", len(lines[0].encode("utf-8")) + 1)
    cut = _map(bundle)
    assert cut["lines"] == lines[:1]
    assert cut["lines_truncated"] == len(lines) - 1
    assert cut["lines_count"] == len(lines)