Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

14.3 KB
Raw Blame
"""What an ordinary response says about the index's scope, and what it costs.

The canonical scope answers a question almost no call asks, and it was riding
on every response: about 900 characters, roughly a third of a small
``get_symbol`` reply. The digest keeps the part that changes how an answer
should be read and names where the rest lives.
"""

from __future__ import annotations

import json
from pathlib import Path
from typing import Any

import pytest

from repowise.core.index_scope import (
    INDEX_SCOPE_ENV,
    compact_index_scope,
    index_scope_fingerprint,
    resolve_index_scope,
)
from repowise.server.mcp_server import _meta


class _Repo:
    def __init__(self, path: Path) -> None:
        self.local_path = str(path)
        self.head_commit = "abc123def456"
        self.indexed_at = "2026-09-16T00:00:00+00:00"


def _write_state(path: Path, state: dict[str, Any]) -> _Repo:
    repowise_dir = path / ".repowise"
    repowise_dir.mkdir(exist_ok=True)
    (repowise_dir / "state.json").write_text(json.dumps(state), encoding="utf-8")
    return _Repo(path)


_FULL_STATE: dict[str, Any] = {
    "run_mode": "standard",
    "git_tier": "full",
    "docs_mode": "llm",
    "index_scope": {
        "git_commit_cap": 500,
        "file_pages": {"eligible": 2499, "generated": 2247, "omitted": 252},
        "provider": {"name": "openai", "model": "a-model", "embedder": "openai"},
        "search": {"full_text": "available", "semantic": "available"},
    },
    "git_history_coverage": {"eligible_files": 4024, "retained_commits": 15360},
    "full_upgrade": {"status": "complete", "completed_stages": ["generation"]},
}


@pytest.fixture(autouse=True)
def _no_env(monkeypatch: pytest.MonkeyPatch) -> None:
    monkeypatch.delenv(INDEX_SCOPE_ENV, raising=False)
    monkeypatch.setattr(_meta, "read_live_head", lambda _p: None)


def _chars(value: Any) -> int:
    return len(json.dumps(value, separators=(",", ":"), default=str))


_WHOLE_PAGES = {"eligible": 10, "generated": 10, "omitted": 0}


def _scope_with(**overrides: Any) -> dict[str, Any]:
    """A canonical scope from the full fixture, with sub-blocks replaced."""
    return resolve_index_scope(
        {**_FULL_STATE, "index_scope": {**_FULL_STATE["index_scope"], **overrides}}
    )


def _status_of(**overrides: Any) -> str:
    return compact_index_scope(_scope_with(**overrides))["status"]


# --- the projection itself -------------------------------------------------


def test_the_digest_keeps_what_changes_how_an_answer_reads() -> None:
    scope = resolve_index_scope(_FULL_STATE)
    compact = compact_index_scope(scope)

    assert compact is not None
    assert compact["run_mode"] == "standard"
    assert compact["content_provenance"] == "model"
    assert compact["git_tier"] == "full"
    assert compact["projection"] == "compact"
    # Says outright that it is not the whole thing, and where the rest is.
    assert compact["full"] == 'get_overview(include=["scope"])'


def test_the_digest_is_a_fraction_of_the_scope_it_stands_for() -> None:
    scope = resolve_index_scope(_FULL_STATE)

    assert _chars(compact_index_scope(scope)) < _chars(scope) * 0.5


def test_nothing_to_project_stays_nothing() -> None:
    assert compact_index_scope(None) is None


@pytest.mark.parametrize(
    ("state", "expected"),
    [
        ({**_FULL_STATE, "full_upgrade": {"status": "running"}}, "upgrading"),
        ({**_FULL_STATE, "full_upgrade": {"status": "resumable"}}, "upgrading"),
        ({**_FULL_STATE, "full_upgrade": {"status": "failed"}}, "degraded"),
        ({**_FULL_STATE, "degraded": ["health"]}, "degraded"),
        (_FULL_STATE, "partial"),
    ],
)
def test_status_names_the_condition_that_explains_the_rest(
    state: dict[str, Any], expected: str
) -> None:
    assert compact_index_scope(resolve_index_scope(state))["status"] == expected


def test_a_pending_upgrade_with_a_provider_is_upgrading() -> None:
    state = {**_FULL_STATE, "full_upgrade": {"status": "pending"}}
    assert compact_index_scope(resolve_index_scope(state))["status"] == "upgrading"


def _keyless_state(embedder: str | None, **scope: Any) -> dict[str, Any]:
    """The scope a default keyless init stamps: no provider, no semantic vectors."""
    return {
        **_FULL_STATE,
        "docs_mode": "deterministic",
        "index_scope": {
            "git_commit_cap": 500,
            "file_pages": _WHOLE_PAGES,
            "provider": {"name": None, "embedder": embedder},
            "search": {"full_text": "available", "semantic": "unavailable"},
            **scope,
        },
        "full_upgrade": {"status": "pending"},
    }


