chemenu/tools/chemenu/tests/test_index_build.py

from pathlib import Path

import pytest

from chemenu.commands.index_build import (
    SHARD_THRESHOLD,
    _anchor,
    build_index,
    index_rebuild,
    plan_index,
    stale_shards,
)
from chemenu.frontmatter_io import write_page
from chemenu.kb_scan import GENERATED_INDEX, iter_kb_pages
from chemenu.type_resolver import resolver


def _area_title(subtype: str, type_path: str = "types/entity.md") -> str:
    """The display title `index rebuild` will use for a subtype's area.

    Read from the type-spec rather than written out, because these titles follow
    the KB language: hard-coding them made translating the wiki fail tests that
    are not about wording at all.
    """
    return resolver.get_layout(type_path)[subtype]["title"]


@pytest.fixture
def plan(kb_dir: Path):
    return plan_index(kb_dir)


def _shard(plan: dict, kb_dir: Path, *parts: str) -> str:
    return plan[kb_dir.joinpath(*parts, GENERATED_INDEX)]


def _section(content: str, heading: str) -> str:
    """Text from a heading line up to the next heading of any level."""
    start = content.index(heading) + len(heading)
    rest = content[start:]
    for line in rest.splitlines(keepends=True):
        if line.startswith("#"):
            return rest[: rest.index(line)]
    return rest


# --- the map ----------------------------------------------------------------


def test_map_reports_totals_per_collection(kb_dir):
    content = build_index(kb_dir)
    assert "**Total Pages:** 5" in content
    assert "**Entities:** 3" in content
    assert "**Concepts:** 1" in content
    assert "**Sources:** 1" in content


def test_map_lists_an_empty_collection_rather_than_hiding_it(kb_dir):
    """comparisons/ holds no pages but is a real collection - a reader must
    still be able to see that it exists."""
    assert "| `comparisons/` | 0 |" in build_index(kb_dir)


def test_map_lists_every_area_with_its_count(kb_dir):
    content = build_index(kb_dir)
    assert f"| {_area_title('system')} | 2 |" in content
    assert f"| {_area_title('tool')} | 1 |" in content
    # Areas that exist as directories but hold no pages are simply absent.
    assert f"| {_area_title('person')} |" not in content


def test_map_carries_no_page_rows(kb_dir):
    """The whole point of the map: reading it must not cost one row per page."""
    content = build_index(kb_dir)
    assert "[[aurora]]" not in content
    assert "[[Modbus]]" not in content
    assert len(content.splitlines()) < 60


def test_map_points_at_search_first(kb_dir):
    assert "wikitool search" in build_index(kb_dir)


def test_map_links_to_each_collection_shard(kb_dir):
    content = build_index(kb_dir)
    assert f"[entities/{GENERATED_INDEX}](entities/{GENERATED_INDEX})" in content


def test_map_deep_links_an_inlined_area_by_anchor(kb_dir):
    # The anchor is derived from the area's display title, so it follows the KB
    # language along with it. Both sides of the link are generated in the same
    # run, so they stay consistent; only a bookmark to an old anchor would break.
    anchor = _anchor(_area_title("system"))
    assert f"entities/{GENERATED_INDEX}#{anchor}" in build_index(kb_dir)


# --- collection shards ------------------------------------------------------


def test_collection_shard_holds_the_page_rows(plan, kb_dir):
    entities = _shard(plan, kb_dir, "entities")
    assert "[[aurora]]" in entities
    assert "[[Borealis]]" in entities
    assert "[[gdeploy]]" in entities


def test_pages_are_grouped_by_area_and_sorted_case_insensitively(plan, kb_dir):
    systems = _section(_shard(plan, kb_dir, "entities"), f"## {_area_title('system')}")
    assert systems.index("[[aurora]]") < systems.index("[[Borealis]]")
    assert "[[gdeploy]]" not in systems


def test_area_titles_come_from_the_entity_type_spec_layout(plan, kb_dir):
    entities = _shard(plan, kb_dir, "entities")
    assert f"## {_area_title('system')}" in entities
    assert f"## {_area_title('tool')}" in entities


def test_anchor_keeps_non_ascii_letters():
    """An area title follows the KB language, so it may carry a letter outside
    `a-z`. Deleting it - which is what the old `[^a-z0-9\\s-]` did - produced a
    map link (`#ablufe`) that pointed at no heading in the shard it named."""
    assert _anchor("Abläufe") == "abläufe"
    assert _anchor("Größere Muster") == "größere-muster"
    # Punctuation is still dropped and any run of whitespace still collapses to
    # a single hyphen.
    assert _anchor("Tools & Utilities (v2)") == "tools-utilities-v2"


