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.

feat(workspace): derived workspace store, and route bare symbol names across repos (#3786)

Raghav Chamadiyaaaf3e60eb0d2
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.md
index 03782325f..eda64bfb9 100644
--- a/docs/agent/MCP_TOOLS.md
+++ b/docs/agent/MCP_TOOLS.md
@@ -531,6 +531,8 @@ Only four tools answer across every repo with `repo="all"`. The rest return an e
With `repo` omitted, `get_context`, `get_symbol`, `get_risk` and `get_health` route each path or `path::Name` target to its repo: the default repo when the file exists there, else the one other repo whose checkout has it. Write `<alias>:<target>` (for example `web:src/app.ts::App`) to name the repo outright. A path found in several other repos returns its `candidates`. A path in no repo gets the default repo's usual not-found answer plus a `hint` naming `search_codebase(repo="all")` and the `<alias>:<path>` form; routed results carry `repo`. `get_context` takes a batch spanning repos, while `get_risk` and `get_health` answer one repo per call and name the per-repo calls when a batch spans several.
+`get_context` and `get_symbol` route a bare symbol name (`render`, `Client.send`) the same way, through the workspace store's symbol index: the default repo keeps a name it has, one other repo that has it gets the call, and several return `candidates`. A `repowise#<ref>` omission ref is found in whichever repo's omission store holds it.
+
A `repo="all"` call queries up to 4 repos at a time and gives each 60 seconds (`REPOWISE_WORKSPACE_CONCURRENCY`, `REPOWISE_WORKSPACE_REPO_TIMEOUT_S`). A repo that fails to open, errors or times out is listed in `repos_failed` with its reason while the other repos still answer. A repo whose index is behind its checkout is listed in `repos_stale` with `indexed_commit` and `live_head`, and its rows carry `stale: true`. Both keys appear only when non-empty.
Single-repo tools also gain cross-repo evidence in workspace mode:
diff --git a/docs/scale/WORKSPACES.md b/docs/scale/WORKSPACES.md
index 7f563ffcb..2a9518fbe 100644
--- a/docs/scale/WORKSPACES.md
+++ b/docs/scale/WORKSPACES.md
@@ -541,6 +541,8 @@ my-workspace/
system_graph.json # Service-granular system graph + diagnostics
breaking_changes.json # Breaking provider changes vs the last index
conformance.json # Architecture rule violations + dependency cycles
+ workspace.db # Workspace store: symbol and path index, components,
+ # recent changes, per-repo health and freshness
.claude/
CLAUDE.md # Workspace-level CLAUDE.md for AI editors
backend/
@@ -549,6 +551,8 @@ my-workspace/
.repowise/
```
+`workspace.db` is derived from each repo's own index and refreshed after every workspace update and whenever a repo is re-indexed, so deleting it is always safe: it is rebuilt the next time it is needed.
+
What lives in each repo's `.repowise/` is described in
[CONFIG.md](../reference/CONFIG.md#the-repowise-directory).
diff --git a/packages/core/src/repowise/core/workspace/repo_index.py b/packages/core/src/repowise/core/workspace/repo_index.py
index 4ec613ee0..443f8794b 100644
--- a/packages/core/src/repowise/core/workspace/repo_index.py
+++ b/packages/core/src/repowise/core/workspace/repo_index.py
@@ -310,13 +310,31 @@ class WorkspaceIndex:
self._repos.clear()
-async def open_repo_index(alias: str, repo_path: Path) -> RepoIndex | None:
- """Open *repo_path*'s ``wiki.db`` read side, or None when it has no index."""
+async def checkout_repository(session: AsyncSession, repo_path: Path) -> Any:
+ """The ``repositories`` row describing *repo_path*, or None in an empty index.
+
+ A wiki.db normally holds one repository row; prefer the one recorded at
+ this checkout when it holds more, since test runs and moved checkouts leave
+ others behind. Newest first so the fallback is a decision rather than
+ whatever order the scan returns.
+ """
from sqlalchemy import select
from repowise.core.persistence.crud.repository import get_repository_by_path
from repowise.core.persistence.models import Repository
+ repo = await get_repository_by_path(session, str(repo_path))
+ if repo is None:
+ repo = (
+ await session.execute(
+ select(Repository).order_by(Repository.updated_at.desc()).limit(1)
+ )
+ ).scalar_one_or_none()
+ return repo
+
+
+async def open_repo_index(alias: str, repo_path: Path) -> RepoIndex | None:
+ """Open *repo_path*'s ``wiki.db`` read side, or None when it has no index."""
from .registry import open_repo_db, repo_db_path
if not repo_db_path(repo_path).is_file():
@@ -326,17 +344,7 @@ async def open_repo_index(alias: str, repo_path: Path) -> RepoIndex | None:
session = session_factory()
ok = False
try:
- # A wiki.db normally holds one repository row; prefer the one recorded
- # at this checkout when it holds more, since test runs and moved
- # checkouts leave others behind. Newest first so the fallback is a
- # decision rather than whatever order the scan returns.
- repo = await get_repository_by_path(session, str(repo_path))
- if repo is None:
- repo = (
- await session.execute(
- select(Repository).order_by(Repository.updated_at.desc()).limit(1)
- )
- ).scalar_one_or_none()
+ repo = await checkout_repository(session, repo_path)
if repo is None:
raise LookupError(f"No repository row in {repo_path}")
index = RepoIndex(alias, repo_path, session, engine, repo_id=repo.id)
diff --git a/packages/core/src/repowise/core/workspace/store.py b/packages/core/src/repowise/core/workspace/store.py
new file mode 100644
index 000000000..91af11fed
--- /dev/null
+++ b/packages/core/src/repowise/core/workspace/store.py
@@ -0,0 +1,520 @@
+"""The workspace store: ``.repowise-workspace/workspace.db``.
+
+A derived SQLite file holding the cross-repo rows a workspace query needs in
+one lookup: which repo has a path or a symbol, each repo's components, recent
+change summaries, health and index freshness. Each repo's own ``wiki.db`` stays
+the source of truth; every row here is rebuilt from it, so the file can be
+deleted at any time. A missing, corrupt or older-schema file is rebuilt.
+
+A repo's rows are refreshed when its stamp moves. The stamp is the repo's
+``.repowise/state.json`` (written by every index run) plus whether ``wiki.db``
+exists, so serving reads never invalidate it. Refreshes happen after a
+workspace update (:func:`repowise.core.workspace.update.run_cross_repo_hooks`)
+and lazily when a reader finds a stamp moved.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import sqlite3
+from collections.abc import Iterable, Iterator
+from contextlib import closing, contextmanager, suppress
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from repowise.core.sqlite_pragmas import apply_sqlite_pragmas
+
+from .config import WORKSPACE_DATA_DIR
+
+_log = logging.getLogger("repowise.workspace.store")
+
+STORE_FILENAME = "workspace.db"
+#: Bump on any table change; a file with another version is rebuilt.
+SCHEMA_VERSION = 1
+_BUSY_TIMEOUT_MS = 5000
+#: Change summaries kept per repo, newest first. Ceiling: older changes stay
+#: in the repo's own ``changes`` table; raise this when a reader needs more.
+CHANGES_PER_REPO = 200
+#: Rows per ``executemany``. Ceiling: one repo's rows are still read whole
+#: into memory before the write (tens of MB at ~100k symbols); streaming the
+#: read in chunks of this size is the upgrade path.
+_INSERT_CHUNK = 5000
+
+_SCHEMA = """
+CREATE TABLE repos (
+ alias TEXT PRIMARY KEY,
+ path TEXT NOT NULL,
+ stamp TEXT NOT NULL,
+ indexed INTEGER NOT NULL,
+ indexed_commit TEXT,
+ index_updated_at TEXT,
+ refreshed_at TEXT NOT NULL,
+ health_json TEXT,
+ error TEXT
+);
+CREATE TABLE files (
+ alias TEXT NOT NULL,
+ path TEXT NOT NULL,
+ PRIMARY KEY (path, alias)
+) WITHOUT ROWID;
+CREATE INDEX ix_files_alias ON files (alias);
+CREATE TABLE symbols (
+ alias TEXT NOT NULL,
+ symbol_id TEXT NOT NULL,
+ name TEXT NOT NULL,
+ qualified_name TEXT NOT NULL,
+ kind TEXT NOT NULL,
+ file_path TEXT NOT NULL
+);
+CREATE INDEX ix_symbols_name ON symbols (name);
+CREATE INDEX ix_symbols_qualified ON symbols (qualified_name);
+CREATE INDEX ix_symbols_alias ON symbols (alias);
+CREATE TABLE components (
+ alias TEXT NOT NULL,
+ name TEXT NOT NULL,
+ source TEXT NOT NULL,
+ owner TEXT,
+ system TEXT,
+ criticality TEXT,
+ tags_json TEXT NOT NULL,
+ file_count INTEGER NOT NULL,
+ PRIMARY KEY (alias, name)
+);
+CREATE TABLE changes (
+ alias TEXT NOT NULL,
+ change_id TEXT NOT NULL,
+ merged_at TEXT,
+ title TEXT NOT NULL,
+ category TEXT NOT NULL,
+ files_changed INTEGER NOT NULL,
+ lines_added INTEGER NOT NULL,
+ lines_deleted INTEGER NOT NULL,
+ provenance TEXT,
+ PRIMARY KEY (alias, change_id)
+);
+"""
+_TABLES = ("files", "symbols", "components", "changes")
+
+
+def store_path(workspace_root: Path) -> Path:
+ return Path(workspace_root) / WORKSPACE_DATA_DIR / STORE_FILENAME
+
+
+def repo_stamp(repo_path: Path) -> str:
+ """What must move for a repo's rows to be re-read."""
+ from .registry import repo_db_path
+
+ try:
+ st = (repo_path / ".repowise" / "state.json").stat()
+ state = f"{st.st_mtime_ns}:{st.st_size}"
+ except OSError:
+ state = "-"
+ return f"{state}|{int(repo_db_path(repo_path).is_file())}"
+
+
+@dataclass
+class RepoRows:
+ """Everything the store holds for one repo, read from its ``wiki.db``."""
+
+ indexed: bool = False
+ indexed_commit: str | None = None
+ index_updated_at: str | None = None
+ health: dict[str, Any] | None = None
+ files: list[str] = field(default_factory=list)
+ symbols: list[tuple[str, str, str, str, str]] = field(default_factory=list)
+ components: list[tuple[str, str, str | None, str | None, str | None, str, int]] = field(
+ default_factory=list
+ )
+ changes: list[tuple[str, str | None, str, str, int, int, int, str | None]] = field(
+ default_factory=list
+ )
+ error: str | None = None
+
+
+class WorkspaceStore:
+ """One open connection to the workspace store; the caller closes it."""
+
+ def __init__(self, path: Path) -> None:
+ self.path = path
+ path.parent.mkdir(parents=True, exist_ok=True)
+ try:
+ self._conn = self._open()
+ except sqlite3.DatabaseError as exc:
+ if not _corrupt(exc):
+ raise
+ _log.warning("Workspace store at %s is unreadable; rebuilding it", path)
+ discard(path)
+ self._conn = self._open()
+
+ def _open(self) -> sqlite3.Connection:
+ conn = sqlite3.connect(self.path, isolation_level=None)
+ try:
+ apply_sqlite_pragmas(conn, _BUSY_TIMEOUT_MS)
+ if conn.execute("PRAGMA user_version").fetchone()[0] != SCHEMA_VERSION:
+ with _transaction(conn):
+ # Re-read under the write lock: another process may have
+ # just built the schema.
+ if conn.execute("PRAGMA user_version").fetchone()[0] == SCHEMA_VERSION:
+ return conn
+ for (table,) in conn.execute(
+ "SELECT name FROM sqlite_master WHERE type='table'"
+ ).fetchall():
+ conn.execute(f'DROP TABLE "{table}"')
+ for statement in _SCHEMA.split(";"):
+ if statement.strip():
+ conn.execute(statement)
+ conn.execute(f"PRAGMA user_version={SCHEMA_VERSION}")
+ except BaseException:
+ conn.close()
+ raise
+ return conn
+
+ def close(self) -> None:
+ self._conn.close()
+
+ def stamps(self) -> dict[str, tuple[str, str]]:
+ """``alias -> (path, stamp)`` for every repo the store holds."""
+ rows = self._conn.execute("SELECT alias, path, stamp FROM repos")
+ return {alias: (path, stamp) for alias, path, stamp in rows}
+
+ def replace_repo(self, alias: str, path: str, stamp: str, rows: RepoRows) -> None:
+ """Swap one repo's rows for *rows* in one transaction."""
+ conn = self._conn
+ with _transaction(conn):
+ self._delete(alias)
+ conn.execute(
+ "INSERT INTO repos VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+ (
+ alias,
+ path,
+ stamp,
+ int(rows.indexed),
+ rows.indexed_commit,
+ rows.index_updated_at,
+ datetime.now(UTC).isoformat(),
+ json.dumps(rows.health) if rows.health is not None else None,
+ rows.error,
+ ),
+ )
+ for table, items in (
+ ("files", [(f,) for f in rows.files]),
+ ("symbols", rows.symbols),
+ ("components", rows.components),
+ ("changes", rows.changes),
+ ):
+ if not items:
+ continue
+ marks = ", ".join("?" * (len(items[0]) + 1))
+ sql = f"INSERT OR IGNORE INTO {table} VALUES ({marks})"
+ for i in range(0, len(items), _INSERT_CHUNK):
+ conn.executemany(sql, ((alias, *r) for r in items[i : i + _INSERT_CHUNK]))
+
+ def drop_repos(self, aliases: Iterable[str]) -> None:
+ with _transaction(self._conn):
+ for alias in aliases:
+ self._delete(alias)
+
+ def _delete(self, alias: str) -> None:
+ for table in (*_TABLES, "repos"):
+ self._conn.execute(f"DELETE FROM {table} WHERE alias = ?", (alias,))
+
+
+@contextmanager
+def _transaction(conn: sqlite3.Connection) -> Iterator[None]:
+ conn.execute("BEGIN IMMEDIATE")
+ try:
+ yield
+ except BaseException:
+ conn.execute("ROLLBACK")
+ raise
+ conn.execute("COMMIT")
+
+
+def _corrupt(exc: sqlite3.DatabaseError) -> bool:
+ """Not a database, a malformed one, or one missing its tables. Locks and
+ integrity errors are ``DatabaseError`` subclasses too and say nothing about
+ the file."""
+ if isinstance(exc, sqlite3.OperationalError):
+ return str(exc).startswith("no such table")
+ return type(exc) is sqlite3.DatabaseError
+
+
+def discard(path: Path) -> None:
+ """Delete the store file and its WAL sidecars; the next open rebuilds it."""
+ for suffix in ("", "-wal", "-shm"):
+ with suppress(OSError):
+ Path(f"{path}{suffix}").unlink(missing_ok=True)
+
+
+# ---------------------------------------------------------------------------
+# Reading a repo's index
+# ---------------------------------------------------------------------------
+
+
+async def read_repo_rows(alias: str, repo_path: Path, services: list[tuple[str, str]]) -> RepoRows:
+ """Read one repo's store rows from its ``wiki.db``; never raises."""
+ from .registry import open_repo_db, repo_db_path
+
+ if not repo_db_path(repo_path).is_file():
+ return RepoRows()
+ try:
+ engine, session_factory = await open_repo_db(repo_path)
+ except Exception as exc:
+ _log.warning("Workspace store: could not open the index of %r", alias, exc_info=True)
+ return RepoRows(error=f"{type(exc).__name__}: {exc}"[:200])
+ try:
+ async with session_factory() as session:
+ return await _read(session, repo_path, services)
+ except Exception as exc:
+ _log.warning("Workspace store: could not read the index of %r", alias, exc_info=True)
+ return RepoRows(error=f"{type(exc).__name__}: {exc}"[:200])
+ finally:
+ await engine.dispose()
+
+
+async def _read(session: Any, repo_path: Path, services: list[tuple[str, str]]) -> RepoRows:
+ from sqlalchemy import select
+
+ from repowise.core.components.store import load_repo_components
+ from repowise.core.persistence.models import Change, GraphNode, HealthSnapshot, WikiSymbol
+
+ from .repo_index import checkout_repository
+ from .update import resolve_indexed_commit
+
+ repo = await checkout_repository(session, repo_path)
+ if repo is None:
+ return RepoRows()
+ rows = RepoRows(
+ indexed=True,
+ # May spawn git (ancestry), so off the event loop.
+ indexed_commit=(
+ await asyncio.to_thread(resolve_indexed_commit, repo_path, repo.head_commit)
+ ).sha,
+ index_updated_at=repo.updated_at.isoformat() if repo.updated_at else None,
+ )
+ rows.files = list(
+ (
+ await session.execute(
+ select(GraphNode.node_id).where(
+ GraphNode.repository_id == repo.id, GraphNode.node_type == "file"
+ )
+ )
+ ).scalars()
+ )
+ rows.symbols = [
+ tuple(r)
+ for r in await session.execute(
+ select(
+ WikiSymbol.symbol_id,
+ WikiSymbol.name,
+ WikiSymbol.qualified_name,
+ WikiSymbol.kind,
+ WikiSymbol.file_path,
+ ).where(WikiSymbol.repository_id == repo.id)
+ )
+ ]
+ resolved = (
+ await load_repo_components(session, repo.id, repo_path, services=services)
+ ).resolved
+ rows.components = [
+ (
+ c.name,
+ c.source,
+ c.owner,
+ c.system,
+ c.criticality,
+ json.dumps(list(c.tags)),
+ len(resolved.files.get(c.name, ())),
+ )
+ for c in resolved.components
+ ]
+ rows.changes = [
+ (
+ c.change_id,
+ c.merged_at.isoformat() if c.merged_at else None,
+ c.title,
+ c.category,
+ c.files_changed,
+ c.lines_added,
+ c.lines_deleted,
+ c.provenance,
+ )
+ for c in (
+ await session.execute(
+ select(Change)
+ .where(Change.repository_id == repo.id)
+ .order_by(Change.merged_at.desc(), Change.change_id)
+ .limit(CHANGES_PER_REPO)
+ )
+ ).scalars()
+ ]
+ snap = (
+ await session.execute(
+ select(HealthSnapshot)
+ .where(HealthSnapshot.repository_id == repo.id)
+ .order_by(HealthSnapshot.taken_at.desc())
+ .limit(1)
+ )
+ ).scalar_one_or_none()
+ if snap is not None:
+ rows.health = {
+ "taken_at": snap.taken_at.isoformat() if snap.taken_at else None,
+ "average_health": snap.average_health,
+ "hotspot_health": snap.hotspot_health,
+ "maintainability_average": snap.maintainability_average,
+ }
+ return rows
+
+
+# ---------------------------------------------------------------------------
+# Refresh
+# ---------------------------------------------------------------------------
+
+
+async def refresh_workspace_store(ws_config: Any, workspace_root: Path) -> Path | None:
+ """Bring the store up to date with every repo's index; the store's path, or
+ None when it cannot be written. Only repos whose stamp moved are re-read.
+
+ Every SQLite and file step runs in a worker thread, so a writer holding the
+ store (a concurrent ``repowise update``) never blocks the caller's loop.
+ """
+ from repowise.core.components.store import services_from_system_graph
+
+ path = store_path(workspace_root)
+ wanted = {
+ e.alias: (Path(workspace_root) / e.path).resolve() for e in ws_config.repos
+ }
+ plan = await asyncio.to_thread(_plan, path, wanted)
+ if plan is None:
+ return None
+ stamps, stale = plan
+ if not stale:
+ return path
+ graph = await asyncio.to_thread(_system_graph_dict, workspace_root)
+ rows: dict[str, RepoRows] = {}
+ for alias in stale:
+ services = services_from_system_graph(graph, alias)
+ rows[alias] = await read_repo_rows(alias, wanted[alias], services)
+ ok = await asyncio.to_thread(_write, path, stamps, rows)
+ return path if ok else None
+
+
+#: ``store path -> (repo stamps, store file stat)`` after this process's last
+#: refresh. When both still match, a refresh is a few ``stat`` calls and opens
+#: no database.
+_last_refresh: dict[Path, tuple[Any, Any]] = {}
+
+
+def _file_stat(path: Path) -> tuple[tuple[int, int] | None, ...]:
+ out = []
+ for suffix in ("", "-wal"):
+ try:
+ st = Path(f"{path}{suffix}").stat()
+ out.append((st.st_mtime_ns, st.st_size))
+ except OSError:
+ out.append(None)
+ return tuple(out)
+
+
+def _plan(
+ path: Path, wanted: dict[str, Path]
+) -> tuple[dict[str, tuple[str, str]], list[str]] | None:
+ """``(alias -> (path key, stamp), stale aliases)``; drops repos no longer
+ configured. None when the store cannot be opened."""
+ stamps = {alias: (str(repo), repo_stamp(repo)) for alias, repo in wanted.items()}
+ memo = (tuple(sorted(stamps.items())), _file_stat(path))
+ if _last_refresh.get(path) == memo and memo[1][0] is not None:
+ return stamps, []
+ try:
+ store = WorkspaceStore(path)
+ except (OSError, sqlite3.Error):
+ _log.warning("Workspace store at %s cannot be opened", path, exc_info=True)
+ return None
+ try:
+ known = store.stamps()
+ store.drop_repos(a for a in known if a not in wanted)
+ except sqlite3.Error as exc:
+ _failed(store, path, exc)
+ return None
+ store.close()
+ stale = [a for a, key in stamps.items() if known.get(a) != key]
+ if not stale:
+ _last_refresh[path] = (memo[0], _file_stat(path))
+ return stamps, stale
+
+
+def _write(path: Path, stamps: dict[str, tuple[str, str]], rows: dict[str, RepoRows]) -> bool:
+ try:
+ store = WorkspaceStore(path)
+ except (OSError, sqlite3.Error):
+ _log.warning("Workspace store at %s cannot be opened", path, exc_info=True)
+ return False
+ try:
+ for alias, repo_rows in rows.items():
+ key, stamp = stamps[alias]
+ store.replace_repo(alias, key, stamp, repo_rows)
+ except sqlite3.Error as exc:
+ _failed(store, path, exc)
+ return False
+ store.close()
+ _last_refresh[path] = (tuple(sorted(stamps.items())), _file_stat(path))
+ return True
+
+
+def _failed(store: WorkspaceStore, path: Path, exc: sqlite3.Error) -> None:
+ _log.warning("Workspace store at %s failed mid-refresh", path, exc_info=True)
+ store.close()
+ _last_refresh.pop(path, None)
+ if isinstance(exc, sqlite3.DatabaseError) and _corrupt(exc):
+ discard(path) # rebuilt on the next refresh rather than served
+
+
+def _system_graph_dict(workspace_root: Path) -> dict[str, Any] | None:
+ from .system_graph import load_system_graph
+
+ graph = load_system_graph(workspace_root)
+ return graph.to_dict() if graph else None
+
+
+def lookup_symbols(
+ path: Path, names: Iterable[str], *, components_of: str | None = None
+) -> tuple[dict[str, list[tuple[str, str, str]]], set[str]] | None:
+ """``(name -> [(alias, symbol_id, file_path)], component names)``.
+
+ The first holds the symbols whose name or qualified name is exactly
+ *name*; the second the casefolded component names of *components_of*.
+ None when the store cannot be read (a corrupt file is discarded so the
+ next refresh rebuilds it).
+ """
+ out: dict[str, list[tuple[str, str, str]]] = {}
+ components: set[str] = set()
+ try:
+ uri = f"{Path(path).resolve().as_uri()}?mode=ro"
+ with closing(sqlite3.connect(uri, uri=True)) as conn:
+ conn.execute(f"PRAGMA busy_timeout={_BUSY_TIMEOUT_MS}")
+ for name in dict.fromkeys(names):
+ rows = conn.execute(
+ "SELECT alias, symbol_id, file_path FROM symbols "
+ "WHERE name = ?1 OR qualified_name = ?1 ORDER BY alias, symbol_id",
+ (name,),
+ ).fetchall()
+ if rows:
+ out[name] = [(a, s, f) for a, s, f in rows]
+ if components_of is not None:
+ components = {
+ str(n).casefold()
+ for (n,) in conn.execute(
+ "SELECT name FROM components WHERE alias = ?", (components_of,)
+ )
+ }
+ except sqlite3.Error as exc:
+ if isinstance(exc, sqlite3.DatabaseError) and _corrupt(exc):
+ _log.warning("Workspace store at %s is unreadable; discarding it", path)
+ _last_refresh.pop(path, None)
+ discard(path)
+ return None
+ return out, components
diff --git a/packages/core/src/repowise/core/workspace/update.py b/packages/core/src/repowise/core/workspace/update.py
index 44f7eb137..b881836de 100644
--- a/packages/core/src/repowise/core/workspace/update.py
+++ b/packages/core/src/repowise/core/workspace/update.py
@@ -1279,7 +1279,8 @@ async def run_cross_repo_hooks(
Detects cross-repo co-changes (files committed by the same author within
a time window across repos) and package/manifest dependencies. Results are
persisted to ``.repowise-workspace/cross_repo_edges.json`` and loaded by
- the MCP server's :class:`CrossRepoEnricher` at startup.
+ the MCP server's :class:`CrossRepoEnricher` at startup. Ends by refreshing
+ the workspace store (:mod:`.store`).
"""
if len(ws_config.repos) < 2:
return
@@ -1303,6 +1304,17 @@ async def run_cross_repo_hooks(
finally:
await workspace_index.close()
+ # Last: derived components read the system graph the phases just wrote.
+ from .store import refresh_workspace_store
+
+ timings.on_phase_start("workspace_store", None)
+ try:
+ await refresh_workspace_store(ws_config, workspace_root)
+ except Exception:
+ _log.warning("Workspace store refresh failed", exc_info=True)
+ timings.on_phase_done("workspace_store")
+ _log_phase(timings, "workspace_store")
+
async def _run_phases(
ws_config: WorkspaceConfig,
diff --git a/packages/server/src/repowise/server/mcp_server/_federation.py b/packages/server/src/repowise/server/mcp_server/_federation.py
index 1e8254af3..bc0c57475 100644
--- a/packages/server/src/repowise/server/mcp_server/_federation.py
+++ b/packages/server/src/repowise/server/mcp_server/_federation.py
@@ -1,12 +1,13 @@
-"""Workspace fan-out for ``repo="all"``: one per-repo call run across every repo.
+"""Workspace fan-out: one per-repo call run across every repo, or a chosen few.
-Every tool that answers across the workspace goes through :class:`Federation`,
-so concurrency, timeouts, partial results and freshness mean the same thing in
-each of them. A repo that cannot be opened, raises or runs past its timeout is
-named in ``repos_failed`` and the rest still answer; a repo whose index is
-behind its checkout is named in ``repos_stale`` and its rows carry
-``stale: true``. Both keys are added only when non-empty, so a healthy
-workspace gets the response shape it always had.
+Every tool that answers across repos (``repo="all"``, and targets routed to
+several repos) goes through :class:`Federation`, so concurrency, timeouts,
+partial results and freshness mean the same thing in each of them. A repo
+that cannot be opened, raises or runs past its timeout is named in
+``repos_failed`` and the rest still answer; a repo whose index is behind its
+checkout is named in ``repos_stale`` and its rows carry ``stale: true``. Both
+keys are added only when non-empty, so a healthy workspace gets the response
+shape it always had.
The merge rules live here too, one per kind of result: ranked lists
(:func:`merge_ranked`), findings (:func:`merge_findings`) and aggregates
@@ -103,9 +104,23 @@ class Federation:
read-only connections for fan-out are the upgrade path.
"""
- def __init__(self, *, concurrency: int | None = None, timeout_s: float | None = None):
+ def __init__(
+ self,
+ *,
+ aliases: Sequence[str] | None = None,
+ concurrency: int | None = None,
+ timeout_s: float | None = None,
+ check_freshness: bool = True,
+ ):
+ """*aliases* limits the call to those repos (default: all of them);
+ ``check_freshness=False`` skips ``repos_stale`` for answers that carry
+ their own freshness."""
registry = _state._registry
- self._aliases: list[str | None] = registry.get_all_aliases() if registry else [None]
+ if aliases is not None:
+ self._aliases: list[str | None] = list(aliases)
+ else:
+ self._aliases = registry.get_all_aliases() if registry else [None]
+ self._check = check_freshness
self._semaphore = asyncio.Semaphore(concurrency or fanout_concurrency())
self._timeout_s = timeout_s or fanout_timeout_s()
self._failed: dict[str | None, str] = {}
@@ -137,7 +152,7 @@ class Federation:
async def _call(self, alias: str | None, fn: Callable[[Any], Awaitable[T]]) -> tuple[Any, T]:
ctx = await _open(alias)
- if ctx.alias not in self._checked:
+ if self._check and ctx.alias not in self._checked:
self._checked.add(ctx.alias)
await self._check_freshness(ctx)
return ctx, await fn(ctx)
diff --git a/packages/server/src/repowise/server/mcp_server/_workspace_routing.py b/packages/server/src/repowise/server/mcp_server/_workspace_routing.py
index 3d9966a56..bdb8b15b1 100644
--- a/packages/server/src/repowise/server/mcp_server/_workspace_routing.py
+++ b/packages/server/src/repowise/server/mcp_server/_workspace_routing.py
@@ -17,26 +17,39 @@ Rules, exact matches only:
answer (suggestions, ``moved_to``) is kept; :func:`hint_misses` only adds a
pointer to ``search_codebase``. In a change set it is a deleted file and
gets no hint (:func:`settle_missing`).
-- Bare names and opaque refs stay with the default repo: resolving them
- elsewhere needs a workspace-wide symbol locator.
-
-Existence is checked on each repo's checkout, so routing opens no database.
-Ceiling: one ``exists()`` per non-default repo per missed target; a workspace
-locator replaces the probe when the workspace store lands.
+- A bare identifier (``get_answer``, ``Client.send``) is looked up in the
+ workspace store's symbol locator, by exact name or qualified name. The
+ default repo keeps it when it has the symbol, a component of that name or
+ a path of that name; otherwise it routes to the one other repo that has it,
+ and several give candidates. A name no repo has, or one that is not
+ identifier-shaped, stays with the default repo.
+- Omission refs (``repowise#<hex>``) stay with the default repo here;
+ ``get_symbol`` looks them up in every repo's omission store.
+
+Path existence is checked on each repo's checkout, so path routing opens no
+database. Ceiling: one ``exists()`` per non-default repo per missed path.
"""
from __future__ import annotations
+import asyncio
+import logging
import os
+import re
from collections.abc import Awaitable, Callable, Collection, Sequence
from dataclasses import dataclass, replace
from pathlib import Path
from typing import Any
from repowise.server.mcp_server import _state
+from repowise.server.mcp_server._federation import Federation
from repowise.server.mcp_server._query_shape import _LINE_SUFFIX_RE, _is_path
+_log = logging.getLogger("repowise.mcp")
+
_TARGET_KINDS = frozenset({"component", "change", "module"})
+# A dotted identifier: the only bare targets the symbol locator routes.
+_IDENTIFIER_RE = re.compile(r"[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*")
@dataclass(frozen=True)
@@ -47,8 +60,9 @@ class Route:
local: str # the target inside its repo, any ``alias:`` prefix removed
repo: str | None # owning alias; None when unresolved
routed: bool = False # True when the repo came from a prefix or a lookup
- candidates: tuple[str, ...] = () # set when several repos have the path
+ candidates: tuple[str, ...] = () # set when several repos have the path or name
missed: bool = False # no repo has the path; served by the default repo
+ name: bool = False # a bare symbol name, still to be looked up
@property
def refusal(self) -> str | None:
@@ -68,7 +82,9 @@ class Route:
return entry
-def route_targets(targets: Sequence[str], *, paths_only: bool = False) -> list[Route] | None:
+async def route_targets(
+ targets: Sequence[str], *, paths_only: bool = False
+) -> list[Route] | None:
"""One :class:`Route` per target, or None outside workspace mode.
``paths_only`` reads every target without a path shape as a path anyway
@@ -79,7 +95,12 @@ def route_targets(targets: Sequence[str], *, paths_only: bool = False) -> list[R
return None
roots = _repo_roots()
default = registry.get_default_alias()
- return [_route_one(t, roots, default, paths_only) for t in targets]
+ routes = [_route_one(t, roots, default, paths_only) for t in targets]
+ names = [r.target for r in routes if r.name]
+ if names and len(roots) > 1:
+ owners = await _symbol_owners(names, roots, default)
+ routes = [_route_name(r, owners, roots, default) if r.name else r for r in routes]
+ return routes
def needs_routing(routes: list[Route] | None) -> bool:
@@ -182,12 +203,17 @@ async def run_grouped(
Cards keep the caller's target order and key; a routed card carries
``repo``. Top-level fields come from the default repo's call (else the
first), with omission refs pooled so nothing dropped is unrecoverable.
- Sequential on purpose: shared fan-out belongs to one federation helper.
+ The calls run through :class:`Federation`: a repo that fails or times out
+ is named in ``repos_failed`` and its cards say so, while the rest answer.
+ Cards carry their own freshness, so no repo-level check runs.
"""
groups = _group([r for r in routes if r.repo is not None])
- results: dict[str, dict[str, Any]] = {}
- for alias, rs in groups.items():
- results[alias] = await call(alias, list(dict.fromkeys(r.local for r in rs)))
+ local_targets = {
+ alias: list(dict.fromkeys(r.local for r in rs)) for alias, rs in groups.items()
+ }
+ federation = Federation(aliases=list(groups), check_freshness=False)
+ outcomes = await federation.run(lambda ctx: call(ctx.alias, local_targets[ctx.alias]))
+ results: dict[str, dict[str, Any]] = {ctx.alias: result for ctx, result in outcomes}
default = _state._registry.get_default_alias() if _state._registry is not None else None
lead = results.get(default) if default in results else next(iter(results.values()), {})
@@ -201,6 +227,12 @@ async def run_grouped(
if r.repo is None:
cards[r.target] = r.card()
continue
+ if r.repo not in results:
+ cards[r.target] = {
+ "repo": r.repo,
+ "error": f"Repo '{r.repo}' did not answer; see repos_failed.",
+ }
+ continue
result = results[r.repo]
card = (result.get("targets") or {}).get(r.local)
if card is None:
@@ -209,7 +241,16 @@ async def run_grouped(
merged.setdefault("_meta", {})
response = {"targets": cards, **merged}
hint_misses(response, routes)
- return response
+ return federation.annotate(response)
+
+
+def other_repo_roots() -> list[tuple[str, Path]]:
+ """The non-default workspace repos and their checkouts; empty outside workspace mode."""
+ registry = _state._registry
+ if registry is None:
+ return []
+ default = registry.get_default_alias()
+ return [(alias, root) for alias, root in _repo_roots().items() if alias != default]
# -- internals ---------------------------------------------------------------
@@ -233,7 +274,7 @@ def _route_one(target: str, roots: dict[str, Path], default: str, paths_only: bo
if not file_part or file_part.startswith("repowise#"):
return Route(target, target, default)
if not (paths_only or "::" in target or _is_path(file_part)):
- return Route(target, target, default)
+ return Route(target, target, default, name=bool(_IDENTIFIER_RE.fullmatch(target)))
if Path(file_part).is_absolute():
return _route_absolute(target, file_part, roots, default)
@@ -247,6 +288,76 @@ def _route_one(target: str, roots: dict[str, Path], default: str, paths_only: bo
return Route(target, target, default, missed=True)
+def _route_name(
+ route: Route, owners: dict[str, list[str]], roots: dict[str, Path], default: str
+) -> Route:
+ """Route a bare symbol name by the repos the locator says hold it.
+
+ *owners* carries the default repo for a name it keeps (see
+ :func:`_symbol_owners`)."""
+ repos = owners.get(route.target, [])
+ if not repos or default in repos or _exists(roots.get(default), route.target):
+ return Route(route.target, route.local, default)
+ if len(repos) == 1:
+ return Route(route.target, route.local, repos[0], routed=True)
+ return Route(route.target, route.local, None, candidates=tuple(repos))
+
+
+_store_lock = asyncio.Lock()
+
+
+async def _symbol_owners(
+ names: list[str], roots: dict[str, Path], default: str
+) -> dict[str, list[str]]:
+ """``name -> repos holding it``, in workspace order, from the workspace store.
+
+ Refreshes the store first when a repo's index moved. A symbol in a file its
+ repo excludes does not count, and a default-repo component of that name
+ counts as the default repo having it. Empty when the store is unavailable,
+ so every name stays with the default repo.
+ """
+ from repowise.core.workspace.store import refresh_workspace_store
+
+ registry = _state._registry
+ try:
+ async with _store_lock:
+ path = await refresh_workspace_store(registry.ws_config, Path(registry.workspace_root))
+ if path is None:
+ return {}
+ return await asyncio.to_thread(_owners_from_store, path, names, roots, default)
+ except Exception:
+ _log.warning("Workspace store lookup failed", exc_info=True)
+ return {}
+
+
+def _owners_from_store(
+ path: Path, names: list[str], roots: dict[str, Path], default: str
+) -> dict[str, list[str]]:
+ from repowise.core.exclusion import build_exclude_spec, is_excluded
+ from repowise.core.workspace.store import lookup_symbols
+
+ found_rows = lookup_symbols(path, names, components_of=default)
+ if found_rows is None:
+ return {}
+ hits, default_components = found_rows
+ owners: dict[str, list[str]] = {}
+ # build_exclude_spec memoises by rule-file stamps; this keeps it to one
+ # build per repo per call.
+ specs: dict[str, Any] = {}
+ for name in names:
+ found: set[str] = {default} if name.casefold() in default_components else set()
+ for alias, _symbol_id, file_path in hits.get(name, ()):
+ if alias in found or alias not in roots:
+ continue
+ if alias not in specs:
+ specs[alias] = build_exclude_spec(roots[alias])
+ if not is_excluded(file_path, specs[alias]):
+ found.add(alias)
+ if found:
+ owners[name] = [a for a in roots if a in found]
+ return owners
+
+
def _route_absolute(target: str, file_part: str, roots: dict[str, Path], default: str) -> Route:
"""An absolute path belongs to the repo whose checkout contains it."""
path = Path(os.path.normpath(file_part))
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 d221f084d..26da9eff3 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
@@ -160,7 +160,7 @@ async def get_context(
"""
if repo == "all":
return _unsupported_repo_all("get_context")
- routes = route_targets(targets) if repo is None else None
+ routes = await route_targets(targets) if repo is None else None
if needs_routing(routes):
return await run_grouped(
routes,
diff --git a/packages/server/src/repowise/server/mcp_server/tool_health/tool.py b/packages/server/src/repowise/server/mcp_server/tool_health/tool.py
index 11e25c8f4..0a969b20f 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_health/tool.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_health/tool.py
@@ -192,7 +192,7 @@ async def get_health(
)
if conflict is not None:
return _note_inapplicable_controls(conflict, scope, counts)
- routes = route_targets(targets, paths_only=True) if repo is None and targets else None
+ routes = await route_targets(targets, paths_only=True) if repo is None and targets else None
routed_repo = None
if needs_routing(routes):
routed_repo = single_repo(routes)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_risk/get_risk.py b/packages/server/src/repowise/server/mcp_server/tool_risk/get_risk.py
index 256c2ce2c..9defe47e5 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_risk/get_risk.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_risk/get_risk.py
@@ -478,7 +478,7 @@ async def get_risk(
if not targets and not changed_files:
return {"error": "targets or changed_files is required", "_meta": _build_meta()}
routes = (
- route_targets([*(targets or []), *(changed_files or [])], paths_only=True)
+ await route_targets([*(targets or []), *(changed_files or [])], paths_only=True)
if repo is None
else None
)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_symbol.py b/packages/server/src/repowise/server/mcp_server/tool_symbol.py
index 461a048b9..b50067a7a 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_symbol.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_symbol.py
@@ -47,6 +47,7 @@ import json
import re
import sqlite3
import time
+from collections.abc import Sequence
from datetime import UTC, datetime
from pathlib import Path
from typing import Any, NamedTuple
@@ -93,6 +94,7 @@ from repowise.server.mcp_server._verify import (
from repowise.server.mcp_server._workspace_routing import (
hint_misses,
needs_routing,
+ other_repo_roots,
route_targets,
)
@@ -501,26 +503,37 @@ def _extract_omission_ref(symbol_id: str) -> str | None:
def _resolve_omission_ref(
- symbol_id: str, ref: str, query: str | None, repo_root: Any, t0: float
+ symbol_id: str,
+ ref: str,
+ query: str | None,
+ repo_root: Any,
+ t0: float,
+ other_roots: Sequence[tuple[str, Path]] = (),
) -> dict:
"""Look *ref* up in the omission store(s) and shape a tool response.
- Checks the repo-local store first, then the user-level fallback —
- the same order as ``repowise expand``. Stores are only opened when the
- DB file already exists (opening would otherwise create an empty one).
+ Checks the repo-local store first, then the stores of *other_roots* (the
+ other workspace repos, whose responses write their own), then the
+ user-level fallback — the same order as ``repowise expand``. Stores are
+ only opened when the DB file already exists (opening would otherwise
+ create an empty one). A ref is a content hash, so the first store holding
+ it has the content.
"""
from repowise.core.distill.store import OmissionStore, default_store_path
canonical_ref = f"repowise#{ref}"
- candidates: list[Path] = []
+ candidates: list[tuple[str | None, Path]] = []
if repo_root:
- candidates.append(default_store_path(Path(str(repo_root))))
+ candidates.append((None, default_store_path(Path(str(repo_root)))))
+ for alias, root in other_roots:
+ candidates.append((alias, default_store_path(root)))
home_store = default_store_path(Path.home())
- if home_store not in candidates:
- candidates.append(home_store)
+ if home_store not in {path for _alias, path in candidates}:
+ candidates.append((None, home_store))
record: dict | None = None
- for db_path in candidates:
+ found_in: str | None = None
+ for alias, db_path in candidates:
try:
if not db_path.exists():
continue
@@ -534,6 +547,7 @@ def _resolve_omission_ref(
# Recovery must never make get_symbol itself fail.
continue
if record is not None:
+ found_in = alias
break
if record is None:
@@ -550,6 +564,7 @@ def _resolve_omission_ref(
created = record.get("created_at")
response: dict[str, Any] = {
+ **({"repo": found_in} if found_in else {}),
"symbol_id": symbol_id,
"ref": canonical_ref,
"kind": "omission",
@@ -1056,10 +1071,15 @@ async def get_symbol(
if omission_ref is not None:
canonical_omission = omission_reference(symbol_id) or symbol_id
return _resolve_omission_ref(
- canonical_omission, omission_ref, query, ctx.path, t0
+ canonical_omission,
+ omission_ref,
+ query,
+ ctx.path,
+ t0,
+ other_repo_roots() if repo is None else (),
)
- routes = route_targets([symbol_id.strip()]) if repo is None else None
+ routes = await route_targets([symbol_id.strip()]) if repo is None else None
if needs_routing(routes):
route = routes[0]
if route.repo is None:
diff --git a/tests/unit/server/test_mcp_workspace_routing.py b/tests/unit/server/test_mcp_workspace_routing.py
index 7e583d32a..37fb0b6f6 100644
--- a/tests/unit/server/test_mcp_workspace_routing.py
+++ b/tests/unit/server/test_mcp_workspace_routing.py
@@ -39,15 +39,15 @@ def _by_target(routes: list[Route]) -> dict[str, Route]:
# -- the router -------------------------------------------------------------
-def test_router_is_off_outside_workspace_mode():
+async def test_router_is_off_outside_workspace_mode():
assert _state._registry is None
- assert route_targets(["src/probe.py", "frontend:src/probe.py"]) is None
+ assert await route_targets(["src/probe.py", "frontend:src/probe.py"]) is None
async def test_router_rules(routed_ws):
abs_fe = str(routed_ws.workspace_root / "web-client" / "src" / "only_fe.py")
routes = _by_target(
- route_targets(
+ await route_targets(
[
"src/probe.py",
"src/only_fe.py",
@@ -79,7 +79,7 @@ async def test_router_rules(routed_ws):
async def test_router_never_lets_a_path_escape_its_repo(routed_ws):
- (route,) = route_targets(["../web-client/src/only_fe.py"])
+ (route,) = await route_targets(["../web-client/src/only_fe.py"])
assert (route.repo, route.missed) == ("backend", True)
@@ -248,3 +248,138 @@ async def test_get_health_refuses_cross_repo_and_ambiguous_hints_unknown(routed_
unknown = await get_health(targets=["src/nowhere.py"])
assert "repo" not in unknown
assert "search_codebase" in unknown["unresolved"][0]["hint"]
+
+
+# -- bare symbol names, through the workspace store -----------------------------
+
+
+async def located_ws(routed_ws):
+ from tests.unit.workspace.test_store import write_repo_index
+
+ root = routed_ws.workspace_root
+ await write_repo_index(
+ root / "backend",
+ "backend",
+ {"src/probe.py": ["backend_probe", "everywhere"], "auth/login.py": ["login"]},
+ )
+ await write_repo_index(
+ root / "web-client",
+ "frontend",
+ {
+ "src/only_fe.py": ["only_fe", "Widget.paint", "twice", "auth"],
+ "src/probe.py": ["everywhere"],
+ "gen/out.py": ["generated_only"],
+ },
+ )
+ await write_repo_index(root / "docs-site", "docs", {"src/shared.py": ["twice"]})
+ (root / "web-client" / ".gitignore").write_text("gen/\n")
+ return routed_ws
+
+
+async def test_router_routes_bare_names_by_the_locator(located_ws):
+ targets = [
+ "only_fe",
+ "Widget.paint",
+ "paint",
+ "twice",
+ "everywhere",
+ "backend_probe",
+ "nowhere_at_all",
+ "generated_only",
+ "auth",
+ "only fe",
+ ]
+ routes = _by_target(await route_targets(targets))
+ for name in ("only_fe", "Widget.paint", "paint"):
+ assert routes[name] == Route(name, name, "frontend", routed=True)
+ assert routes["twice"].repo is None
+ assert routes["twice"].candidates == ("frontend", "docs")
+ # The default repo keeps a name it has, wherever else it also lives.
+ assert routes["everywhere"] == Route("everywhere", "everywhere", "backend")
+ assert routes["backend_probe"] == Route("backend_probe", "backend_probe", "backend")
+ # Unknown, or only in a file its repo excludes: the default repo, as before.
+ assert routes["nowhere_at_all"] == Route("nowhere_at_all", "nowhere_at_all", "backend")
+ assert routes["generated_only"] == Route("generated_only", "generated_only", "backend")
+ # A default-repo component name stays there, though another repo has the symbol.
+ assert routes["auth"] == Route("auth", "auth", "backend")
+ # Only identifier-shaped names are looked up.
+ assert routes["only fe"] == Route("only fe", "only fe", "backend")
+ # Paths and target kinds are untouched by the locator.
+ assert (await route_targets(["module:src"]))[0] == Route("module:src", "module:src", "backend")
+
+
+async def test_paths_only_tools_never_read_the_locator(located_ws):
+ from repowise.core.workspace.store import store_path
+
+ (route,) = await route_targets(["only_fe"], paths_only=True)
+ assert (route.repo, route.missed) == ("backend", True)
+ assert not store_path(located_ws.workspace_root).exists()
+
+
+async def test_get_context_and_get_symbol_route_a_bare_name(located_ws):
+ from repowise.server.mcp_server import get_context, get_symbol
+
+ cards = (await get_context(targets=["only_fe", "twice", "everywhere"]))["targets"]
+ assert cards["only_fe"]["repo"] == "frontend"
+ assert cards["twice"]["candidates"] == ["frontend", "docs"]
+ assert "frontend:twice" in cards["twice"]["error"]
+ assert "repo" not in cards["everywhere"]
+
+ assert (await get_symbol("only_fe"))["repo"] == "frontend"
+ assert (await get_symbol("twice"))["candidates"] == ["frontend", "docs"]
+
+
+async def test_get_symbol_finds_an_omission_ref_in_another_repo(located_ws):
+ from repowise.core.distill.store import OmissionStore, default_store_path
+ from repowise.server.mcp_server import get_symbol
+
+ store = OmissionStore(default_store_path(located_ws.workspace_root / "web-client"))
+ ref = store.put("frontend payload", source="mcp:get_context", original_tokens=9, kept_tokens=1)
+ store.close()
+
+ result = await get_symbol(f"repowise#{ref}")
+ assert result["repo"] == "frontend"
+ assert result["content"] == "frontend payload"
+ pinned = await get_symbol(f"repowise#{ref}", repo="backend")
+ assert "error" in pinned
+
+
+async def test_a_routed_batch_survives_a_failing_repo(routed_ws, monkeypatch):
+ from repowise.server.mcp_server import get_context
+
+ real_get = routed_ws.get
+
+ async def flaky(alias):
+ if alias == "frontend":
+ raise RuntimeError("index unreadable")
+ return await real_get(alias)
+
+ monkeypatch.setattr(routed_ws, "get", flaky)
+ result = await get_context(targets=["src/probe.py", "src/only_fe.py"])
+ assert result["targets"]["src/probe.py"]["docs"]["title"] == "Backend Probe"
+ assert "did not answer" in result["targets"]["src/only_fe.py"]["error"]
+ assert result["repos_failed"] == [
+ {"repo": "frontend", "reason": "RuntimeError: index unreadable"}
+ ]
+
+
+async def test_a_routed_batch_survives_a_repo_timing_out(routed_ws, monkeypatch):
+ import asyncio
+
+ from repowise.server.mcp_server import get_context
+
+ real_get = routed_ws.get
+
+ async def slow(alias):
+ if alias == "frontend":
+ await asyncio.sleep(30)
+ return await real_get(alias)
+
+ monkeypatch.setenv("REPOWISE_WORKSPACE_REPO_TIMEOUT_S", "0.5")
+ monkeypatch.setattr(routed_ws, "get", slow)
+ result = await get_context(targets=["src/probe.py", "src/only_fe.py"])
+ assert result["targets"]["src/probe.py"]["docs"]["title"] == "Backend Probe"
+ assert result["targets"]["src/only_fe.py"]["repo"] == "frontend"
+ assert "did not answer" in result["targets"]["src/only_fe.py"]["error"]
+ assert result["repos_failed"] == [{"repo": "frontend", "reason": "timed out after 0.5s"}]
diff --git a/tests/unit/workspace/test_store.py b/tests/unit/workspace/test_store.py
new file mode 100644
index 000000000..d11d87ba2
--- /dev/null
+++ b/tests/unit/workspace/test_store.py
@@ -0,0 +1,261 @@
+"""The workspace store: rebuild, staleness, corrupt-file recovery."""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from datetime import UTC, datetime
+from pathlib import Path
+
+from repowise.core.persistence.models import (
+ Change,
+ GraphNode,
+ HealthSnapshot,
+ Repository,
+ WikiSymbol,
+)
+from repowise.core.workspace.config import RepoEntry, WorkspaceConfig
+from repowise.core.workspace.registry import open_repo_db
+from repowise.core.workspace.store import (
+ SCHEMA_VERSION,
+ lookup_symbols,
+ refresh_workspace_store,
+ store_path,
+)
+from repowise.core.workspace.update import run_cross_repo_hooks
+
+
+async def write_repo_index(repo: Path, alias: str, symbols: dict[str, list[str]]) -> None:
+ """A real ``wiki.db`` for *repo*: file nodes and symbols by file, one change,
+ one health snapshot, and a ``state.json`` stamp."""
+ (repo / ".repowise").mkdir(parents=True, exist_ok=True)
+ engine, factory = await open_repo_db(repo)
+ rid = f"repo-{alias}"
+ async with factory() as session:
+ session.add(Repository(id=rid, name=alias, url="", local_path=str(repo)))
+ await session.flush()
+ for path, names in symbols.items():
+ session.add(GraphNode(repository_id=rid, node_id=path, node_type="file"))
+ for name in names:
+ session.add(
+ WikiSymbol(
+ repository_id=rid,
+ file_path=path,
+ symbol_id=f"{path}::{name}",
+ name=name.rsplit(".", 1)[-1],
+ qualified_name=name,
+ kind="function",
+ )
+ )
+ session.add(
+ Change(
+ repository_id=rid,
+ change_id="pr-7",
+ identity_kind="pr",
+ identity_value="7",
+ shape="squash",
+ title=f"{alias} change",
+ merged_at=datetime(2026, 10, 1, tzinfo=UTC),
+ head_sha="a" * 40,
+ files_changed=2,
+ )
+ )
+ session.add(HealthSnapshot(repository_id=rid, average_health=7.5))
+ await session.commit()
+ await engine.dispose()
+ touch_state(repo)
+
+
+def touch_state(repo: Path) -> None:
+ """What an index run does: rewrite ``state.json``."""
+ state = repo / ".repowise" / "state.json"
+ n = json.loads(state.read_text())["n"] + 1 if state.exists() else 0
+ state.write_text(json.dumps({"n": n}))
+ os.utime(state, ns=(state.stat().st_atime_ns, state.stat().st_mtime_ns + n + 1))
+
+
+async def add_symbol(repo: Path, alias: str, path: str, name: str) -> None:
+ engine, factory = await open_repo_db(repo)
+ async with factory() as session:
+ session.add(
+ WikiSymbol(
+ repository_id=f"repo-{alias}",
+ file_path=path,
+ symbol_id=f"{path}::{name}",
+ name=name,
+ qualified_name=name,
+ kind="function",
+ )
+ )
+ await session.commit()
+ await engine.dispose()
+
+
+def make_config(*aliases: str) -> WorkspaceConfig:
+ return WorkspaceConfig(repos=[RepoEntry(path=a, alias=a) for a in aliases])
+
+
+async def make_workspace(tmp_path: Path) -> tuple[WorkspaceConfig, Path]:
+ await write_repo_index(tmp_path / "api", "api", {"src/app.py": ["serve", "App.run"]})
+ await write_repo_index(tmp_path / "web", "web", {"src/ui.ts": ["render", "serve"]})
+ return make_config("api", "web"), tmp_path
+
+
+def symbols(path: Path, names: list[str]) -> dict:
+ found = lookup_symbols(path, names)
+ assert found is not None
+ return found[0]
+
+
+def rows(path: Path, sql: str) -> list[tuple]:
+ conn = sqlite3.connect(path)
+ try:
+ return conn.execute(sql).fetchall()
+ finally:
+ conn.close()
+
+
+async def test_refresh_builds_every_table_from_the_repo_indexes(tmp_path):
+ config, root = await make_workspace(tmp_path)
+ path = await refresh_workspace_store(config, root)
+
+ assert path == store_path(root)
+ assert rows(path, "PRAGMA user_version") == [(SCHEMA_VERSION,)]
+ assert sorted(rows(path, "SELECT alias, path FROM files")) == [
+ ("api", "src/app.py"),
+ ("web", "src/ui.ts"),
+ ]
+ repos = {r[0]: r for r in rows(path, "SELECT alias, indexed, health_json, error FROM repos")}
+ assert repos["api"][1] == 1 and repos["api"][3] is None
+ assert json.loads(repos["api"][2])["average_health"] == 7.5
+ assert rows(path, "SELECT alias, change_id, title FROM changes WHERE alias='web'") == [
+ ("web", "pr-7", "web change")
+ ]
+ # Derived components (top-level directories here) per repo.
+ assert ("api", "src") in rows(path, "SELECT alias, name FROM components")
+ assert lookup_symbols(path, [], components_of="api") == ({}, {"src"})
+
+ assert symbols(path, ["serve", "App.run", "run", "missing"]) == {
+ "serve": [
+ ("api", "src/app.py::serve", "src/app.py"),
+ ("web", "src/ui.ts::serve", "src/ui.ts"),
+ ],
+ "App.run": [("api", "src/app.py::App.run", "src/app.py")],
+ "run": [("api", "src/app.py::App.run", "src/app.py")],
+ }
+
+
+async def test_a_deleted_store_is_rebuilt(tmp_path):
+ config, root = await make_workspace(tmp_path)
+ path = await refresh_workspace_store(config, root)
+ path.unlink()
+ assert await refresh_workspace_store(config, root) == path
+ assert symbols(path, ["render"]) == {
+ "render": [("web", "src/ui.ts::render", "src/ui.ts")]
+ }
+
+
+async def test_only_repos_whose_index_moved_are_reread(tmp_path):
+ config, root = await make_workspace(tmp_path)
+ path = await refresh_workspace_store(config, root)
+ before = dict(rows(path, "SELECT alias, refreshed_at FROM repos"))
+
+ # A database write alone (a serving read, a cache) leaves the stamp alone.
+ await add_symbol(root / "api", "api", "src/app.py", "late")
+ await refresh_workspace_store(config, root)
+ assert symbols(path, ["late"]) == {}
+
+ # An index run rewrites state.json: that repo, and only it, is re-read.
+ touch_state(root / "api")
+ await refresh_workspace_store(config, root)
+ assert symbols(path, ["late"]) == {"late": [("api", "src/app.py::late", "src/app.py")]}
+ after = dict(rows(path, "SELECT alias, refreshed_at FROM repos"))
+ assert after["web"] == before["web"]
+ assert after["api"] != before["api"]
+
+
+async def test_a_repo_leaving_the_workspace_drops_its_rows(tmp_path):
+ config, root = await make_workspace(tmp_path)
+ path = await refresh_workspace_store(config, root)
+ await refresh_workspace_store(make_config("web"), root)
+ assert {r[0] for r in rows(path, "SELECT DISTINCT alias FROM symbols")} == {"web"}
+ assert rows(path, "SELECT alias FROM repos") == [("web",)]
+
+
+async def test_an_unindexed_repo_is_listed_without_rows(tmp_path):
+ config, root = await make_workspace(tmp_path)
+ (root / "docs").mkdir()
+ config.repos.append(RepoEntry(path="docs", alias="docs"))
+ path = await refresh_workspace_store(config, root)
+ assert rows(path, "SELECT indexed FROM repos WHERE alias='docs'") == [(0,)]
+ assert not (root / "docs" / ".repowise" / "wiki.db").exists()
+
+
+async def test_a_corrupt_store_is_rebuilt_never_fatal(tmp_path):
+ config, root = await make_workspace(tmp_path)
+ path = store_path(root)
+ path.parent.mkdir(parents=True)
+ path.write_bytes(b"not a database at all" * 100)
+
+ assert await refresh_workspace_store(config, root) == path
+ assert "render" in symbols(path, ["render"])
+
+
+async def test_a_corrupt_store_found_by_a_reader_is_discarded(tmp_path):
+ config, root = await make_workspace(tmp_path)
+ path = await refresh_workspace_store(config, root)
+ path.write_bytes(b"garbage" * 1000)
+ assert lookup_symbols(path, ["render"]) is None
+ assert not path.exists()
+ await refresh_workspace_store(config, root)
+ assert "render" in symbols(path, ["render"])
+
+
+async def test_an_older_schema_is_rebuilt(tmp_path):
+ config, root = await make_workspace(tmp_path)
+ path = await refresh_workspace_store(config, root)
+ conn = sqlite3.connect(path)
+ conn.execute("PRAGMA user_version=0")
+ conn.execute("CREATE TABLE leftover (x)")
+ conn.close()
+ await refresh_workspace_store(config, root)
+ assert rows(path, "PRAGMA user_version") == [(SCHEMA_VERSION,)]
+ assert not rows(path, "SELECT name FROM sqlite_master WHERE name='leftover'")
+ assert "render" in symbols(path, ["render"])
+
+
+async def test_workspace_update_hooks_refresh_the_store(tmp_path):
+ config, root = await make_workspace(tmp_path)
+ await run_cross_repo_hooks(config, root, ["api", "web"])
+ assert "serve" in symbols(store_path(root), ["serve"])
+
+
+async def test_a_single_repo_workspace_gets_no_store(tmp_path):
+ await write_repo_index(tmp_path / "api", "api", {"src/app.py": ["serve"]})
+ await run_cross_repo_hooks(make_config("api"), tmp_path, ["api"])
+ assert not store_path(tmp_path).exists()
+
+
+async def test_a_store_missing_its_tables_is_rebuilt(tmp_path):
+ config, root = await make_workspace(tmp_path)
+ path = await refresh_workspace_store(config, root)
+ conn = sqlite3.connect(path)
+ conn.execute("DROP TABLE repos")
+ conn.close()
+ assert await refresh_workspace_store(config, root) is None # discarded, not served
+ assert await refresh_workspace_store(config, root) == path
+ assert "render" in symbols(path, ["render"])
+
+
+async def test_an_unmoved_workspace_refreshes_without_opening_the_store(tmp_path, monkeypatch):
+ from repowise.core.workspace import store as store_mod
+
+ config, root = await make_workspace(tmp_path)
+ path = await refresh_workspace_store(config, root)
+
+ def refuse(*_args):
+ raise AssertionError("opened the store")
+
+ monkeypatch.setattr(store_mod, "WorkspaceStore", refuse)
+ assert await refresh_workspace_store(config, root) == path