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.

perf(mcp): build get_answer's graph projections once per index state (#2735)

Raghav Chamadiyac10d84734646
diff --git a/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py b/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py
index e622d428e..952acbd4f 100644
--- a/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py
+++ b/packages/server/src/repowise/server/mcp_server/_answer_pipeline.py
@@ -62,6 +62,7 @@ from repowise.server.mcp_server._graph_files import (
is_symbol_node,
keep_projected_edge,
node_to_file,
+ per_index,
)
from repowise.server.mcp_server._helpers import (
_EMBED_TIMEOUT_ENV,
@@ -824,7 +825,9 @@ async def expand_via_graph(hits: list[dict], ctx: Any, repo_id: str) -> list[dic
# and its siblings join ``path::Name`` nodes, so an equality test against
# a seed path matched none of them and the call graph was invisible here.
seed_set = set(seed_paths)
- pairs = await _projected_edges(session, repo_id)
+ pairs = await per_index(
+ session, repo_id, "projected_edges", lambda: _projected_edges(session, repo_id)
+ )
neighbors: set[str] = set()
degree: dict[str, int] = {}
diff --git a/packages/server/src/repowise/server/mcp_server/_basis.py b/packages/server/src/repowise/server/mcp_server/_basis.py
index 5a31cf766..9be407a63 100644
--- a/packages/server/src/repowise/server/mcp_server/_basis.py
+++ b/packages/server/src/repowise/server/mcp_server/_basis.py
@@ -136,12 +136,3 @@ async def call_resolution_bases(
"""One basis entry per language that has call edges in this repo."""
grouping = await _grouping(session, repo_id, cache_key)
return [_entry(lang, origins) for lang, origins in sorted(grouping.items()) if origins]
-
-
-def basis_cache_key(repository: Any) -> str:
- """A key that moves whenever the index does, cheapest field first."""
- head = getattr(repository, "head_commit", None)
- if head:
- return str(head)
- updated = getattr(repository, "updated_at", None)
- return str(updated) if updated else "unknown"
diff --git a/packages/server/src/repowise/server/mcp_server/_flow_path.py b/packages/server/src/repowise/server/mcp_server/_flow_path.py
index b7366a7b3..ef55fd475 100644
--- a/packages/server/src/repowise/server/mcp_server/_flow_path.py
+++ b/packages/server/src/repowise/server/mcp_server/_flow_path.py
@@ -44,6 +44,7 @@ from repowise.server.mcp_server._graph_files import (
file_ext,
keep_projected_edge,
node_to_file,
+ per_index,
)
# Edge kinds that form the file-level dependency graph. ``imports`` is
@@ -232,6 +233,13 @@ async def _load_file_adjacency(session: Any, repo_id: str) -> dict[str, list[str
return {node: sorted(neighbours) for node, neighbours in adj.items()}
+async def file_adjacency(session: Any, repo_id: str) -> dict[str, list[str]]:
+ """:func:`_load_file_adjacency`, built once per index state. Read-only."""
+ return await per_index(
+ session, repo_id, "file_adjacency", lambda: _load_file_adjacency(session, repo_id)
+ )
+
+
def _bfs_path(adj: dict[str, list[str]], src: str, dst: str, max_depth: int) -> list[str] | None:
"""Shortest file path between ``src`` and ``dst`` (inclusive), or None.
@@ -351,7 +359,7 @@ async def expand_via_flow_path(
endpoints.append(top_hit)
endpoints = endpoints[:_FLOW_MAX_ANCHORS]
- adj = await _load_file_adjacency(session, repo_id)
+ adj = await file_adjacency(session, repo_id)
paths: list[list[str]] = []
for i in range(len(endpoints)):
diff --git a/packages/server/src/repowise/server/mcp_server/_graph_files.py b/packages/server/src/repowise/server/mcp_server/_graph_files.py
index 7dea2467c..51ec62361 100644
--- a/packages/server/src/repowise/server/mcp_server/_graph_files.py
+++ b/packages/server/src/repowise/server/mcp_server/_graph_files.py
@@ -6,11 +6,34 @@ keyed on paths sees only the first layer until it projects the second.
Projecting also manufactures a self-loop out of every intra-file call and
stitches files across a language boundary, so the guards live here with it.
+
+A projection reads every edge of the repo, which is the slowest local step of
+an answer, and its result only moves when the index does. :func:`per_index`
+keeps one copy per index state so a question pays for the scan once.
"""
from __future__ import annotations
+import asyncio
import os
+from collections import OrderedDict
+from collections.abc import Awaitable, Callable
+from typing import Any, TypeVar
+
+from sqlalchemy import select
+
+from repowise.core.persistence.models import Repository
+from repowise.server.mcp_server._index_state import index_state_key
+
+_T = TypeVar("_T")
+
+# repo_id -> (index state key, {projection name: value}), least recently used
+# first. Bounded by repos because one entry holds whole-repo projections; a
+# workspace server keeps its members warm up to this many.
+_CACHE: OrderedDict[str, tuple[str, dict[str, Any]]] = OrderedDict()
+_CACHE_MAX_REPOS = 8
+# Concurrent cold questions would each pay the scan; one builds, the rest wait.
+_LOCK = asyncio.Lock()
# Confidence floor for ``calls`` edges. Imports are always 1.0; calls average
# 0.90 with a low-confidence tail from heuristic resolution. 0.5 keeps every
@@ -53,3 +76,49 @@ def keep_projected_edge(
if not src_file or not tgt_file or src_file == tgt_file:
return False
return file_ext(src_file) == file_ext(tgt_file)
+
+
+def reset_cache() -> None:
+ """Drop every cached projection. For tests and for a re-index in-process."""
+ _CACHE.clear()
+
+
+def _cached(repo_id: str, key: str, name: str) -> Any | None:
+ entry = _CACHE.get(repo_id)
+ if entry is None or entry[0] != key or name not in entry[1]:
+ return None
+ _CACHE.move_to_end(repo_id)
+ return entry[1][name]
+
+
+async def per_index(
+ session: Any, repo_id: str, name: str, build: Callable[[], Awaitable[_T]]
+) -> _T:
+ """``await build()``, reused until this repo's index changes.
+
+ Keyed by :func:`index_state_key`, shared with the server's other per-index
+ caches. Callers must treat the result as read-only: it is shared across
+ questions.
+ """
+ repository = (
+ await session.execute(select(Repository).where(Repository.id == repo_id))
+ ).scalar_one_or_none()
+ key = index_state_key(repository)
+ hit = _cached(repo_id, key, name)
+ if hit is not None:
+ return hit
+ async with _LOCK:
+ hit = _cached(repo_id, key, name)
+ if hit is not None:
+ return hit
+ value = await build()
+ entry = _CACHE.get(repo_id)
+ if entry is None or entry[0] != key:
+ # An older index state of this repo is never asked for again.
+ entry = (key, {})
+ _CACHE[repo_id] = entry
+ entry[1][name] = value
+ _CACHE.move_to_end(repo_id)
+ while len(_CACHE) > _CACHE_MAX_REPOS:
+ _CACHE.popitem(last=False)
+ return value
diff --git a/packages/server/src/repowise/server/mcp_server/_index_state.py b/packages/server/src/repowise/server/mcp_server/_index_state.py
new file mode 100644
index 000000000..1362f0714
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/_index_state.py
@@ -0,0 +1,29 @@
+"""One answer to "has this repo's index moved", for the server's per-index caches.
+
+The repo row is stamped when an index or update run starts, before its edges
+and layers are written, so the row alone can key a cache on a half-written
+index. ``state.json`` is saved when the run ends, so its modification time
+closes that window; it also moves on an update over uncommitted work, which
+leaves ``head_commit`` unchanged.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+_STATE_FILE = os.path.join(".repowise", "state.json")
+
+
+def index_state_key(repository: Any) -> str:
+ """Head commit, row write time and the end-of-run state file's mtime."""
+ head = getattr(repository, "head_commit", None) or ""
+ updated = getattr(repository, "updated_at", None) or ""
+ local_path = getattr(repository, "local_path", None)
+ saved = ""
+ if local_path:
+ try:
+ saved = str(os.stat(os.path.join(local_path, _STATE_FILE)).st_mtime_ns)
+ except OSError:
+ saved = ""
+ return f"{head}:{updated}:{saved}"
diff --git a/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py b/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py
index 17a768582..e6c8a44f3 100644
--- a/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py
+++ b/packages/server/src/repowise/server/mcp_server/_neighbor_rerank.py
@@ -38,7 +38,7 @@ from sqlalchemy import select
from repowise.core.persistence.models import Page
from repowise.core.providers.embedding import store_has_semantic_vectors
from repowise.server.mcp_server._answer_pipeline import question_vector, vector_search
-from repowise.server.mcp_server._flow_path import _is_plumbing, _load_file_adjacency
+from repowise.server.mcp_server._flow_path import _is_plumbing, file_adjacency
# Motion cues that mark a data-flow question. Loose on purpose: the walk (reaches
# only files near the top hits) and the single contested slot are the real
@@ -219,7 +219,7 @@ async def expand_via_neighbor_rerank(
if not seed_paths:
return hits
- adj = await _load_file_adjacency(session, repo_id)
+ adj = await file_adjacency(session, repo_id)
pool = _walk_neighborhood(adj, seed_paths) if adj else set()
if not pool:
return hits
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py b/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py
index a97e8a526..f5ee68c2d 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/projection.py
@@ -411,8 +411,8 @@ async def _refresh_freshness(payload: dict[str, Any], repo: str | None) -> None:
return
try:
from repowise.core.persistence.database import get_session
- from repowise.server.mcp_server._basis import basis_cache_key
from repowise.server.mcp_server._helpers import _get_repo, _resolve_repo_context
+ from repowise.server.mcp_server._index_state import index_state_key
from repowise.server.mcp_server._meta import freshness_from_repo
from repowise.server.mcp_server._scope import unrelated_scope_hint
@@ -424,7 +424,7 @@ async def _refresh_freshness(payload: dict[str, Any], repo: str | None) -> None:
session,
repository.id,
[path.split("::", 1)[0] for path in served],
- cache_key=f"{repository.id}:{basis_cache_key(repository)}",
+ cache_key=f"{repository.id}:{index_state_key(repository)}",
)
freshness = freshness_from_repo(repository, targets=served)
except Exception:
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/context.py b/packages/server/src/repowise/server/mcp_server/tool_context/context.py
index 90897b755..c129fb533 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/context.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/context.py
@@ -89,7 +89,7 @@ _INCLUDE_BLOCKS = frozenset(
async def _scope_hint(session: Any, repository: Any, raw_results: list[Any]) -> str | None:
"""One sentence naming index layers that hold none of the files served here."""
try:
- from repowise.server.mcp_server._basis import basis_cache_key
+ from repowise.server.mcp_server._index_state import index_state_key
from repowise.server.mcp_server._scope import unrelated_scope_hint
served = [
@@ -101,7 +101,7 @@ async def _scope_hint(session: Any, repository: Any, raw_results: list[Any]) ->
session,
repository.id,
served,
- cache_key=f"{repository.id}:{basis_cache_key(repository)}",
+ cache_key=f"{repository.id}:{index_state_key(repository)}",
)
except Exception:
return None
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py
index 4053acf76..a4375e94d 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/enrichment.py
@@ -56,7 +56,7 @@ from repowise.core.persistence.models import (
HealthFinding,
Repository,
)
-from repowise.server.mcp_server._basis import basis_cache_key, call_resolution_basis
+from repowise.server.mcp_server._basis import call_resolution_basis
from repowise.server.mcp_server._budget import OmissionCollector, cap_collection
from repowise.server.mcp_server._graph_files import keep_projected_edge, node_to_file
from repowise.server.mcp_server._helpers import (
@@ -65,6 +65,7 @@ from repowise.server.mcp_server._helpers import (
filter_rows_by_attr,
is_missing_table,
)
+from repowise.server.mcp_server._index_state import index_state_key
from repowise.server.schemas.intelligence import SYMBOL_RELATION_GROUP_OF
#: Where a resolved target path waits between its card being built and the
@@ -219,7 +220,7 @@ async def _resolve_call_graph(
if want_callees:
result_data["callees"] = []
result_data["callees_basis"] = await call_resolution_basis(
- session, repo_id, node.language, cache_key=basis_cache_key(repository)
+ session, repo_id, node.language, cache_key=index_state_key(repository)
)
return
if want_callers:
@@ -401,7 +402,7 @@ async def _resolve_call_graph(
for key in ("callers", "callees"):
if key in result_data and not result_data[key]:
result_data[f"{key}_basis"] = await call_resolution_basis(
- session, repo_id, node.language, cache_key=basis_cache_key(repository)
+ session, repo_id, node.language, cache_key=index_state_key(repository)
)
if relations:
@@ -519,7 +520,7 @@ async def _resolve_file_level_callers(
)
if repository is not None and not result_data.get("callers"):
result_data["callers_basis"] = await call_resolution_basis(
- session, repo_id, node.language, cache_key=basis_cache_key(repository)
+ session, repo_id, node.language, cache_key=index_state_key(repository)
)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
index 3f4da4465..3a321a4c8 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
@@ -41,7 +41,7 @@ from repowise.core.persistence.models import (
Repository,
WikiSymbol,
)
-from repowise.server.mcp_server._basis import basis_cache_key, call_resolution_basis
+from repowise.server.mcp_server._basis import call_resolution_basis
from repowise.server.mcp_server._budget import OmissionCollector, cap_collection
from repowise.server.mcp_server._helpers import (
LIKE_ESCAPE,
@@ -52,6 +52,7 @@ from repowise.server.mcp_server._helpers import (
is_excluded,
read_repo_file_text,
)
+from repowise.server.mcp_server._index_state import index_state_key
from repowise.server.mcp_server._references import path_identity, symbol_identity
from repowise.server.mcp_server._symbol_lookup import resolve_symbol_rows
from repowise.server.mcp_server.tool_context.enrichment import (
@@ -816,7 +817,7 @@ async def _resolve_one_target(
session,
repo_id,
getattr(sym, "language", None),
- cache_key=basis_cache_key(repository),
+ cache_key=index_state_key(repository),
)
# Candidates
if len(sym_matches) > 1: # type: ignore[possibly-undefined]
diff --git a/packages/server/src/repowise/server/mcp_server/tool_dead_code.py b/packages/server/src/repowise/server/mcp_server/tool_dead_code.py
index 17487630c..9e41dc1ed 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_dead_code.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_dead_code.py
@@ -28,7 +28,7 @@ from repowise.core.persistence.models import (
)
from repowise.core.registry import mcp_tool_registry as mcp
from repowise.server.mcp_server import _state
-from repowise.server.mcp_server._basis import basis_cache_key, call_resolution_bases
+from repowise.server.mcp_server._basis import call_resolution_bases
from repowise.server.mcp_server._budget import OmissionCollector
from repowise.server.mcp_server._helpers import (
_get_exclude_spec,
@@ -40,6 +40,7 @@ from repowise.server.mcp_server._helpers import (
filter_rows_by_attr,
resolve_enum_argument,
)
+from repowise.server.mcp_server._index_state import index_state_key
from repowise.server.mcp_server._meta import build_meta as _build_meta
from repowise.server.mcp_server._references import path_identity, stable_entity_id
@@ -486,7 +487,7 @@ async def get_dead_code(
# How much of the call graph these findings rest on, per language. A
# reachability finding is only as strong as the edges that reached.
summary["call_resolution_basis"] = await call_resolution_bases(
- session, repository.id, cache_key=basis_cache_key(repository)
+ session, repository.id, cache_key=index_state_key(repository)
)
result["_meta"] = _build_meta(repository=repository)
diff --git a/tests/conftest.py b/tests/conftest.py
index 43e023a30..ae260f49b 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import os
+import sys
from pathlib import Path
import pytest
@@ -109,6 +110,20 @@ def _isolate_db_url_env():
os.environ[key] = value
[email protected](autouse=True)
+def _fresh_per_index_caches():
+ """Drop the MCP server's per-index caches before every test.
+
+ Test repositories share one id and one ``updated_at`` and have no state file,
+ so every test's index looks the same to the cache key. Looked up in
+ ``sys.modules`` so a test that never loads the server pays nothing.
+ """
+ for name in ("_basis", "_scope", "_graph_files"):
+ module = sys.modules.get(f"repowise.server.mcp_server.{name}")
+ if module is not None:
+ module.reset_cache()
+
+
@pytest.fixture(autouse=True)
def _isolate_structlog_config():
"""Restore structlog's global configuration after every test.
diff --git a/tests/unit/server/mcp/conftest.py b/tests/unit/server/mcp/conftest.py
index c44284ddf..6b6eb3429 100644
--- a/tests/unit/server/mcp/conftest.py
+++ b/tests/unit/server/mcp/conftest.py
@@ -567,12 +567,6 @@ async def populated_db(session: AsyncSession, repo_id: str) -> str:
async def setup_mcp(factory, fts, vector_store, populated_db, tmp_path):
"""Configure the MCP module's global state for testing."""
import repowise.server.mcp_server as mcp_mod
- from repowise.server.mcp_server import _basis, _scope
-
- # Every test repo shares one id and one updated_at, so a grouping cached
- # from an earlier test would be served to the next one's different seed.
- _basis.reset_cache()
- _scope.reset_cache()
mcp_mod._session_factory = factory
mcp_mod._fts = fts
diff --git a/tests/unit/server/mcp/test_graph_projection_cache.py b/tests/unit/server/mcp/test_graph_projection_cache.py
new file mode 100644
index 000000000..0d97a8cf4
--- /dev/null
+++ b/tests/unit/server/mcp/test_graph_projection_cache.py
@@ -0,0 +1,84 @@
+"""A graph projection is built once per index state, not once per question."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+import pytest
+
+from repowise.server.mcp_server import _graph_files
+from repowise.server.mcp_server._graph_files import per_index
+
+
+def _counting_build(calls: list[int]):
+ async def build():
+ calls.append(1)
+ await asyncio.sleep(0)
+ return {"built": len(calls)}
+
+ return build
+
+
+async def test_a_second_question_on_the_same_index_reuses_the_projection(session, repo_id):
+ calls: list[int] = []
+ build = _counting_build(calls)
+
+ first = await per_index(session, repo_id, "adjacency", build)
+ second = await per_index(session, repo_id, "adjacency", build)
+
+ assert calls == [1]
+ assert second is first
+
+
+async def test_concurrent_cold_questions_build_once(session, repo_id):
+ calls: list[int] = []
+ build = _counting_build(calls)
+
+ await asyncio.gather(*(per_index(session, repo_id, "adjacency", build) for _ in range(3)))
+
+ assert calls == [1]
+
+
+async def test_the_end_of_an_update_run_invalidates_the_projection(session, repo_id, tmp_path):
+ # The repo row is stamped when a run starts; the state file is saved when it
+ # ends, so a projection read mid-run is not served after it.
+ calls: list[int] = []
+ build = _counting_build(calls)
+ await per_index(session, repo_id, "adjacency", build)
+
+ state = tmp_path / ".repowise" / "state.json"
+ state.parent.mkdir(parents=True, exist_ok=True)
+ state.write_text("{}", encoding="utf-8")
+ os.utime(state, ns=(1, 1))
+ rebuilt = await per_index(session, repo_id, "adjacency", build)
+
+ assert calls == [1, 1]
+ assert rebuilt == {"built": 2}
+
+
+async def test_each_projection_is_cached_under_its_own_name(session, repo_id):
+ calls: list[int] = []
+ build = _counting_build(calls)
+
+ await per_index(session, repo_id, "adjacency", build)
+ await per_index(session, repo_id, "projected_edges", build)
+
+ assert calls == [1, 1]
+
+
+async def test_the_least_recently_used_repo_is_evicted(session, repo_id, monkeypatch):
+ monkeypatch.setattr(_graph_files, "_CACHE_MAX_REPOS", 1)
+ calls: list[int] = []
+ build = _counting_build(calls)
+
+ await per_index(session, repo_id, "adjacency", build)
+ await per_index(session, "another-repo", "adjacency", build)
+ await per_index(session, repo_id, "adjacency", build)
+
+ assert calls == [1, 1, 1]