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
feat(mcp): get_overview lays out every package, its front doors, layer roots and commands (#4214)
Raghav Chamadiya9b95f0c6e013
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.mdindex 25c857a61..bb30d32db 100644--- a/docs/agent/MCP_TOOLS.md+++ b/docs/agent/MCP_TOOLS.md@@ -315,7 +315,7 @@ Orientation for an unfamiliar repo: summary, key modules, entry points, layers,| `include` | list[string] | none | Any of `content` (full essay), `outline` (wiki page tree), `tour` (guided tour and reading order), `decisions`, `graph` (community clusters), `ownership` (top owners), `components` (declared and derived components with file counts), `changes` (Change Records by category and week, and the agent share of changes with coverage), `actions` (the quarter's actions too, with `done_when`), `tools` (`tool_surface`: enabled tools, opt-ins and recipes), `scope` (the whole `_meta.index_scope`) || `repo` | string | default repo | Workspace repo alias, or `"all"` for the cross-repo topology |-**Key return fields:** `title`, `content_md` (summary section by default), `key_modules`, `entry_points`, `architecture` (layers in stack order, plus `dependencies`: the ten heaviest package-to-package edges with `from`, `to`, `verb` and `weight`, and `edges_total` when more exist; absent in a single-package repo), `code_health`, `git_health` (`riskiest_files`), `next_actions` (top three for the week, or the quarter when the week is empty), `more` (names the opt-in blocks), and a `workspace` footer in workspace mode.+**Key return fields:** `title`, `content_md` (summary section by default), `key_modules` (one row per package or top-level directory), `entry_points`, `commands` (build, test, lint and similar commands from manifests), `architecture` (layers in stack order with their `root`, plus `dependencies`: the ten heaviest package-to-package edges with `from`, `to`, `verb` and `weight`, and `edges_total` when more exist; absent in a single-package repo), `code_health`, `git_health` (`riskiest_files`), `next_actions` (top three for the week, or the quarter when the week is empty), `more` (names the opt-in blocks), and a `workspace` footer in workspace mode.```get_overview()diff --git a/docs/architecture/editor-files.md b/docs/architecture/editor-files.mdindex eb2740aa2..f0405c2b0 100644--- a/docs/architecture/editor-files.md+++ b/docs/architecture/editor-files.md@@ -188,6 +188,10 @@ WHERE repository_id = :repo_id AND is_entry_point = TRUE# then centrality as a tiebreak; sliced to 10 after ranking.```+Both lists pass through `orientation_entry_points_view`, the rule+`get_overview` shares. It sets build and CI tooling (`scripts/`, `docker/`) aside+unless that is all there is.+PageRank deliberately does **not** lead here. Centrality rewards fan-in, so itfloats a widely-imported barrel above the real front door — see`generation/entry_points.py`.diff --git a/docs/reference/MCP_RESPONSE_FIELDS.md b/docs/reference/MCP_RESPONSE_FIELDS.mdindex 8df0d36c0..41e087f43 100644--- a/docs/reference/MCP_RESPONSE_FIELDS.md+++ b/docs/reference/MCP_RESPONSE_FIELDS.md@@ -325,9 +325,10 @@ The `candidates` and `history` lanes shed first under budget pressure, so an abs| Field | Meaning ||-------|---------|| `content_md` | The overview essay's summary section; the full essay with `include=["content"]` |-| `key_modules` | Name, path, and outline section |-| `entry_points` | Detected entry points |-| `architecture` | Layer names and file counts in stack order, test layer left out |+| `key_modules` | One row per topmost module page (a package or top-level directory), in outline order, up to 12: name, path, outline section, `package` when the page sits inside one, and `pages` beneath it |+| `entry_points` | Detected entry points with build and CI tooling set aside, each package's together |+| `architecture` | Layer names, file counts and `root` (the directory holding most of the layer, when one does) in stack order, test layer left out |+| `commands` | Build, test, lint, dev, format and typecheck commands read from manifests: `"."` for the root, plus each package that names a task the root does not || `code_health` | Headline score and band, `production_average` (non-test files, when the reading holds tests), hotspot health, worst file, open findings, `code_files` (every code file health read; `files_scored` when some carry no score) and `files_by_band` || `git_health` | Hotspot count, churn trend and `riskiest_files`: five paths, bug magnets first, then fix mass, then churn || `next_actions` | The first three stored actions (`id`, `tier`, `title`, a one-line `impact`, `target`) for the week, or the quarter when the week is empty, with each horizon's `total`. `include=["actions"]` serves both horizons with `done_when` and `by_tier`. `get_health(fix_id="act_...")` opens one in full |diff --git a/packages/core/src/repowise/core/analysis/kg_curation.py b/packages/core/src/repowise/core/analysis/kg_curation.pyindex a98f143df..ceabc1b90 100644--- a/packages/core/src/repowise/core/analysis/kg_curation.py+++ b/packages/core/src/repowise/core/analysis/kg_curation.py@@ -56,7 +56,10 @@ from repowise.core.entry_candidacy import (conventional_entry_stems,not_an_execution_start,)-from repowise.core.generation.entry_points import rank_entry_points+from repowise.core.generation.entry_points import (+ orientation_entry_points_view,+ rank_entry_points,+)from repowise.core.generation.layers import (ADJACENT_LAYERS,compute_layer_order,@@ -400,7 +403,7 @@ def _curate_entry_points(candidates = [(path, pagerank.get(path, 0.0), betweenness.get(path, 0.0)) for path in paths]ranked = rank_entry_points(candidates, conventional_entry_stems(), manifest)- kg.project["entry_points"] = ranked[:_MAX_ENTRY_POINTS]+ kg.project["entry_points"] = orientation_entry_points_view(ranked)[:_MAX_ENTRY_POINTS]kg.project["entry_candidates"] = rankeddiff --git a/packages/core/src/repowise/core/generation/editor_files/fetcher.py b/packages/core/src/repowise/core/generation/editor_files/fetcher.pyindex 56504316c..3200d366d 100644--- a/packages/core/src/repowise/core/generation/editor_files/fetcher.py+++ b/packages/core/src/repowise/core/generation/editor_files/fetcher.py@@ -28,7 +28,10 @@ from repowise.core.analysis.health.rows import split_unscoredfrom repowise.core.analysis.health.scoring import hotspot_health, nloc_weighted_scorefrom repowise.core.analysis.health.trends import DECLINE_LOOKBACK, hotspot_trendfrom repowise.core.entry_candidacy import conventional_entry_stems-from repowise.core.generation.entry_points import rank_entry_points+from repowise.core.generation.entry_points import (+ orientation_entry_points_view,+ rank_entry_points,+)from repowise.core.index_scope import load_index_scope, resolve_index_scopefrom repowise.core.persistence import crudfrom repowise.core.persistence.crud.analysis.fix_first import load_fix_first@@ -219,7 +222,7 @@ class EditorFileDataFetcher:except (json.JSONDecodeError, TypeError):curated = []if curated:- return curated[:_MAX_ENTRY_POINTS]+ return orientation_entry_points_view(curated)[:_MAX_ENTRY_POINTS]result = await self._session.execute(select(GraphNode.node_id, GraphNode.pagerank, GraphNode.betweenness).where(@@ -229,7 +232,7 @@ class EditorFileDataFetcher:)candidates = [(node_id, pr or 0.0, bt or 0.0) for node_id, pr, bt in result.all()]ranked = rank_entry_points(candidates, conventional_entry_stems())- return ranked[:_MAX_ENTRY_POINTS]+ return orientation_entry_points_view(ranked)[:_MAX_ENTRY_POINTS]async def _get_hotspots(self) -> list[HotspotFile]:"""Top attention-worthy files: bug-fix history first, churn as fallback.diff --git a/packages/core/src/repowise/core/generation/entry_points.py b/packages/core/src/repowise/core/generation/entry_points.pyindex 48b7c6590..303e327c7 100644--- a/packages/core/src/repowise/core/generation/entry_points.py+++ b/packages/core/src/repowise/core/generation/entry_points.py@@ -16,6 +16,9 @@ conventional entry filename and a shallow path — and uses centrality only tobreak ties. It is deliberately free of any DB/graph/LLM dependency so theordering can be unit-tested directly.+Every orientation surface also passes its list through+:func:`orientation_entry_points_view`, which sets build and CI tooling aside.+Three callable shapes, one rule: :func:`orientation_entry_points` for a``RepoStructure``, :func:`rank_entry_point_paths` for bare paths, and:func:`rank_entry_points` for callers holding centrality.@@ -185,3 +188,20 @@ def rank_entry_points(),)]+++#: Directories of build and CI tooling. Narrower than the layer map's tooling+#: tokens: a ``plugins/`` tree can be a runtime plugin system.+_TOOLING_DIRS = frozenset({"scripts", "docker"})+++def orientation_entry_points_view(paths: Iterable[str]) -> list[str]:+ """*paths* without build and CI tooling (``scripts/``, ``docker/``), order kept.++ A lint or gate script is a real entry point, so candidacy and dead code keep+ it, but it is not where a reader enters the system. When tooling is all+ there is, the list is returned whole rather than emptied.+ """+ paths = list(paths)+ runtime = [p for p in paths if not _TOOLING_DIRS & set(p.lower().split("/")[:-1])]+ return runtime or pathsdiff --git a/packages/server/src/repowise/server/mcp_server/tool_overview/graph.py b/packages/server/src/repowise/server/mcp_server/tool_overview/graph.pyindex 26a29e896..f658a29c1 100644--- a/packages/server/src/repowise/server/mcp_server/tool_overview/graph.py+++ b/packages/server/src/repowise/server/mcp_server/tool_overview/graph.py@@ -5,6 +5,7 @@ from __future__ import annotationsimport copyimport jsonfrom collections import Counter, defaultdict+from pathlib import Pathfrom typing import Anyfrom sqlalchemy import select@@ -105,7 +106,9 @@ def _stored_label(node: GraphNode) -> str:return ""-async def _build_architecture(session: Any, repository: Any) -> dict[str, Any]:+async def _build_architecture(+ session: Any, repository: Any, package_roots: list[str]+) -> dict[str, Any]:"""KG architecture layers, in stack order, + tour availability."""kg_layers = [layer@@ -116,19 +119,34 @@ async def _build_architecture(session: Any, repository: Any) -> dict[str, Any]:if not kg_layers:return {}return {- # Names and sizes only: the layer prose restates the overview essay.- "layers": [- {- "name": layer.name,- "file_count": len(json.loads(layer.node_ids_json) if layer.node_ids_json else []),- }- for layer in kg_layers- ],+ # Names, sizes and roots only: the layer prose restates the overview essay.+ "layers": [_layer_row(layer, package_roots) for layer in kg_layers],"tour_available": bool(kg_tour),"tour_step_count": len(kg_tour),}+def _layer_row(layer: Any, package_roots: list[str]) -> dict[str, Any]:+ ids = json.loads(layer.node_ids_json) if layer.node_ids_json else []+ row: dict[str, Any] = {"name": layer.name, "file_count": len(ids)}+ root = _majority_root([i.removeprefix("file:") for i in ids])+ # A directory above two packages (``packages/``) locates nothing.+ if root and sum(p.startswith(root + "/") for p in package_roots) < 2:+ row["root"] = root+ return row+++def _majority_root(paths: list[str]) -> str | None:+ """The deepest directory holding most of *paths*, or ``None``."""+ under: Counter = Counter()+ for path in paths:+ parts = path.split("/")[:-1]+ for depth in range(1, len(parts) + 1):+ under["/".join(parts[:depth])] += 1+ held = [d for d, n in under.items() if 2 * n > len(paths)]+ return max(held, key=lambda d: (d.count("/"), under[d]), default=None)++async def _build_package_dependencies(session: Any, repository: Any, exclude_spec: Any = None) -> dict[str, Any]:@@ -137,6 +155,17 @@ async def _build_package_dependencies(The containers and roll-up are the container view's, so test files add noweight in either. ``weight`` counts the file pairs behind an edge."""+ cached = await _container_view(session, repository, exclude_spec)+ # A copy: the response is shaped after this returns.+ return copy.deepcopy(cached["dependencies"])+++async def _package_roots(session: Any, repository: Any, exclude_spec: Any = None) -> list[str]:+ """The container view's package roots, the repository root as ``""``."""+ return list((await _container_view(session, repository, exclude_spec))["roots"])+++async def _container_view(session: Any, repository: Any, exclude_spec: Any) -> dict[str, Any]:key = (repository.id, index_state_key(repository), id(exclude_spec))cached = _DEPENDENCY_CACHE.get(key)if cached is None:@@ -144,8 +173,7 @@ async def _build_package_dependencies(if len(_DEPENDENCY_CACHE) >= _DEPENDENCY_CACHE_LIMIT:_DEPENDENCY_CACHE.clear()_DEPENDENCY_CACHE[key] = cached- # A copy: the response is shaped after this returns.- return copy.deepcopy(cached)+ return cachedasync def _package_dependencies(session: Any, repo_id: str, exclude_spec: Any) -> dict[str, Any]:@@ -163,9 +191,31 @@ async def _package_dependencies(session: Any, repo_id: str, exclude_spec: Any) -for r in relations[:_DEPENDENCY_EDGES]if r.source_id in path_of and r.target_id in path_of]- if not edges:- return {}- block: dict[str, Any] = {"edges": edges}- if len(relations) > len(edges):+ block: dict[str, Any] = {"edges": edges} if edges else {}+ if edges and len(relations) > len(edges):block["edges_total"] = len(relations)- return block+ return {"dependencies": block, "roots": sorted({c.path or "" for c in containers})}+++#: Packages whose commands the overview names beside the root's.+_COMMAND_PACKAGES = 8+++def _build_commands(repo_root: Any, package_roots: list[str]) -> dict[str, dict[str, str]]:+ """Build, test, lint, dev, format and typecheck commands read from manifests: the root's, then each+ package's that names a task the root does not. Run those from the package."""+ if not repo_root:+ return {}+ # Imported here: the editor-files package is heavy and only this reads it.+ from repowise.core.generation.editor_files.tech_stack import detect_build_commands++ base = Path(repo_root)+ root = detect_build_commands(base)+ out: dict[str, dict[str, str]] = {".": root} if root else {}+ for package in package_roots:+ if len(out) - ("." in out) >= _COMMAND_PACKAGES or not package:+ continue+ found = detect_build_commands(base / package)+ if set(found) - set(root):+ out[package] = found+ return outdiff --git a/packages/server/src/repowise/server/mcp_server/tool_overview/pages.py b/packages/server/src/repowise/server/mcp_server/tool_overview/pages.pyindex 99515cf3f..471c669c0 100644--- a/packages/server/src/repowise/server/mcp_server/tool_overview/pages.py+++ b/packages/server/src/repowise/server/mcp_server/tool_overview/pages.py@@ -8,6 +8,7 @@ from typing import Anyfrom sqlalchemy import select+from repowise.core.generation.entry_points import orientation_entry_points_viewfrom repowise.core.persistence.crud import (get_kg_project_meta as _get_kg_project_meta,)@@ -15,10 +16,9 @@ from repowise.core.persistence.models import GraphNode, Pagefrom repowise.server.mcp_server._budget import OmissionCollectorfrom repowise.server.mcp_server._helpers import filter_graph_nodes, is_excluded-# Orientation, not a directory listing — the top few modules are enough to-# point a fresh agent at the interesting subsystems. The rest are persisted-# to the omission store, not dropped.-_MODULE_CAP = 8+# One row per package or top-level directory; the rest are persisted to the+# omission store, not dropped.+_MODULE_CAP = 12# Split point between markdown H2 sections ("\n## ...")._H2_SPLIT_RE = re.compile(r"\n(?=#{1,2}\s)")@@ -88,9 +88,15 @@ def _module_order_key(page: Any) -> tuple:async def _load_module_pages(- session: Any, repository: Any, collector: OmissionCollector-) -> list[Page]:- """Module pages capped to ``_MODULE_CAP``; the remainder goes to the omission store."""+ session: Any, repository: Any, collector: OmissionCollector, package_roots: list[str]+) -> list[dict[str, Any]]:+ """Key-module rows: the topmost module pages, capped to ``_MODULE_CAP``.++ A topmost page has no module page above it, so each package or top-level+ directory gets one row, with ``pages`` counting what sits beneath it. Too+ few rows to orient by opens the largest into its own topmost children.+ Rows follow outline order; the pages no row names go to the omission store.+ """result = await session.execute(select(Page).where(@@ -100,17 +106,62 @@ async def _load_module_pages().order_by(Page.title))- # Outline order, not alphabetical: the stored tree already ranks modules by- # the dependency layer they sit in, so the capped-to-8 list is the top of- # the spine rather than whatever sorts first.- all_module_pages = sorted(result.scalars().all(), key=_module_order_key)- if len(all_module_pages) > _MODULE_CAP:+ pages = list(result.scalars().all())+ heads = _key_module_heads(pages)+ rest = [p for p in pages if p not in heads]+ if rest:collector.add(- f"module pages beyond cap={_MODULE_CAP} "- f"({len(all_module_pages) - _MODULE_CAP} dropped)",- "\n".join(f"{p.title}: {p.target_path}" for p in all_module_pages[_MODULE_CAP:]),+ f"module pages beneath the key modules, cap={_MODULE_CAP} ({len(rest)} dropped)",+ "\n".join(f"{p.title}: {p.target_path}" for p in rest),)- return all_module_pages[:_MODULE_CAP]+ roots = sorted((r for r in package_roots if r), key=len, reverse=True)+ rows = []+ for head in heads:+ path = head.target_path or ""+ row = {"name": head.title, "path": head.target_path, "section": head.section_number}+ package = next((r for r in roots if _under(path, r)), path)+ if package != path:+ row["package"] = package+ below = sum(_under(p.target_path or "", path) for p in pages)+ if below > 1:+ row["pages"] = below+ rows.append(row)+ return rows+++#: Fewer rows than this name too little of the repository to orient by.+_MODULE_FLOOR = 4+++def _under(path: str, root: str) -> bool:+ return not root or path == root or path.startswith(root + "/")+++def _topmost(pages: list[Any]) -> list[Any]:+ paths = [p.target_path or "" for p in pages]+ return [+ p+ for p in pages+ if not any(o != (p.target_path or "") and _under(p.target_path or "", o) for o in paths)+ ]+++def _key_module_heads(pages: list[Any]) -> list[Any]:+ heads = _topmost(pages)+ while len(heads) < _MODULE_FLOOR:+ # Open the head with the most pages beneath it into its own top layer.+ def beneath(head: Any) -> list[Any]:+ path = head.target_path or ""+ return [+ p for p in pages if (p.target_path or "") != path and _under(p.target_path or "", path)+ ]++ widest = max(heads, key=lambda h: len(beneath(h)), default=None)+ if widest is None or not beneath(widest):+ break+ gone = widest.target_path or ""+ heads = [h for h in heads if (h.target_path or "") != gone] + _topmost(beneath(widest))+ return sorted(heads, key=_module_order_key)[:_MODULE_CAP]def _drop_fixtures(ids: list[str], exclude_spec: Any) -> list[str]:@@ -141,7 +192,7 @@ async def _resolve_entry_point_ids(session: Any, repository: Any, exclude_spec:curated_ids = []if curated_ids:- return _drop_fixtures(curated_ids, exclude_spec)+ return orientation_entry_points_view(_drop_fixtures(curated_ids, exclude_spec))result = await session.execute(select(GraphNode).where(@@ -161,7 +212,7 @@ async def _resolve_entry_point_ids(session: Any, repository: Any, exclude_spec:],exclude_spec,)- return [n.node_id for n in entry_nodes]+ return orientation_entry_points_view(n.node_id for n in entry_nodes)def _resolve_title(overview_page: Page | None, repository: Any) -> str:@@ -178,6 +229,15 @@ def _resolve_title(overview_page: Page | None, repository: Any) -> str:return persisted_title+def _grouped_by_package(paths: list[str], package_roots: list[str]) -> list[str]:+ """*paths* with each package's entries together, packages in first-seen order."""+ roots = sorted((r for r in package_roots if r), key=len, reverse=True)+ order: dict[str, int] = {}+ for path in paths:+ order.setdefault(next((r for r in roots if _under(path, r)), ""), len(order))+ return sorted(paths, key=lambda p: order[next((r for r in roots if _under(p, r)), "")])++def _capped_entry_points(entry_ids: list[str], collector: OmissionCollector) -> list[str]:"""First 15 entry-point ids; the remainder goes to the omission store."""if len(entry_ids) > 15:diff --git a/packages/server/src/repowise/server/mcp_server/tool_overview/tool.py b/packages/server/src/repowise/server/mcp_server/tool_overview/tool.pyindex 1fa066f37..ebf51b53b 100644--- a/packages/server/src/repowise/server/mcp_server/tool_overview/tool.py+++ b/packages/server/src/repowise/server/mcp_server/tool_overview/tool.py@@ -36,9 +36,11 @@ from repowise.server.mcp_server.tool_overview.actions import _build_next_actionsfrom repowise.server.mcp_server.tool_overview.decisions import _build_key_decisionsfrom repowise.server.mcp_server.tool_overview.graph import (_build_architecture,+ _build_commands,_build_community_summary,_build_package_dependencies,_load_community_nodes,+ _package_roots,)from repowise.server.mcp_server.tool_overview.health import _build_code_healthfrom repowise.server.mcp_server.tool_overview.history import (@@ -48,6 +50,7 @@ from repowise.server.mcp_server.tool_overview.history import (from repowise.server.mcp_server.tool_overview.outline import _build_outline, _load_tree_rowsfrom repowise.server.mcp_server.tool_overview.pages import (_capped_entry_points,+ _grouped_by_package,_load_module_pages,_load_overview_page,_overview_content,@@ -179,10 +182,11 @@ async def _repo_overview(slow = _slow_reads(session, session_factory, repository, full_actions="actions" in want)try:overview_page = await _load_overview_page(session, repository)- module_pages = await _load_module_pages(session, repository, collector)+ package_roots = await _package_roots(session, repository, exclude_spec)+ module_rows = await _load_module_pages(session, repository, collector, package_roots)entry_point_ids = await _resolve_entry_point_ids(session, repository, exclude_spec)all_git = await _load_git_rows(session, repository, exclude_spec)- architecture = await _build_architecture(session, repository)+ architecture = await _build_architecture(session, repository, package_roots)dependencies = await _build_package_dependencies(session, repository, exclude_spec)if dependencies:architecture = {**architecture, "dependencies": dependencies}@@ -204,11 +208,10 @@ async def _repo_overview(**({"next_actions_reason": next_actions_reason} if next_actions_reason else {}),# Names and paths only. get_context(path) carries the prose, and# section indexes into include=["outline"].- "key_modules": [- {"name": p.title, "path": p.target_path, "section": p.section_number}- for p in module_pages- ],- "entry_points": _capped_entry_points(entry_point_ids, collector),+ "key_modules": module_rows,+ "entry_points": _capped_entry_points(+ _grouped_by_package(entry_point_ids, package_roots), collector+ ),"git_health": _build_git_health(all_git, repo_root),"more": ('get_overview(include=[...]) also serves: "outline" (the wiki '@@ -225,6 +228,7 @@ async def _repo_overview("outline": outline,"outline_hint": _OUTLINE_HINT if outline else None,"architecture": architecture,+ "commands": _build_commands(repo_root, package_roots),"key_decisions": requested["key_decisions"],"reading_order": requested["reading_order"],"reading_order_hint": _READING_ORDER_HINT if requested["reading_order"] else None,diff --git a/tests/unit/generation/test_orientation_entry_points.py b/tests/unit/generation/test_orientation_entry_points.pyindex cc6c2462e..84161c4ab 100644--- a/tests/unit/generation/test_orientation_entry_points.py+++ b/tests/unit/generation/test_orientation_entry_points.py@@ -276,3 +276,26 @@ def test_deterministic_kg_tour_starts_at_the_best_entry_point():assert stopsassert stops[0]["nodeIds"] == ["file:src/main.py"]+++def test_orientation_view_sets_tooling_aside_unless_it_is_all_there_is():+ from repowise.core.generation.entry_points import orientation_entry_points_view++ ranked = [+ "packages/cli/main.py",+ "packages/ui/scripts/contrast-check.py",+ "packages/ui/scripts/ui-gates.sh",+ "packages/vscode/src/extension.ts",+ ]+ assert orientation_entry_points_view(ranked) == [+ "packages/cli/main.py",+ "packages/vscode/src/extension.ts",+ ]+ assert orientation_entry_points_view(["scripts/release.py"]) == ["scripts/release.py"]+++def test_orientation_view_keeps_a_runtime_plugin_system():+ from repowise.core.generation.entry_points import orientation_entry_points_view++ ranked = ["src/plugins/main.py", "docker/entry.sh", "src/main.py"]+ assert orientation_entry_points_view(ranked) == ["src/plugins/main.py", "src/main.py"]diff --git a/tests/unit/server/mcp/test_budget.py b/tests/unit/server/mcp/test_budget.pyindex 684d8c8bd..4f35468b3 100644--- a/tests/unit/server/mcp/test_budget.py+++ b/tests/unit/server/mcp/test_budget.py@@ -650,7 +650,7 @@ async def test_get_overview_module_cap_is_expandable(setup_mcp, session, repo_roomitted = result["_meta"]["omitted"]stored = "\n".join(_store_get(repo_root, r) or "" for r in omitted["refs"])# 27 module pages total, ordered by title — the tail is in the store.- assert f"module pages beyond cap={_MODULE_CAP}" in stored+ assert f"module pages beneath the key modules, cap={_MODULE_CAP}" in storedassert stored.count("Extra Module") + stored.count("Module") >= 7diff --git a/tests/unit/server/mcp/test_overview_packages.py b/tests/unit/server/mcp/test_overview_packages.pynew file mode 100644index 000000000..a67cdcafa--- /dev/null+++ b/tests/unit/server/mcp/test_overview_packages.py@@ -0,0 +1,89 @@+"""get_overview's package-shaped blocks: key modules, entry points, layer roots, commands."""++from __future__ import annotations++import json+from types import SimpleNamespace++from repowise.server.mcp_server.tool_overview.graph import _build_commands, _layer_row+from repowise.server.mcp_server.tool_overview.pages import (+ _MODULE_CAP,+ _grouped_by_package,+ _key_module_heads,+)+++def _page(path: str, section: str | None = None) -> SimpleNamespace:+ return SimpleNamespace(target_path=path, title=path, section_number=section)+++def test_key_modules_are_the_topmost_pages_in_outline_order():+ pages = [+ _page("packages/web", "3"),+ _page("packages/core/src/core", "1"),+ _page("packages/core/src/core/store", "1.1"),+ _page("packages/core/alembic", "2"),+ _page("packages/web/lib", "3.1"),+ _page("scripts", "4"),+ ]+ heads = _key_module_heads(pages)+ assert [h.target_path for h in heads] == [+ "packages/core/src/core",+ "packages/core/alembic",+ "packages/web",+ "scripts",+ ]+++def test_too_few_heads_open_the_widest_into_its_top_layer():+ pages = [_page("src", "1"), *(_page(f"src/m{i}", f"1.{i + 1}") for i in range(5))]+ pages.append(_page("src/m0/deep", "1.1.1"))+ heads = _key_module_heads(pages)+ assert [h.target_path for h in heads] == [f"src/m{i}" for i in range(5)]+++def test_key_modules_stop_at_the_cap():+ pages = [_page(f"m{i:02d}", str(i + 1)) for i in range(20)]+ assert len(_key_module_heads(pages)) == _MODULE_CAP+++def test_entry_points_keep_their_rank_within_each_package():+ roots = ["", "packages/cli", "packages/web"]+ ranked = ["packages/cli/main.py", "packages/web/app.ts", "packages/cli/hook.py", "run.py"]+ assert _grouped_by_package(ranked, roots) == [+ "packages/cli/main.py",+ "packages/cli/hook.py",+ "packages/web/app.ts",+ "run.py",+ ]+++def test_a_layer_names_the_directory_holding_most_of_it():+ ids = [f"file:packages/ui/src/c{i}.tsx" for i in range(3)] + ["file:packages/web/x.ts"]+ layer = SimpleNamespace(name="UI", node_ids_json=json.dumps(ids))+ assert _layer_row(layer, ["packages/ui", "packages/web"])["root"] == "packages/ui/src"+++def test_a_layer_spread_over_packages_names_no_root():+ ids = ["file:packages/ui/a.ts", "file:packages/web/b.ts"]+ layer = SimpleNamespace(name="Types", node_ids_json=json.dumps(ids))+ assert "root" not in _layer_row(layer, ["packages/ui", "packages/web"])+++def test_commands_name_a_package_only_for_tasks_the_root_lacks(tmp_path):+ (tmp_path / "package.json").write_text(json.dumps({"scripts": {"test": "x", "lint": "y"}}))+ for name, scripts in (("same", {"test": "x"}), ("app", {"build": "b", "test": "x"})):+ (tmp_path / name).mkdir()+ (tmp_path / name / "package.json").write_text(json.dumps({"scripts": scripts}))++ commands = _build_commands(tmp_path, ["", "same", "app"])++ assert commands["."] == {"test": "npm run test", "lint": "npm run lint"}+ assert "same" not in commands+ assert commands["app"]["build"] == "npm run build"+ assert _build_commands(None, []) == {}+++def test_twin_module_pages_do_not_stall_the_widening():+ pages = [_page("src", "1"), _page("src", "2"), _page("src/a", "1.1")]+ assert [h.target_path for h in _key_module_heads(pages)] == ["src/a"]diff --git a/tests/unit/server/test_mcp_kg_enrichment.py b/tests/unit/server/test_mcp_kg_enrichment.pyindex 80b7fea68..329805971 100644--- a/tests/unit/server/test_mcp_kg_enrichment.py+++ b/tests/unit/server/test_mcp_kg_enrichment.py@@ -384,7 +384,7 @@ async def test_overview_layer_file_count(setup_mcp_with_kg):@pytest.mark.asyncio-async def test_overview_layers_carry_names_and_counts_only(setup_mcp_with_kg):+async def test_overview_layers_carry_names_counts_and_roots_only(setup_mcp_with_kg):from repowise.server.mcp_server import get_overviewresult = await get_overview()@@ -393,7 +393,7 @@ async def test_overview_layers_carry_names_and_counts_only(setup_mcp_with_kg):# The layer prose restated the overview essay; get_context on a layer file# is the route to it now.for layer in layers:- assert set(layer) == {"name", "file_count"}+ assert set(layer) <= {"name", "file_count", "root"}# ---------------------------------------------------------------------------