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
"""No recoverable state may reach the agent as a protocol-level isError.
An early isError teaches an agent to abandon the MCP server for the whole
session, so the failure shield must convert every exception that escapes a
tool handler — including the un-init'd-repo LookupError that previously fired
on EVERY tool's first call — into a success-shaped dict with a remedy.
"""
from __future__ import annotations
import inspect
import pytest
from repowise.server.mcp_server._failure_shield import shield
@pytest.fixture
async def empty_mcp(factory, fts, vector_store):
"""MCP globals wired to an EMPTY database — the un-init'd repo state."""
import repowise.server.mcp_server as mcp_mod
mcp_mod._session_factory = factory
mcp_mod._fts = fts
mcp_mod._vector_store = vector_store
mcp_mod._repo_path = "/tmp/test-repo"
yield
mcp_mod._session_factory = None
mcp_mod._fts = None
mcp_mod._vector_store = None
mcp_mod._repo_path = None
@pytest.mark.asyncio
async def test_uninitialized_repo_is_success_shaped(empty_mcp):
"""The 'No repositories found' LookupError becomes guidance, not isError."""
from repowise.server.mcp_server import get_symbol
result = await shield(get_symbol)("pkg/mod.py::alpha")
assert isinstance(result, dict) # no exception escaped
assert "no repowise index" in result["error"].lower()
assert "repowise init" in result["remedy"]
# The user decides whether to index; the agent must not run init itself.
assert "user" in result["remedy"]
# Session-scoped guidance: fall back to the agent's own tools, named by
# capability rather than by one host's tool names.
assert "file-reading and searching tools" in result["guidance"]
assert "Read/Grep/Glob" not in result["guidance"]
@pytest.mark.asyncio
async def test_unknown_repo_alias_is_success_shaped(setup_mcp):
from repowise.server.mcp_server import get_symbol
result = await shield(get_symbol)("pkg/mod.py::alpha", repo="no-such-repo")
assert "no-such-repo" in result["error"]
assert "list_repos" in result["remedy"]
@pytest.mark.asyncio
async def test_workspace_unknown_repo_valueerror_is_success_shaped():
"""Workspace mode raises ValueError (not LookupError) for a bad alias —
caught live on a real workspace server before this branch existed."""
async def workspace_tool(repo: str) -> dict:
raise ValueError(f"Unknown repo {repo!r}. Available: ['a', 'b']")
result = await shield(workspace_tool)("no-such-repo")
assert "no-such-repo" in result["error"]
assert "list_repos" in result["remedy"]
assert "Retry" not in result.get("guidance", "")
@pytest.mark.asyncio
async def test_a_store_older_than_the_models_says_run_update_not_give_up():
"""Drift ``init_db`` cannot repair must not read as an internal crash.
Every read path now reconciles *additive* drift, so a ``no such column``
that still reaches here is the kind ``_reconcile_schema`` deliberately
skips — a removed or renamed column, a changed type. The generic shape
tells the caller to stop using the tool for the rest of the session, which
is the worst possible advice when one ``repowise update`` fixes it.
"""
from sqlalchemy.exc import OperationalError
async def stale_store_tool() -> dict:
raise OperationalError(
"SELECT repositories.churn_anchor_sha FROM repositories",
{},
Exception("no such column: repositories.churn_anchor_sha"),
)
result = await shield(stale_store_tool)()
assert "predates the installed repowise" in result["error"]
# First line only — SQLAlchemy appends the whole compiled statement.
assert "\n" not in result["error"]
assert "repowise update" in result["remedy"]
assert "user" in result["remedy"]
assert "Retry this call once" not in result.get("guidance", "")
# The same capability wording as the not-indexed shape; this is the second
# of the two sites, and a host tool name here would not travel either.
assert "file-reading and searching tools" in result["guidance"]
assert "Read/Grep/Glob" not in result["guidance"]
@pytest.mark.asyncio
async def test_an_unrelated_operationalerror_keeps_the_internal_error_shape():
"""The stale-index branch is keyed on the message, so guard the negative."""
from sqlalchemy.exc import OperationalError
async def locked_db_tool() -> dict:
raise OperationalError("SELECT 1", {}, Exception("database is locked"))
result = await shield(locked_db_tool)()
assert "predates" not in result["error"]
assert "Retry this call once" in result["guidance"]
@pytest.mark.asyncio
async def test_the_users_own_question_cannot_fake_a_stale_index():
"""`str()` on a SQLAlchemy error appends the statement AND its parameters.
`get_answer` binds the caller's question as a parameter, so matching the
full string let someone who merely ASKS about "no such column" be told
their index is stale and to re-index — over what is really a transient
lock. Match the driver's own message instead.
"""
from sqlalchemy.exc import OperationalError
async def locked_while_asking_about_columns() -> dict:
raise OperationalError(
"INSERT INTO answer_cache (question, payload) VALUES (?, ?)",
("why do I get no such column errors when I upgrade?", "{}"),
Exception("database is locked"),
)
result = await shield(locked_while_asking_about_columns)()
assert "predates" not in result["error"], result["error"]
assert "Retry this call once" in result["guidance"]
@pytest.mark.asyncio
async def test_a_server_older_than_the_checkout_says_restart_not_give_up():
"""A long-running server's lazy import of a name only the new checkout has.
The generic shape tells the caller to drop the tool for the session; a
restart fixes it, so say that instead.
"""
async def stale_server_tool() -> dict:
from repowise.core.ingestion.type_names import name_added_after_server_start # noqa: F401
return {}
result = await shield(stale_server_tool)()
assert "older repowise code than this checkout" in result["error"]
assert "Restart the MCP server" in result["error"]
assert "user" in result["remedy"]
assert "guidance" not in result
@pytest.mark.asyncio
async def test_a_removed_repowise_module_is_also_a_stale_server():
async def stale_server_tool() -> dict:
import repowise.core.module_removed_from_checkout # noqa: F401
return {}
result = await shield(stale_server_tool)()
assert "Restart the MCP server" in result["error"]
@pytest.mark.asyncio
async def test_a_missing_dependency_keeps_the_internal_error_shape():
async def missing_dep_tool() -> dict:
import repowise_no_such_dependency # noqa: F401
return {}
result = await shield(missing_dep_tool)()
assert "ModuleNotFoundError" in result["error"]
assert "Retry this call once" in result["guidance"]
@pytest.mark.asyncio
async def test_unexpected_exception_is_success_shaped():
async def exploding_tool(x: int) -> dict:
raise RuntimeError("boom")
result = await shield(exploding_tool)(1)
assert "RuntimeError" in result["error"]
assert "exploding_tool" in result["error"]
assert "Retry this call once" in result["guidance"]
@pytest.mark.asyncio
async def test_successful_result_passes_through_untouched():
async def fine_tool() -> dict:
return {"answer": 42}
assert await shield(fine_tool)() == {"answer": 42}
def test_shield_preserves_signature_for_fastmcp_schema():
async def tool_fn(symbol_id: str, context_lines: int = 0) -> dict:
return {}
wrapped = shield(tool_fn)
assert wrapped.__name__ == "tool_fn"
assert str(inspect.signature(wrapped)) == str(inspect.signature(tool_fn))
def test_sync_callables_pass_through():
def sync_fn() -> dict:
return {}
assert shield(sync_fn) is sync_fn
@pytest.mark.asyncio
async def test_server_composes_shield_into_middleware():
"""Pin the __init__.py wiring: every registered tool goes through the
shield. Without this, a refactor could silently drop the composition and
reopen the isError-on-every-tool hole.
Asserted through behaviour rather than by matching the composition's
source text, so reordering or renaming the layers cannot fail this while
the guarantee still holds — nor pass while it does not.
"""
from repowise.server.mcp_server import tool_middleware
async def exploding_tool() -> dict:
raise RuntimeError("boom")
result = await tool_middleware(exploding_tool)()
assert isinstance(result, dict), "an exception escaped the shield"
assert "boom" not in repr(result).lower() or "error" in repr(result).lower()
# ---------------------------------------------------------------------------
# Import warm-up gate
#
# The deferred `import lancedb` runs on a worker thread and holds Python's
# import locks. A tool body that lazily imports while it is in flight blocks
# against it, and the event loop stops making progress — which also stops the
# asyncio timeouts that would otherwise cap the call from ever firing. The
# observed symptom was the first tool call of a session never returning. The
# shield holds calls until the import is done so the two never overlap.
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
async def test_tool_waits_for_the_lancedb_import(monkeypatch):
"""A call that arrives mid-import runs only after the import signals done."""
import asyncio
from repowise.server.mcp_server import _state
ready = asyncio.Event()
monkeypatch.setattr(_state, "_lancedb_ready", ready, raising=False)
started = asyncio.Event()
async def tool() -> dict:
started.set()
return {"ok": True}
task = asyncio.create_task(shield(tool)())
await asyncio.sleep(0.05)
assert not started.is_set(), "handler body ran while the import was in flight"
ready.set()
assert await task == {"ok": True}
assert started.is_set()
@pytest.mark.asyncio
async def test_no_wait_once_the_import_is_done(monkeypatch):
"""A warmed server pays nothing: the gate is a set-Event check."""
import asyncio
from repowise.server.mcp_server import _state
ready = asyncio.Event()
ready.set()
monkeypatch.setattr(_state, "_lancedb_ready", ready, raising=False)
async def tool() -> dict:
return {"ok": True}
assert await shield(tool)() == {"ok": True}
@pytest.mark.asyncio
async def test_no_gate_when_no_import_was_started(monkeypatch):
"""No background import (no event) means no wait at all."""
from repowise.server.mcp_server import _state
monkeypatch.setattr(_state, "_lancedb_ready", None, raising=False)
async def tool() -> dict:
return {"ok": True}
assert await shield(tool)() == {"ok": True}
@pytest.mark.asyncio
async def test_gate_is_bounded(monkeypatch):
"""A pathological import degrades to a slow answer, never a stuck client."""
import asyncio
# Reach the module through importlib: the package re-exports `shield`
# under the name `_failure_shield`, so attribute access finds the function
# rather than the submodule.
import importlib
from repowise.server.mcp_server import _state
shield_mod = importlib.import_module("repowise.server.mcp_server._failure_shield")
monkeypatch.setattr(_state, "_lancedb_ready", asyncio.Event(), raising=False)
monkeypatch.setattr(shield_mod, "_WARMUP_TIMEOUT_S", 0.05)
async def tool() -> dict:
return {"ok": True}
assert await shield(tool)() == {"ok": True}
@pytest.mark.asyncio
@pytest.mark.parametrize(
("exc", "reason"),
[
(LookupError("No repositories found. Run repowise init."), "no_index"),
(LookupError("Repository 'x' not found"), "not_found"),
(ValueError("Unknown repo 'x'. Available: []"), "not_found"),
(RuntimeError("boom"), "internal"),
],
)
async def test_a_shielded_failure_notes_its_reason_code(exc, reason):
"""The mcp_tool_call event says why, from a fixed code, never the message."""
from repowise.server.mcp_server._savings import interaction
async def get_answer() -> dict:
raise exc
with interaction.begin("get_answer") as live:
result = await shield(get_answer)()
assert result["error"]
assert live.error_reason == reason