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.

fix(why): say when the index has no accepted decisions or the path is missing (#3654)

Swati Ahuja3c3335d67a46
diff --git a/packages/server/src/repowise/server/mcp_server/_helpers.py b/packages/server/src/repowise/server/mcp_server/_helpers.py
index 2ce9f8678..a2239c0ab 100644
--- a/packages/server/src/repowise/server/mcp_server/_helpers.py
+++ b/packages/server/src/repowise/server/mcp_server/_helpers.py
@@ -556,12 +556,17 @@ def _compute_alignment(
reachable from any caller that forgot it.
"""
if not governing:
+ # With nothing accepted anywhere, "ungoverned" describes the index, not
+ # this file, so say that instead.
+ reason = (
+ "This file is ungoverned — it may be an outlier or simply undocumented."
+ if currencies
+ else "This index holds no accepted decisions, so no file is governed "
+ "yet; a person accepts a candidate with `repowise decision confirm`."
+ )
return {
"score": "none",
- "explanation": (
- f"No architectural decisions govern {file_path}. "
- "This file is ungoverned — it may be an outlier or simply undocumented."
- ),
+ "explanation": f"No architectural decisions govern {file_path}. {reason}",
"governing_count": 0,
"active_count": 0,
"candidate_count": 0,
diff --git a/packages/server/src/repowise/server/mcp_server/tool_why/path_mode.py b/packages/server/src/repowise/server/mcp_server/tool_why/path_mode.py
index cde93302f..57df7b2f8 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_why/path_mode.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_why/path_mode.py
@@ -70,11 +70,20 @@ async def _why_path(query: str, repo: str | None) -> dict:
# Load git metadata for origin story
git_meta = await _git_metadata_for(session, repository.id, query)
+ matched = _records_naming_path(all_decisions, query)
+ # A typo or a stale path: nothing to excavate, so say so before the
+ # archaeology fallback mines unrelated commits for it.
+ if git_meta is None and not matched and not _maybe_on_disk(ctx.path, query):
+ return {
+ "mode": "path",
+ "path": query,
+ "error": f"Path not found: '{query}' is neither in the checkout "
+ "nor in the indexed git history.",
+ }
# Pre-load all git metadata for cross-file search (used by fallback)
all_git_meta = await _all_git_metadata(session, repository.id)
- matched = _records_naming_path(all_decisions, query)
# A record with no acceptance row is a candidate whatever its status.
# Over every record, since alignment reads records this path did not match.
currencies = await decision_currencies(session, repository.id, all_decisions)
@@ -136,6 +145,23 @@ async def _why_path(query: str, repo: str | None) -> dict:
return _fit_path_response(result_data, ctx.path, collector=collector)
+def _maybe_on_disk(repo_path: str | Path | None, path: str) -> bool:
+ """False only when the checkout is known and *path* is not in it.
+
+ Resolved and contained, like ``read_repo_file_text``: an absolute path,
+ a ``..`` escape or a symlink out of the checkout is not in it.
+ """
+ if not repo_path:
+ return True
+ root = Path(repo_path).resolve()
+ try:
+ candidate = (root / path).resolve()
+ candidate.relative_to(root)
+ except (OSError, ValueError):
+ return False
+ return candidate.exists()
+
+
def _records_naming_path(all_decisions: list, path: str) -> list:
"""Records whose own scope names *path* as a file or a module."""
# A record whose file list is just its source commit's footprint does not
diff --git a/tests/unit/server/mcp/test_why.py b/tests/unit/server/mcp/test_why.py
index 11586ed14..95e65973f 100644
--- a/tests/unit/server/mcp/test_why.py
+++ b/tests/unit/server/mcp/test_why.py
@@ -127,10 +127,25 @@ async def test_get_why_file_no_git_metadata(setup_mcp):
assert alignment["candidate_count"] >= 1
+def _write(root, path: str) -> None:
+ """Put *path* in the checkout, so path mode treats it as a real file."""
+ (root / path).parent.mkdir(parents=True, exist_ok=True)
+ (root / path).write_text("x = 1\n", encoding="utf-8")
+
+
@pytest.mark.asyncio
-async def test_get_why_file_ungoverned(setup_mcp):
+async def test_get_why_file_ungoverned(session, setup_mcp, tmp_path):
+ from repowise.core.persistence.crud.authority import accept_decision
+ from repowise.core.persistence.models import DecisionRecord
from repowise.server.mcp_server import get_why
+ # An accepted decision exists, just not one naming this file.
+ await accept_decision(
+ session, await session.get(DecisionRecord, "dec2"), accepter="test", evidence=["pr#1"]
+ )
+ await session.flush()
+ _write(tmp_path, "src/other/utils.py")
+
# Use a path that has no decisions — triggers git archaeology fallback
result = await get_why("src/other/utils.py")
assert result["mode"] == "path"
@@ -148,9 +163,56 @@ async def test_get_why_file_ungoverned(setup_mcp):
@pytest.mark.asyncio
-async def test_get_why_fallback_with_cross_references(setup_mcp):
+async def test_get_why_says_when_the_index_has_no_accepted_decisions(setup_mcp, tmp_path):
+ """With nothing accepted anywhere, "ungoverned" would blame the file."""
+ from repowise.server.mcp_server import get_why
+
+ _write(tmp_path, "src/other/utils.py")
+ result = await get_why("src/other/utils.py")
+
+ explanation = result["alignment"]["explanation"]
+ assert "holds no accepted decisions" in explanation
+ assert "ungoverned" not in explanation
+
+
+async def test_get_why_path_not_found_skips_archaeology(setup_mcp):
+ """A path in neither the checkout nor git history gets a short answer."""
from repowise.server.mcp_server import get_why
+ result = await get_why("src/nowhere/typo.py")
+
+ assert result["mode"] == "path"
+ assert "Path not found" in result["error"]
+ assert "git_archaeology" not in result
+ assert "alignment" not in result
+
+
+def test_a_path_outside_the_checkout_is_not_on_disk(tmp_path):
+ """Absolute paths, ``..`` escapes and symlinks out are not in the checkout."""
+ from repowise.server.mcp_server.tool_why.path_mode import _maybe_on_disk
+
+ root = tmp_path / "repo"
+ _write(root, "src/a.py")
+ _write(tmp_path, "outside.py")
+
+ assert _maybe_on_disk(root, "src/a.py")
+ assert not _maybe_on_disk(root, str(tmp_path / "outside.py"))
+ assert not _maybe_on_disk(root, "../outside.py")
+ try:
+ (root / "link.py").symlink_to(tmp_path / "outside.py")
+ except OSError:
+ pytest.skip("symlinks need privileges on this platform")
+ assert not _maybe_on_disk(root, "link.py")
+
+
+async def test_get_why_fallback_with_cross_references(setup_mcp, tmp_path):
+ from repowise.server.mcp_server import get_why
+
+ # A new file with no history yet: on disk, absent from git metadata.
+ _write(tmp_path, "src/auth/new_handler.py")
+
# src/auth/service.py has git metadata with commits mentioning "auth"
# Query a nonexistent auth file — cross-references should find commits
# from service.py that mention "auth" terms
diff --git a/tests/unit/server/mcp/test_why_evidence_contract.py b/tests/unit/server/mcp/test_why_evidence_contract.py
index 1875a5892..5f3089e0b 100644
--- a/tests/unit/server/mcp/test_why_evidence_contract.py
+++ b/tests/unit/server/mcp/test_why_evidence_contract.py
@@ -567,9 +567,14 @@ async def test_every_single_repository_mode_is_exactly_accounted_after_middlewar
@pytest.mark.asyncio
-async def test_no_decision_and_unsupported_modes_remain_compatible(setup_mcp) -> None:
+async def test_no_decision_and_unsupported_modes_remain_compatible(
+ setup_mcp, tmp_path
+) -> None:
from repowise.server.mcp_server import get_why
+ # On disk, so path mode answers rather than reporting the path missing.
+ (tmp_path / "src/other").mkdir(parents=True)
+ (tmp_path / "src/other/utils.py").write_text("x = 1\n", encoding="utf-8")
fallback = await get_why("src/other/utils.py")
assert list(fallback)[:5] == [
"mode",