@pytest.mark.parametrize("embedder", ["mock", None])
def test_a_finished_keyless_index_reads_complete(embedder: str | None) -> None:
    """Nothing takes a keyless pending upgrade up, and no semantic leg was meant."""
    state = _keyless_state(embedder)
    assert compact_index_scope(resolve_index_scope(state))["status"] == "complete"


@pytest.mark.parametrize("embedder", ["mock", None])
def test_a_keyless_index_with_omitted_pages_reads_partial(embedder: str | None) -> None:
    state = _keyless_state(embedder, file_pages={"eligible": 10, "generated": 8, "omitted": 2})
    assert compact_index_scope(resolve_index_scope(state))["status"] == "partial"


def test_a_fast_keyless_index_with_no_pages_reads_partial() -> None:
    state = _keyless_state(
        "mock",
        file_pages={"eligible": 10, "generated": 0, "omitted": 10},
        analysis={"skipped": ["generation"]},
        search={"full_text": "unavailable", "semantic": "unavailable"},
    )
    assert compact_index_scope(resolve_index_scope(state))["status"] == "partial"


def test_a_keyless_index_whose_real_embedder_failed_is_degraded() -> None:
    state = _keyless_state("openai")
    assert compact_index_scope(resolve_index_scope(state))["status"] == "degraded"


def test_omitted_pages_are_never_reported_as_complete() -> None:
    """A partial index must not read as a whole one to save a word."""
    scope = resolve_index_scope(_FULL_STATE)
    assert scope["file_pages"]["omitted"] == 252

    assert compact_index_scope(scope)["status"] != "complete"


def test_a_whole_index_says_so() -> None:
    assert _status_of(file_pages=_WHOLE_PAGES) == "complete"


# --- the fingerprint -------------------------------------------------------


def test_the_same_scope_fingerprints_the_same() -> None:
    scope = resolve_index_scope(_FULL_STATE)

    assert index_scope_fingerprint(scope) == index_scope_fingerprint(
        resolve_index_scope(_FULL_STATE)
    )


def test_a_changed_scope_fingerprints_differently() -> None:
    """The point of carrying it: a held copy can be checked without resending."""
    other = resolve_index_scope({**_FULL_STATE, "run_mode": "fast"})

    assert index_scope_fingerprint(resolve_index_scope(_FULL_STATE)) != (
        index_scope_fingerprint(other)
    )


# --- what a response carries -----------------------------------------------


def test_a_routine_response_carries_the_digest(tmp_path: Path) -> None:
    out = _meta.build_meta(repository=_write_state(tmp_path, _FULL_STATE))

    assert out["index_scope"]["projection"] == "compact"
    assert "git_history_coverage" not in out["index_scope"]


def test_a_complete_index_leaves_the_digest_off(tmp_path: Path) -> None:
    """``complete`` restates the default, so only a gap rides on a response."""
    whole = {
        **_FULL_STATE,
        "index_scope": {**_FULL_STATE["index_scope"], "file_pages": _WHOLE_PAGES},
    }
    out = _meta.build_meta(repository=_write_state(tmp_path, whole))

    assert "index_scope" not in out


def test_an_orientation_call_carries_the_whole_scope(tmp_path: Path) -> None:
    out = _meta.build_meta_with_full_scope(
        repository=_write_state(tmp_path, _FULL_STATE)
    )

    assert out["index_scope"]["git_history_coverage"]["eligible_files"] == 4024
    assert "projection" not in out["index_scope"]


