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
refactor(core): move knowledge silo ranking and onboarding targets into core (#2517)
Raghav Chamadiya991a9ec3af4a
diff --git a/packages/core/src/repowise/core/analysis/knowledge_map.py b/packages/core/src/repowise/core/analysis/knowledge_map.pynew file mode 100644index 000000000..42f72ada0--- /dev/null+++ b/packages/core/src/repowise/core/analysis/knowledge_map.py@@ -0,0 +1,85 @@+"""Knowledge silos and onboarding targets, folded from rows the caller fetched.++Sync, no I/O, no clock. The server reads these rows with SQL; any other+producer can hand in the same keys from its own store. Rows may be dicts,+dataclasses or ORM/SQL rows (read through :func:`..health.rows.field`).+"""++from __future__ import annotations++from collections.abc import Iterable, Mapping+from typing import Any++from repowise.core.analysis.health.rows import field++#: A file is a silo when its primary owner holds more than this share of commits.+SILO_OWNER_PCT = 0.8++#: Onboarding targets returned per repository.+ONBOARDING_LIMIT = 10+++def rank_silos(git_rows: Iterable[Any]) -> list[dict[str, Any]]:+ """Files whose primary owner holds more than :data:`SILO_OWNER_PCT`, riskiest first.++ Each row carries ``file_path``, ``primary_owner_email``,+ ``primary_owner_commit_pct``, ``commit_count_90d`` and ``is_hotspot``; rows at+ or under the threshold are dropped, so a caller may pass every file.+ """+ kept = [r for r in git_rows if (field(r, "primary_owner_commit_pct") or 0.0) > SILO_OWNER_PCT]+ # Activity first, concentration second: sole ownership of a file nobody+ # touches is a fact, not a risk, so previews should lead with live code.+ kept.sort(+ key=lambda r: (+ not field(r, "is_hotspot"),+ field(r, "commit_count_90d") is None,+ -(field(r, "commit_count_90d") or 0),+ -field(r, "primary_owner_commit_pct"),+ )+ )+ return [+ {+ "file_path": field(r, "file_path"),+ "owner_email": field(r, "primary_owner_email") or "",+ "owner_pct": round(float(field(r, "primary_owner_commit_pct")), 3),+ "commit_count_90d": int(field(r, "commit_count_90d") or 0),+ "is_hotspot": bool(field(r, "is_hotspot")),+ }+ for r in kept+ ]+++def onboarding_targets(+ file_nodes: Iterable[Any],+ doc_size: Mapping[str, int],+ *,+ limit: int = ONBOARDING_LIMIT,+) -> list[dict[str, Any]]:+ """High-centrality files carrying the least documentation.++ ``file_nodes`` are non-test graph nodes with ``node_id`` and ``pagerank``;+ nodes without a positive pagerank are skipped. ``doc_size`` maps a path to+ its file page's word count, or any measure that ranks like one; 0 or absent+ when undocumented. Rows report it as ``doc_words``, so a caller ranking by a+ proxy must swap exact words in. Sorted by size, then pagerank descending;+ ties keep input order.+ """+ candidates = [+ {+ "path": field(n, "node_id"),+ "pagerank": field(n, "pagerank"),+ "doc_words": doc_size.get(field(n, "node_id"), 0),+ }+ for n in file_nodes+ if (field(n, "pagerank") or 0.0) > 0.0+ ]+ candidates.sort(key=lambda c: (c["doc_words"], -c["pagerank"]))+ return candidates[:limit]+++__all__ = [+ "ONBOARDING_LIMIT",+ "SILO_OWNER_PCT",+ "onboarding_targets",+ "rank_silos",+]diff --git a/packages/server/src/repowise/server/services/knowledge_map.py b/packages/server/src/repowise/server/services/knowledge_map.pyindex 2c5c265d3..64588ee15 100644--- a/packages/server/src/repowise/server/services/knowledge_map.py+++ b/packages/server/src/repowise/server/services/knowledge_map.py@@ -8,6 +8,11 @@ from typing import Anyfrom sqlalchemy import func, selectfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.analysis.knowledge_map import (+ SILO_OWNER_PCT,+ onboarding_targets,+ rank_silos,+)from repowise.core.persistence.models import GitMetadata, GraphNode, Page@@ -20,7 +25,7 @@ async def compute_knowledge_silos(session: AsyncSession, repo_id: str) -> list[dblob columns) and loads the full ``content`` of every file page to countwords for a top-10 onboarding list Overview never reads.- Three columns, one query, no entity hydration.+ Five columns, one query, no entity hydration; ranked by :func:`rank_silos`."""rows = await session.execute(select(@@ -29,32 +34,12 @@ async def compute_knowledge_silos(session: AsyncSession, repo_id: str) -> list[dGitMetadata.primary_owner_commit_pct,GitMetadata.commit_count_90d,GitMetadata.is_hotspot,- )- .where(+ ).where(GitMetadata.repository_id == repo_id,- GitMetadata.primary_owner_commit_pct > 0.8,- )- # Activity first, concentration second. Sole ownership of a file nobody- # has touched in a year is a fact, not a risk: the bus factor only- # costs anything on code that still changes. Ordered here so every- # caller previewing a few of these gets the ones that matter rather- # than whatever the table returned first.- .order_by(- GitMetadata.is_hotspot.desc(),- GitMetadata.commit_count_90d.desc().nulls_last(),- GitMetadata.primary_owner_commit_pct.desc(),+ GitMetadata.primary_owner_commit_pct > SILO_OWNER_PCT,))- return [- {- "file_path": file_path,- "owner_email": owner_email or "",- "owner_pct": round(float(owner_pct or 0.0), 3),- "commit_count_90d": int(commits or 0),- "is_hotspot": bool(is_hotspot),- }- for file_path, owner_email, owner_pct, commits, is_hotspot in rows- ]+ return rank_silos(rows)async def compute_onboarding_targets(@@ -67,7 +52,7 @@ async def compute_onboarding_targets(feeds the first-index experience. Overview used to reach it through:func:`compute_knowledge_map` and pay for the owner aggregation as well."""- # `pagerank > 0` in SQL, not in the comprehension below: the filter+ # `pagerank > 0` in SQL too, though the fold repeats it: the filter# discards most rows and there is no reason to ship them.node_result = await session.execute(select(GraphNode.node_id, GraphNode.pagerank).where(@@ -93,21 +78,11 @@ async def compute_onboarding_targets())doc_chars: dict[str, int] = {path: int(n or 0) for path, n in size_result}-- candidates = [- {- "path": node_id,- "pagerank": pagerank,- "doc_chars": doc_chars.get(node_id, 0),- }- for node_id, pagerank in all_nodes- ]- candidates.sort(key=lambda x: (x["doc_chars"], -x["pagerank"]))- shortlist = candidates[:10]+ shortlist = onboarding_targets(all_nodes, doc_chars)# Exact words for the ten rows that are actually returned. Most of them are# undocumented files with no page at all, so this usually fetches nothing.- documented = [c["path"] for c in shortlist if c["doc_chars"] > 0]+ documented = [c["path"] for c in shortlist if c["doc_words"] > 0]exact_words: dict[str, int] = {}if documented:word_rows = await session.execute(@@ -119,16 +94,7 @@ async def compute_onboarding_targets()exact_words = {path: len((content or "").split()) for path, content in word_rows}- onboarding_targets = [- {- "path": c["path"],- "pagerank": c["pagerank"],- "doc_words": exact_words.get(c["path"], 0),- }- for c in shortlist- ]-- return onboarding_targets+ return [{**c, "doc_words": exact_words.get(c["path"], 0)} for c in shortlist]async def compute_knowledge_map(session: AsyncSession, repo_id: str) -> dict[str, Any]:@@ -191,13 +157,11 @@ async def compute_knowledge_map(session: AsyncSession, repo_id: str) -> dict[str"owner_pct": round(float(pct or 0.0), 3),}for file_path, owner_email, _owner_name, pct in all_git- if (pct or 0.0) > 0.8+ if (pct or 0.0) > SILO_OWNER_PCT]- onboarding_targets = await compute_onboarding_targets(session, repo_id)-return {"top_owners": top_owners,"knowledge_silos": knowledge_silos,- "onboarding_targets": onboarding_targets,+ "onboarding_targets": await compute_onboarding_targets(session, repo_id),}diff --git a/tests/unit/analysis/test_knowledge_map_folds.py b/tests/unit/analysis/test_knowledge_map_folds.pynew file mode 100644index 000000000..2c35e8c94--- /dev/null+++ b/tests/unit/analysis/test_knowledge_map_folds.py@@ -0,0 +1,60 @@+"""The knowledge-map folds over plain dicts, as a non-SQL producer passes them."""++from __future__ import annotations++from repowise.core.analysis.knowledge_map import onboarding_targets, rank_silos+++def _git(path, pct, commits=0, hotspot=False, email="[email protected]"):+ return {+ "file_path": path,+ "primary_owner_email": email,+ "primary_owner_commit_pct": pct,+ "commit_count_90d": commits,+ "is_hotspot": hotspot,+ }+++def test_rank_silos_filters_then_ranks_hotspot_activity_concentration() -> None:+ rows = [+ _git("quiet.py", 1.0),+ _git("shared.py", 0.8, commits=99, hotspot=True),+ _git("unknown.py", 0.9, commits=None),+ _git("busy.py", 0.85, commits=20),+ _git("hot.py", 0.81, commits=3, hotspot=True),+ _git("hot_tie.py", 0.95, commits=3, hotspot=True, email=None),+ _git("no_pct.py", None),+ # Equal once rounded to 3 places; ranked by the raw share.+ _git("close_low.py", 0.8496, commits=7),+ _git("close_high.py", 0.8504, commits=7),+ ]+ out = rank_silos(rows)+ assert [s["file_path"] for s in out] == [+ "hot_tie.py",+ "hot.py",+ "busy.py",+ "close_high.py",+ "close_low.py",+ "quiet.py",+ "unknown.py",+ ]+ assert out[0] == {+ "file_path": "hot_tie.py",+ "owner_email": "",+ "owner_pct": 0.95,+ "commit_count_90d": 3,+ "is_hotspot": True,+ }+ assert out[-1]["commit_count_90d"] == 0+++def test_onboarding_targets_skip_unranked_nodes_and_cap() -> None:+ nodes = [{"node_id": f"f{i}.py", "pagerank": 0.1 * (i + 1)} for i in range(12)]+ nodes.append({"node_id": "zero.py", "pagerank": 0.0})+ out = onboarding_targets(nodes, {"f11.py": 5, "f10.py": 2}, limit=10)+ assert len(out) == 10+ assert out[0] == {"path": "f9.py", "pagerank": 0.1 * 10, "doc_words": 0}+ everything = onboarding_targets(nodes, {"f11.py": 5, "f10.py": 2}, limit=20)+ assert len(everything) == 12+ tail = everything[-2:]+ assert [t["path"] for t in tail] == ["f10.py", "f11.py"]diff --git a/tests/unit/health/test_lightweight_health_imports.py b/tests/unit/health/test_lightweight_health_imports.pyindex 5f3dfc1fa..e5420243f 100644--- a/tests/unit/health/test_lightweight_health_imports.py+++ b/tests/unit/health/test_lightweight_health_imports.py@@ -27,6 +27,7 @@ _LIGHTWEIGHT = ("repowise.core.analysis.health.ranking","repowise.core.analysis.health.aggregation","repowise.core.analysis.health.trends",+ "repowise.core.analysis.knowledge_map","repowise.core.analysis.health.grading","repowise.core.analysis.health.suggestions","repowise.core.analysis.health.defect_accuracy",diff --git a/tests/unit/server/golden/knowledge_map.json b/tests/unit/server/golden/knowledge_map.jsonnew file mode 100644index 000000000..f9f5af13e--- /dev/null+++ b/tests/unit/server/golden/knowledge_map.json@@ -0,0 +1,305 @@+{+ "silos": [+ {+ "file_path": "src/db.py",+ "owner_email": "[email protected]",+ "owner_pct": 0.99,+ "commit_count_90d": 30,+ "is_hotspot": true+ },+ {+ "file_path": "src/core.py",+ "owner_email": "[email protected]",+ "owner_pct": 0.85,+ "commit_count_90d": 30,+ "is_hotspot": true+ },+ {+ "file_path": "src/cli.py",+ "owner_email": "[email protected]",+ "owner_pct": 0.81,+ "commit_count_90d": 12,+ "is_hotspot": false+ },+ {+ "file_path": "src/api.py",+ "owner_email": "[email protected]",+ "owner_pct": 0.95,+ "commit_count_90d": 4,+ "is_hotspot": false+ },+ {+ "file_path": "src/old.py",+ "owner_email": "",+ "owner_pct": 1.0,+ "commit_count_90d": 0,+ "is_hotspot": false+ }+ ],+ "onboarding_targets": [+ {+ "path": "src/m07.py",+ "pagerank": 0.08,+ "doc_words": 0+ },+ {+ "path": "src/m06.py",+ "pagerank": 0.07,+ "doc_words": 0+ },+ {+ "path": "src/m05.py",+ "pagerank": 0.06,+ "doc_words": 0+ },+ {+ "path": "src/m04.py",+ "pagerank": 0.05,+ "doc_words": 0+ },+ {+ "path": "src/m03.py",+ "pagerank": 0.04,+ "doc_words": 0+ },+ {+ "path": "src/m02.py",+ "pagerank": 0.03,+ "doc_words": 0+ },+ {+ "path": "src/m01.py",+ "pagerank": 0.02,+ "doc_words": 0+ },+ {+ "path": "src/m00.py",+ "pagerank": 0.01,+ "doc_words": 0+ },+ {+ "path": "src/m11.py",+ "pagerank": 0.3,+ "doc_words": 6+ },+ {+ "path": "src/m10.py",+ "pagerank": 0.2,+ "doc_words": 1+ }+ ],+ "knowledge_map": {+ "top_owners": [+ {+ "email": "[email protected]",+ "name": "Alice",+ "files_owned": 2,+ "percentage": 25.0+ },+ {+ "email": "[email protected]",+ "name": "Bob",+ "files_owned": 2,+ "percentage": 25.0+ },+ {+ "email": "[email protected]",+ "name": "Carol",+ "files_owned": 1,+ "percentage": 12.5+ },+ {+ "email": "[email protected]",+ "name": "Dan",+ "files_owned": 1,+ "percentage": 12.5+ }+ ],+ "knowledge_silos": [+ {+ "file_path": "src/api.py",+ "owner_email": "[email protected]",+ "owner_pct": 0.95+ },+ {+ "file_path": "src/cli.py",+ "owner_email": "[email protected]",+ "owner_pct": 0.81+ },+ {+ "file_path": "src/core.py",+ "owner_email": "[email protected]",+ "owner_pct": 0.85+ },+ {+ "file_path": "src/db.py",+ "owner_email": "[email protected]",+ "owner_pct": 0.99+ },+ {+ "file_path": "src/old.py",+ "owner_email": "",+ "owner_pct": 1.0+ }+ ],+ "onboarding_targets": [+ {+ "path": "src/m07.py",+ "pagerank": 0.08,+ "doc_words": 0+ },+ {+ "path": "src/m06.py",+ "pagerank": 0.07,+ "doc_words": 0+ },+ {+ "path": "src/m05.py",+ "pagerank": 0.06,+ "doc_words": 0+ },+ {+ "path": "src/m04.py",+ "pagerank": 0.05,+ "doc_words": 0+ },+ {+ "path": "src/m03.py",+ "pagerank": 0.04,+ "doc_words": 0+ },+ {+ "path": "src/m02.py",+ "pagerank": 0.03,+ "doc_words": 0+ },+ {+ "path": "src/m01.py",+ "pagerank": 0.02,+ "doc_words": 0+ },+ {+ "path": "src/m00.py",+ "pagerank": 0.01,+ "doc_words": 0+ },+ {+ "path": "src/m11.py",+ "pagerank": 0.3,+ "doc_words": 6+ },+ {+ "path": "src/m10.py",+ "pagerank": 0.2,+ "doc_words": 1+ }+ ]+ },+ "endpoint": {+ "top_owners": [+ {+ "email": "[email protected]",+ "name": "Alice",+ "files_owned": 2,+ "percentage": 25.0+ },+ {+ "email": "[email protected]",+ "name": "Bob",+ "files_owned": 2,+ "percentage": 25.0+ },+ {+ "email": "[email protected]",+ "name": "Carol",+ "files_owned": 1,+ "percentage": 12.5+ },+ {+ "email": "[email protected]",+ "name": "Dan",+ "files_owned": 1,+ "percentage": 12.5+ }+ ],+ "knowledge_silos": [+ {+ "file_path": "src/api.py",+ "owner_email": "[email protected]",+ "owner_pct": 0.95+ },+ {+ "file_path": "src/cli.py",+ "owner_email": "[email protected]",+ "owner_pct": 0.81+ },+ {+ "file_path": "src/core.py",+ "owner_email": "[email protected]",+ "owner_pct": 0.85+ },+ {+ "file_path": "src/db.py",+ "owner_email": "[email protected]",+ "owner_pct": 0.99+ },+ {+ "file_path": "src/old.py",+ "owner_email": "",+ "owner_pct": 1.0+ }+ ],+ "onboarding_targets": [+ {+ "path": "src/m07.py",+ "pagerank": 0.08,+ "doc_words": 0+ },+ {+ "path": "src/m06.py",+ "pagerank": 0.07,+ "doc_words": 0+ },+ {+ "path": "src/m05.py",+ "pagerank": 0.06,+ "doc_words": 0+ },+ {+ "path": "src/m04.py",+ "pagerank": 0.05,+ "doc_words": 0+ },+ {+ "path": "src/m03.py",+ "pagerank": 0.04,+ "doc_words": 0+ },+ {+ "path": "src/m02.py",+ "pagerank": 0.03,+ "doc_words": 0+ },+ {+ "path": "src/m01.py",+ "pagerank": 0.02,+ "doc_words": 0+ },+ {+ "path": "src/m00.py",+ "pagerank": 0.01,+ "doc_words": 0+ },+ {+ "path": "src/m11.py",+ "pagerank": 0.3,+ "doc_words": 6+ },+ {+ "path": "src/m10.py",+ "pagerank": 0.2,+ "doc_words": 1+ }+ ]+ }+}diff --git a/tests/unit/server/test_knowledge_map_golden.py b/tests/unit/server/test_knowledge_map_golden.pynew file mode 100644index 000000000..b96d79ca5--- /dev/null+++ b/tests/unit/server/test_knowledge_map_golden.py@@ -0,0 +1,132 @@+"""Golden output of the knowledge-map services and endpoint.++Pins silos, onboarding targets and the full map exactly, so moving the folds+between packages cannot change what Overview or ``/knowledge-map`` serves.+Rewrite with ``REPOWISE_REWRITE_GOLDEN=1`` only for an intended behaviour change.+"""++from __future__ import annotations++import json+import os+from datetime import UTC, datetime+from pathlib import Path++import pytest+from httpx import AsyncClient++from repowise.core.persistence import crud+from repowise.core.persistence.database import get_session+from repowise.core.persistence.models import GraphNode, Page+from repowise.server.routers import knowledge_map+from repowise.server.services.knowledge_map import (+ compute_knowledge_map,+ compute_knowledge_silos,+ compute_onboarding_targets,+)+from tests.unit.server.conftest import create_test_repo++GOLDEN = Path(__file__).parent / "golden" / "knowledge_map.json"+_AT = datetime(2026, 9, 1, tzinfo=UTC)++# (path, owner, email, pct, commits_90d, hotspot)+_GIT = [+ ("src/api.py", "Alice", "[email protected]", 0.95, 4, False),+ ("src/core.py", "Bob", "[email protected]", 0.85, 30, True),+ ("src/db.py", "Alice", "[email protected]", 0.99, 30, True),+ ("src/cli.py", "Carol", "[email protected]", 0.81, 12, False),+ ("src/old.py", "Carol", None, 1.0, 0, False),+ ("src/shared.py", "Bob", "[email protected]", 0.8, 50, True),+ ("src/team.py", "Dan", "[email protected]", 0.4, 9, False),+ ("src/none.py", None, None, None, 0, False),+]++# (node_id, pagerank, is_test)+_NODES = [(f"src/m{i:02d}.py", 0.01 * (i + 1), False) for i in range(8)] + [+ ("src/m10.py", 0.2, False),+ ("src/m11.py", 0.3, False),+ ("src/api.py", 0.5, False),+ ("src/core.py", 0.9, False),+ ("tests/test_core.py", 0.7, True),+ ("src/zero.py", 0.0, False),+]++# Shortlisted by character length (m11 before m10), reported in words.+_PAGES = {+ "src/m11.py": "a b c d e f",+ "src/m10.py": "supercalifragilisticexpialidocious",+ "src/api.py": "a " * 400,+ "src/core.py": "documented " * 50,+}+++async def _seed(session_factory, repo_id: str) -> None:+ async with get_session(session_factory) as session:+ for path, owner, email, pct, commits, hotspot in _GIT:+ await crud.upsert_git_metadata(+ session,+ repository_id=repo_id,+ file_path=path,+ primary_owner_name=owner,+ primary_owner_email=email,+ primary_owner_commit_pct=pct,+ commit_count_90d=commits,+ is_hotspot=hotspot,+ )+ session.add_all(+ [+ GraphNode(+ id=f"n{i:02d}",+ repository_id=repo_id,+ node_id=node_id,+ pagerank=pagerank,+ is_test=is_test,+ )+ for i, (node_id, pagerank, is_test) in enumerate(_NODES)+ ]+ )+ session.add_all(+ [+ Page(+ id=f"file_page:{path}",+ repository_id=repo_id,+ page_type="file_page",+ title=path,+ content=content,+ target_path=path,+ source_hash="h",+ model_name="m",+ provider_name="p",+ created_at=_AT,+ updated_at=_AT,+ )+ for path, content in _PAGES.items()+ ]+ )+ await session.commit()+++async def test_knowledge_map_matches_the_golden(+ client: AsyncClient, app, session_factory+) -> None:+ # The shared test app does not mount this router.+ app.include_router(knowledge_map.router)+ repo = await create_test_repo(client)+ await _seed(session_factory, repo["id"])++ async with get_session(session_factory) as session:+ result = {+ "silos": await compute_knowledge_silos(session, repo["id"]),+ "onboarding_targets": await compute_onboarding_targets(session, repo["id"]),+ "knowledge_map": await compute_knowledge_map(session, repo["id"]),+ }+ resp = await client.get(f"/api/repos/{repo['id']}/knowledge-map")+ assert resp.status_code == 200+ result["endpoint"] = resp.json()++ if os.environ.get("REPOWISE_REWRITE_GOLDEN"):+ GOLDEN.parent.mkdir(exist_ok=True)+ GOLDEN.write_text(json.dumps(result, indent=2) + "\n", encoding="utf-8", newline="\n")+ pytest.skip("golden rewritten")+ assert result == json.loads(GOLDEN.read_text(encoding="utf-8"))