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(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.md
index 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.md
index 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 it
floats 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.md
index 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.py
index 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"] = ranked
diff --git a/packages/core/src/repowise/core/generation/editor_files/fetcher.py b/packages/core/src/repowise/core/generation/editor_files/fetcher.py
index 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_unscored
from repowise.core.analysis.health.scoring import hotspot_health, nloc_weighted_score
from repowise.core.analysis.health.trends import DECLINE_LOOKBACK, hotspot_trend
from 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_scope
from repowise.core.persistence import crud
from 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.py
index 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 to
break ties. It is deliberately free of any DB/graph/LLM dependency so the
ordering 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 paths
diff --git a/packages/server/src/repowise/server/mcp_server/tool_overview/graph.py b/packages/server/src/repowise/server/mcp_server/tool_overview/graph.py
index 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 annotations
import copy
import json
from collections import Counter, defaultdict
+from pathlib import Path
from typing import Any
from 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 no
weight 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 cached
async 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 out
diff --git a/packages/server/src/repowise/server/mcp_server/tool_overview/pages.py b/packages/server/src/repowise/server/mcp_server/tool_overview/pages.py
index 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 Any
from sqlalchemy import select
+from repowise.core.generation.entry_points import orientation_entry_points_view
from 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, Page
from repowise.server.mcp_server._budget import OmissionCollector
from 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.py
index 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_actions
from repowise.server.mcp_server.tool_overview.decisions import _build_key_decisions
from 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_health
from 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_rows
from 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.py
index 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 stops
assert 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.py
index 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_ro
omitted = 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 stored
assert stored.count("Extra Module") + stored.count("Module") >= 7
diff --git a/tests/unit/server/mcp/test_overview_packages.py b/tests/unit/server/mcp/test_overview_packages.py
new file mode 100644
index 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.py
index 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_overview
result = 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"}
# ---------------------------------------------------------------------------