def test_the_environment_restores_the_old_shape_everywhere(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """The compatibility window for a reader that parses the whole object."""
    monkeypatch.setenv(INDEX_SCOPE_ENV, "full")

    out = _meta.build_meta(repository=_write_state(tmp_path, _FULL_STATE))

    assert out["index_scope"]["file_pages"]["eligible"] == 2499
    assert "projection" not in out["index_scope"]


def test_the_digest_stays_under_a_fixed_ceiling(tmp_path: Path) -> None:
    """The measured regression was ~900 characters on every response.

    A fixed ceiling rather than a ratio against the canonical object: tying
    the digest's budget to the size of the thing it replaced would tighten
    this bar every time a diagnostic is added to that object, and fail a test
    about the digest for a reason that has nothing to do with it.
    """
    compact = _meta.build_meta(repository=_write_state(tmp_path, _FULL_STATE))

    assert _chars(compact["index_scope"]) <= 300


def test_a_repo_with_no_state_still_carries_no_scope(tmp_path: Path) -> None:
    out = _meta.build_meta(repository=_Repo(tmp_path))

    assert "index_scope" not in out


# --- absence of evidence is not completeness -------------------------------


def test_an_index_that_never_recorded_its_coverage_says_unknown() -> None:
    """The invariant: a missing result is never reported as a clean result.

    Every field the fold reads projects as ``unknown``/``None`` for a legacy
    index, and reading that as "nothing is wrong" would launder silence into
    a claim of completeness.
    """
    assert compact_index_scope(resolve_index_scope({}))["status"] == "unknown"


def test_an_index_with_no_scope_key_says_unknown() -> None:
    state = {"run_mode": "standard", "git_tier": "full", "docs_mode": "llm"}

    assert compact_index_scope(resolve_index_scope(state))["status"] == "unknown"


def _legs(**override: str) -> dict[str, str]:
    return {"full_text": "available", "semantic": "available", **override}


@pytest.mark.parametrize("leg", ["full_text", "semantic"])
def test_an_unavailable_search_leg_is_degraded(leg: str) -> None:
    assert _status_of(search=_legs(**{leg: "unavailable"})) == "degraded"


@pytest.mark.parametrize("leg", ["full_text", "semantic"])
def test_a_pending_search_leg_is_partial(leg: str) -> None:
    """Pending means not usable yet — smaller than failed, larger than fine."""
    status = _status_of(file_pages=_WHOLE_PAGES, search=_legs(**{leg: "pending"}))

    assert status == "partial"


def test_skipped_analysis_is_partial() -> None:
    status = _status_of(
        file_pages=_WHOLE_PAGES, analysis={"skipped": ["performance"]}
    )

    assert status == "partial"


def test_a_degraded_index_names_what_degraded() -> None:
    """"health failed" and "the graph failed" are not the same warning."""
    state = {**_FULL_STATE, "degraded": ["health"]}

    compact = compact_index_scope(resolve_index_scope(state))

    assert compact["status"] == "degraded"
    assert compact["degraded_analyses"] == ["health"]
    assert "degraded_analyses_total" not in compact


def test_a_long_degraded_list_is_sampled_with_its_count() -> None:
    """The canonical scope keeps every entry; the compact one names a few and counts all."""
    names = [f"skipped file {i}" for i in range(17)]
    scope = resolve_index_scope({**_FULL_STATE, "degraded": names})

    compact = compact_index_scope(scope)

    assert compact["degraded_analyses"] == sorted(names)[:3]
    assert compact["degraded_analyses_total"] == 17
    assert compact["degraded_analyses_emitted"] == 3
    assert compact["degraded_analyses_reduced_reason"] == "compact_projection"
    assert len(scope["analysis"]["unavailable"]) == 17


def test_a_real_analysis_id_survives_a_flood_of_run_warnings() -> None:
    """Warnings with a leading space sort first alphabetically; the id still shows."""
    warnings = [f"  Warning: failed to trace step {i}" for i in range(16)]
    scope = resolve_index_scope({**_FULL_STATE, "degraded": [*warnings, "dead_code"]})

    compact = compact_index_scope(scope)

    assert compact["degraded_analyses"][0] == "dead_code"
    assert compact["degraded_analyses_total"] == 17


def test_a_sound_index_carries_no_degraded_names() -> None:
    assert "degraded_analyses" not in compact_index_scope(
        resolve_index_scope(_FULL_STATE)
    )


# --- the fingerprint has to be on both shapes ------------------------------


def test_the_held_copy_carries_the_fingerprint_too(tmp_path: Path) -> None:
    """Checking a held copy needs the fingerprint on the copy, not only the
    digest that would be compared against it."""
    repository = _write_state(tmp_path, _FULL_STATE)

    compact = _meta.build_meta(repository=repository)["index_scope"]
    full = _meta.build_meta_with_full_scope(repository=repository)["index_scope"]

    assert full["fingerprint"] == compact["fingerprint"]


def test_the_fingerprint_refuses_what_it_cannot_canonicalise() -> None:
    """A silent str() fallback would churn the digest every process."""
    with pytest.raises(TypeError):
        index_scope_fingerprint({"version": 1, "odd": object()})


# --- where the rest actually lives -----------------------------------------


def test_the_pointer_names_the_repo_argument_in_workspace_mode(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """The digest names the repo argument: in a workspace it picks the repo."""
    from repowise.server.mcp_server import _state

    monkeypatch.setattr(_state, "_registry", object(), raising=False)

    out = _meta.build_meta(repository=_write_state(tmp_path, _FULL_STATE))

    assert out["index_scope"]["full"] == 'get_overview(repo=..., include=["scope"])'


def test_the_pointer_is_a_plain_call_for_a_single_repo(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    from repowise.server.mcp_server import _state

    monkeypatch.setattr(_state, "_registry", None, raising=False)

    out = _meta.build_meta(repository=_write_state(tmp_path, _FULL_STATE))

    assert out["index_scope"]["full"] == 'get_overview(include=["scope"])'


def test_the_window_opens_without_a_restart(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    """A client spawns this server; it cannot be told to start again."""
    repository = _write_state(tmp_path, _FULL_STATE)
    assert _meta.build_meta(repository=repository)["index_scope"]["projection"]

    monkeypatch.setenv(INDEX_SCOPE_ENV, "full")

    assert "projection" not in _meta.build_meta(repository=repository)["index_scope"]