Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
"""``get_context(include=["doc_drift"])`` — the drift reverse view.
The drift pass files a finding against the *document*, so a question asked
about a code file can only be answered from the stored reference rows. What
these tests pin is the honesty of that answer: the two claims it makes must
stay apart, and an answer it cannot support must not render as a confident
zero. "No document mentions src/auth.py" is a far stronger statement than "no
drift findings", and an unpopulated store produces it silently.
"""
from __future__ import annotations
import pytest
from sqlalchemy.exc import OperationalError
from repowise.core.analysis.doc_drift.constants import REFERENCE_BASIS
from repowise.core.persistence.models import DocDriftFinding, DocDriftReference
_TARGET = "src/auth/service.py"
def _ref(repo_id: str, document: str, line: int, **kw) -> DocDriftReference:
return DocDriftReference(
repository_id=repo_id,
document_path=document,
target_path=kw.get("target", _TARGET),
kind=kw.get("kind", "path"),
line_number=line,
section=kw.get("section", "Authentication"),
)
def _finding(repo_id: str, document: str, line: int) -> DocDriftFinding:
return DocDriftFinding(
repository_id=repo_id,
file_path=document,
line_number=line,
kind="path",
target="src/gone.py",
confidence=0.9,
reason="Document names src/gone.py, which no longer exists.",
origin="path_no_candidate",
evidence_json="[]",
raw="src/gone.py",
context="see src/gone.py",
)
@pytest.fixture
async def reference_rows(session, repo_id):
session.add_all(
[
_ref(repo_id, "docs/auth.md", 12),
_ref(repo_id, "docs/auth.md", 40, kind="link"),
_ref(repo_id, "docs/overview.md", 3, section=""),
# A different file entirely: it must not reach the answer.
_ref(repo_id, "docs/db.md", 5, target="src/db/models.py"),
]
)
await session.commit()
return repo_id
@pytest.mark.asyncio
async def test_the_block_is_absent_until_it_is_asked_for(setup_mcp, reference_rows):
from repowise.server.mcp_server import get_context
card = (await get_context(targets=[_TARGET]))["targets"][_TARGET]
assert "doc_drift" not in card
@pytest.mark.asyncio
async def test_doc_drift_is_a_known_include_key(setup_mcp, reference_rows):
"""An unrecognised key lands in ignored_arguments, so this would be visible."""
from repowise.server.mcp_server import get_context
result = await get_context(targets=[_TARGET], include=["doc_drift"])
ignored = [
value
for entry in (result.get("ignored_arguments") or [])
for value in entry.get("values", [])
]
assert "doc_drift" not in ignored
@pytest.mark.asyncio
async def test_it_answers_with_the_documents_that_name_this_file(
setup_mcp, reference_rows
):
from repowise.server.mcp_server import get_context
card = (await get_context(targets=[_TARGET], include=["doc_drift"]))["targets"][
_TARGET
]
block = card["doc_drift"]
assert [r["document"] for r in block["references"]] == [
"docs/auth.md",
"docs/auth.md",
"docs/overview.md",
]
assert block["documents"] == 2
assert block["references"][0] == {
"document": "docs/auth.md",
"line": 12,
"kind": "path",
"section": "Authentication",
}
@pytest.mark.asyncio
async def test_a_reference_to_another_file_stays_out_of_the_answer(
setup_mcp, reference_rows
):
"""The reverse index is keyed by target; a leak here answers the wrong question."""
from repowise.server.mcp_server import get_context
card = (await get_context(targets=[_TARGET], include=["doc_drift"]))["targets"][
_TARGET
]
assert "docs/db.md" not in {r["document"] for r in card["doc_drift"]["references"]}
@pytest.mark.asyncio
async def test_the_basis_rides_along_even_when_nothing_was_found(
setup_mcp, reference_rows
):
"""The empty answer is the one most likely to be read as proof of absence."""
from repowise.server.mcp_server import get_context
result = await get_context(
targets=["src/auth/middleware.py"], include=["doc_drift"]
)
block = result["targets"]["src/auth/middleware.py"]["doc_drift"]
assert block["references"] == []
assert block["documents"] == 0
assert block["references_basis"] == REFERENCE_BASIS
@pytest.mark.asyncio
async def test_an_unpopulated_store_is_not_reported_as_a_clean_tree(setup_mcp, repo_id):
"""The gate this slice had to settle.
The table is created on the ordinary schema-reconcile path, but the pass
only runs when an update has work to do. "Upgraded, never analysed" is a
real state, and without this it is indistinguishable from "no document
mentions this file" --- a far stronger claim, wrong in the same silent way.
"""
from repowise.server.mcp_server import get_context
card = (await get_context(targets=[_TARGET], include=["doc_drift"]))["targets"][
_TARGET
]
assert card["doc_drift"] == {"unavailable": "not_computed"}
@pytest.mark.asyncio
async def test_an_index_without_the_reference_table_says_so(
setup_mcp, reference_rows, monkeypatch
):
""""Could not read" must never render as "nothing to report"."""
import repowise.server.mcp_server.tool_context.enrichment as enrichment
from repowise.server.mcp_server import get_context
async def _raise(*_a, **_k):
raise OperationalError(
"select", {}, Exception("no such table: doc_drift_references")
)
monkeypatch.setattr(enrichment, "get_doc_drift_references", _raise)
result = await get_context(targets=[_TARGET], include=["doc_drift"])
card = result["targets"][_TARGET]
assert card["doc_drift"] == {"unavailable": "index_predates_doc_drift"}
# And the failed read did not take the rest of the card with it.
assert card["type"] == "file"
assert "docs" in card
@pytest.mark.asyncio
async def test_a_transient_read_failure_is_not_reported_as_an_old_index(
setup_mcp, reference_rows, monkeypatch
):
""""Reindex" is the wrong advice for a locked database.
Both refusals name a cause the reader will act on, so mapping every
failure onto the schema one sends them to rebuild an index that was
never the problem.
"""
import repowise.server.mcp_server.tool_context.enrichment as enrichment
from repowise.server.mcp_server import get_context
async def _raise(*_a, **_k):
raise OperationalError("select", {}, Exception("database is locked"))
monkeypatch.setattr(enrichment, "get_doc_drift_references", _raise)
card = (await get_context(targets=[_TARGET], include=["doc_drift"]))["targets"][
_TARGET
]
assert card["doc_drift"] == {"unavailable": "drift_read_failed"}
@pytest.mark.asyncio
async def test_one_link_with_a_fragment_is_counted_once(setup_mcp, session, repo_id):
"""The store keeps the link and the anchor apart; a reader counts mentions.
``[guide](x.py#top)`` yields both a link row and an anchor row at the same
site, because the two drift apart and a finding has to name which. Showing
the reader the same document and line twice over-reports how many places
mention the file, and spends two of twenty card slots saying it.
"""
from repowise.server.mcp_server import get_context
session.add_all(
[
_ref(repo_id, "docs/auth.md", 12, kind="link"),
_ref(repo_id, "docs/auth.md", 12, kind="anchor"),
]
)
await session.commit()
block = (await get_context(targets=[_TARGET], include=["doc_drift"]))["targets"][
_TARGET
]["doc_drift"]
assert len(block["references"]) == 1
assert block["documents"] == 1
@pytest.mark.asyncio
async def test_an_answer_emptied_by_exclusions_says_so(
setup_mcp, session, repo_id, monkeypatch
):
"""An excluded document is not an absent one.
Without the count, a repository whose documentation directory is excluded
reports every file in it as mentioned by nothing --- the same false claim
the unpopulated-store guard exists to prevent, reached by another route.
"""
import repowise.server.mcp_server.tool_context.context as context_mod
from repowise.server.mcp_server import get_context
session.add(_ref(repo_id, "docs/auth.md", 12))
await session.commit()
import pathspec
# Excludes the naming document, not the target, which is the case that
# empties the answer without emptying the card.
spec = pathspec.PathSpec.from_lines("gitwildmatch", ["docs/"])
monkeypatch.setattr(context_mod, "_get_exclude_spec", lambda *_a, **_k: spec)
block = (await get_context(targets=[_TARGET], include=["doc_drift"]))["targets"][
_TARGET
]["doc_drift"]
assert block["references"] == []
assert block["references_excluded"] == 1
@pytest.mark.asyncio
async def test_a_documents_own_drift_is_reported_as_the_documents_and_not_the_targets(
setup_mcp, session, reference_rows
):
"""The easiest way for this surface to lie.
A document that describes this file and a document carrying a drifted
reference are different claims. The drifted reference here points at
``src/gone.py``, not at the target, and the block must keep that separate
rather than implying the description of the target is wrong.
"""
from repowise.server.mcp_server import get_context
session.add(_finding(reference_rows, "docs/auth.md", 90))
await session.commit()
card = (await get_context(targets=[_TARGET], include=["doc_drift"]))["targets"][
_TARGET
]
block = card["doc_drift"]
assert block["documents_with_drift"] == [{"document": "docs/auth.md", "findings": 1}]
# The reference rows themselves are untouched by it.
assert len(block["references"]) == 3
assert "which need not be about this file" in block["references_basis"]
@pytest.mark.asyncio
async def test_several_targets_in_one_call_each_get_their_own_answer(
setup_mcp, reference_rows
):
"""Targets are resolved concurrently over ONE shared session.
This block is the only enrichment helper that opens a savepoint, and
``asyncio.gather`` means a second target can enter one while the first is
still inside. If those nest, the first to exit closes the other's
transaction and every later statement in the call fails --- turning the
guard meant to isolate one bad read into the thing that breaks the rest.
"""
from repowise.server.mcp_server import get_context
result = await get_context(
targets=[_TARGET, "src/auth/middleware.py", "src/db/models.py"],
include=["doc_drift"],
)
cards = result["targets"]
assert len(cards) == 3
assert [r["document"] for r in cards[_TARGET]["doc_drift"]["references"]] == [
"docs/auth.md",
"docs/auth.md",
"docs/overview.md",
]
assert cards["src/db/models.py"]["doc_drift"]["references"] == [
{"document": "docs/db.md", "line": 5, "kind": "path", "section": "Authentication"}
]
assert cards["src/auth/middleware.py"]["doc_drift"]["references"] == []
# No target reported a failure, and the rest of each card survived.
assert not any("error" in c for c in cards.values())
assert all("docs" in c for c in cards.values())
@pytest.mark.asyncio
async def test_a_clean_document_gets_no_drift_entry(setup_mcp, reference_rows):
from repowise.server.mcp_server import get_context
card = (await get_context(targets=[_TARGET], include=["doc_drift"]))["targets"][
_TARGET
]
assert "documents_with_drift" not in card["doc_drift"]
@pytest.mark.asyncio
async def test_a_target_with_no_file_path_gets_a_null_block(setup_mcp, reference_rows):
"""A module target resolves to a directory, which nothing can reference."""
from repowise.server.mcp_server import get_context
result = await get_context(targets=["nonexistent-target-xyz"], include=["doc_drift"])
card = result["targets"]["nonexistent-target-xyz"]
assert card.get("doc_drift") in (None, {"unavailable": "not_computed"})
@pytest.mark.asyncio
async def test_the_answer_is_capped_with_a_recoverable_receipt(setup_mcp, session, repo_id):
"""Twenty documents is a card; the rest is a CLI question."""
from repowise.server.mcp_server import get_context
session.add_all([_ref(repo_id, f"docs/g{i:03d}.md", 1) for i in range(30)])
await session.commit()
card = (await get_context(targets=[_TARGET], include=["doc_drift"]))["targets"][
_TARGET
]
block = card["doc_drift"]
assert len(block["references"]) == 20
assert block["references_total"] == 30
assert block["references_omitted"] == 10
assert block["references_reduced_reason"] == "construction_cap"