def test_area_titles_are_read_from_every_type_spec_not_only_entity(plan, kb_dir):
    """Gitea #59: the title lookup used to resolve `entity` by name and read
    only its `layout:`, so a second type declaring one got `.title()` on its
    directory name (`Protocols`) instead of the title it declared. The concept
    areas are the first case; nothing about them is special."""
    concepts = _shard(plan, kb_dir, "concepts")
    declared = _area_title("protocol", "types/concept.md")
    assert f"## {declared}" in concepts
    assert "## Protocols" not in concepts


def test_summary_prefers_frontmatter_then_falls_back_to_body(plan, kb_dir):
    entities = _shard(plan, kb_dir, "entities")
    assert "Server hosting DocStore with ZFS storage" in entities  # frontmatter
    assert "Deploy tool." in entities  # first line of ## Description


def test_shards_are_marked_generated(plan, kb_dir):
    assert all(content.startswith("<!-- Generated by") for content in plan.values())


# --- sharding threshold -----------------------------------------------------


def test_area_over_the_threshold_gets_its_own_shard(kb_dir):
    for n in range(SHARD_THRESHOLD + 1):
        write_page(
            kb_dir / f"entities/tools/tool-{n:03d}.md",
            {
                "type": "types/entity.md", "entity_type": "tool",
                "created": "2026-08-01", "modified": "2026-08-01",
                "summary": f"Tool {n}",
            },
            f"\n# tool-{n:03d}\n",
        )
    plan = plan_index(kb_dir)

    tools_shard = kb_dir / "entities" / "tools" / GENERATED_INDEX
    assert tools_shard in plan
    assert "[[tool-000]]" in plan[tools_shard]

    # The collection shard links to it instead of inlining the rows again.
    entities = _shard(plan, kb_dir, "entities")
    assert "[[tool-000]]" not in entities
    assert f"tools/{GENERATED_INDEX}" in entities
    # ...and the map points straight at the area's own shard.
    assert f"entities/tools/{GENERATED_INDEX}" in plan[kb_dir / "index.md"]


def test_area_at_the_threshold_stays_inlined(kb_dir):
    for n in range(SHARD_THRESHOLD - 1):  # +1 existing tool = exactly threshold
        write_page(
            kb_dir / f"entities/tools/tool-{n:03d}.md",
            {
                "type": "types/entity.md", "entity_type": "tool",
                "created": "2026-08-01", "modified": "2026-08-01", "summary": "x",
            },
            f"\n# tool-{n:03d}\n",
        )
    plan = plan_index(kb_dir)
    assert kb_dir / "entities" / "tools" / GENERATED_INDEX not in plan
    assert "[[tool-000]]" in _shard(plan, kb_dir, "entities")


# --- stale shards -----------------------------------------------------------


def test_stale_shard_is_detected(kb_dir, plan):
    orphan = kb_dir / "entities" / "people" / GENERATED_INDEX
    orphan.write_text("# leftover\n", encoding="utf-8")
    assert stale_shards(kb_dir, plan) == [orphan]


def test_planned_shards_are_not_stale(kb_dir, plan):
    for path, content in plan.items():
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(content, encoding="utf-8")
    assert stale_shards(kb_dir, plan_index(kb_dir)) == []


# --- interaction with the scanner -------------------------------------------


def test_scanner_ignores_generated_shards_at_any_depth(kb_dir, plan):
    """A shard lists every page in its subtree as a wikilink. Counted as a page
    it would make every page look linked-to and silence the orphan check."""
    for path, content in plan.items():
        path.parent.mkdir(parents=True, exist_ok=True)
        path.write_text(content, encoding="utf-8")
    (kb_dir / "entities" / "systems" / GENERATED_INDEX).write_text("# x\n", encoding="utf-8")

    scanned = {p.name for p in iter_kb_pages(kb_dir)}
    assert GENERATED_INDEX not in scanned
    assert "COLLECTION.md" not in scanned


def test_rebuild_is_idempotent(kb_dir):
    assert plan_index(kb_dir) == plan_index(kb_dir)


def test_rebuild_warns_about_a_nested_page_without_failing(kb_dir, capsys):
    """#57: `group_pages` still folds a nested page into its area silently -
    that part is unchanged, reporting is the fix - so `index rebuild` warns
    rather than refusing, and must not raise."""
    write_page(
        kb_dir / "entities/projects/someowner/nested-tool.md",
        {"type": "types/entity.md", "entity_type": "project", "tags": [],
         "created": "2026-07-25", "modified": "2026-07-25",
         "related": [], "sources": []},
        "\n# nested-tool\n",
    )
    index_rebuild(dry_run=False)
    out = capsys.readouterr().out
    assert "WARNING" in out
    assert "nested-tool" in out


def test_rebuild_is_silent_about_a_healthy_tree(kb_dir, capsys):
    index_rebuild(dry_run=False)
    assert "WARNING" not in capsys.readouterr().out