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
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.pyindex 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.pyindex 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 storygit_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 notdiff --git a/tests/unit/server/mcp/test_why.py b/tests/unit/server/mcp/test_why.pyindex 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 DecisionRecordfrom 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 fallbackresult = 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" termsdiff --git a/tests/unit/server/mcp/test_why_evidence_contract.py b/tests/unit/server/mcp/test_why_evidence_contract.pyindex 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",